migrate

type AddColumnOp ¶

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 ¶

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 ¶

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 ¶

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 ¶

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 au 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 ¶

type AutoMigratorOption func(m *AutoMigrator)

func WithExcludeTable(tables ...string) AutoMigratorOption

func WithLocksTableNameAuto(table string) AutoMigratorOption

func WithMarkAppliedOnSuccessAuto(enabled bool) AutoMigratorOption

func WithMigrationsDirectoryAuto(directory string) AutoMigratorOption

func WithModel(models ...interface{}) AutoMigratorOption

func WithSchemaName(schemaName string) AutoMigratorOption

func WithTableNameAuto(table string) AutoMigratorOption

type ChangeColumnTypeOp ¶

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 ¶

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 ¶

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

type CreateTableOp ¶

type CreateTableOp struct {
	TableName string
	Model     interface{}
}

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 ¶

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 ¶

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 ¶

type DropPrimaryKeyOp struct {
	TableName  string
	PrimaryKey sqlschema.PrimaryKey
}

DropPrimaryKeyOp drops the table's PRIMARY KEY.

func (op *DropPrimaryKeyOp) GetReverse() Operation

type DropTableOp ¶

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 ¶

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 ¶

type GoMigrationOption func(cfg *goMigrationConfig)

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   MigrationFunc `bun:"-"`
	Down MigrationFunc `bun:"-"`
}

func (m Migration) IsApplied() bool

func (m Migration) String() string

type MigrationFile ¶

type MigrationFile struct {
	Name    string
	Path    string
	Content string
}

type MigrationFunc ¶

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

func NewSQLMigrationFunc(fsys fs.FS, name string) MigrationFunc

type MigrationGroup ¶

type MigrationGroup struct {
	ID         int64
	Migrations MigrationSlice
}

func (g MigrationGroup) IsZero() bool

func (g MigrationGroup) String() string

type MigrationOption ¶

type MigrationOption func(cfg *migrationConfig)

func WithNopMigration() MigrationOption

type MigrationSlice ¶

type MigrationSlice []Migration

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
}

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)

func WithMigrationsDirectory(directory string) MigrationsOption

type Migrator ¶

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

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) TruncateTable(ctx context.Context) error

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

type MigratorOption ¶

type MigratorOption func(m *Migrator)

func WithLocksTableName(table string) MigratorOption

func WithMarkAppliedOnSuccess(enabled bool) MigratorOption

func WithTableName(table string) MigratorOption

type Operation ¶

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 migation file.

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

type RenameColumnOp ¶

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 ¶

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