schema

Documentation

Overview

Package schema is used to apply sql migrations to modify the state of a database instance. It also provides functionality to report on the state of a database instance and how it compares with the migration editions in the running binary.

This package requires that the migration editions are first registered, prior to creating a schema.Manager. This is generally done in an init function of another package, i.e.:

//go:embed postgres
var postgres embed.FS

func init() {
    schema.RegisterEdition("oss", schema.Postgres, postgres, 0)
}

Then a manager can be created and used to apply the migrations:

m := schema.NewManager(ctx, schema.Postgres, db)
m.ApplyMigrations()

Index

• func MigrateStore(ctx context.Context, dialect Dialect, url string, opt ...Option) (bool, error)
• func RegisterEdition(name string, dialect Dialect, fs embed.FS, priority int)
• func TestCreatePartialEditions(dialect Dialect, p PartialEditions) edition.Editions
• type DatabaseState
• type Dialect
• type EditionState
• type LogEntry
• type Manager
  • func NewManager(ctx context.Context, dialect Dialect, db *sql.DB, opt ...Option) (*Manager, error)
  • func (b *Manager) ApplyMigrations(ctx context.Context) error
  • func (b *Manager) CurrentState(ctx context.Context) (*State, error)
  • func (b *Manager) ExclusiveLock(ctx context.Context) error
  • func (b *Manager) ExclusiveUnlock(ctx context.Context) error
  • func (b *Manager) GetMigrationLog(ctx context.Context, opt ...Option) ([]LogEntry, error)
  • func (b *Manager) SharedLock(ctx context.Context) error
  • func (b *Manager) SharedUnlock(ctx context.Context) error
• type Option
  • func WithDeleteLog(del bool) Option
  • func WithEditions(editions edition.Editions) Option
• type PartialEditions
• type State
  • func (s State) MigrationsApplied() bool

Functions

func MigrateStore

func MigrateStore(ctx context.Context, dialect Dialect, url string, opt ...Option) (bool, error)

MigrateStore executes the migrations needed to initialize the store. It returns true if migrations actually ran; false if the database is already current or if there was an error. Supports the WithEditions(...) option.

func RegisterEdition

func RegisterEdition(name string, dialect Dialect, fs embed.FS, priority int)

RegisterEdition registers an edition for use by the Manager. It will panic if: - An unsupported dialect is provided. - The same (dialect, name) is registered. - The same (dialect, priority) is registered.

func TestCreatePartialEditions

func TestCreatePartialEditions(dialect Dialect, p PartialEditions) edition.Editions

TestCreatePartialEditions is used by tests to create a subset of the Edition migrations.

Types

type DatabaseState

type DatabaseState int

DatabaseState defines the state of the Database schema as compared to the latest version for the binary.

const (
	Behind DatabaseState = iota // Database schema version is older then latest for the binary, so it needs migrations applied.
	Ahead                       // Database schema version is newer then latest for the binary, so binary needs to be updated.
	Equal                       // Database schema version matches latest version for the binary.
)

Valid states.

type Dialect

type Dialect = edition.Dialect

Dialect is same as edition.Dialect

const (
	Postgres Dialect = "postgres"
)

Supported dialects.

type EditionState

type EditionState struct {
	// Name is the identifier of the Edition.
	Name string

	// DatabaseSchemaVersion is the schema version that is currently running in the database.
	DatabaseSchemaVersion int
	// BinarySchemaVersion is the schema version which this boundary binary supports.
	BinarySchemaVersion int

	DatabaseSchemaState DatabaseState
}

EditionState is the current state of a schema Edition.

type LogEntry

type LogEntry struct {
	Id               int
	MigrationVersion int
	MigrationEdition string
	CreateTime       time.Time
	Entry            string
}

LogEntry represents a log entry generated during migrations.

type Manager

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

Manager provides a way to run operations and retrieve information regarding the underlying boundary database schema. Manager is not thread safe.

func NewManager

func NewManager(ctx context.Context, dialect Dialect, db *sql.DB, opt ...Option) (*Manager, error)

NewManager creates a new schema manager. An error is returned if the provided dialect is unrecognized or if the passed in db is unreachable.

func (*Manager) ApplyMigrations

func (b *Manager) ApplyMigrations(ctx context.Context) error

ApplyMigrations updates the database schema to match the latest version known by the boundary binary. An error is not returned if the database is already at the most recent version.

func (*Manager) CurrentState

func (b *Manager) CurrentState(ctx context.Context) (*State, error)

CurrentState provides the state of the boundary schema contained in the backing database.

func (*Manager) ExclusiveLock

func (b *Manager) ExclusiveLock(ctx context.Context) error

ExclusiveLock attempts to obtain an exclusive lock on the database. An error is returned if a lock was unable to be obtained.

func (*Manager) ExclusiveUnlock

func (b *Manager) ExclusiveUnlock(ctx context.Context) error

ExclusiveUnlock releases a shared lock on the database. If this fails for whatever reason an error is returned. Unlocking a lock that is not held is not an error.

func (*Manager) GetMigrationLog

func (b *Manager) GetMigrationLog(ctx context.Context, opt ...Option) ([]LogEntry, error)

GetMigrationLog will retrieve the migration logs from the db for the last migration. Once it's read the entries, it will delete them from the database.

The WithDeleteLog option is supported and will remove all log entries when provided.

func (*Manager) SharedLock

func (b *Manager) SharedLock(ctx context.Context) error

SharedLock attempts to obtain a shared lock on the database. This can fail if an exclusive lock is already held. If the lock can't be obtained an error is returned.

func (*Manager) SharedUnlock

func (b *Manager) SharedUnlock(ctx context.Context) error

SharedUnlock releases a shared lock on the database. If this fails for whatever reason an error is returned. Unlocking a lock that is not held is not an error.

type Option

type Option func(*options)

Option - how Options are passed as arguments.

func WithDeleteLog

func WithDeleteLog(del bool) Option

WithDeleteLog provides an option to specify the deletion of log entries.

func WithEditions

func WithEditions(editions edition.Editions) Option

WithEditions provides an optional migration states.

type PartialEditions

type PartialEditions map[string]int

PartialEditions is used by TestCreatePartialEditions. It is a map of edition names to the max version that should be included.

type State

type State struct {
	// Initialized indicates if the current database has been previously initialized.
	Initialized bool
	Editions    []EditionState
}

State contains information regarding the current state of a boundary database's schema.

func (State) MigrationsApplied

func (s State) MigrationsApplied() bool

MigrationsApplied checks to see that all Editions are in the Equal SchemaState.