appdbdrift

package
v1.154.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 8, 2026 License: Apache-2.0 Imports: 7 Imported by: 0

Documentation

Overview

Package appdbdrift compares an application database's live schema with the schema its applied migrations build (#2406), and writes an existing schema as a baseline migration so a database the platform did not create is managed from then on.

The expected schema is built, not remembered: the applied migrations are applied from zero on a throwaway database (the postgres toolkit's DescribeBuilt) and both are read with the same describe, so a difference is a change made outside migrations and never a difference in how two snapshots were taken.

Index

Constants

View Source
const (
	ChangeAdded   = "added"
	ChangeMissing = "missing"
	ChangeChanged = "changed"
)

The changes a difference reports.

View Source
const BaselineVersion = 1

BaselineVersion is the version an adopted baseline takes.

Variables

View Source
var ErrManaged = errors.New("the schema is already managed by migrations; adopting is for a schema the platform keeps none for")

ErrManaged refuses to adopt a schema the platform already keeps migrations for, or whose ledger records any.

View Source
var ErrTooLarge = errors.New("the schema has more objects of one kind than the connection's max_rows; raise max_rows to adopt it")

ErrTooLarge refuses a schema one of whose sections has more objects than a statement on the connection may return (its max_rows).

Functions

This section is empty.

Types

type AdoptKit

type AdoptKit interface {
	Kit
	Reader
	Apply(ctx context.Context, o postgres.ApplyOptions, migrations []postgres.Migration) ([]postgres.Migration, error)
}

AdoptKit is the part of the postgres toolkit an adoption uses.

type AdoptResult

type AdoptResult struct {
	Connection string `json:"connection"`
	Schema     string `json:"schema"`
	// Adopted is true when the baseline was saved and marked applied.
	Adopted bool `json:"adopted"`
	// Version is the baseline's version, 1.
	Version  int    `json:"version"`
	Checksum string `json:"checksum,omitempty"`
	// Up is the baseline's SQL.
	Up string `json:"up,omitempty"`
	// Unsupported are the objects the baseline cannot write; Differences
	// what the baseline, built from zero, still differs in. Either refuses.
	Unsupported []Unsupported `json:"unsupported"`
	Differences []Difference  `json:"differences"`
}

AdoptResult is what an adoption did, or why it did nothing.

func Adopt

func Adopt(ctx context.Context, kit AdoptKit, store Store, target Target) (*AdoptResult, error)

Adopt writes schema as a baseline migration and marks it applied, so a database created before the platform knew it is managed from then on. The baseline is first applied from zero on a throwaway database and compared with the live schema; it is saved only when nothing differs.

type Difference

type Difference struct {
	// Kind is the object: table, column, constraint, index, trigger, policy,
	// partition, row_security, view, function, enum or domain.
	Kind string `json:"kind"`
	// Object names it: table, table.column, table.index, function(args).
	Object string `json:"object"`
	// Change is added (in the live schema only), missing (built by the
	// migrations and absent live) or changed.
	Change string `json:"change"`
	// Live and Expected are the two definitions, for a changed object.
	Live     string `json:"live,omitempty"`
	Expected string `json:"expected,omitempty"`
}

Difference is one object that differs between the live schema and the one its migrations build.

func Compare

func Compare(live, expected *postgres.Description) []Difference

Compare lists every difference between live and expected, in a stable order: tables and their parts, then functions, enums and domains.

type Kit

type Kit interface {
	Describe(ctx context.Context, connection, schema string) (*postgres.Description, error)
	DescribeBuilt(ctx context.Context, connection, schema string, migrations []postgres.Migration) (*postgres.Description, error)
	Status(ctx context.Context, connection, schema string, migrations []postgres.Migration) (*postgres.LedgerStatus, error)
}

Kit is the part of the postgres toolkit a drift check reads.

type Migrations

type Migrations interface {
	List(ctx context.Context, connection, schema string) ([]postgres.Migration, error)
}

Migrations lists the migrations the platform keeps for a schema.

type Reader

type Reader interface {
	ReadTx(ctx context.Context, connection string) (Tx, error)
}

Reader opens a READ ONLY transaction on an application database.

type Result

type Result struct {
	Connection string    `json:"connection"`
	Schema     string    `json:"schema"`
	CheckedAt  time.Time `json:"checked_at"`
	// Checked is false when the check could not be made, and Reason says why:
	// the schema has no migrations, the ledger disagrees with them, or the
	// expected schema could not be built.
	Checked bool   `json:"checked"`
	Reason  string `json:"reason,omitempty"`
	// AppliedVersion is the latest applied migration the expected schema was
	// built through.
	AppliedVersion int          `json:"applied_version"`
	Differences    []Difference `json:"differences"`
}

Result is one drift check of a schema.

func Check

func Check(ctx context.Context, kit Kit, store Migrations, connection, schema string) Result

Check compares schema's live objects with the ones its applied migrations build. Pending migrations are left out of the build: they are not drift.

type Store

type Store interface {
	Migrations
	Put(ctx context.Context, m postgres.Migration) (bool, error)
	Record(ctx context.Context, e postgres.MigrationEvent) error
}

Store keeps the platform's migrations and their history.

type Target

type Target struct {
	Connection, Schema string
	// Actor is recorded as the baseline's author and in its history.
	Actor string
}

Target is the schema an adoption reads and who asked for it.

type Toolkit

type Toolkit struct{ *postgres.Toolkit }

Toolkit is the postgres toolkit as a Reader.

func (Toolkit) ReadTx

func (t Toolkit) ReadTx(ctx context.Context, connection string) (Tx, error)

ReadTx implements Reader.

type Tx

type Tx interface {
	Query(ctx context.Context, s postgres.Statement) (*postgres.Result, error)
	Rollback()
}

Tx is a READ ONLY transaction the catalog is read in: the postgres toolkit's.

type Unsupported

type Unsupported struct {
	Kind string `json:"kind"`
	Name string `json:"name"`
}

Unsupported is an object an adopted baseline cannot write, which refuses the adoption: writing a baseline without it would describe a schema the database does not hold.

func Render

func Render(ctx context.Context, kit Reader, connection, schema string) (string, []Unsupported, error)

Render reads schema's objects and writes the DDL that builds them from zero, every name schema-qualified. Objects it cannot write are returned instead, and refuse the adoption.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL