Documentation
¶
Overview ¶
Package appschema is what an application's release does to its application database schema (#2411): apply the pending migrations so that a release with a failing migration changes nothing, and revert to an earlier release's migration version when every migration between has a down migration. It drives the appdb kind through the toolkit's exported methods and records each step in the migration history manage_schema keeps.
Index ¶
- Constants
- Variables
- type Applied
- type FailedError
- type Kit
- type Reverted
- type Schema
- func (s *Schema) ApplyIn(ctx context.Context, at Target, actor string, upTo int) (*Applied, error)
- func (s *Schema) Baseline(ctx context.Context, at Target, actor string, upTo int) error
- func (s *Schema) Release(ctx context.Context, connection, schema, actor string) (*Applied, error)
- func (s *Schema) Rollback(ctx context.Context, connection, schema, actor string, to int) (*Reverted, error)
- func (s *Schema) RollbackIn(ctx context.Context, at Target, actor string, to int) (*Reverted, error)
- func (s *Schema) State(ctx context.Context, connection, schema string) (*State, error)
- func (s *Schema) StateIn(ctx context.Context, at Target) (*State, error)
- type State
- type Store
- type Target
Constants ¶
const AllVersions = -1
AllVersions is the upTo that applies every pending migration.
Variables ¶
var ErrNoKit = errors.New("this deployment has no application database connection kind")
ErrNoKit is a release of an application with a schema on a deployment with no application database kind.
Functions ¶
This section is empty.
Types ¶
type Applied ¶
type Applied struct {
// Versions is the migrations applied, in order.
Versions []int
// Head is the highest applied version after the release.
Head int
}
Applied is what a release did to the schema.
type FailedError ¶
FailedError is a release whose migrations did not all apply. Undone is the versions applied before the failure and reverted again; Left is any that could not be reverted and stay applied.
func (*FailedError) Error ¶
func (e *FailedError) Error() string
func (*FailedError) Unwrap ¶
func (e *FailedError) Unwrap() error
type Kit ¶
type Kit interface {
Status(ctx context.Context, connection, schema string, migrations []postgreskit.Migration) (*postgreskit.LedgerStatus, error)
PlanMigrations(ctx context.Context, connection, schema string, pending []postgreskit.Migration) (*postgreskit.Plan, error)
Apply(ctx context.Context, o postgreskit.ApplyOptions, migrations []postgreskit.Migration) ([]postgreskit.Migration, error)
Revert(ctx context.Context, o postgreskit.ApplyOptions, migrations []postgreskit.Migration, toVersion int) ([]postgreskit.Migration, error)
}
Kit is the part of the appdb toolkit a release uses.
type Reverted ¶
type Reverted struct {
Versions []int
// Head is the highest applied version after the rollback.
Head int
// Kept says why migrations stayed applied, empty when none did.
Kept string
}
Reverted is what a rollback did to the schema.
type Schema ¶
type Schema struct {
// Kit is the live toolkit, nil when none is registered.
Kit func() Kit
Store Store
}
Schema applies and reverts an application's migrations.
func (*Schema) ApplyIn ¶ added in v1.165.0
ApplyIn applies the source's pending migrations to at's schema, as Release does: up to and including version upTo, every one for AllVersions, none for 0. A promote applies what the release it moves recorded, no more (#2709).
func (*Schema) Baseline ¶ added in v1.165.0
Baseline records the source's migrations through version upTo as applied in at's schema without running them (#2709): a new environment's schema, built from the structure of a schema that applied them, holds what they made already.
func (*Schema) Release ¶
Release applies every pending migration. The pending migrations that run in a transaction are first run together in one transaction that is rolled back, so one that fails is found before anything changes. Should a migration still fail during the apply, the ones this release applied are reverted with their down migrations.
func (*Schema) Rollback ¶
func (s *Schema) Rollback(ctx context.Context, connection, schema, actor string, to int) (*Reverted, error)
Rollback reverts every applied migration above to when each has a down migration. When any lacks one nothing is reverted and Kept says which.
func (*Schema) RollbackIn ¶ added in v1.165.0
func (s *Schema) RollbackIn(ctx context.Context, at Target, actor string, to int) (*Reverted, error)
RollbackIn is Rollback of the source's migrations in at's schema.
type State ¶
type State struct {
// Applied is the highest applied version, 0 for none.
Applied int `json:"applied"`
// Pending is the versions a release would apply.
Pending []int `json:"pending"`
}
State is where a schema's migrations stand.
type Store ¶
type Store interface {
List(ctx context.Context, connection, schema string) ([]postgreskit.Migration, error)
Record(ctx context.Context, e postgreskit.MigrationEvent) error
}
Store is the platform's record of the migrations and their history.
type Target ¶ added in v1.165.0
type Target struct {
Connection, Source, Schema string
}
Target is where an application's migrations apply (#2709): the schema they are kept under, Source, which is the application's, and the schema an environment runs in, Schema, whose ledger records what it applied. Every environment applies the one set of migrations to its own schema.