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 ¶
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.
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.