migrate

package
v2.3.5 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 30, 2026 License: MIT Imports: 14 Imported by: 45

Documentation

Overview

Example (OnStartMigrationProgressLogging)
conn, err := pgx.Connect(context.Background(), os.Getenv("MIGRATE_TEST_CONN_STRING"))
if err != nil {
	fmt.Printf("Unable to establish connection: %v", err)
	return
}

// Clear any previous runs
if _, err = conn.Exec(context.Background(), "drop table if exists schema_version"); err != nil {
	fmt.Printf("Unable to drop schema_version table: %v", err)
	return
}

var m *migrate.Migrator
m, err = migrate.NewMigrator(context.Background(), conn, "schema_version")
if err != nil {
	fmt.Printf("Unable to create migrator: %v", err)
	return
}

m.OnStart = func(_ int32, name, direction, _ string) {
	fmt.Printf("Migrating %s: %s", direction, name)
}

m.AppendMigration("create a table", "create temporary table foo(id serial primary key)", "")

if err = m.Migrate(context.Background()); err != nil {
	fmt.Printf("Unexpected failure migrating: %v", err)
	return
}
Output:

Migrating up: create a table

Index

Examples

Constants

This section is empty.

Variables

View Source
var ErrNoFwMigration = errors.New("no sql in forward migration step")

Functions

func FindMigrations

func FindMigrations(fsys fs.FS) ([]string, error)

FindMigrations finds all migration files in fsys.

func InstallCodePackage

func InstallCodePackage(ctx context.Context, conn *pgx.Conn, mergeData map[string]interface{}, codePackage *CodePackage) (err error)

func LockExecTx

func LockExecTx(ctx context.Context, conn *pgx.Conn, sql string) (err error)

Types

type BadVersionError

type BadVersionError string

func (BadVersionError) Error

func (e BadVersionError) Error() string

type CodePackage

type CodePackage struct {
	// contains filtered or unexported fields
}

func LoadCodePackage

func LoadCodePackage(fsys fs.FS) (*CodePackage, error)

func (*CodePackage) Eval

func (cp *CodePackage) Eval(data map[string]interface{}) (string, error)

type ErrorLineExtract

type ErrorLineExtract struct {
	LineNum   int    // Line number starting with 1
	ColumnNum int    // Column number starting with 1
	Text      string // Text of the line without a new line character.
}

func ExtractErrorLine

func ExtractErrorLine(source string, position int) (ErrorLineExtract, error)

ExtractErrorLine takes source and character position extracts the line number, column number, and the line of text.

The first character is position 1.

type IrreversibleMigrationError

type IrreversibleMigrationError struct {
	// contains filtered or unexported fields
}

func (IrreversibleMigrationError) Error

type Migration

type Migration struct {
	// Sequence is a state identifier for the database schema after the up direction of the
	// [Migration] has been applied.
	Sequence int32
	// Name is a human-readable name or description of the [Migration].
	Name string

	// UpSQL declares SQL statements that brings the database up from its prior [Migration]
	// state. The [Migrator] will run the statements in a transaction unless the SQL contains
	// [disableTxPattern]. Cannot be used together with [UpFunc].
	UpSQL string
	// DownSQL declares SQL statements that brings the database back down to its prior
	// [Migration] state. The [Migrator] will run the statements in a transaction unless the SQL
	// contains [disableTxPattern]. Cannot be used together with [DownFunc].
	DownSQL string

	// DisableFuncTx, when true, tells the [Migrator] to not start a new transaction before
	// calling [UpFunc] (or [DownFunc]). Some SQL statements such as `create index concurrently`
	// cannot run within a transaction.
	DisableFuncTx bool
	// UpFunc is a Go function that brings the database up from its prior state [Migration]
	// state. Cannot be used together with [UpSQL].
	UpFunc MigrationFunc
	// DownFunc is a Go function that brings the database back down to its prior [Migration]
	// state. Cannot be used together with [DownSQL].
	DownFunc MigrationFunc
}

A Migration is a database schema state transition. It performs the modifications needed to bring the database schema up from its prior state to the new state (and optionally back down again).

type MigrationFunc added in v2.3.3

type MigrationFunc func(context.Context, *pgx.Conn) error

MigrationFunc can be used to define a Migration using a Go function. The Migrator will open a new transaction for the passed pgx.Conn unless [Migration.DisableFuncTx] is true.

type MigrationPgError

type MigrationPgError struct {
	MigrationName string
	Sql           string
	*pgconn.PgError
}

func (MigrationPgError) Error

func (e MigrationPgError) Error() string

func (MigrationPgError) Unwrap

func (e MigrationPgError) Unwrap() error

type Migrator

type Migrator struct {
	Migrations []*Migration
	OnStart    func(int32, string, string, string) // OnStart is called when a migration is run with the sequence, name, direction, and SQL
	Data       map[string]interface{}              // Data available to use in migrations
	// contains filtered or unexported fields
}

func NewMigrator

func NewMigrator(ctx context.Context, conn *pgx.Conn, versionTable string) (m *Migrator, err error)

NewMigrator initializes a new Migrator. It is highly recommended that versionTable be schema qualified.

func NewMigratorEx

func NewMigratorEx(ctx context.Context, conn *pgx.Conn, versionTable string, opts *MigratorOptions) (m *Migrator, err error)

NewMigratorEx initializes a new Migrator. It is highly recommended that versionTable be schema qualified.

func (*Migrator) AppendMigration

func (m *Migrator) AppendMigration(name, upSQL, downSQL string)

func (*Migrator) GetCurrentVersion

func (m *Migrator) GetCurrentVersion(ctx context.Context) (v int32, err error)

func (*Migrator) LoadMigrations

func (m *Migrator) LoadMigrations(fsys fs.FS) error

func (*Migrator) Migrate

func (m *Migrator) Migrate(ctx context.Context) error

Migrate runs pending migrations It calls m.OnStart when it begins a migration

func (*Migrator) MigrateTo

func (m *Migrator) MigrateTo(ctx context.Context, targetVersion int32) (err error)

MigrateTo migrates to targetVersion

type MigratorOptions

type MigratorOptions struct {
	// DisableTx causes the Migrator not to run migrations in a transaction.
	DisableTx bool
}

type NoMigrationsFoundError

type NoMigrationsFoundError struct{}

func (NoMigrationsFoundError) Error

func (e NoMigrationsFoundError) Error() string

Directories

Path Synopsis
internal

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL