Documentation
¶
Overview ¶
Package migration provides a framework for orchestrating ordered database migrations.
Use this package when you need to manage database schema or data changes across application versions. The package handles migration ordering, status tracking, and distributed locking to ensure only one instance runs migrations at a time. Migrations are registered with a numeric order and executed sequentially.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Config ¶
type Config struct {
// MigrationDeadlineMillis is the maximum time for the migrations to complete.
MigrationDeadlineMillis int `config:"ENV" config_default:"3600000" validate:"gt=0"`
// MigrationUnlockDeadlineMillis is the maximum time for a release operation to complete.
MigrationUnlockDeadlineMillis int `config:"ENV" config_default:"120000" validate:"gt=0"`
// MigrationHeartbeatIntervalMillis is how often a heart beat is sent to the migration lock.
MigrationHeartbeatIntervalMillis int `config:"ENV" config_default:"10000" validate:"gt=0"`
// MigrationHeartbeatFailureRetryCount is how many times to retry the heart beat before quitting.
MigrationHeartbeatFailureRetryCount int `config:"ENV" 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(ctx 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 for migration statuses.
EnsureDataStores(ctx context.Context) error
// ReleaseDBLock must release the DB lock acquired by AcquireDBLock.
ReleaseDBLock(ctx context.Context) error
// AcquireMigrationLock must acquire a migration lock.
// This is to ensure only one migrator can run at any given time.
AcquireMigrationLock(ctx context.Context) error
// MigrationLockHeartbeat is called on a configurable frequency.
// It is meant to maintain the lock acquired with AcquireMigrationLock.
MigrationLockHeartbeat(ctx context.Context) error
// ListStatuses returns data previously stored with PersistStatus.
ListStatuses(ctx context.Context) ([]PersistedStatus, error)
// PersistStatus stores or overrides the status of a migration.
// Order must be unique in the data store.
PersistStatus(ctx context.Context, order Order, status Status) error
// ReleaseMigrationLock must release the migration lock acquired with AcquireMigrationLock.
ReleaseMigrationLock(ctx 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 ¶
WithConfigProvider provides an Option to overwrite the configuration provider.
func WithRegistry ¶
WithRegistry overwrites the registry used during migration orchestration.
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.
// The Status parameter contains the previous persisted status, defaulting to Pending if none exists.
Migrate func(context.Context, Status) 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 Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry stores migration registrations keyed by their order.
func (*Registry) MustRegister ¶
func (r *Registry) MustRegister(registration *Registration)
MustRegister stores a migration registration in the registry.
func (*Registry) OrderedRegistrations ¶
func (r *Registry) OrderedRegistrations() []*Registration
OrderedRegistrations returns an ordered list of the registrations in the registry. The registrations are sorted by their Order.
type Status ¶
type Status string
Status represents the status of a persisted migration.
const ( // Pending indicates a migration is queued to run. Pending Status = "PENDING" // Started indicates a migration is currently running. Started Status = "STARTED" // Failed indicates a migration failed during execution. Failed Status = "FAILED" // Completed indicates a migration successfully finished. Completed Status = "COMPLETED" )
Source Files