schemadiff

type AddCheck ¶

type AddCheck struct {
	Table string
	Check *Check
}

func (AddCheck) Kind() OpKind

func (AddCheck) RequiresBackfill() bool

func (AddCheck) Reversible() bool

func (AddCheck) Risk() RiskClass

func (o AddCheck) String() string

type AddColumn ¶

type AddColumn struct {
	Table  string
	Column *Column
}

func (AddColumn) Kind() OpKind

func (o AddColumn) RequiresBackfill() bool

func (o AddColumn) Reversible() bool

func (o AddColumn) Risk() RiskClass

func (o AddColumn) String() string

type AddForeignKey ¶

type AddForeignKey struct {
	Table string
	FK    *ForeignKey
}

func (AddForeignKey) Kind() OpKind

func (AddForeignKey) RequiresBackfill() bool

func (AddForeignKey) Reversible() bool

func (AddForeignKey) Risk() RiskClass

func (o AddForeignKey) String() string

type AddIndex ¶

type AddIndex struct {
	Table string
	Index *Index
}

func (AddIndex) Kind() OpKind

func (AddIndex) RequiresBackfill() bool

func (AddIndex) Reversible() bool

func (AddIndex) Risk() RiskClass

func (o AddIndex) String() string

type AddPrimaryKey ¶

type AddPrimaryKey struct {
	Table string
	PK    *PrimaryKey
}

func (AddPrimaryKey) Kind() OpKind

func (AddPrimaryKey) RequiresBackfill() bool

func (AddPrimaryKey) Reversible() bool

func (AddPrimaryKey) Risk() RiskClass

func (o AddPrimaryKey) String() string

type AddUnique ¶

type AddUnique struct {
	Table  string
	Unique *UniqueConstraint
}

func (AddUnique) Kind() OpKind

func (AddUnique) RequiresBackfill() bool

func (AddUnique) Reversible() bool

func (AddUnique) Risk() RiskClass

func (o AddUnique) String() string

type AlterColumn ¶

type AlterColumn struct {
	Table string
	From  *Column
	To    *Column
}

AlterColumn changes a column in place. From is the current column, To the desired one; the specific sub-changes (type / nullability / default) are derivable.

func (o AlterColumn) DefaultChanged() bool

func (AlterColumn) Kind() OpKind

func (o AlterColumn) NullabilityAdded() bool

func (o AlterColumn) NullabilityDropped() bool

func (o AlterColumn) RequiresBackfill() bool

func (o AlterColumn) Reversible() bool

func (o AlterColumn) Risk() RiskClass

func (o AlterColumn) String() string

func (o AlterColumn) TypeChanged() bool

type BaseType ¶

type BaseType int

BaseType is the canonical family of a column type (the alias map collapses every Postgres spelling — int4/int/integer, varchar/character varying, etc. — onto one of these).

const (
	BaseUnknown BaseType = iota
	BaseSmallint
	BaseInteger
	BaseBigint
	BaseNumeric
	BaseReal   // float4
	BaseDouble // float8
	BaseBool
	BaseText
	BaseVarchar
	BaseChar
	BaseUUID
	BaseTimestamptz
	BaseTimestamp
	BaseDate
	BaseTime
	BaseTimetz
	BaseJSON
	BaseJSONB
	BaseBytea
	BaseInterval
	BaseInet
	BaseUserDefined // enum / domain / anything not in the alias map (see Type.UserName)
)

func (b BaseType) String() string

type Check ¶

type Check struct {
	Symbol     string
	Expression string
}

Check is a CHECK constraint. Expression is the predicate text from pg_get_constraintdef (minus the leading "CHECK ").

type Column ¶

type Column struct {
	Name string

	// RenamedFrom is the EXPLICIT previous column name when the desired schema
	// declares a rename (never a heuristic). Empty for an introspected column.
	RenamedFrom string

	Type    Type
	NotNull bool

	// Default is the normalized DEFAULT expression, or nil when the column has
	// none. A serial/identity column carries its generation in Identity, not here
	// (its nextval default is implied), so Default is nil for those.
	Default *Expr

	// Identity is set for an auto-generated value: legacy serial, or an explicit
	// GENERATED { ALWAYS | BY DEFAULT } AS IDENTITY column. nil for a plain column.
	Identity *Identity
}

Column is one column. Type is the canonical struct (never a string), so type comparison is exact and spelling-independent.

type Concern ¶

type Concern struct {
	Op      Operation
	Risk    RiskClass
	Message string
}

Concern flags an operation in a plan that a human/gate should review before applying: data loss, a backfill requirement, or a data rewrite.

func Validate(plan *Plan) []Concern

type CreateTable ¶

type CreateTable struct{ Table *Table }

func (CreateTable) Kind() OpKind

func (CreateTable) RequiresBackfill() bool

func (CreateTable) Reversible() bool

func (CreateTable) Risk() RiskClass

func (o CreateTable) String() string

type DropCheck ¶

type DropCheck struct {
	Table string
	Check *Check
}

func (DropCheck) Kind() OpKind

func (DropCheck) RequiresBackfill() bool

func (DropCheck) Reversible() bool

func (DropCheck) Risk() RiskClass

func (o DropCheck) String() string

type DropColumn ¶

type DropColumn struct {
	Table  string
	Column *Column
}

func (DropColumn) Kind() OpKind

func (DropColumn) RequiresBackfill() bool

func (DropColumn) Reversible() bool

func (DropColumn) Risk() RiskClass

func (o DropColumn) String() string

type DropForeignKey ¶

type DropForeignKey struct {
	Table string
	FK    *ForeignKey
}

func (DropForeignKey) Kind() OpKind

func (DropForeignKey) RequiresBackfill() bool

func (DropForeignKey) Reversible() bool

func (DropForeignKey) Risk() RiskClass

func (o DropForeignKey) String() string

type DropIndex ¶

type DropIndex struct {
	Table string
	Index *Index
}

func (DropIndex) Kind() OpKind

func (DropIndex) RequiresBackfill() bool

func (DropIndex) Reversible() bool

func (DropIndex) Risk() RiskClass

func (o DropIndex) String() string

type DropPrimaryKey ¶

type DropPrimaryKey struct {
	Table string
	PK    *PrimaryKey
}

func (DropPrimaryKey) Kind() OpKind

func (DropPrimaryKey) RequiresBackfill() bool

func (DropPrimaryKey) Reversible() bool

func (DropPrimaryKey) Risk() RiskClass

func (o DropPrimaryKey) String() string

type DropTable ¶

type DropTable struct{ Table *Table }

func (DropTable) Kind() OpKind

func (DropTable) RequiresBackfill() bool

func (DropTable) Reversible() bool

func (DropTable) Risk() RiskClass

func (o DropTable) String() string

type DropUnique ¶

type DropUnique struct {
	Table  string
	Unique *UniqueConstraint
}

func (DropUnique) Kind() OpKind

func (DropUnique) RequiresBackfill() bool

func (DropUnique) Reversible() bool

func (DropUnique) Risk() RiskClass

func (o DropUnique) String() string

type EnumType ¶

type EnumType struct {
	Name   string
	Values []string
}

EnumType is a Postgres enum type with its labels in sort order. Appximo' own converger does not create enums (enum fields are TEXT + app-layer validation), but the model captures them so an introspected schema that has them is faithful.

type Executor ¶

type Executor struct {
	Pool   *pgxpool.Pool
	Schema string // tenant schema name (the migration's search_path)

	LockTimeout time.Duration // per-statement lock wait before failing fast (default 5s)
	MaxRetries  int           // retries after a lock-timeout failure (default 5)
	BackoffBase time.Duration // first retry backoff, doubling each attempt (default 50ms)

	// OnRetry, if set, is called before each retry with the attempt number (1-based)
	// and the lock-timeout error that triggered it (used by tests/observability).
	OnRetry func(attempt int, err error)
}

Executor applies a Plan to one tenant schema with production-safety guarantees. The zero value is unusable; set Pool and Schema. The timing knobs default when zero.

func (e *Executor) Apply(ctx context.Context, plan *Plan) error

func (e *Executor) Exec(ctx context.Context, sql string) error

func (e *Executor) ExecBatch(ctx context.Context, sqls ...string) error

type Expr ¶

type Expr struct {
	Raw string
}

Expr is a (default / check) expression captured verbatim from pg_get_expr. The text Postgres returns is already canonical and deterministic; deeper semantic normalization (e.g. stripping redundant `::type` casts so a desired default matches a real one) is a diff-session concern, intentionally not done here.

type ForeignKey ¶

type ForeignKey struct {
	Symbol     string
	Columns    []string
	RefTable   string
	RefColumns []string
	OnDelete   RefAction
	OnUpdate   RefAction
}

ForeignKey is one foreign-key constraint, including its referential actions — which the current converger never emits (docs/MIGRATION_DIAG.md §2). Columns and RefColumns are ordered and may be composite.

type Identity ¶

type Identity struct {
	// Generated is one of:
	//   "serial"     — legacy serial / bigserial (integer + an owned sequence
	//                  default). The implied nextval default is NOT stored on the
	//                  column (it is fully captured by this field).
	//   "always"     — GENERATED ALWAYS AS IDENTITY
	//   "by_default" — GENERATED BY DEFAULT AS IDENTITY
	Generated string
}

Identity describes how a column's value is auto-generated.

type Index ¶

type Index struct {
	Name      string
	Columns   []string
	Unique    bool
	Method    string // access method: btree, gin, …
	Predicate string

	// Opclass is the operator class applied to every column when the index is
	// CREATED (e.g. "jsonb_path_ops" on a GIN index). It is DELIBERATELY not part
	// of indexKey: the introspector reads an index's key columns from
	// pg_index.indkey, which carries no opclass, so an opclass can never be read
	// back. Excluding it from the diff key is what keeps a declared opclass from
	// churning (drop+recreate) on every migration. Rendered, never compared.
	Opclass string
}

Index is a STANDALONE index — one NOT backing a primary-key or unique constraint (those live in PK / Uniques). Columns are in index order; an expression key is captured as "(expression)". Predicate is the partial-index WHERE text, empty for a total index.

type OpKind ¶

type OpKind int

OpKind enumerates the operation kinds (useful for switch-free grouping/tests).

const (
	OpCreateTable OpKind = iota
	OpDropTable
	OpRenameTable
	OpAddColumn
	OpDropColumn
	OpAlterColumn
	OpRenameColumn
	OpAddPrimaryKey
	OpDropPrimaryKey
	OpAddForeignKey
	OpDropForeignKey
	OpAddUnique
	OpDropUnique
	OpAddCheck
	OpDropCheck
	OpAddIndex
	OpDropIndex
)

type Operation ¶

type Operation interface {
	Kind() OpKind
	Risk() RiskClass
	// Reversible reports whether rolling the operation back does not, by itself,
	// lose pre-existing data (adding a column is reversible — dropping it only
	// loses data that did not exist before; dropping a column is not).
	Reversible() bool
	// RequiresBackfill reports whether the operation needs a data backfill (or a
	// table rewrite) to be safe over a non-empty table.
	RequiresBackfill() bool
	String() string
}

Operation is one typed entry in a migration Plan.

type Plan ¶

type Plan struct {
	Ops []Operation
}

Plan is the ordered list of operations that turn the current schema into the desired one. Operations are emitted in a coarse, dependency-respecting PHASE order (renames → drops → creates → adds, FKs last) that is applicable for the common acyclic case; the FINE topological order (inter-table dependency sort + FK cycle breaking) is a later session that re-orders this same op list.

func Diff(desired, current *Schema) (*Plan, error)

func OrderPlan(p *Plan) (*Plan, error)

func (p *Plan) Empty() bool

func (p *Plan) String() string

type PrimaryKey ¶

type PrimaryKey struct {
	Name    string
	Columns []string // in key order
}

PrimaryKey is the table's primary key (always exactly one, or nil).

type Querier ¶

type Querier interface {
	Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error)
}

Querier is the minimal read surface Introspect needs. *pgxpool.Pool, *pgxpool.Conn and pgx.Tx all satisfy it. Pass a transaction (REPEATABLE READ) when a snapshot consistent across the four catalog queries matters; a pool is fine for a quiescent schema.

type RefAction ¶

type RefAction int

RefAction is a foreign-key referential action (ON DELETE / ON UPDATE).

const (
	NoAction   RefAction = iota // 'a' — Postgres default
	Restrict                    // 'r'
	Cascade                     // 'c'
	SetNull                     // 'n'
	SetDefault                  // 'd'
)

func (a RefAction) String() string

type RenameColumn ¶

type RenameColumn struct {
	Table    string
	From, To string
}

RenameColumn preserves data (ALTER … RENAME COLUMN). Table is the CURRENT (post table-rename) table name. This is the fix for the diagnostic's worst bug.

func (RenameColumn) Kind() OpKind

func (RenameColumn) RequiresBackfill() bool

func (RenameColumn) Reversible() bool

func (RenameColumn) Risk() RiskClass

func (o RenameColumn) String() string

type RenameTable ¶

type RenameTable struct{ From, To string }

RenameTable preserves data (the whole point — the converger's drop+add loses it).

func (RenameTable) Kind() OpKind

func (RenameTable) RequiresBackfill() bool

func (RenameTable) Reversible() bool

func (RenameTable) Risk() RiskClass

func (o RenameTable) String() string

type RiskClass ¶

type RiskClass int

RiskClass is how dangerous an operation is to apply over live data. It is a coarse, conservative classification — the detailed risk/backfill-strategy engine is a later session; these values exist so a Plan is introspectable now.

const (
	// RiskSafe — additive / non-destructive, no table rewrite, no data loss
	// (create table, add nullable column, add/drop index, drop a constraint).
	RiskSafe RiskClass = iota
	// RiskBackfill — needs existing data to already satisfy it (or a backfill) to
	// apply cleanly: add NOT NULL without default, add PK/unique/check on data.
	RiskBackfill
	// RiskDestructive — loses data (drop table, drop column).
	RiskDestructive
	// RiskTransformational — rewrites the data representation (column type change).
	RiskTransformational
)

func (r RiskClass) String() string

type Schema ¶

type Schema struct {
	Name   string
	Tables map[string]*Table    // by table name
	Enums  map[string]*EnumType // by enum type name
}

Schema is the canonical, comparable model of one Postgres schema (namespace). Tables and Enums are indexed by name for O(1) lookup — the diff that compares two Schemas walks these maps, never a linear list. Two Schemas built by Introspect are reflect.DeepEqual iff they describe the same database state.

func Introspect(ctx context.Context, q Querier, schemaName string) (*Schema, error)

func NewSchema(name string) *Schema

type Statement ¶

type Statement struct {
	SQL string
	// Concurrent marks a statement that MUST run outside a transaction
	// (CREATE/DROP INDEX CONCURRENTLY) — the executor runs it on its own connection.
	Concurrent bool
	// CleanupSQL, if set, is run (best-effort) before a retry of a failed Concurrent
	// statement — e.g. dropping the invalid index a failed CONCURRENTLY build leaves.
	CleanupSQL string
	// Op is the source operation (for risk/diagnostics).
	Op Operation
}

Statement is one rendered SQL statement plus how it must be executed.

func Render(plan *Plan) ([]Statement, error)

type Table ¶

type Table struct {
	Name string

	// RenamedFrom is the EXPLICIT previous name of this table when the desired
	// schema declares a rename. It is never inferred by a heuristic — the diff
	// uses it to emit ALTER TABLE … RENAME instead of drop+create. Empty for an
	// introspected (real) table.
	RenamedFrom string

	Columns     map[string]*Column
	ColumnOrder []string

	PK      *PrimaryKey
	FKs     map[string]*ForeignKey       // by constraint symbol
	Uniques map[string]*UniqueConstraint // by constraint symbol
	Checks  map[string]*Check            // by constraint symbol
	Indexes map[string]*Index            // by index name (standalone indexes only)
}

Table is one relation with its columns and constraints. Columns are indexed by name (O(1)); ColumnOrder preserves the on-disk column order so DDL can be emitted stably. Constraints are split by kind — PK, FKs, Uniques and Checks are declarative integrity (each altered with distinct DDL), while Indexes holds the STANDALONE indexes only (those NOT backing a PK or unique constraint).

func NewTable(name string) *Table

func (t *Table) AddColumn(c *Column)

type Type ¶

type Type struct {
	Base  BaseType
	Size  int // length for varchar(N) / char(N); 0 if unspecified
	Prec  int // precision for numeric(P,S); fractional-seconds precision for time/timestamp
	Scale int // scale for numeric(P,S)
	Array bool

	// UserName holds the raw type name when Base == BaseUserDefined (a Postgres
	// enum, domain, or any type outside the alias map). Empty otherwise.
	UserName string
}

Type is the canonical, comparable representation of a column type. It is a struct of comparable fields, so `==` and reflect.DeepEqual both work and two textual spellings of the same type normalize to the SAME Type — the whole point of not modeling types as strings (e.g. "varchar(255)" and "character varying(255)" both → {Base: BaseVarchar, Size: 255}).

func ParseType(pgType string) Type

func TypeForAPIType(apiType string) Type

func (t Type) String() string

type UniqueConstraint ¶

type UniqueConstraint struct {
	Symbol  string
	Columns []string
}

UniqueConstraint is a UNIQUE constraint (distinct from a standalone UNIQUE INDEX: a constraint is altered via ALTER TABLE ADD/DROP CONSTRAINT and can be the target of a foreign key, so the diff must treat the two differently).