migration

package
v0.0.0-...-9dee9fb Latest Latest
Warning

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

Go to latest
Published: Feb 17, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package migration provides a migration management system with schema providers, distributed locking, and a migration runner for applying database schema changes.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DiffSchemas

func DiffSchemas(oldDDL, newDDL string) (upSQL string, downSQL string)

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

type AppliedMigration struct {
	SchemaName string
	Version    int
	Checksum   string
	AppliedAt  time.Time
}

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

type PendingMigration struct {
	SchemaName  string
	FromVersion int
	ToVersion   int
	UpSQL       string
}

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.

func (*PostgresLock) Acquire

func (l *PostgresLock) Acquire(ctx context.Context, key string) (func(), error)

Acquire obtains a PostgreSQL advisory lock. The lock key is hashed to an int64 from the string key. The returned release function unlocks the advisory lock.

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.

func (*SQLiteLock) Acquire

func (l *SQLiteLock) Acquire(ctx context.Context, _ string) (func(), error)

Acquire obtains the mutex lock. Returns an error if the context is already cancelled.

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.

func (*SQLiteMigrationStore) Record

func (s *SQLiteMigrationStore) Record(ctx context.Context, schemaName string, version int, checksum string) error

Record stores an applied migration record.

type SchemaDiff

type SchemaDiff struct {
	FromVersion int
	ToVersion   int
	UpSQL       string
	DownSQL     string
}

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.

type TableDef

type TableDef struct {
	Name    string
	Columns []ColumnDef
	Indexes []string // raw CREATE INDEX statements
}

TableDef represents a parsed CREATE TABLE statement.

Jump to

Keyboard shortcuts

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