migratory

Documentation

Index

• Variables
• func RegisterDialect(name string, fn dialectFunc)
• type Dialect
• type Migrator
  • func (m *Migrator) AddDownHook(hook MigratorHook)
  • func (m *Migrator) AddUpHook(hook MigratorHook)
  • func (m *Migrator) Current() int
  • func (m *Migrator) Dialect() Dialect
  • func (m *Migrator) Down() error
  • func (m *Migrator) DownTo(version int) error
  • func (m *Migrator) Get(migration string) *Migrator
  • func (m *Migrator) Has(migration string) bool
  • func (m *Migrator) Len() int
  • func (m *Migrator) Migrations() []string
  • func (m *Migrator) SetSchema(schema string)
  • func (m *Migrator) SetTable(name string)
  • func (m *Migrator) Target() int
  • func (m *Migrator) Up() error
  • func (m *Migrator) UpTo(version int) error
• type MigratorGenerator
• type MigratorHook
• type Migratory
  • func New(uri string) (*Migratory, error)
  • func (m *Migratory) Dialect() Dialect
  • func (m *Migratory) Migrate(path string) (migrator *Migrator, err error)
  • func (m *Migratory) Options(opts Options) error
  • func (m *Migratory) TargetDB() *dbConn
  • func (m *Migratory) Unlock() *Migratory
  • func (m *Migratory) UnlockUsing(tags []string) *Migratory
  • func (m *Migratory) UsingVFS(fs vfs.VFS)
  • func (m *Migratory) VersionDB() *dbConn
• type MySQLDialect
  • func (d MySQLDialect) Conn() *dbConn
• type Options
• type PostgresDialect
  • func (d PostgresDialect) Conn() *dbConn
• type SchemaDialect
• type SchemaOptions
• type Sqlite3Dialect
  • func (d Sqlite3Dialect) Conn() *dbConn
• type Statement
• type Version

Variables

var ErrDatabaseConnection = errors.NewError("error connecting to database")

ErrDatabaseConnection is returned whenever a connection to the database could not be established. This is usually a configuration error.

var ErrIncompleteStatement = errors.NewError("incomplete statement")

ErrIncompleteStatement is returned if a new migration directive is supplied prior to the completion of the previous statement.

var ErrInvalidDialect = errors.NewError("invalid dialect")

ErrInvalidDialect is returned whenever a dialect is requested that isn't supported.

var ErrInvalidVersion = errors.NewError("invalid version identifier for migration")

ErrInvalidVersion is returned if the version specifier for the migration file could not be parsed.

var ErrNoActiveTransaction = errors.NewError("no transaction is active")

ErrNoActiveTransaction is returned if a transaction call (Commit, Rollback, etc) is called on a dbConn where no transaction is currently active.

var ErrNoCurrentVersion = errors.NewError("no current migration available")

ErrNoCurrentVersion is returned whenever there are no migrations available for the current configuration. This is usually returned whenever migrations are run without being setup.

var ErrNoDirectives = errors.NewError("no directive(s) present in file")

ErrNoDirectives indicates no migration directives were present in the migration file. This is an optional error.

var ErrNoNextVersion = errors.NewError("no additional migrations available")

ErrNoNextVersion is returned when there are no further migrations available in the current configuration.

var ErrNoStatementEnd = errors.NewError("new directive specified following +begin with no matching +end")

ErrNoStatementEnd is thrown when the end of a migration is reached without encountering the "+end" directive following a "+begin".

var ErrOnHook = errors.NewError("error encountered while running migration hook")

ErrOnHook is returned whenever an up or down migration encounters an error while running a configured hook.

var ErrParserWritingBuffer = errors.NewError("failed to write buffer")

ErrParserWritingBuffer is returned whenever the parser is unable to write to its internal buffer. This should not ordinarily happen.

var ErrParsingMigration = errors.NewError("failed to parse migration")

ErrParsingMigration is returned whenever the SQL parser encounters a condition it is unable to recover from.

var ErrRunningMigration = errors.NewError("error on migration")

ErrRunningMigration is triggered whenever an error is encountered running a migration. See associated metadata to determine the underlying version, statement, and possible cause.

var ErrUnsupportedDriver = errors.NewError("unsupported driver type")

ErrUnsupportedDriver is returned when the specified driver isn't supported by the migration utility.

var PGSQLCheckTable = `select tablename
	from pg_catalog.pg_tables
	where
		tablename = $1 and
		schemaname = $2
		limit 1;`

Functions

func RegisterDialect

func RegisterDialect(name string, fn dialectFunc)

Types

type Dialect

type Dialect interface {

	// Conn returns a pointer to the internal database connection used by the
	// current dialect.
	Conn() *dbConn
	// contains filtered or unexported methods
}

Dialect is an interface that defines the public contract for individual database dialects. Individual dialects handle database communication themselves but interface with other parts of Migratory by way of this contract.

type Migrator

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

Migrator handles the actual migration(s) following dispatch from Migratory.

Migrator is unique in that it can handle multiple migrator instances internally, such as if a directory contains multiple migrations (e.g. per-schema or per-application). This provides some flexibility for software that manages hierarchical migrations.

func (*Migrator) AddDownHook

func (m *Migrator) AddDownHook(hook MigratorHook)

AddDownHook adds a MigratorHook function to be processed for every "down" statement.

func (*Migrator) AddUpHook

func (m *Migrator) AddUpHook(hook MigratorHook)

AddUpHook adds a MigratorHook function to be processed for every "up" statement.

func (*Migrator) Current

func (m *Migrator) Current() int

Current migration version from the database.

If the returned value is 0, no migrations are currently recorded in the versioning table; if the current value is -1 and the Migrator was loaded from a path containing subdirectories (schema-based or otherwise), Len() will return the number of migrations pending.

func (*Migrator) Dialect

func (m *Migrator) Dialect() Dialect

Dialect returns the current dialect configured for this Migrator.

func (*Migrator) Down

func (m *Migrator) Down() error

Down runs all reverse migrations from the current migration to the earliest migration state.

func (*Migrator) DownTo

func (m *Migrator) DownTo(version int) error

DownTo runs all reverse migrations to the version specified, exclusive.

func (*Migrator) Get

func (m *Migrator) Get(migration string) *Migrator

Get the specified migration returning nil if no such migration exists.

func (*Migrator) Has

func (m *Migrator) Has(migration string) bool

Has indicates whether the `migration` has been loaded into this migrator.

func (*Migrator) Len

func (m *Migrator) Len() int

Len returns the number of migration paths under control of this Migrator.

func (*Migrator) Migrations

func (m *Migrator) Migrations() []string

Migrations returns a list of migrations this Migrator instance controls. If this Migrator is only responsible for a single migration, this will return an empty slice.

func (*Migrator) SetSchema

func (m *Migrator) SetSchema(schema string)

SetSchema to the schema specified, overriding other means of deriving the schema (e.g. "+schema" directives).

This function will also transform the schema currently in use by the configured dialect.

func (*Migrator) SetTable

func (m *Migrator) SetTable(name string)

SetTable configures the table to use for this migration. By default, the table name will be _migration_versions but this may be configured on a per-database or per-application basis.

Using SetTable() allows callers to configure a new migration(s) table for hosting different applications from the same database or configuring a distinct migrations schema to act as a container for multiple application(s) migrations.

Alternatively, the application name itself can be specified for instances where infrastructure requires storing multiple application migration(s) metadata in the same database.

func (*Migrator) Target

func (m *Migrator) Target() int

Target version as derived from the file system.

If the returned value is 0, no migrations are currently available from the configured file system. If the returned value is -1 and the Migrator was loaded from a path containing subdirectories (schema-based or otherwise), Get() should be called first and Target() may be derived from there instead.

func (*Migrator) Up

func (m *Migrator) Up() error

Up runs all migrations for the current configuration up to the last version available.

func (*Migrator) UpTo

func (m *Migrator) UpTo(version int) error

UpTo runs all migrations up to the version specified, inclusive.

type MigratorGenerator

type MigratorGenerator func(*Migrator, vfs.VFS) (*Migrator, error)

type MigratorHook

type MigratorHook func(statement Statement, version Version) (skip bool, err error)

MigratorHook is a function type that accepts a single statement, its version, and returns a tuple containing a boolean and an error. If the boolean value is true, the current statement is skipped. If the error type is non-nil the migration is cancelled.

type Migratory

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

Migratory is the central entrypoint and data structure for managing migrations.

A single Migratory instance describes a single dialect; within that dialect, for those that support schemas (e.g. PostgreSQL), the schema name will be applied as necessary to the migration version table.

By default, if the schema.Name is set and the schema.IsDir value is false, all of the migrations within the Migratory VFS will be applied to the specified schema. Otherwise, if the schema.IsDir value is true, the schema.Name will be used as a sub-path of the VFS. Schemas are disabled if Migratory.schema is nil or if the dialect doesn't implement SchemaDialect.

func New

func New(uri string) (*Migratory, error)

New Migratory instance.

This returns a migratory instance configured to use the database connection `uri` with the specified `dialect`. If a connection is made successfully and the dialect is one of the Migratory-supported dialects, a new instance will be returned.

On error, this function will return either ErrInvalidDialect containing metadata with the invalid dialect name, or ErrDatabaseConnection if the connection to the database failed.

func (*Migratory) Dialect

func (m *Migratory) Dialect() Dialect

Dialect associated with the current Migratory instance.

func (*Migratory) Migrate

func (m *Migratory) Migrate(path string) (migrator *Migrator, err error)

Migrate returns the migration collection(s) associated with the specified path.

If path is a directory encapsulated by a VFS entity that contains only migration versions and nothing else, the Migration instance returned will interact strictly with those versions. Whatever schema is configured, if any, the versioning metadata table, and other migration-specific configurations, will apply to that single migration.

If path is a directory containing multiple subdirectories, the behavior of this call will be determined by the configuration:

If Options.Schema.UseDirNames is true, each subdirectory within `path` will be interpreted as the parent schema for each migration contained therein. Consequently, Migration.Len() will return the number of individual migrations

func (*Migratory) Options

func (m *Migratory) Options(opts Options) error

func (*Migratory) TargetDB

func (m *Migratory) TargetDB() *dbConn

TargetDB instance. To retrieve the underlying sqlx.DB connection, call .DB() on the returned struct.

This is the connection used to commit changes to the target database.

func (*Migratory) Unlock

func (m *Migratory) Unlock() *Migratory

Unlock the current migration.

When called, if a +up;lock or +down;lock directive is present in a migration, this function will disable all global locks but not named locks. If a named lock is present that was not unlocked by UnlockUsing, migrations will be halted at that lock.

func (*Migratory) UnlockUsing

func (m *Migratory) UnlockUsing(tags []string) *Migratory

UnlockUsing the specified tags.

When called, if a +up;lock=<name> or +down;lock=<name> directive is present in a migration, this function will disable only those locks specified by the `lock=` tags. For example, setting:

-- +up;lock=initial_state

and from your application source:

migratory.UnlockUsing([]string{"initial_state"})

the migration guarded by the `initial_state` lock will be unlocked.

This function does not unlock global locks; use Unlock for that instead. Likewise, migrations will halt at the first lock that was not unlocked by this function or Unlock.

func (*Migratory) UsingVFS

func (m *Migratory) UsingVFS(fs vfs.VFS)

UsingVFS configures the virtual file system to use for the migrations directory. `fs` must contain any of: a VFSFS file system pointing to a physical location on disk, an embedded asset, a .zip file, or a VFSCollection entity that provides fall through support for any of the above to create layered, multiple migrations, that can be overridden locally or via upgrade processes.

Whichever VFS is passed in will be cloned and configured as read-only.

func (*Migratory) VersionDB

func (m *Migratory) VersionDB() *dbConn

VersionDB instance. To retrieve the underlying sqlx.DB connection, call .DB() on the returned struct.

This is the connection used to store versioning information relating to the current migration status.

type MySQLDialect

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

MySQLDialect struct.

func (MySQLDialect) Conn

func (d MySQLDialect) Conn() *dbConn

type Options

type Options struct {
	VersionTable   string
	TargetDatabase string
	Schema         SchemaOptions
}

Options for per-migration configuration.

type PostgresDialect

type PostgresDialect struct {
	Schema        string
	VersionSchema string
	// contains filtered or unexported fields
}

PostgresDialect definition.

The PostgreSQL dialect requires PostgreSQL 9.1+.

This dialect supports schemas.

func (PostgresDialect) Conn

func (d PostgresDialect) Conn() *dbConn

type SchemaDialect

type SchemaDialect interface {
	// Dialect is included as part of this interface.
	Dialect
	// contains filtered or unexported methods
}

SchemaDialect is a Dialect specifically intended for use with databases that provide schema suport for migration isolation (e.g. for separate applications).

type SchemaOptions

type SchemaOptions struct {
	// Version schema for storing migratory-related tables.
	Version string

	// UseDirNames configures the migrator to use the directory names contained
	// in the VFS path as the schema name for the migrations contained therein.
	UseDirNames bool

	// Name of the current schema. If this isn't configured, the public/global
	// schema will be used instead for migrations.
	//
	// The special migration variable `$(SCHEMA)` will be replaced in migrations
	// where it is declared with this value.
	Name string

	// Authorization configures the username having access to this schema.
	Authorization string
}

SchemaOptions to configure schema management for databases that support schemas.

type Sqlite3Dialect

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

Sqlite3Dialect struct.

func (Sqlite3Dialect) Conn

func (d Sqlite3Dialect) Conn() *dbConn

type Statement

type Statement interface {
	Add(string, string)
	Get(string) string
	Has(string) bool
	IsUp() bool
	IsDown() bool
	IsLocked() bool
	LockTag() string
	Query() string
	SetMeta(map[string]string)
	String() string
}

type Version

type Version interface {
	ID() int
	Schema() string
	Statements() *statements
}