migrate

Documentation

Index

• func Create(dir, name, migrationType string) error
• func Down(ctx context.Context, db *sql.DB, cfg Config) error
• func DownTo(ctx context.Context, db *sql.DB, cfg Config, version int64) error
• func Postgres(ctx context.Context, db *sql.DB, dir string) error
• func Reset(ctx context.Context, db *sql.DB, cfg Config) error
• func SQLite(ctx context.Context, db *sql.DB, dir string) error
• func Status(ctx context.Context, db *sql.DB, cfg Config) error
• func Up(ctx context.Context, db *sql.DB, cfg Config) error
• func Version(ctx context.Context, db *sql.DB, cfg Config) (int64, error)
• type Config
  • func DefaultConfig() Config
• type MigrationStatus
  • func MigrationStatuses(ctx context.Context, db *sql.DB, cfg Config) ([]MigrationStatus, error)

Functions

func Create

func Create(dir, name, migrationType string) error

Create creates a new migration file.

Example:

err := migrate.Create("migrations", "add_users_table", "sql")

func Down

func Down(ctx context.Context, db *sql.DB, cfg Config) error

Down rolls back the last migration.

func DownTo

func DownTo(ctx context.Context, db *sql.DB, cfg Config, version int64) error

DownTo rolls back to a specific version.

func Postgres

func Postgres(ctx context.Context, db *sql.DB, dir string) error

Postgres is a convenience function for PostgreSQL migrations.

Example:

pool, _ := gokart.OpenPostgres(ctx, url)
db := stdlib.OpenDBFromPool(pool)
err := migrate.Postgres(ctx, db, "migrations")

func Reset

func Reset(ctx context.Context, db *sql.DB, cfg Config) error

Reset rolls back all migrations.

func SQLite

func SQLite(ctx context.Context, db *sql.DB, dir string) error

SQLite is a convenience function for SQLite migrations.

Example:

db, _ := gokart.OpenSQLite("app.db")
err := migrate.SQLite(ctx, db, "migrations")

func Status

func Status(ctx context.Context, db *sql.DB, cfg Config) error

Status verifies that migration status can be loaded. It is retained for compatibility; use MigrationStatuses when the caller needs the results.

func Up

func Up(ctx context.Context, db *sql.DB, cfg Config) error

Up runs all pending migrations.

Example with file-based migrations:

db, _ := gokart.OpenPostgres(ctx, url)
err := migrate.Up(ctx, db.Config().ConnConfig.Database, migrate.Config{
    Dir:     "migrations",
    Dialect: "postgres",
})

Example with embedded migrations:

//go:embed migrations/*.sql
var migrations embed.FS

err := migrate.Up(ctx, db, migrate.Config{
    FS:      migrations,
    Dir:     "migrations",
    Dialect: "postgres",
})

func Version

func Version(ctx context.Context, db *sql.DB, cfg Config) (int64, error)

Version returns the current migration version.

Types

type Config

type Config struct {
	// Dir is the directory containing migration files.
	// Default: "migrations"
	Dir string

	// Table is the name of the migrations tracking table.
	// Default: "goose_db_version"
	Table string

	// Dialect is the required database dialect (postgres, sqlite3, mysql).
	Dialect string

	// FS is an optional filesystem for embedded migrations.
	FS fs.FS

	// AllowMissing allows applying missing (out-of-order) migrations.
	// Default: false
	AllowMissing bool

	// NoVersioning disables version tracking (for one-off scripts).
	// Default: false
	NoVersioning bool
}

Config configures database migrations.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns sensible defaults.

type MigrationStatus

type MigrationStatus struct {
	Version   int64
	Applied   bool
	AppliedAt time.Time
}

MigrationStatus reports whether one discovered migration has been applied.

func MigrationStatuses

func MigrationStatuses(ctx context.Context, db *sql.DB, cfg Config) ([]MigrationStatus, error)

MigrationStatuses returns the status of every discovered migration in provider order.