migratekit

type Adopted struct {
	// Tool is the migration tool whose history was adopted (compat.ToolGoose,
	// or compat.ToolForge for a squashed forge history).
	Tool string
	// Version is the baseline's version, now the schema's.
	Version uint
	// Name is the baseline's filename.
	Name string
	// Versions is how many of the tool's versions were verified applied.
	Versions int
}

type AdoptionError struct {
	// Tool is the tool that migrated the database (compat.ToolGoose).
	Tool string
	// Table is the tool's version table that was read.
	Table string
	// Baseline is the migration that declares the adoption.
	Baseline string
	// Declared is how many versions the baseline lists.
	Declared int
	// Missing is every listed version the database never applied: it is
	// BEHIND the baseline.
	Missing []int64
	// Unexpected is every version the database applied that the baseline
	// does not list.
	Unexpected []int64
}

type Ahead struct {
	// Version is the schema version recorded in the database.
	Version uint
	// Latest is the newest migration version this binary embeds.
	Latest uint
	// Versions is every version the database has that this binary does not
	// embed, in order. Each was declared backward-compatible.
	Versions []uint
}

type AwaitOptions struct {
	// Timeout bounds the wait; zero is DefaultAwaitTimeout. A waiter that
	// never sees its schema fails loudly instead of hanging in boot.
	Timeout time.Duration
	// Poll is how often the version is re-read; zero is one second.
	Poll time.Duration
}

type DashboardPrivilegeError struct {
	Role       string
	Violations []dbgrants.Violation
}

type DashboardRole struct {
	// Created is true when the role did not exist and this run created it,
	// NOLOGIN.
	Created bool
	// Missing is true when the role does not exist and the migrating role may
	// not create it. No migration this run applied names it.
	Missing bool
	// CanLogin is true when dashboards are on: the deploy made the role
	// login-capable. Off, its grants stay in place and nobody can use them.
	CanLogin bool
	// SecurityDefiner lists the SECURITY DEFINER functions the role can
	// execute (dbgrants.SecurityDefinerExposure), whether or not it can log in
	// now: each runs as its owner, so it can read past the column grants and
	// write. A warning for the caller to log, never a failure.
	SecurityDefiner []string
}

type DashboardRoleMissingError struct {
	Role string
	// Migrations are the pending files that name the role.
	Migrations []string
}

type ForeignHistoryError struct {
	// Version is the schema version recorded in the database.
	Version uint
	// First and Latest name the migrations this binary embeds.
	First  string
	Latest uint
	// Embedded is how many migrations this binary embeds.
	Embedded int
}

type Grants struct {
	// Applied is true when the script ran.
	Applied bool
	// RoleMissing is true when the database has no [dbgrants.RoleName], so
	// the script was not run. That is the normal state of a database nobody
	// provisioned the role for, not a fault.
	RoleMissing bool
	// SecurityDefiner lists the SECURITY DEFINER functions the role can
	// execute (dbgrants.SecurityDefinerExposure): a way around its column
	// grants. A warning for the caller to log, never a failure.
	SecurityDefiner []string
}

type Limits struct {
	// LockTimeout is lock_timeout for each attempt at a migration. Zero is
	// DefaultLockTimeout; Off disables it.
	LockTimeout time.Duration
	// StatementTimeout is statement_timeout. Zero is
	// DefaultStatementTimeout; Off disables it.
	StatementTimeout time.Duration
	// LockAttempts is how many times a migration whose lock timed out is
	// tried, the first included. Zero is DefaultLockAttempts; 1 never
	// retries.
	LockAttempts int
	// RetryBackoff is the wait before the second attempt, doubling after
	// each (with jitter, so replicas do not retry in step). Zero is
	// DefaultRetryBackoff.
	RetryBackoff time.Duration
}

type LockTimeoutError struct {
	Version uint
	Name    string
	// Grants is true when the statement that timed out was a grants script
	// (grants.go) and not a migration. The run's migrations are committed by
	// then, and the next run applies the grants again.
	Grants bool
	// PartlyApplied is true when the migration could not be proven
	// all-or-nothing (it controls its own transaction, runs statement by
	// statement, or builds something concurrently the migrator cannot clean
	// up). It was not retried, and part of it may be committed: the schema is
	// left dirty at Version for a human to inspect.
	PartlyApplied bool
	Attempts      int
	Timeout       time.Duration
	// Leftover names the INVALID indexes a CONCURRENTLY attempt left behind
	// and that could not be dropped while the blocker still ran (dropping
	// one waits for the same sessions the build did). They do no harm beyond
	// their write cost, and the next run drops them before it builds again.
	Leftover []string
	// Err is the last timeout, as postgres reported it. It is the bare
	// postgres error, never a golang-migrate database.Error: the driver
	// wrapper above this one would rewrap that and lose this type.
	Err error
}

type MigrationMismatch struct {
	Version uint
	// Applied is the descriptor recorded when the version was applied.
	Applied string
	// Embedded is the descriptor this binary carries for the same version.
	Embedded string
}

type MigrationMismatchError struct {
	Mismatches []MigrationMismatch
}

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

type MissingMigration struct {
	Version uint
	// Name is the migration's filename, so the fix names a real file.
	Name string
}

type MissingMigrationError struct {
	Missing []MissingMigration
	// Version is the schema version the database has reached.
	Version uint
}

type Options struct {
	// FS holds the migration files — typically the project's embedded
	// `forgedb.MigrationsFS`. A nil FS is a hard error: it means the
	// binary embeds no migrations, and a migrate command that exits 0
	// against an unmigrated database is precisely the silence this
	// package exists to remove.
	FS fs.FS
	// Dir is the directory INSIDE FS holding the .sql files — "migrations"
	// for the conventional `//go:embed migrations/*.sql` layout. Empty
	// means the FS root.
	Dir string
	// DSN is the database URL. Passed through NormalizeDSN, so callers
	// hand over the DATABASE_URL they already have.
	DSN string
	// Run says how the run guards the locks and the time its migrations take
	// (locktimeout.go). The zero value is the defaults.
	Run RunOptions
}

type Result struct {
	// Changed reports whether THIS call applied anything.
	//
	// It is taken from the return of the migrate call itself, not from a
	// before/after version comparison, because the advisory lock is taken
	// INSIDE that call: when several replicas race the same release, one
	// applies and the others are released to find nothing to do. Only the
	// call's own return distinguishes "I applied it" from "someone else
	// did"; a version diff would credit every replica.
	Changed bool
	// Before is the state as of entry, After the state on exit. Both are
	// reported so a caller can log a "N -> M" line without a second round
	// trip, and so "no change" still carries the version it is at.
	Before State
	After  State
	// Ahead is set when the schema was AHEAD of this binary — the previous
	// release meeting the next one's schema mid-deploy — and every version it
	// does not embed was declared
	// backward-compatible. Nothing was applied (Changed is false); the
	// binary's code can run. A caller should say so loudly: it is the fact
	// an operator mid-deploy most needs confirmed. A schema ahead that is
	// NOT proven compatible is a *SchemaAheadError instead, never this.
	Ahead *Ahead
	// Adopted is set when THIS call adopted a database another tool
	// migrated: the baseline that declares that history was recorded as
	// applied without running its SQL (see adopt.go). Before is then the
	// state after adoption, so Changed and Before → After describe only the
	// migrations that ran on top of it. A caller should say so: it is the
	// one run in a database's life where the version moved and no SQL did.
	Adopted *Adopted
	// NothingEmbedded is set by Apply when the binary embeds no migrations
	// (a nil FS, or a directory with no .sql in it): a project that has not
	// written its first one. Nothing was read or applied. Open refuses that
	// instead; see AutoMigrate.
	NothingEmbedded bool
	// Grants is what the run did with the read-only role's grants (grants.go):
	// nil when the binary embeds none, or when the schema was ahead of it.
	Grants *Grants
	// Dashboard is what the run found of the dashboard role (dashboard.go):
	// nil when the schema was ahead of the binary.
	Dashboard *DashboardRole
}

type RunOptions struct {
	Limits Limits
	// Logger receives one WARN line per attempt whose lock timed out. Nil is
	// slog.Default().
	Logger *slog.Logger
}

type SchemaAheadError struct {
	// Version is the schema version recorded in the database.
	Version uint
	// Latest is the newest migration version this binary embeds.
	Latest uint
	// Incompatible is every version this binary does not embed that is not
	// recorded as backward-compatible — either declared otherwise, or
	// applied by a migrator that recorded nothing.
	Incompatible []uint
	// Unrecorded is true when the database holds no compatibility record
	// for the schema's own version: it was migrated by a binary that
	// predates the record, so nothing about the extra versions is known.
	Unrecorded bool
}

type SchemaPendingError struct {
	// Want is the newest migration version the binary embeds.
	Want uint
	// State is what the schema reported last.
	State State
	// Waited is how long AwaitSchema waited.
	Waited time.Duration
}

type State struct {
	// Version is the migration version recorded in the schema. Only
	// meaningful when Applied is true.
	Version uint
	// Dirty means a previous migration failed PARTWAY: the version was
	// recorded but its SQL did not finish. migratekit reports it and
	// stops there — whether that aborts the run or is force-cleared is
	// the caller's policy.
	Dirty bool
	// Applied reports whether any migration has ever been applied. False
	// is a normal, healthy state for a fresh database, which is why it is
	// a field rather than an error: golang-migrate signals it as
	// ErrNilVersion, and a caller that forgot to special-case that
	// sentinel would treat an empty database as broken.
	Applied bool
}