Migrator API

The Migrator is the central component of go-migration. It manages migration registration, execution, rollback, and status tracking.

Import path: github.com/gopackx/go-migration/migrator

For conceptual documentation, see Migrations.

migrator.Run()

The all-in-one CLI runner. Handles argument parsing, config loading (migration.json with ${ENV} interpolation, falls back to go-migration.yaml), database connection, auto-discovery of migrations and seeders, grammar auto-resolution from driver name, and command dispatch.

func Run()

This function does not return — it calls os.Exit() on completion or error.

package main

import (
    "github.com/gopackx/go-migration/migrator"
    _ "your-project/database/migrations"
    _ "your-project/database/seeders"
)

func main() {
    migrator.Run()
}

Run() performs the following steps:

1. Parses CLI arguments to determine the command
2. For commands that need a database (smart classification skips DB for version, help, make:*):
   • Loads migration.json (or --config path) with ${ENV} variable interpolation. Falls back to go-migration.yaml for backward compatibility.
   • Opens a database connection using the config
   • Auto-discovers all registered migrations and seeders
   • Resolves the grammar from the driver field (postgres → PostgreSQL, mysql → MySQL, sqlite → SQLite)
3. Dispatches the command

See Quick Start for a complete example.

migrator.New()

Creates a new Migrator instance bound to a database connection.

func New(db *sql.DB, opts ...Option) *Migrator

Returns: *Migrator

import (
    "database/sql"
    "github.com/gopackx/go-migration/migrator"
    "github.com/gopackx/go-migration/grammar"
)

// Default (PostgreSQL grammar)
m := migrator.New(db)

// With a specific grammar
m := migrator.New(db, migrator.WithGrammar(grammar.MySQL()))

See Database Grammars for grammar selection details.

migrator.AutoRegister()

Registers a migration in the global auto-registry. Intended to be called from init() functions in migration files.

func AutoRegister(name string, m Migration)

Panics if the name is invalid or a duplicate — fail-fast at startup.

package migrations

import "github.com/gopackx/go-migration/migrator"

func init() {
    migrator.AutoRegister("20240101000001_create_users", &CreateUsersTable{})
}

See Registering Migrations for the full auto-discovery pattern.

migrator.GetAutoRegistered()

Returns all auto-registered migrations in timestamp-sorted order.

func GetAutoRegistered() []registeredMigration

Returns: []registeredMigration — a defensive copy of the auto-registry contents.

migrator.ResetAutoRegistry()

Clears the global auto-registry. Intended for testing only.

func ResetAutoRegistry()

migrator.WithAutoDiscover()

Returns an Option that loads all auto-registered migrations into the Migrator during construction.

func WithAutoDiscover() Option

Panics if a name conflict exists between auto-registered and manually registered migrations.

m := migrator.New(db, migrator.WithAutoDiscover())

See Registering Migrations for usage details.

migrator.WithProgress()

Returns an Option that registers a callback function to receive progress events during migration execution.

type ProgressEvent struct {
    Name      string
    Index     int
    Total     int
    Duration  time.Duration
    Direction string
}

type ProgressFunc func(event ProgressEvent)

func WithProgress(fn ProgressFunc) Option

The callback is invoked after each migration completes, giving you real-time visibility into the migration process.

m := migrator.New(db, migrator.WithProgress(func(e migrator.ProgressEvent) {
    fmt.Printf("[%d/%d] %s %s (%s)\n", e.Index, e.Total, e.Direction, e.Name, e.Duration)
}))

See Progress Reporting.

m.Register()

Registers a migration struct with the migrator under a unique name.

func (m *Migrator) Register(name string, migration Migration)

m.Register("20240101_create_users_table", &migrations.CreateUsersTable{})
m.Register("20240115_create_posts_table", &migrations.CreatePostsTable{})

See Registering Migrations for naming conventions and auto-discovery.

m.AutoDiscover()

Loads all migrations from the global auto-registry into the Migrator's internal registry.

func (m *Migrator) AutoDiscover() error

Returns: error — returns nil on success, or an error wrapping ErrDuplicateMigration if a name conflict exists with manually registered migrations.

m := migrator.New(db)
if err := m.AutoDiscover(); err != nil {
    log.Fatal(err)
}

See Registering Migrations for the full auto-discovery workflow.

m.Up()

Executes all pending (not yet run) migrations in alphabetical order.

func (m *Migrator) Up() error

Returns: error — returns nil on success, or the first error encountered.

if err := m.Up(); err != nil {
    log.Fatal(err)
}

All migrations executed in a single Up() call are assigned the same batch number. Calling Up() multiple times is safe — already-executed migrations are skipped.

See Running Migrations for execution details and Batch Tracking for batch behavior.

m.Rollback()

Rolls back migrations by batch or by step count.

func (m *Migrator) Rollback(steps int) error

Returns: error

// Roll back the last batch
if err := m.Rollback(0); err != nil {
    log.Fatal(err)
}

// Roll back the last 3 migrations
if err := m.Rollback(3); err != nil {
    log.Fatal(err)
}

See Rollback for detailed examples.

m.Reset()

Rolls back all executed migrations in reverse order by calling each migration's Down method.

func (m *Migrator) Reset() error

Returns: error

if err := m.Reset(); err != nil {
    log.Fatal(err)
}

See Reset, Refresh & Fresh.

m.Refresh()

Rolls back all migrations and then re-runs them. Equivalent to Reset() followed by Up().

func (m *Migrator) Refresh() error

Returns: error

if err := m.Refresh(); err != nil {
    log.Fatal(err)
}

See Reset, Refresh & Fresh.

m.Fresh()

Drops all tables in the database and runs all migrations from scratch. Does not call Down methods.

func (m *Migrator) Fresh() error

Returns: error

if err := m.Fresh(); err != nil {
    log.Fatal(err)
}

See Reset, Refresh & Fresh.

m.Status()

Returns the current state of all registered migrations.

func (m *Migrator) Status() ([]MigrationStatus, error)

Returns: []MigrationStatus, error

Each MigrationStatus contains:

statuses, err := m.Status()
if err != nil {
    log.Fatal(err)
}

for _, s := range statuses {
    fmt.Printf("%s — Ran: %v, Batch: %d\n", s.Name, s.Ran, s.Batch)
}

See Migration Status.

m.Install()

Manually creates the migrations tracking table. This is normally done automatically on the first Up() call.

func (m *Migrator) Install() error

Returns: error

if err := m.Install(); err != nil {
    log.Fatal(err)
}

m.BeforeMigrate()

Registers a hook that runs before any migration is executed.

func (m *Migrator) BeforeMigrate(fn func() error)

If the callback returns an error, the migration is aborted and no changes are applied.

m.BeforeMigrate(func() error {
    log.Println("Starting migration...")
    return nil
})

See Hooks for use cases and error behavior.

m.AfterMigrate()

Registers a hook that runs after all migrations complete successfully.

func (m *Migrator) AfterMigrate(fn func() error)

If the callback returns an error, the error is logged but migrations are not rolled back.

m.AfterMigrate(func() error {
    log.Println("Migrations completed!")
    return nil
})

See Hooks for use cases and error behavior.

Migration Interface

Structs registered with the migrator must implement this interface:

type Migration interface {
    Up(s *schema.Builder)
    Down(s *schema.Builder)
}

Optionally implement DisableTransaction() to opt out of per-migration transaction wrapping:

type TransactionDisabler interface {
    DisableTransaction()
}

See Defining Migrations and Transactions.

TaggedSeeder Interface

Seeders can implement TaggedSeeder to be selectively run using the --tag flag on db:seed.

type TaggedSeeder interface {
    Tags() []string
}

type UserSeeder struct{}

func (s *UserSeeder) Run(db *sql.DB) error { /* ... */ }
func (s *UserSeeder) Tags() []string { return []string{"core"} }

# Run only seeders tagged "core"
go-migration db:seed --tag=core

See Seeder Tags for details.

RollbackableSeeder Interface

Seeders can implement RollbackableSeeder to support rollback via the db:seed:rollback command.

type RollbackableSeeder interface {
    Rollback(db *sql.DB) error
}

type UserSeeder struct{}

func (s *UserSeeder) Run(db *sql.DB) error { /* ... */ }

func (s *UserSeeder) Rollback(db *sql.DB) error {
    _, err := db.Exec("DELETE FROM users WHERE seeded = true")
    return err
}

go-migration db:seed:rollback --class=UserSeeder

See Seeder Rollback for details.

Quick Reference