migrate

type Applied ¶

type Applied struct {
	Key       Key       `json:"key"`
	Version   Version   `json:"version"`
	Checksum  Checksum  `json:"checksum"`
	Batch     int64     `json:"batch"`
	AppliedAt time.Time `json:"applied_at"`
}

Applied records a completed migration. Nontransactional statements finish before their history entry; their effects are not atomic with history.

type Checksum ¶

type Checksum [32]byte

Checksum is the SHA-256 identity of a complete migration definition.

func ParseChecksum(text string) (Checksum, error)

func (c Checksum) MarshalText() ([]byte, error)

func (c Checksum) String() string

func (c *Checksum) UnmarshalText(text []byte) error

type Definition ¶

type Definition struct {
	Mode     ExecutionMode
	Key      Key
	Version  Version
	SQL      []string
	Down     []string
	Requires []Key
}

Definition is the handwritten or generated source of an immutable migration. SQL entries execute in order using Mode (transactional by default). Requires references declared migrations; New snapshots all slices and computes hashes.

Down optionally reverses the migration for an explicit Postgres.Rollback. It is excluded from the checksum, so adding or correcting Down never drifts applied history, and it must be valid inside one transaction: a nontransactional migration cannot declare Down. Without Down a migration is irreversible and rollback refuses to cross it.

func (d Definition) Clone() Definition

type Entry ¶

type Entry struct {
	Mode       ExecutionMode `json:"mode,omitempty"`
	Key        Key           `json:"key"`
	Version    Version       `json:"version"`
	Checksum   Checksum      `json:"checksum"`
	Requires   []Key         `json:"requires,omitempty"`
	Reversible bool          `json:"reversible,omitempty"`
}

Entry is immutable migration metadata, returned as a caller-owned snapshot. Checksum covers origin, ID, introduced version, ordered SQL and dependencies.

type ExecutionMode ¶

type ExecutionMode string

ExecutionMode selects atomic execution or individually journaled statements. The zero value preserves the historical transactional checksum and behavior.

const (
	Transactional    ExecutionMode = ""
	NonTransactional ExecutionMode = "nontransactional"
)

type ID ¶

type ID string

ID is a stable migration identifier within an origin. Sortable numeric prefixes are conventional, but explicit Requires dependencies take precedence.

type InterruptedMigration ¶

type InterruptedMigration struct {
	Progress Progress
	// contains filtered or unexported fields
}

InterruptedMigration retains the checkpoint and cause of an interrupted nontransactional migration. Inspect database state before reconciling an uncertain statement.

func (*InterruptedMigration) Error() string

func (*InterruptedMigration) Is(target error) bool

func (e *InterruptedMigration) Unwrap() error

type Key ¶

type Key struct {
	Origin Origin `json:"origin"`
	ID     ID     `json:"id"`
}

Key identifies one migration without ambiguous delimiter concatenation.

type Origin ¶

type Origin string

Origin identifies the application, framework, or plugin owning a migration.

type Postgres ¶

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

Postgres is an explicit PostgreSQL migration runner over Foundry's DB. Creating it performs no I/O. Status never creates a history table; Up is the only schema mutation entry point. There is no reset, wipe, or automatic synchronization.

func NewPostgres(db *database.DB, registry *Registry, config PostgresConfig) (*Postgres, error)

func (p *Postgres) Reconcile(ctx context.Context, expected Progress, outcome StatementOutcome) (Progress, error)

func (p *Postgres) Registry() *Registry

func (p *Postgres) Rollback(ctx context.Context, steps int) (result RollbackResult, err error)

func (p *Postgres) RollbackPlan(ctx context.Context, steps int) ([]Applied, error)

func (p *Postgres) Status(ctx context.Context) (Report, error)

func (p *Postgres) Up(ctx context.Context) (result RunResult, err error)

type PostgresConfig ¶

type PostgresConfig struct {
	Schema               string
	Table                string
	LockTimeout          time.Duration
	LockPollInterval     time.Duration
	CleanupTimeout       time.Duration
	MaxHistory           int
	StatementLockTimeout time.Duration
	StatementTimeout     time.Duration
	SearchPath           string
}

PostgresConfig owns a migration history namespace and resource bounds. The schema/table must be simple PostgreSQL identifiers of at most 63 ASCII bytes. All cooperating runners must use the same history schema and table.

LockTimeout bounds acquisition of the runner's advisory lock. Up also sets PostgreSQL's lock_timeout to StatementLockTimeout for its session, so DDL that cannot obtain a table lock fails instead of queueing behind long transactions and blocking application traffic; a transactional migration then rolls back and can be retried. StatementTimeout sets statement_timeout for the session; zero disables it, so long migrations are not canceled by an application pool limit. SearchPath, when set, makes that one schema (then pg_temp) the session search_path, so unqualified migration SQL creates and alters objects in it; empty keeps the connection's own path. All settings are restored before the connection returns to the pool. History and progress tables are always schema-qualified.

func DefaultPostgresConfig() PostgresConfig

func (c PostgresConfig) Validate() error

type Problem ¶

type Problem struct {
	Code       ProblemCode `json:"code"`
	Key        Key         `json:"key"`
	Dependency *Key        `json:"dependency,omitempty"`
}

Problem identifies history drift without including migration SQL or values.

type ProblemCode ¶

type ProblemCode string

ProblemCode names a specific history conflict that prevents an up operation.

const (
	ReconciliationRequired ProblemCode = "reconciliation_required"
	ProgressMismatch       ProblemCode = "progress_mismatch"
	DefinitionChanged      ProblemCode = "definition_changed"
	DefinitionMissing      ProblemCode = "definition_missing"
	DependencyNotApplied   ProblemCode = "dependency_not_applied"
)

type Progress ¶

type Progress struct {
	Key       Key       `json:"key"`
	Version   Version   `json:"version"`
	Checksum  Checksum  `json:"checksum"`
	Batch     int64     `json:"batch"`
	Confirmed int       `json:"confirmed_statements"`
	State     StepState `json:"state"`
	Revision  int64     `json:"revision"`
	UpdatedAt time.Time `json:"updated_at"`
}

Progress is a durable nontransactional checkpoint. Confirmed counts statements with a successfully recorded result. InFlight/Uncertain never authorize retry. Revision protects reconciliation against a stale inspection snapshot.

type Registry ¶

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

Registry owns validated definitions in deterministic dependency order. It is safe to share across goroutines; returned metadata and plans are copies.

func New(definitions ...Definition) (*Registry, error)

func (r *Registry) Definition(key Key) (Definition, bool)

func (r *Registry) Entries() []Entry

func (r *Registry) Inspect(history []Applied) (Report, error)

func (r *Registry) Pending(history []Applied) ([]Entry, error)

type Report ¶

type Report struct {
	Statuses  []Status  `json:"migrations"`
	Problems  []Problem `json:"problems,omitempty"`
	LastBatch int64     `json:"last_batch"`
}

Report is a caller-owned status snapshot. Problems may be shown by read-only status commands; Check must succeed before applying any pending definitions.

func (r Report) Check() error

type RollbackResult ¶

type RollbackResult struct {
	RolledBack  []Applied `json:"rolled_back"`
	Interrupted *Key      `json:"interrupted,omitempty"`
}

RollbackResult lists migrations whose reversal committed, newest first. Interrupted names the attempted reversal lacking a successful confirmation; it may have committed when the returned database outcome is Unknown.

type RunResult ¶

type RunResult struct {
	Batch       int64     `json:"batch"`
	Applied     []Applied `json:"applied"`
	Interrupted *Key      `json:"interrupted,omitempty"`
}

RunResult preserves migrations known to have committed before a later failure. Interrupted names the attempted migration lacking a successful confirmation; it may have committed when the returned database outcome is Unknown.

type State ¶

type State string

State is a migration's status relative to the currently registered definitions.

const (
	Pending    State = "pending"
	Incomplete State = "incomplete"
	Complete   State = "applied"
	Changed    State = "changed"
	Missing    State = "missing_definition"
)

type StatementOutcome ¶

type StatementOutcome string

StatementOutcome is an operator's explicit attestation after inspecting actual database state. Foundry does not infer whether an interrupted statement ran.

const (
	StatementApplied    StatementOutcome = "applied"
	StatementNotApplied StatementOutcome = "not_applied"
)

type Status ¶

type Status struct {
	Progress   *Progress `json:"progress,omitempty"`
	Key        Key       `json:"key"`
	State      State     `json:"state"`
	Definition *Entry    `json:"definition,omitempty"`
	Applied    *Applied  `json:"applied,omitempty"`
}

Status contains current metadata and, when present, its recorded history.

type StepState ¶

type StepState string

StepState identifies a nontransactional migration statement's durable checkpoint state.

const (
	StepReady     StepState = "ready"
	StepInFlight  StepState = "in_flight"
	StepUncertain StepState = "uncertain"
)

type Version ¶

type Version string

Version records the release that introduced a migration, not the currently installed framework/plugin version. Changing it changes historical identity.