migrate

type AddColumnOp ¶ added in v1.2.6

type AddColumnOp struct {
	TableName  string
	ColumnName string
	Column     sqlschema.Column
}

AddColumnOp adds a new column to the table.

func (op *AddColumnOp) GetReverse() Operation

type AddForeignKeyOp ¶ added in v1.2.6

type AddForeignKeyOp struct {
	ForeignKey     sqlschema.ForeignKey
	ConstraintName string
}

AddForeignKey adds a new FOREIGN KEY constraint.

func (op *AddForeignKeyOp) DependsOn(another Operation) bool

func (op *AddForeignKeyOp) GetReverse() Operation

func (op *AddForeignKeyOp) TableName() string

type AddPrimaryKeyOp ¶ added in v1.2.6

type AddPrimaryKeyOp struct {
	TableName  string
	PrimaryKey sqlschema.PrimaryKey
}

AddPrimaryKeyOp adds a new PRIMARY KEY to the table.

func (op *AddPrimaryKeyOp) DependsOn(another Operation) bool

func (op *AddPrimaryKeyOp) GetReverse() Operation

type AddUniqueConstraintOp ¶ added in v1.2.6

type AddUniqueConstraintOp struct {
	TableName string
	Unique    sqlschema.Unique
}

AddUniqueConstraintOp adds new UNIQUE constraint to the table.

func (op *AddUniqueConstraintOp) DependsOn(another Operation) bool

func (op *AddUniqueConstraintOp) GetReverse() Operation

type AutoMigrator ¶ added in v1.2.6

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

AutoMigrator performs automated schema migrations.

It is designed to be a drop-in replacement for some Migrator functionality and supports all existing configuration options. Similarly to Migrator, it has methods to create SQL migrations, write them to a file, and apply them. Unlike Migrator, it detects the differences between the state defined by bun models and the current database schema automatically.

Usage:

1. Generate migrations and apply them at once with AutoMigrator.Migrate().
2. Create up- and down-SQL migration files and apply migrations using Migrator.Migrate().

While both methods produce complete, reversible migrations (with entries in the database and SQL migration files), prefer creating migrations and applying them separately for any non-trivial cases to ensure AutoMigrator detects expected changes correctly.

Limitations:

• AutoMigrator only supports a subset of the possible ALTER TABLE modifications.
• Some changes are not automatically reversible. For example, you would need to manually add a CREATE TABLE query to the .down migration file to revert a DROP TABLE migration.
• Does not validate most dialect-specific constraints. For example, when changing column data type, make sure the data con be auto-casted to the new type.
• Due to how the schema-state diff is calculated, it is not possible to rename a table and modify any of its columns' _data type_ in a single run. This will cause the AutoMigrator to drop and re-create the table under a different name; it is better to apply this change in 2 steps. Renaming a table and renaming its columns at the same time is possible.
• Renaming table/column to an existing name, i.e. like this [A->B] [B->C], is not possible due to how AutoMigrator distinguishes "rename" and "unchanged" columns.

Dialect must implement both sqlschema.Inspector and sqlschema.Migrator to be used with AutoMigrator.

func NewAutoMigrator(db *bun.DB, opts ...AutoMigratorOption) (*AutoMigrator, error)

func (am *AutoMigrator) CreateSQLMigrations(ctx context.Context) ([]*MigrationFile, error)

func (am *AutoMigrator) CreateTxSQLMigrations(ctx context.Context) ([]*MigrationFile, error)

func (am *AutoMigrator) Migrate(ctx context.Context, opts ...MigrationOption) (*MigrationGroup, error)

type AutoMigratorOption ¶ added in v1.2.6

type AutoMigratorOption func(m *AutoMigrator)

AutoMigratorOption configures an AutoMigrator.

func WithExcludeForeignKeys(fks ...sqlschema.ForeignKey) AutoMigratorOption

func WithExcludeTable(tables ...string) AutoMigratorOption

func WithLocksTableNameAuto(table string) AutoMigratorOption

func WithMarkAppliedOnSuccessAuto(enabled bool) AutoMigratorOption

func WithMigrationsDirectoryAuto(directory string) AutoMigratorOption

func WithModel(models ...any) AutoMigratorOption

func WithSchemaName(schemaName string) AutoMigratorOption

func WithTableNameAuto(table string) AutoMigratorOption

type ChangeColumnTypeOp ¶ added in v1.2.6

type ChangeColumnTypeOp struct {
	TableName string
	Column    string
	From      sqlschema.Column
	To        sqlschema.Column
}

ChangeColumnTypeOp set a new data type for the column. The two types should be such that the data can be auto-casted from one to another. E.g. reducing VARCHAR lenght is not possible in most dialects. AutoMigrator does not enforce or validate these rules.

func (op *ChangeColumnTypeOp) GetReverse() Operation

type ChangePrimaryKeyOp ¶ added in v1.2.6

type ChangePrimaryKeyOp struct {
	TableName string
	Old       sqlschema.PrimaryKey
	New       sqlschema.PrimaryKey
}

ChangePrimaryKeyOp changes the PRIMARY KEY of the table.

func (op *ChangePrimaryKeyOp) GetReverse() Operation

type CompareTypeFunc ¶ added in v1.2.6

type CompareTypeFunc func(sqlschema.Column, sqlschema.Column) bool

CompareTypeFunc compares two column definitions and reports whether they have the same SQL type.

type CreateTableOp ¶ added in v1.2.6

type CreateTableOp struct {
	TableName string
	Model     any
}

CreateTableOp creates a new table in the schema.

It does not report dependency on any other migration and may be executed first. Make sure the dialect does not include FOREIGN KEY constraints in the CREATE TABLE statement, as those may potentially reference not-yet-existing columns/tables.

func (op *CreateTableOp) GetReverse() Operation

type DropColumnOp ¶ added in v1.2.6

type DropColumnOp struct {
	TableName  string
	ColumnName string
	Column     sqlschema.Column
}

DropColumnOp drop a column from the table.

While some dialects allow DROP CASCADE to drop dependent constraints, explicit handling on constraints is preferred for transparency and debugging. DropColumnOp depends on DropForeignKeyOp, DropPrimaryKeyOp, and ChangePrimaryKeyOp if any of the constraints is defined on this table.

func (op *DropColumnOp) DependsOn(another Operation) bool

func (op *DropColumnOp) GetReverse() Operation

type DropForeignKeyOp ¶ added in v1.2.6

type DropForeignKeyOp struct {
	ForeignKey     sqlschema.ForeignKey
	ConstraintName string
}

DropForeignKeyOp drops a FOREIGN KEY constraint.

func (op *DropForeignKeyOp) GetReverse() Operation

func (op *DropForeignKeyOp) TableName() string

type DropPrimaryKeyOp ¶ added in v1.2.6

type DropPrimaryKeyOp struct {
	TableName  string
	PrimaryKey sqlschema.PrimaryKey
}

DropPrimaryKeyOp drops the table's PRIMARY KEY.

func (op *DropPrimaryKeyOp) GetReverse() Operation

type DropTableOp ¶ added in v1.2.6

type DropTableOp struct {
	TableName string
}

DropTableOp drops a database table. This operation is not reversible.

func (op *DropTableOp) DependsOn(another Operation) bool

func (op *DropTableOp) GetReverse() Operation

type DropUniqueConstraintOp ¶ added in v1.2.6

type DropUniqueConstraintOp struct {
	TableName string
	Unique    sqlschema.Unique
}

DropUniqueConstraintOp drops a UNIQUE constraint.

func (op *DropUniqueConstraintOp) DependsOn(another Operation) bool

func (op *DropUniqueConstraintOp) GetReverse() Operation

type GoMigrationOption ¶ added in v0.3.4

type GoMigrationOption func(cfg *goMigrationConfig)

GoMigrationOption configures Go migration file generation.

func WithGoTemplate(template string) GoMigrationOption

func WithPackageName(name string) GoMigrationOption

type Migration ¶

type Migration struct {
	bun.BaseModel

	ID         int64 `bun:",pk,autoincrement"`
	Name       string
	Comment    string `bun:"-"`
	GroupID    int64
	MigratedAt time.Time `bun:",notnull,nullzero,default:current_timestamp"`

	Up   internalMigrationFunc `bun:"-"`
	Down internalMigrationFunc `bun:"-"`
}

Migration represents a single database migration with up and down functions.

func (m Migration) IsApplied() bool

func (m Migration) String() string

type MigrationFile ¶ added in v0.3.0

type MigrationFile struct {
	Name    string
	Path    string
	Content string
}

MigrationFile represents a generated migration file on disk.

type MigrationFunc ¶

type MigrationFunc func(ctx context.Context, db *bun.DB) error

MigrationFunc is a function that executes a migration against a database.

type MigrationGroup ¶ added in v0.3.0

type MigrationGroup struct {
	ID         int64
	Migrations MigrationSlice
}

MigrationGroup is a group of migrations that were applied together in a single Migrate call.

func (g MigrationGroup) IsZero() bool

func (g MigrationGroup) String() string

type MigrationHook ¶ added in v1.2.16

type MigrationHook func(ctx context.Context, db bun.IConn, migration *Migration) error

MigrationHook is a callback invoked before or after each migration runs.

type MigrationOption ¶ added in v0.3.1

type MigrationOption func(cfg *migrationConfig)

MigrationOption configures how a migration is executed.

func WithNopMigration() MigrationOption

type MigrationSlice ¶ added in v0.3.0

type MigrationSlice []Migration

MigrationSlice is a slice of migrations that provides helper methods for filtering and grouping.

func (ms MigrationSlice) Applied() MigrationSlice

func (ms MigrationSlice) LastGroup() *MigrationGroup

func (ms MigrationSlice) LastGroupID() int64

func (ms MigrationSlice) String() string

func (ms MigrationSlice) Unapplied() MigrationSlice

type Migrations ¶

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

Migrations is a collection of registered migrations.

func NewMigrations(opts ...MigrationsOption) *Migrations

func (m *Migrations) Add(migration Migration)

func (m *Migrations) Discover(fsys fs.FS) error

func (m *Migrations) DiscoverCaller() error

func (m *Migrations) MustRegister(up, down MigrationFunc)

func (m *Migrations) Register(up, down MigrationFunc) error

func (m *Migrations) Sorted() MigrationSlice

type MigrationsOption ¶

type MigrationsOption func(m *Migrations)

MigrationsOption configures a Migrations instance.

func WithMigrationsDirectory(directory string) MigrationsOption

type Migrator ¶ added in v0.3.0

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

Migrator manages the lifecycle of database migrations.

func NewMigrator(db *bun.DB, migrations *Migrations, opts ...MigratorOption) *Migrator

func (m *Migrator) AppliedMigrations(ctx context.Context) (MigrationSlice, error)

func (m *Migrator) CreateGoMigration(
	ctx context.Context, name string, opts ...GoMigrationOption,
) (*MigrationFile, error)

func (m *Migrator) CreateSQLMigrations(ctx context.Context, name string) ([]*MigrationFile, error)

func (m *Migrator) CreateTxSQLMigrations(ctx context.Context, name string) ([]*MigrationFile, error)

func (m *Migrator) DB() *bun.DB

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

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

func (m *Migrator) MarkApplied(ctx context.Context, migration *Migration) error

func (m *Migrator) MarkUnapplied(ctx context.Context, migration *Migration) error

func (m *Migrator) Migrate(ctx context.Context, opts ...MigrationOption) (*MigrationGroup, error)

func (m *Migrator) MigrationsWithStatus(ctx context.Context) (MigrationSlice, error)

func (m *Migrator) MissingMigrations(ctx context.Context) (MigrationSlice, error)

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

func (m *Migrator) Rollback(ctx context.Context, opts ...MigrationOption) (*MigrationGroup, error)

func (m *Migrator) RunMigration(
	ctx context.Context, migrationName string, opts ...MigrationOption,
) error

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

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

type MigratorOption ¶ added in v0.3.0

type MigratorOption func(m *Migrator)

MigratorOption configures a Migrator.

func AfterMigration(hook MigrationHook) MigratorOption

func BeforeMigration(hook MigrationHook) MigratorOption

func WithLocksTableName(table string) MigratorOption

func WithMarkAppliedOnSuccess(enabled bool) MigratorOption

func WithTableName(table string) MigratorOption

func WithTemplateData(data any) MigratorOption

func WithUpsert(enabled bool) MigratorOption

type Operation ¶ added in v1.2.6

type Operation interface {
	GetReverse() Operation
}

Operation encapsulates the request to change a database definition and knowns which operation can revert it.

It is useful to define "monolith" Operations whenever possible, even though they a dialect may require several distinct steps to apply them. For example, changing a primary key involves first dropping the old constraint before generating the new one. Yet, this is only an implementation detail and passing a higher-level ChangePrimaryKeyOp will give the dialect more information about the applied change.

Some operations might be irreversible due to technical limitations. Returning a *comment from GetReverse() will add an explanatory note to the generate migration file.

To declare dependency on another Operation, operations should implement { DependsOn(Operation) bool } interface, which Changeset will use to resolve dependencies.

type RenameColumnOp ¶ added in v1.2.6

type RenameColumnOp struct {
	TableName string
	OldName   string
	NewName   string
}

RenameColumnOp renames a column in the table. If the changeset includes a rename operation for the column's table, it should be executed first.

func (op *RenameColumnOp) DependsOn(another Operation) bool

func (op *RenameColumnOp) GetReverse() Operation

type RenameTableOp ¶ added in v1.2.6

type RenameTableOp struct {
	TableName string
	NewName   string
}

RenameTableOp renames the table. Changing the "schema" part of the table's FQN (moving tables between schemas) is not allowed.

func (op *RenameTableOp) GetReverse() Operation

type Unimplemented ¶ added in v1.2.12

type Unimplemented string

Unimplemented denotes an Operation that cannot be executed.

Operations, which cannot be reversed due to current technical limitations, may have their GetReverse() return &Unimplemented with a helpful message.

When applying operations, changelog should skip it or output as a log message, and write it as an SQL Unimplemented when creating migration files.

func (reason *Unimplemented) GetReverse() Operation