migration

Documentation

Overview

Package migration implements the core migration engine: file discovery, schema_history bookkeeping, and up/down/rollback/fresh execution. This is the riskiest, most stateful component in drp and is tested hardest.

Index

• Variables
• func FormatStatus(entries []StatusEntry) string
• type Engine
  • func NewEngine(conn *drpdb.Connection, migrationsDir string) *Engine
  • func (e *Engine) Down() error
  • func (e *Engine) Fresh(dryRun bool) error
  • func (e *Engine) Rollback() error
  • func (e *Engine) Status() ([]StatusEntry, error)
  • func (e *Engine) Up() error
• type File
  • func DiscoverFiles(dir string) ([]File, error)
  • func NewFile(dir, name string) (File, error)
  • func NewFileForTable(dir, name, tableName string) (File, error)
  • func (f File) Identifier() string
• type StatusEntry

Variables

var (
	ErrNothingToMigrate  = fmt.Errorf("migration: nothing to migrate — all migrations are up to date")
	ErrNothingToRollback = fmt.Errorf("migration: nothing to roll back — no migrations have been applied")
)

Sentinel errors returned by Engine methods so callers can inspect them.

Functions

func FormatStatus

func FormatStatus(entries []StatusEntry) string

FormatStatus renders a slice of StatusEntry into an aligned, human-readable table suitable for CLI output.

Example output:

[✓] 20240115120000_create_users_table   (batch 1)
[ ] 20240116080000_add_email_index

Types

type Engine

type Engine struct {
	DB               *sql.DB
	DriverName       string
	MigrationsDir    string
	TransactionalDDL bool // true for Postgres, false for MySQL
}

Engine runs migrations against a database, recording state in schema_history. It is driver-aware for transactional DDL support.

func NewEngine

func NewEngine(conn *drpdb.Connection, migrationsDir string) *Engine

NewEngine constructs a migration Engine from a db.Connection.

func (*Engine) Down

func (e *Engine) Down() error

Down reverts only the single most-recently applied migration.

func (*Engine) Fresh

func (e *Engine) Fresh(dryRun bool) error

Fresh drops all tables (via schema_history-tracked DDL) and re-runs all migrations from scratch. When dryRun is true, prints the plan without making any changes.

func (*Engine) Rollback

func (e *Engine) Rollback() error

Rollback reverts the most recent batch of applied migrations, executing each migration's down file in reverse-application order.

func (*Engine) Status

func (e *Engine) Status() ([]StatusEntry, error)

Status returns a list of all known migrations with their applied/pending state.

func (*Engine) Up

func (e *Engine) Up() error

Up runs all pending migrations in timestamp order as a single new batch. On Postgres, each file executes inside a transaction — failure rolls back cleanly. On MySQL, DDL cannot be rolled back; a clear error is returned with a warning that partial changes may have been applied.

type File

type File struct {
	Timestamp int64

	Name     string // e.g. "create_users_table"
	UpPath   string // absolute path to the .up.sql file
	DownPath string // absolute path to the .down.sql file (may be empty warning)
}

File represents a discovered migration on disk.

func DiscoverFiles

func DiscoverFiles(dir string) ([]File, error)

DiscoverFiles scans dir and returns all migration File entries sorted by timestamp ascending. Returns an error if an up file exists without a matching down file or vice versa.

func NewFile

func NewFile(dir, name string) (File, error)

NewFile creates a new timestamped up/down migration file pair in dir. Returns an error if a migration with the same timestamp-and-name already exists (collision guard — callers should not generate two in the same second).

func NewFileForTable

func NewFileForTable(dir, name, tableName string) (File, error)

NewFileForTable creates a new migration pair with starter table SQL. If tableName is empty, the table name is inferred from common migration names.

func (File) Identifier

func (f File) Identifier() string

Identifier returns the canonical migration ID stored in schema_history, e.g. "1719929853123456_create_users_table".

type StatusEntry

type StatusEntry struct {
	Migration string
	Applied   bool
	Batch     int
}

StatusEntry describes one migration's applied/pending state.