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/pkg/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/pkg/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 help, init, 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/pkg/migrator"
    "github.com/gopackx/go-migration/pkg/schema/grammars"
)

// Default (no grammar configured; required for Fresh())
m := migrator.New(db)

// With a specific grammar
m := migrator.New(db, migrator.WithGrammar(&grammars.MySQLGrammar{}))

Available options:

WithGrammar accepts any value implementing schema.Grammar. The grammars package provides &grammars.MySQLGrammar{}, &grammars.PostgresGrammar{}, and &grammars.SQLiteGrammar{} (or the matching grammars.NewMySQLGrammar(), grammars.NewPostgresGrammar(), and grammars.NewSQLiteGrammar() constructors).

The Logger interface required by WithLogger is:

type Logger interface {
    Info(msg string, args ...any)
    Error(msg string, args ...any)
}

// Custom table name and logger
m := migrator.New(db,
    migrator.WithGrammar(&grammars.PostgresGrammar{}),
    migrator.WithTableName("schema_migrations"),
    migrator.WithLogger(myLogger),
)

// Dry-run: print SQL to stdout instead of executing
m := migrator.New(db,
    migrator.WithGrammar(&grammars.PostgresGrammar{}),
    migrator.WithDryRun(os.Stdout),
)

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/pkg/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) {
    // Index is 0-based; add 1 for human-friendly "N of Total" display.
    fmt.Printf("[%d/%d] %s %s (%s)\n", e.Index+1, 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) error

Returns: error — nil on success, or an error wrapping ErrInvalidMigrationName (bad name format) or ErrDuplicateMigration (name already registered).

if err := m.Register("20240101000001_create_users_table", &migrations.CreateUsersTable{}); err != nil {
    log.Fatal(err)
}
if err := m.Register("20240115000001_create_posts_table", &migrations.CreatePostsTable{}); err != nil {
    log.Fatal(err)
}

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 — Applied: %v, Batch: %d\n", s.Name, s.Applied, s.Batch)
}

See Migration Status.

m.BeforeMigrate()

Registers a hook that runs before each migration is executed. The hook fires once per migration, receiving that migration's name and direction.

func (m *Migrator) BeforeMigrate(fn func(name string, direction string) error)

If the callback returns an error, that migration is aborted and no further migrations run.

m.BeforeMigrate(func(name, direction string) error {
    log.Printf("Starting %s %s...", direction, name)
    return nil
})

See Hooks for use cases and error behavior.

m.AfterMigrate()

Registers a hook that runs after each migration completes. The hook fires once per migration, receiving its name, direction, and execution duration.

func (m *Migrator) AfterMigrate(fn func(name string, direction string, duration time.Duration) error)

If the callback returns an error, the error is ignored and execution continues.

m.AfterMigrate(func(name, direction string, duration time.Duration) error {
    log.Printf("Finished %s %s in %s", direction, name, duration)
    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) error
    Down(s *schema.Builder) error
}

Optionally implement TransactionOption to opt out of per-migration transaction wrapping. Return true to disable the surrounding transaction:

type TransactionOption interface {
    DisableTransaction() bool
}

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