migrate

Documentation

Index

• Constants
• type Driver
• type Manager
  • func NewManager[D Driver[C, T], C any, T any]() *Manager[D, C, T]
  • func (m *Manager[D, C, T]) HeadRevision() (string, error)
  • func (m *Manager[D, C, T]) IsHeadCompatible(revision string) (bool, error)
  • func (m *Manager[D, C, T]) Register(version, replaces string, up MigrationFunc[C], upTx TxMigrationFunc[T]) error
  • func (m *Manager[D, C, T]) Run(ctx context.Context, driver D, throughRevision string, dryRun RunType) error
• type MigrationFunc
• type MigrationVariable
• type RunType
• type TxMigrationFunc

Constants

const (
	Head = "head"
	None = ""
)

Types

type Driver

type Driver[C any, T any] interface {
	// Version returns the current version of the schema in the backing datastore.
	// If the datastore is brand new, version should return the empty string without
	// an error.
	Version(ctx context.Context) (string, error)

	// WriteVersion stores the migration version being run
	WriteVersion(ctx context.Context, tx T, version string, replaced string) error

	// Conn returns the drivers underlying connection handler to be used by one or more MigrationFunc
	Conn() C

	// RunTx returns a transaction for to be used by one or more TxMigrationFunc
	RunTx(context.Context, TxMigrationFunc[T]) error

	// Close frees up any resources in use by the driver.
	Close(ctx context.Context) error
}

Driver represents the common interface for enabling the orchestration of migrations for a specific type of datastore. The driver is parameterized with a type representing a connection handler that will be forwarded by the Manager to the MigrationFunc to execute.

type Manager

type Manager[D Driver[C, T], C any, T any] struct {
	// contains filtered or unexported fields
}

Manager is used to manage a self-contained set of migrations. Standard usage would be to instantiate one at the package level for a particular application and then statically register migrations to the single instantiation in init functions. The manager is parameterized using the Driver interface along the concrete type of a database connection handler. This makes it possible for MigrationFunc to run without having to abstract each connection handler behind a common interface.

func NewManager

func NewManager[D Driver[C, T], C any, T any]() *Manager[D, C, T]

NewManager creates a new empty instance of a migration manager.

func (*Manager[D, C, T]) HeadRevision

func (m *Manager[D, C, T]) HeadRevision() (string, error)

func (*Manager[D, C, T]) IsHeadCompatible

func (m *Manager[D, C, T]) IsHeadCompatible(revision string) (bool, error)

func (*Manager[D, C, T]) Register

func (m *Manager[D, C, T]) Register(version, replaces string, up MigrationFunc[C], upTx TxMigrationFunc[T]) error

Register is used to associate a single migration with the migration engine. The up parameter should be a function that performs the actual upgrade logic and which takes a pointer to a concrete implementation of the Driver interface as its only parameters, which will be passed directly from the Run method into the upgrade function. If not extra fields or data are required the function can alternatively take a Driver interface param.

func (*Manager[D, C, T]) Run

func (m *Manager[D, C, T]) Run(ctx context.Context, driver D, throughRevision string, dryRun RunType) error

Run will actually perform the necessary migrations to bring the backing datastore from its current revision to the specified revision.

type MigrationFunc

type MigrationFunc[C any] func(ctx context.Context, conn C) error

MigrationFunc is a function that executes in the context of a specific database connection handler.

type MigrationVariable

type MigrationVariable int

MigrationVariable contains constants that can be used as context keys that might be relevant in a number of different migration scenarios.

const (
	// BackfillBatchSize represents the number of items that should be backfilled in a
	// single step of an incremental backfill, and should be of type uint64.
	BackfillBatchSize MigrationVariable = iota
)

type RunType

type RunType bool

var (
	DryRun  RunType = true
	LiveRun RunType = false
)

type TxMigrationFunc

type TxMigrationFunc[T any] func(ctx context.Context, tx T) error

TxMigrationFunc is a function that executes in the context of a specific database transaction.