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 ¶
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.
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.