gormigrate

To use Gormigrate with Gorm v2, import the package using the following path:

github.com/go-gormigrate/gormigrate/v2

If you are using the older Gorm v1 (which uses github.com/jinzhu/gorm), you must use the gopkg.in/gormigrate.v1 import path instead.

import "github.com/go-gormigrate/gormigrate/v2"

When deploying to a new, empty database, running a long list of individual migrations can be inefficient. You can use m.InitSchema(func(tx *gorm.DB) error { ... }) to define a single function that runs only if no previous migrations have been recorded in the database. This is ideal for performing a bulk AutoMigrate or setting up complex constraints and foreign keys in one step.

m.InitSchema(func(tx *gorm.DB) error {
	err := tx.AutoMigrate(
		&Organization{},
		&User{},
	)
	if err != nil {
		return err
	}

	if err := tx.Exec("ALTER TABLE users ADD CONSTRAINT fk_users_organizations FOREIGN KEY (organization_id) REFERENCES organizations (id)").Error; err != nil {
		return err
	}
	return nil
})

Use the Options struct to customize how migrations are stored and executed. If you don't provide options, DefaultOptions is used.

options := &gormigrate.Options{
	TableName:     "my_migrations",
	UseTransaction: true,
}

You can customize the behavior of the migration manager by providing a custom Options struct to gormigrate.New.

type Options struct {
	// TableName is the migration table.
	TableName string
	// IDColumnName is the name of column where the migration id will be stored.
	IDColumnName string
	// IDColumnSize is the length of the migration id column
	IDColumnSize int
	// UseTransaction makes Gormigrate execute migrations inside a single transaction.
	// Keep in mind that not all databases support DDL commands inside transactions.
	UseTransaction bool
	// ValidateUnknownMigrations will cause migrate to fail if there's unknown migration
	// IDs in the database
	ValidateUnknownMigrations bool
}

Gormigrate supports any database that is compatible with Gorm, including:

• MySQL
• MariaDB
• PostgreSQL
• SQLite
• Microsoft SQL Server
• TiDB
• Clickhouse

If you are working with a completely empty database, you can use InitSchema(fn) to define a function that runs once to set up the initial state (e.g., creating all base tables and foreign keys).

InitSchema is only executed if no migrations have been recorded in the migration table yet. This prevents running a full migration suite on an existing database that was already initialized.

g.InitSchema(func(tx *gorm.DB) error {
	return tx.AutoMigrate(&User{}, &Account{})
})

// When Migrate() is called on a fresh DB, it runs InitSchema first
err := g.Migrate()

To use Gormigrate, call New() with a *gorm.DB instance, an optional *Options pointer, and a slice of *Migration objects. If options is nil, it defaults to DefaultOptions.

import (
	"gorm.io/gorm"
	"github.com/go-gormigrate/go-gormigrate/gormigrate"
)

// ... setup db ...

migrations := []*gormigrate.Migration{
	{
		ID: "20230101000000",
		Migrate: func(tx *gorm.DB) error {
			return tx.AutoMigrate(&User{})
		},
	},
}

g := gormigrate.New(db, nil, migrations)

To undo changes, use RollbackLast() to undo the single most recent migration, or RollbackTo(migrationID) to undo all migrations occurring after the specified migrationID (the target ID itself is NOT rolled back).

Note: A migration can only be rolled back if a Rollback function was provided in its definition. If missing, it returns ErrRollbackImpossible.

// Undo the very last migration that was run
err := g.RollbackLast()

// Undo migrations until we reach this ID
err := g.RollbackTo("20230101000000")

Use Migrate() to execute all pending migrations in the order they are defined. Use MigrateTo(migrationID) to execute all pending migrations up to and including the specified migrationID.

// Run all pending migrations
err := g.Migrate()

// Run migrations up to a specific ID
err := g.MigrateTo("202301021504")