Help us shape the future of Go! Take the 2026 Go Developer Survey

migration

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 31, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package migration registers Go migrations and runs them through Goose.

Index

Constants

View Source
const DefaultTable = "migrations"

DefaultTable is the bookkeeping table (Laravel calls it "migrations").

Variables

View Source
var Default = NewRegistry()

Default is the registry used by Register and by the CLI.

Functions

func ParseVersion

func ParseVersion(name string) (int64, error)

ParseVersion extracts the numeric version from a migration name.

func Register

func Register(name string, up, down Func)

Register adds a migration to Default. name must look like "20261030061400_create_users_table": a numeric version, an underscore and a description. It panics on a malformed or duplicate name, because that is a programming error caught at start-up.

Types

type Entry

type Entry struct {
	Version int64  // numeric prefix, e.g. 20261030061400
	Name    string // full name, e.g. 20261030061400_create_users_table
	Up      Func
	Down    Func
}

Entry is one registered migration.

type Func

type Func func(s *schema.Builder) error

Func is the body of a migration's up or down step.

type Migrator

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

Migrator runs the migrations of a Registry against a database. Goose does the bookkeeping (version table, ordering, transactions); dbkit supplies the Schema Builder.

func New

func New(db *sql.DB, driver string, reg *Registry, opts ...Options) (*Migrator, error)

New creates a Migrator. driver is postgres, mysql or sqlite (aliases such as pgx and sqlite3 are accepted).

func (*Migrator) Fresh

func (m *Migrator) Fresh(ctx context.Context) ([]Result, error)

Fresh drops every table (including the bookkeeping table) and migrates from scratch. It is destructive.

func (*Migrator) Pretend

func (m *Migrator) Pretend(ctx context.Context) (map[string][]string, []string, error)

Pretend returns the SQL that Up would run, without running it.

func (*Migrator) Refresh

func (m *Migrator) Refresh(ctx context.Context) ([]Result, error)

Refresh = Reset followed by Up.

func (*Migrator) Reset

func (m *Migrator) Reset(ctx context.Context) ([]Result, error)

Reset rolls back every applied migration.

func (*Migrator) Rollback

func (m *Migrator) Rollback(ctx context.Context, steps int) ([]Result, error)

Rollback undoes the last `steps` applied migrations (minimum 1).

func (*Migrator) Status

func (m *Migrator) Status(ctx context.Context) ([]Status, error)

Status lists every registered migration and whether it has been applied.

func (*Migrator) Up

func (m *Migrator) Up(ctx context.Context, steps int) ([]Result, error)

Up runs every pending migration. With steps > 0 it runs at most that many. The returned slice contains the migrations that succeeded, even on error.

type Options

type Options struct {
	// Table is the bookkeeping table. Default: "migrations".
	Table string
	// Lock enables a database-level lock so two deploys cannot migrate at
	// the same time (PostgreSQL only).
	Lock bool
}

Options configure a Migrator.

type Registry

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

Registry holds migrations in memory. Migration files add themselves to Default from init(); tests can create their own Registry.

func NewRegistry

func NewRegistry() *Registry

NewRegistry returns an empty registry.

func (*Registry) Add

func (r *Registry) Add(name string, up, down Func) error

Add registers a migration and returns an error instead of panicking.

func (*Registry) All

func (r *Registry) All() []Entry

All returns the migrations ordered by version.

func (*Registry) Len

func (r *Registry) Len() int

Len returns the number of registered migrations.

func (*Registry) MustRegister

func (r *Registry) MustRegister(name string, up, down Func)

MustRegister is Register on a specific registry.

type Result

type Result struct {
	Name     string
	Version  int64
	Up       bool // false = rolled back
	Duration time.Duration
}

Result describes one migration that was run.

type Status

type Status struct {
	Name      string
	Version   int64
	Applied   bool
	AppliedAt time.Time
}

Status describes the state of one registered migration.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL