migration

Documentation

Index

• type DiagnosticStep
• type Diagnostics
  • func (err *Diagnostics) Error() string
  • func (err *Diagnostics) Unwrap() error
• type MigrateFunc
• type Migration
• type Registry
  • func New(key string) *Registry
  • func (reg *Registry) Add(migrations ...Migration) error
  • func (reg *Registry) Migrate(ctx context.Context) (err error)

Types

type DiagnosticStep

type DiagnosticStep struct {
	Version     string
	Description string
}

DiagnosticStep describes one migration step in the Diagnostics.

type Diagnostics

type Diagnostics struct {
	// Message holds a human readable message of the encountered
	// error.
	Message string
	// Wrapped must be set to the underlying error that was encountered
	// while preparing or executing migrations.
	Wrapped error
	// StartOfMigration is set to the version of the database before
	// any migrations are applied.
	StartOfMigration string
	// LastSuccessfulMigration is set to the version of the database
	// which has been applied successfully before the error happened.
	LastSuccessfulMigration string
	// TargetVersion is set to the version of the database that the
	// migration run aimed for. That is, it's the last available version
	// added to the registry.
	TargetVersion string
	// ExecutionPlan is a list of migration steps that were planned to
	// be executed.
	ExecutionPlan []DiagnosticStep
	// FailedMigration is the description of the migration that has
	// failed.
	FailedMigration string
}

Diagnostics holds a detailed error report about a failed migration.

func (*Diagnostics) Error

func (err *Diagnostics) Error() string

Error returns a string representation of the migration error.

func (*Diagnostics) Unwrap

func (err *Diagnostics) Unwrap() error

Unwrap returns the actual error that happened when executing a migration. It implements the interface required by the stdlib errors package to support errors.Is() and errors.As().

type MigrateFunc

type MigrateFunc func(ctx context.Context, from, to *version.Version, dbInterface *database.Interface) error

MigrateFunc is called when a migration should be applied to the database. It receives the current version (from) and the target version (to) of the database and a dedicated interface for interacting with data stored in the DB. A dedicated log.ContextTracer is added to ctx for each migration run.

type Migration

type Migration struct {
	// Description provides a short human-readable description of the
	// migration.
	Description string
	// Version should hold the version of the database/subsystem after
	// the migration has been applied.
	Version string
	// MigrateFuc is executed when the migration should be performed.
	MigrateFunc MigrateFunc
}

Migration represents a registered data-migration that should be applied to some database. Migrations are stacked on top and executed in order of increasing version number (see Version field).

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry holds a migration stack.

func New

func New(key string) *Registry

New creates a new migration registry. The key should be the name of the database key that is used to store the version of the last successfully applied migration.

func (*Registry) Add

func (reg *Registry) Add(migrations ...Migration) error

Add adds one or more migrations to reg.

func (*Registry) Migrate

func (reg *Registry) Migrate(ctx context.Context) (err error)

Migrate migrates the database by executing all registered migration in order of increasing version numbers. The error returned, if not nil, is always of type *Diagnostics.