migratory

package module
v0.0.0-...-f91d320 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 19, 2021 License: NCSA Imports: 15 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
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.

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

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

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

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

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

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

View Source 
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.

View Source 
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.

View Source 
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.

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

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

View Source 
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".

View Source 
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.

View Source 
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.

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

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

View Source 
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.

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

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

View Source 
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
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.