migration

Documentation

Index

• Constants
• func Migrate(manager Manager, opts ...Option) (returnErr error)
• func MustRegister(registration *Registration)
• type Config
• type Manager
• type Option
  • func WithConfigProvider(callback func() (*Config, error)) Option
• type Order
• type PersistedStatus
• type Registration
• type Status

Constants

const (
	ConfigPrefix = "MIGRATION"
)

Functions

func Migrate

func Migrate(manager Manager, opts ...Option) (returnErr error)

Migrate orchestrates database migrations using the provided Manager and options.

func MustRegister

func MustRegister(registration *Registration)

MustRegister stores a migration registration in the registry.

Types

type Config

type Config struct {
	// DeadlineMilliseconds is the maximum time for the migrations to complete.
	DeadlineMilliseconds int `config_format:"snake" config_default:"3600000" validate:"gt=0"`

	// UnlockDeadlineMilliseconds is the maximum time for a release operation to complete.
	UnlockDeadlineMilliseconds int `config_format:"snake" config_default:"120000" validate:"gt=0"`

	// HeartbeatIntervalMilliseconds is how often a heart beat is sent to the migration lock.
	HeartbeatIntervalMilliseconds int `config_format:"snake" config_default:"10000" validate:"gt=0"`

	// HeartbeatFailureRetryCount is how many times to retry the heart beat before quitting.
	HeartbeatFailureRetryCount int `config_format:"snake" config_default:"1" validate:"gte=0"`
}

Config holds parameters for running a migration.

type Manager

type Manager interface {
	// AcquireDBLock must acquire a database wide lock.
	// It is used in conjunction with EnsureDataStores and ReleaseDBLock.
	AcquireDBLock(context.Context) error

	// EnsureDataStores must ensure the migration data stores (collections, tables, ...) are created.
	// There should be two data stores, one for the migration lock, and one migration statuses.
	EnsureDataStores(context.Context) error

	// ReleaseDBLock must release the DB lock acquired by AcquireDBLock.
	ReleaseDBLock(context.Context) error

	// AcquireMigrationLock must acquire a migration lock.
	// This is to ensure only one migrator can run at any given time.
	AcquireMigrationLock(context.Context) error

	// MigrationLockHeartbeat is called on a configurable frequency.
	// It is meant to maintain the lock acquired with AcquireMigrationLock.
	MigrationLockHeartbeat(context.Context) error

	// ListStatuses returns data previously stored with PersistStatus.
	ListStatuses(context.Context) ([]PersistedStatus, error)

	// PersistStatus stores or override the status of a migration.
	// Order must be unique in the data store.
	PersistStatus(context.Context, Order, Status) error

	// ReleaseMigrationLock must release the migration lock acquired with AcquireMigrationLock.
	ReleaseMigrationLock(context.Context) error
}

Manager defines the functions needed to manage and coordinate migrations.

type Option

type Option func(cfg *migrateConfig)

Option configures a migrateConfig instance.

func WithConfigProvider

func WithConfigProvider(callback func() (*Config, error)) Option

WithConfigProvider provides an Option to overwrite the configuration provider.

type Order

type Order int

Order represents the sequence in which migrations are meant to be run.

type PersistedStatus

type PersistedStatus struct {
	Order  Order  `validate:"gte=0"`
	Status Status `validate:"oneof=PENDING STARTED FAILED COMPLETED"`
}

PersistedStatus is the data stored in the migration table.

type Registration

type Registration struct {
	// Order is compared to other migrations to determine its run sequence.
	Order Order `validate:"gte=0"`

	// Migrate is invoked to run the migration.
	// This function MUST be idempotent and retryable.
	Migrate func(context.Context) error `validate:"required"`

	// Enabled indicates if this migration is to be run or not.
	// A migration could be disabled if another migration covers it.
	Enabled bool
}

Registration defines a migration callback and its order.

type Status

type Status string

Status represents the status of a persisted migration.

const (
	Pending   Status = "PENDING"
	Started   Status = "STARTED"
	Failed    Status = "FAILED"
	Completed Status = "COMPLETED"
)