gooseplus

README

gooseplus

Goose DB migrations, extended.

Purpose

gooseplus extends the great DB migration tool goose to supports a few advanced use cases:

1. Leaves a failed deployment in the initial state: rollbacks migrations back to when the deployment failed
2. Support environment-specific migrations, so we can add migrations for tests, etc.
3. More options: structured zap logger, fined-grained timeouts ...

gooseplus is primarily intended to be used as a library, and does not come with a CLI command.

Usage

    db, _ := sql.Open("postgres", "test")
    migrator := New(db)

    err := migrator.Migrate(context.Background())

Feel free to look at the various examples.

Features

• Everything goose does out of the box.
• Rollback to the state at the start of the call, after a failure.
• Environment-specific migration folders

Caveats

• Concurrent usage is not supported: goose relies on a lot of globals. Minimal locking has ben added so you can run your tests with -race, but migrations should normally run once.

Documentation

Overview

Package gooseplus provides a configurable DB Migrator.

It extends github.com/pressly/goose/v3 with the following features: * rollbacks to the initial state of a deployment whenever a migration fails in a sequence of several migrations * supports multiple-environments, so that it is possible to define environment-specific migrations * supports options: such as structured logging with zap.

Index

• Variables
• type Migrator
  • func New(db *sql.DB, opts ...Option) *Migrator
  • func (m Migrator) Migrate(parentCtx context.Context) error
• type Option
  • func SetEnvironments(envs []string) Option
  • func WithBasePath(base string) Option
  • func WithDialect(dialect string) Option
  • func WithEnvironments(envs ...string) Option
  • func WithFS(fsys fs.FS) Option
  • func WithLogger(zlg *zap.Logger) Option
  • func WithMigrationTimeout(timeout time.Duration) Option
  • func WithTimeout(timeout time.Duration) Option
  • func WithVersionTable(table string) Option

Variables

var (
	ErrMigrationTable  = errors.New("could not ensure goose migration table")
	ErrMergeMigrations = errors.New("error merging migrations")
	ErrRollForward     = errors.New("error rolling forward migrations. Recovered error: the db has been rollbacked to its initial state")
	ErrRollBack        = errors.New("error rolling back migrations")
)

Errors returned by the Migrator

Types

type Migrator

type Migrator struct {
	DB *sql.DB
	// contains filtered or unexported fields
}

Migrator knows how to apply changes (migrations) to a versioned database schema.

By base, the migrator will run migrations from the "base" environment folder. If extra environments are added using options, the migrator will merge the migrations with the other folders corresponding to these environments.

func New

func New(db *sql.DB, opts ...Option) *Migrator

New migrator with options.

func (Migrator) Migrate

func (m Migrator) Migrate(parentCtx context.Context) error

Migrate applies database migrations, provided as either as SQL or go migration functions.

Migrate applies the sequence of required migrations.

Whenever a migration fails, Migrate applies rollbacks back to the initial state before returning an error.

type Option

type Option func(*options)

Option for the Migrator.

Default settings are: dialect: "postgres", base: "sql", envs: []string{"base"}, timeout: 5 * time.Minute, logger: zap.NewExample(), fsys: os.DirFS("."),

func SetEnvironments

func SetEnvironments(envs []string) Option

SetEnvironments overrides environment-specific folders to merge with the migrations.

Setting to nil or an empty slice will disable folders: migrations will be searched for in the base path only.

func WithBasePath

func WithBasePath(base string) Option

WithBasePath provides the root directory where migrations are located on the FS.

func WithDialect

func WithDialect(dialect string) Option

WithDialect indicates the database SQL dialect (see goose ...)

func WithEnvironments

func WithEnvironments(envs ...string) Option

WithEnvironments appends environment-specific folders to merge with the migrations.

The base setting is a single folder "base".

func WithFS

func WithFS(fsys fs.FS) Option

WithFS provides the file system where migrations are located.

The base is os.Dir(".").

func WithLogger

func WithLogger(zlg *zap.Logger) Option

WithLogger provides a structured zap logger to the migrator.

func WithMigrationTimeout

func WithMigrationTimeout(timeout time.Duration) Option

WithMigrationTimeout specifies a timeout to apply for each individual migration.

The zero value disables the timeout.

Default is 1m.

func WithTimeout

func WithTimeout(timeout time.Duration) Option

WithTimeout specifies a timeout to apply to the whole migration process.

NOTE: if Migrate(ctx) is called with a context that already contains a deadline, that deadline will override this option.

The zero value disables the timeout.

Default is 5m.

func WithVersionTable

func WithVersionTable(table string) Option

WithVersionTable tells goose to use an non-default version table.

The default is "". Setting an empty table equates to using the default.