migration

Documentation

Overview

Package migration provides deterministic, module-owned database migration plans with checksum drift detection and dialect-owned execution.

Index

• type Applied
• type Backend
• type Migration
  • func (migration Migration) Checksum() string
  • func (migration Migration) Module() string
  • func (migration Migration) Name() string
  • func (migration Migration) SQL() string
  • func (migration Migration) Version() uint64
• type Observation
• type Observer
• type Plan
  • func NewPlan(specs []Spec) (*Plan, error)
  • func (plan *Plan) Migrations() []Migration
• type Result
• type Runner
  • func NewRunner(backend Backend, observers ...Observer) (*Runner, error)
  • func (runner *Runner) Run(ctx context.Context, plan *Plan) (Result, error)
• type Session
• type Spec

Types

type Applied

type Applied struct {
	Version   uint64
	Module    string
	Name      string
	Checksum  string
	AppliedAt time.Time
}

Applied is one durable migration registry record.

type Backend

type Backend interface {
	RunLocked(context.Context, func(context.Context, Session) error) error
}

Backend owns dialect-specific locking and transaction policy. RunLocked must invoke work exactly once while concurrent migration runners are excluded.

type Migration

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

Migration is one immutable normalized plan entry.

func (Migration) Checksum

func (migration Migration) Checksum() string

Checksum returns the lowercase SHA-256 checksum of normalized SQL.

func (Migration) Module

func (migration Migration) Module() string

Module returns the owning application module.

func (Migration) Name

func (migration Migration) Name() string

Name returns the stable human-readable migration name.

func (Migration) SQL

func (migration Migration) SQL() string

SQL returns normalized executable SQL.

func (Migration) Version

func (migration Migration) Version() uint64

Version returns the application-global migration version.

type Observation

type Observation struct {
	Version  uint64
	Module   string
	Name     string
	Duration time.Duration
	Err      error
}

Observation contains bounded metadata and no SQL text.

type Observer

type Observer func(context.Context, Observation)

Observer receives completed migration attempts synchronously.

type Plan

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

Plan is an immutable migration sequence ordered by global version.

func NewPlan

func NewPlan(specs []Spec) (*Plan, error)

NewPlan validates, normalizes, checksums, and orders module-owned migrations.

func (*Plan) Migrations

func (plan *Plan) Migrations() []Migration

Migrations returns a defensive copy of the deterministic sequence.

type Result

type Result struct {
	Current int
	Applied int
}

Result summarizes one locked migration run.

type Runner

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

Runner reconciles and applies one immutable plan.

func NewRunner

func NewRunner(backend Backend, observers ...Observer) (*Runner, error)

NewRunner constructs an instance-owned migration runner.

func (*Runner) Run

func (runner *Runner) Run(ctx context.Context, plan *Plan) (Result, error)

Run validates the durable registry as an exact plan prefix, then applies pending migrations sequentially under the backend lock.

type Session

type Session interface {
	Applied(context.Context) ([]Applied, error)
	Apply(context.Context, Migration) error
}

Session executes while a Backend holds its migration lock. Apply must atomically execute the SQL and persist its exact metadata.

type Spec

type Spec struct {
	Version uint64
	Module  string
	Name    string
	SQL     string
}

Spec is the inspectable input to NewPlan. Versions are application-global, monotonically increasing identifiers.