migration

package module
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Aug 19, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package migration provides a database schema migration framework inspired by golang-migrate and goose.

It supports versioned SQL migrations with up/down directions, embedded SQL files, and filesystem-based SQL files. The actual migration execution is delegated to a Migrator implementation (e.g. gormmigrator), keeping this core package free of database dependencies.

Migration file naming

Migrations are identified by a numeric version and a description:

0001_create_users.up.sql
0001_create_users.down.sql
0002_add_email_index.up.sql
0002_add_email_index.down.sql

The version is a zero-padded integer. The ".up.sql" and ".down.sql" suffixes distinguish forward and rollback scripts.

Quick start

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

src := migration.NewEmbedSource(migrationFS, "migrations")
migrator := gormmigrator.New(db, src)

if err := migrator.Up(context.Background()); err != nil {
    log.Fatal(err)
}

Integration with bootstrap

app := bootstrap.New("myapp",
    bootstrap.WithProfile(bootstrap.ProfileDev),
    bootstrap.WithMigration(migrator),       // versioned SQL migrations
    // or for dev/test:
    // bootstrap.WithAutoMigrate(db, &User{}, &Order{}),
)

In dev/test profiles, you might prefer WithAutoMigrate (GORM AutoMigrate) for rapid iteration. In production, use WithMigration with versioned SQL files for controlled, reviewable schema changes.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrNoMigrations is returned when the source contains no migrations.
	ErrNoMigrations = errors.New("migration: no migrations found")
	// ErrMigrationNotFound is returned when a specific version is not found.
	ErrMigrationNotFound = errors.New("migration: version not found")
	// ErrAlreadyApplied is returned when trying to apply an already-applied migration.
	ErrAlreadyApplied = errors.New("migration: already applied")
	// ErrNotApplied is returned when trying to roll back a migration that wasn't applied.
	ErrNotApplied = errors.New("migration: not applied")
	// ErrInvalidVersion is returned when a migration version is invalid.
	ErrInvalidVersion = errors.New("migration: invalid version")
)

Functions

This section is empty.

Types

type EmbedSource

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

EmbedSource reads migrations from an embedded filesystem (go:embed).

Usage:

//go:embed migrations/*.sql
var migrationFS embed.FS
src := migration.NewEmbedSource(migrationFS, "migrations")

func NewEmbedSource

func NewEmbedSource(fsys fs.FS, root string) *EmbedSource

NewEmbedSource creates a Source from an embedded filesystem. The root is the directory within the FS containing the .sql files.

func (*EmbedSource) Migrations

func (s *EmbedSource) Migrations() ([]Migration, error)

Migrations implements Source.

type FileSource

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

FileSource reads migrations from a filesystem directory.

Usage:

src := migration.NewFileSource("./db/migrations")

func NewFileSource

func NewFileSource(dir string) *FileSource

NewFileSource creates a Source from a filesystem directory.

func (*FileSource) Migrations

func (s *FileSource) Migrations() ([]Migration, error)

Migrations implements Source.

type Migration

type Migration struct {
	// Version is the numeric version identifier (e.g. 1, 2, 3).
	Version uint64

	// Description is a human-readable name (e.g. "create_users").
	Description string

	// UpSQL is the forward migration SQL. Empty means no-op.
	UpSQL string

	// DownSQL is the rollback migration SQL. Empty means no rollback possible.
	DownSQL string
}

Migration represents a single versioned database migration.

func (*Migration) HasDown

func (m *Migration) HasDown() bool

HasDown returns true if this migration has a rollback SQL script.

func (*Migration) HasUp

func (m *Migration) HasUp() bool

HasUp returns true if this migration has a forward SQL script.

func (*Migration) String

func (m *Migration) String() string

String returns a human-readable representation.

type MigrationStatus

type MigrationStatus struct {
	Migration
	Applied bool
	// AppliedAt is the timestamp when the migration was applied (if applied).
	AppliedAt string
}

MigrationStatus represents the status of a single migration.

type Migrator

type Migrator interface {
	// Up applies all pending migrations. Returns ErrNoMigrations if there
	// are no migrations to apply.
	Up(ctx context.Context) error

	// UpTo applies migrations up to and including the given version.
	UpTo(ctx context.Context, version uint64) error

	// Down rolls back all applied migrations (in reverse order).
	Down(ctx context.Context) error

	// DownTo rolls back migrations down to (but not including) the given
	// version. Version 0 means rollback all.
	DownTo(ctx context.Context, version uint64) error

	// Steps applies n migrations forward (positive n) or backward (negative n).
	Steps(ctx context.Context, n int) error

	// Version returns the current applied version (0 if none).
	Version(ctx context.Context) (uint64, bool, error)

	// Status returns the status of all migrations.
	Status(ctx context.Context) ([]MigrationStatus, error)

	// Close releases any resources held by the migrator.
	Close() error
}

Migrator executes database migrations. Implementations are responsible for tracking applied versions in a schema_migrations table.

type Source

type Source interface {
	// Migrations returns all migrations sorted by version ascending.
	Migrations() ([]Migration, error)
}

Source provides migration files. Implementations include EmbedSource (for go:embed) and FileSource (for filesystem directories).

type StaticSource

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

StaticSource is a Source backed by a fixed list of migrations. Useful for testing or when migrations are defined programmatically.

func NewStaticSource

func NewStaticSource(migrations ...Migration) *StaticSource

NewStaticSource creates a Source from a list of migrations.

func (*StaticSource) Migrations

func (s *StaticSource) Migrations() ([]Migration, error)

Migrations implements Source.

Directories

Path Synopsis
gormmigrator module

Jump to

Keyboard shortcuts

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