voyager

README

voyager

A database migration library that supports Go and SQL migrations.

Documentation

Index

• Variables
• func NewParser(source Source) *parser
• type Migration
• type Migrator
  • func NewMigrator(lockID int, source Source, migrationsRunner runner.MigrationsRunner, ...) Migrator
• type Parser
• type SchemaAdapter
• type Source
• type Strategy

Variables

var ErrCouldNotParseDirection = errors.New("could not parse direction for migration")

Functions

func NewParser

func NewParser(source Source) *parser

Types

type Migration

type Migration struct {
	Name       string
	Version    int
	Direction  string
	Statements []string
	Strategy   Strategy
}

type Migrator

type Migrator interface {
	// CurrentVersion reports the current migration version
	// of the database.
	CurrentVersion(lager.Logger, *sql.DB) (int, error)

	// SupportedVersion reports the latest possible migration
	// version that can be applied.
	SupportedVersion(lager.Logger) (int, error)

	// Migrate migrates the database to the given migration version.
	// Implementations must also updates the migrations_history table'
	// with the status of each migration that is run.
	Migrate(lager.Logger, *sql.DB, int) error

	// Up is equivalent to calling Migrate with the latest supported
	// version.
	Up(lager.Logger, *sql.DB) error
}

The Migrator type supports running migrations on a given database. It supports running `up` and `down` migrations and can report the current migration version of the given database.

All Migrator methods expect an open database; the responsibility of opening, closing and maintaining database connections is left up to the user.

func NewMigrator

func NewMigrator(lockID int, source Source, migrationsRunner runner.MigrationsRunner, adapter SchemaAdapter) Migrator

NewMigrator returns a migrator type that implements the voyager.Migrator interface. It supports database-level advisory locks which it acquires using the lockID.

type Parser

type Parser interface {
	// ParseMigrationFilename is used to populate metadata into a Migration,
	// e.g. whether the given migration is a Go or SQL migration. It is used
	// to determine the Migration strategy
	ParseMigrationFilename(lager.Logger, string) (Migration, error)

	// ParseFileToMigration is used to parse the actual contents of a given
	// migration file into a runnable Migration.
	ParseFileToMigration(lager.Logger, string) (Migration, error)
}

The Parser type is used to parse a given file into a voyager.Migration.

type SchemaAdapter

type SchemaAdapter interface {
	// MigrateFromOldSchema converts from an old database schema to
	// Voyager's migrations_history schema.
	// It returns the latest successful migration version recorded by
	// the old schema, or 0 if the old schema does not exist.
	//
	// The version returned by MigrateFromOldSchema will be used as the
	// first version in the migrations_history table.
	//
	// It is called every time an `up` migration is run, so implementations
	// are responsible for returning a sane default version in the case that
	// the old schema is no longer used.
	MigrateFromOldSchema(*sql.DB, int) (int, error)

	// MigrateToOldSchema converts from the new migrations_history schema
	// to the old schema. It exists to support migrating back down to a
	// previous migration version.
	//
	// It is called every time a `down` migration is run.
	MigrateToOldSchema(*sql.DB, int) error

	// CurrentVersion reports the current successful migration version
	// as recorded by the old schema. It is called only if the
	// migrations_history schema does not exist.
	CurrentVersion(*sql.DB) (int, error)
}

The SchemaAdapter is an optional interface that can be implemented if migrating to and from an older database schema is required. If not implemented, the migrations_history table is assumed to be the only database schema table and all versions are assumed to be timestamps as generated by the Voyager CLI.

type Source

type Source interface {
	AssetNames() []string
	Asset(name string) ([]byte, error)
}

type Strategy

type Strategy int

const (
	GoMigration Strategy = iota
	SQLTransaction
	SQLNoTransaction
)