Documentation
¶
Overview ¶
package migration
This package contains utility types for composing and running schema and data migrations in a strictly serial and ordered nature; against a backing kv.SchemaStore implementation.
The goal is provide a mechanism to ensure an ordered set of changes are applied once and only once to a persisted kv store. To ensure we can make guarantees from one migration to the next, based on the mutations of the previous migrations.
The package offers the `Migrator` type which takes a slice of `Spec` implementations. A spec is a single migration definition, which exposes a name, up and down operations expressed as an Up and Down function on the Spec implementation.
The `Migrator` on a call to `Up(ctx)` applies these defined list of migrations respective `Up(...)` functions on a `kv.SchemaStore` in order and persists their invocation on the store in a reserved Bucket `migrationsv1`. This is to ensure the only once invocation of the migration takes place and allows to the resuming or introduction of new migrations at a later date. This means the defined list needs to remain static from the point of application. Otherwise an error will be raised.
This package also offer utilities types for quickly defining common changes as specifications. For example creating buckets, when can be quickly constructed via `migration.CreateBuckets("create buckets ...", []byte("foo"), []byte{"bar"})`.
As of today all migrations be found in a single defintion in the sub-package to this one named `all` (see `kv/migration/all/all.go`). The `migration.CreateNewMigration()` method can be used to manipulate this `all.go` file in the package and quickly add a new migration file to be populated. This is accessible on the command line via the `internal/cmd/kvmigrate` buildable go tool. Try `go run internal/cmd/kvmigrate/main.go`.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CreateNewMigration ¶
CreateNewMigration persists a new migration file in the appropriate location and updates the appropriate all.go list of migrations
Types ¶
type BucketsMigration ¶
type BucketsMigration struct {
// contains filtered or unexported fields
}
BucketsMigration is a migration Spec which creates the provided list of buckets on a store when Up is called and deletes them on Down.
func (BucketsMigration) Down ¶
func (m BucketsMigration) Down(ctx context.Context, store kv.SchemaStore) error
Down delets the buckets on the store.
func (BucketsMigration) MigrationName ¶
func (m BucketsMigration) MigrationName() string
MigrationName returns the name of the migration.
func (BucketsMigration) Up ¶
func (m BucketsMigration) Up(ctx context.Context, store kv.SchemaStore) error
Up creates the buckets on the store.
type Migration ¶
type Migration struct {
ID platform.ID `json:"id"`
Name string `json:"name"`
State MigrationState `json:"-"`
StartedAt *time.Time `json:"started_at"`
FinishedAt *time.Time `json:"finished_at,omitempty"`
}
Migration is a record of a particular migration.
type MigrationState ¶
type MigrationState uint
MigrationState is a type for describing the state of a migration.
const ( // DownMigrationState is for a migration not yet applied. DownMigrationState MigrationState = iota // UpMigration State is for a migration which has been applied. UpMigrationState )
func (MigrationState) String ¶
func (s MigrationState) String() string
String returns a string representation for a migration state.
type Migrator ¶
type Migrator struct {
Specs []Spec
// contains filtered or unexported fields
}
Migrator is a type which manages migrations. It takes a list of migration specifications and undo (down) all or apply (up) outstanding migrations. It records the state of the world in store under the migrations bucket.
func NewMigrator ¶
NewMigrator constructs and configures a new Migrator.
func (*Migrator) AddMigrations ¶
AddMigrations appends the provided migration specs onto the Migrator.
func (*Migrator) Down ¶
Down applies the down operation of each currently applied migration. Migrations are applied in reverse order from the highest indexed migration in a down state.
For example, given: 0001 add bucket foo | (up) 0002 add bucket bar | (up) 0003 add index "foo on baz" | (down)
Down would call down() on 0002 and then on 0001.
func (*Migrator) List ¶
List returns a list of migrations and their states within the provided store.
func (*Migrator) SetBackupPath ¶ added in v2.1.0
SetBackupPath records the filepath where pre-migration state should be written prior to running migrations.
func (*Migrator) Up ¶
Up applies each outstanding migration in order. Migrations are applied in order from the lowest indexed migration in a down state.
For example, given: 0001 add bucket foo | (up) 0002 add bucket bar | (down) 0003 add index "foo on baz" | (down)
Up would apply migration 0002 and then 0003.
type Spec ¶
type Spec interface {
MigrationName() string
Up(ctx context.Context, store kv.SchemaStore) error
Down(ctx context.Context, store kv.SchemaStore) error
}
Spec is a specification for a particular migration. It describes the name of the migration and up and down operations needed to fulfill the migration.
func CreateBuckets ¶
CreateBuckets returns a new BucketsMigration Spec.
type Store ¶
type Store = kv.SchemaStore
Source Files
Directories