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 ¶
- Variables
- func FindMigrations(fsys fs.FS) ([]string, error)
- func InstallCodePackage(ctx context.Context, conn *pgx.Conn, mergeData map[string]interface{}, ...) (err error)
- func LockExecTx(ctx context.Context, conn *pgx.Conn, sql string) (err error)
- type BadVersionError
- type CodePackage
- type ErrorLineExtract
- type IrreversibleMigrationError
- type Migration
- type MigrationFunc
- type MigrationPgError
- type Migrator
- func (m *Migrator) AppendMigration(name, upSQL, downSQL string)
- func (m *Migrator) GetCurrentVersion(ctx context.Context) (v int32, err error)
- func (m *Migrator) LoadMigrations(fsys fs.FS) error
- func (m *Migrator) Migrate(ctx context.Context) error
- func (m *Migrator) MigrateTo(ctx context.Context, targetVersion int32) (err error)
- type MigratorOptions
- type NoMigrationsFoundError
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNoFwMigration = errors.New("no sql in forward migration step")
Functions ¶
func FindMigrations ¶
FindMigrations finds all migration files in fsys.
func InstallCodePackage ¶
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)
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 ¶
func (e IrreversibleMigrationError) Error() string
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
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 ¶
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 ¶
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 (*Migrator) GetCurrentVersion ¶
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