Planners

A Planner decides which migrations to run and in which direction. It compares the available migrations (from the Source) with the applied migrations (from the Target) and produces a Plan — an ordered list of actions.

Interface

type Planner interface {
    Plan(ctx context.Context) (Plan, error)
}
 
type Plan []*Action
 
type Action struct {
    Action    ActionType  // "do" or "undo"
    Migration Migration
}

Built-in Planners

MigratePlanner (default)

Runs all pending migrations from the current state to the latest.

migrations.Migrate(ctx, source, target)
// or explicitly:
migrations.Migrate(ctx, source, target,
    migrations.WithPlanner(migrations.MigratePlanner),
)

If all migrations are already applied, returns an empty plan (no-op).

ResetPlanner

Undoes all applied migrations in reverse order, then applies all migrations from scratch.

migrations.Migrate(ctx, source, target,
    migrations.WithPlanner(migrations.ResetPlanner),
)

Useful for resetting a development or test database to a known state.

RewindPlanner

Undoes all applied migrations in reverse order. Does not re-apply anything.

migrations.Migrate(ctx, source, target,
    migrations.WithPlanner(migrations.RewindPlanner),
)

StepPlanner

Steps forward or backward by N migrations.

// Apply the next 3 pending migrations
migrations.Migrate(ctx, source, target,
    migrations.WithPlanner(migrations.StepPlanner(3)),
)
 
// Undo the last 2 applied migrations
migrations.Migrate(ctx, source, target,
    migrations.WithPlanner(migrations.StepPlanner(-2)),
)

Returns ErrStepOutOfIndex if the step goes beyond the available range.

DoPlanner

Applies the next single pending migration. Equivalent to StepPlanner(1).

migrations.Migrate(ctx, source, target,
    migrations.WithPlanner(migrations.DoPlanner),
)

UndoPlanner

Undoes the last applied migration. Equivalent to StepPlanner(-1).

migrations.Migrate(ctx, source, target,
    migrations.WithPlanner(migrations.UndoPlanner),
)

Returns ErrMigrationNotUndoable if the migration doesn't support undo.

Summary

Custom Planners

A planner is any function matching the ActionPLanner signature:

type ActionPLanner func(source Source, target Target) Planner

You can implement custom planners to target a specific migration version, skip certain migrations, or implement any other strategy.