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 ¶
const ( ChangeAdded = "added" ChangeMissing = "missing" ChangeChanged = "changed" )
The changes a difference reports.
const BaselineVersion = 1
BaselineVersion is the version an adopted baseline takes.
Variables ¶
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.
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 ¶
func Retarget ¶ added in v1.165.0
Retarget is ddl with every name qualified by schema from qualified by to instead: from.x and "from".x wherever they stand, and from in a function's SET search_path. from and to are lowercase identifiers (the toolkit refuses any other schema name), so neither needs quoting.
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.
type CloneKit ¶ added in v1.165.0
type CloneKit interface {
Reader
BuildSchema(ctx context.Context, connection, schema, ddl string, isolatedFrom []string) error
}
CloneKit is the part of the postgres toolkit a clone uses: the catalog read, and the build of a new schema in one transaction.
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 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.
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 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 ¶
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 Clone ¶ added in v1.165.0
Clone builds schema to on connection from the structure of schema from (#2709): its types, sequences, tables, constraints, views, functions, indexes, triggers, row-level security and comments, and no row. The baseline Render writes names every object with from; each such name is pointed at to, function bodies and search_path settings included, so the new schema's objects reach only each other. Grants are not part of the rendering: the platform grants the new environment's run role on to. BuildSchema refuses the build, keeping nothing, when to would still reach from. Objects the rendering cannot write are returned instead and build nothing.