Documentation
¶
Overview ¶
Package migration provides a migration management system with schema providers, distributed locking, and a migration runner for applying database schema changes.
Index ¶
- func DiffSchemas(oldDDL, newDDL string) (upSQL string, downSQL string)
- type AppliedMigration
- type ColumnDef
- type DistributedLock
- type MigrationRunner
- func (r *MigrationRunner) Pending(ctx context.Context, providers ...SchemaProvider) ([]PendingMigration, error)
- func (r *MigrationRunner) Run(ctx context.Context, db *sql.DB, providers ...SchemaProvider) error
- func (r *MigrationRunner) Status(ctx context.Context, providers ...SchemaProvider) (map[string][]AppliedMigration, error)
- type MigrationStore
- type PendingMigration
- type PostgresLock
- type SQLiteLock
- type SQLiteMigrationStore
- type SchemaDiff
- type SchemaProvider
- type TableDef
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DiffSchemas ¶
DiffSchemas compares an old and new schema DDL and generates ALTER TABLE statements to migrate from old to new. It handles added columns, dropped columns, and added/dropped indexes. It does NOT handle column type changes or renames (those require manual migration).
Types ¶
type AppliedMigration ¶
AppliedMigration records a migration that has already been applied.
type ColumnDef ¶
type ColumnDef struct {
Name string
Definition string // full column definition (type + constraints)
}
ColumnDef represents a column within a CREATE TABLE statement.
type DistributedLock ¶
type DistributedLock interface {
// Acquire obtains the lock for the given key. The returned release function
// must be called to release the lock. The lock is held until release is called
// or the context is cancelled.
Acquire(ctx context.Context, key string) (release func(), err error)
}
DistributedLock provides mutual exclusion for migration operations across multiple processes or nodes.
type MigrationRunner ¶
type MigrationRunner struct {
// contains filtered or unexported fields
}
MigrationRunner coordinates schema migrations across multiple providers.
func NewMigrationRunner ¶
func NewMigrationRunner(store MigrationStore, locker DistributedLock, logger *slog.Logger) *MigrationRunner
NewMigrationRunner creates a new MigrationRunner.
func (*MigrationRunner) Pending ¶
func (r *MigrationRunner) Pending(ctx context.Context, providers ...SchemaProvider) ([]PendingMigration, error)
Pending returns all pending migrations for the given providers without applying them.
func (*MigrationRunner) Run ¶
func (r *MigrationRunner) Run(ctx context.Context, db *sql.DB, providers ...SchemaProvider) error
Run applies all pending migrations for the given providers. It acquires a distributed lock, queries the store for applied versions, compares against providers' current versions, runs pending diffs in order, and records each applied migration.
func (*MigrationRunner) Status ¶
func (r *MigrationRunner) Status(ctx context.Context, providers ...SchemaProvider) (map[string][]AppliedMigration, error)
Status returns the applied migrations for each provider.
type MigrationStore ¶
type MigrationStore interface {
// Applied returns all applied migrations for the given schema, ordered by version.
Applied(ctx context.Context, schemaName string) ([]AppliedMigration, error)
// Record stores an applied migration record.
Record(ctx context.Context, schemaName string, version int, checksum string) error
}
MigrationStore persists records of applied migrations.
type PendingMigration ¶
PendingMigration describes a migration that has not yet been applied.
type PostgresLock ¶
type PostgresLock struct {
// contains filtered or unexported fields
}
PostgresLock implements DistributedLock using PostgreSQL advisory locks.
func NewPostgresLock ¶
func NewPostgresLock(db *sql.DB) *PostgresLock
NewPostgresLock creates a new PostgresLock.
type SQLiteLock ¶
type SQLiteLock struct {
// contains filtered or unexported fields
}
SQLiteLock implements DistributedLock using a process-local mutex. SQLite is inherently single-writer, so a mutex is sufficient for ensuring only one migration runs at a time within a process. For cross-process safety, SQLite's built-in file locking provides protection.
func NewSQLiteLock ¶
func NewSQLiteLock(_ *sql.DB) *SQLiteLock
NewSQLiteLock creates a new SQLiteLock. The db parameter is accepted for interface consistency but the lock uses an in-process mutex since SQLite does not support advisory locks.
type SQLiteMigrationStore ¶
type SQLiteMigrationStore struct {
// contains filtered or unexported fields
}
SQLiteMigrationStore implements MigrationStore using SQLite.
func NewSQLiteMigrationStore ¶
func NewSQLiteMigrationStore(db *sql.DB) (*SQLiteMigrationStore, error)
NewSQLiteMigrationStore creates a new SQLiteMigrationStore and ensures the _migrations table exists.
func (*SQLiteMigrationStore) Applied ¶
func (s *SQLiteMigrationStore) Applied(ctx context.Context, schemaName string) ([]AppliedMigration, error)
Applied returns all applied migrations for the given schema, ordered by version.
type SchemaDiff ¶
SchemaDiff represents a single migration step between two schema versions.
type SchemaProvider ¶
type SchemaProvider interface {
// SchemaName returns a unique identifier for this schema (e.g., "workflow_executions").
SchemaName() string
// SchemaVersion returns the current version of the schema.
SchemaVersion() int
// SchemaSQL returns the full DDL for the current schema version.
SchemaSQL() string
// SchemaDiffs returns ordered diffs for migrating between versions.
SchemaDiffs() []SchemaDiff
}
SchemaProvider defines the interface for components that own database schemas. Each provider declares its schema name, current version, full DDL, and ordered diffs.