Documentation ¶
Index ¶
- Constants
- Variables
- func Applied(conn Queryable) ([]string, error)
- func Apply(db *sql.DB) error
- func ApplyRollbacks(db *sql.DB, revision int) error
- func Available(directory string, direction Direction) ([]string, error)
- func CopyMigrations(tx *sql.Tx) error
- func Create(directory string, name string) error
- func CreateMigrationsApplied(tx *sql.Tx) error
- func CreateMigrationsRollbacks(tx *sql.Tx) error
- func CreateMigrationsSchema(tx *sql.Tx) error
- func CreateSchemaMigrations(tx *sql.Tx) error
- func Downgrade(db *sql.DB) error
- func Filename(path string) string
- func HandleAsync(db *sql.DB, requests RequestChannel, results ResultChannel)
- func HandleEmbeddedRollbacks(db *sql.DB, directory string, version int) error
- func InitializeDB(db *sql.DB, directory string) error
- func IsDown(version int, desired int) bool
- func IsMigrated(tx *sql.Tx, migration string) bool
- func IsUp(version int, desired int) bool
- func LatestMigration(conn Queryable) (string, error)
- func LatestRevision(directory string) int
- func Migrate(db *sql.DB, directory string, version int) error
- func Migrated(tx *sql.Tx, path string, direction Direction) error
- func MissingMigrationsApplied(tx *sql.Tx) bool
- func MissingMigrationsRollbacks(tx *sql.Tx) bool
- func MissingMigrationsSchema(tx *sql.Tx) bool
- func MissingSchemaMigrations(tx *sql.Tx) bool
- func ReadSQL(path string, direction Direction) (SQL, Modifiers, error)
- func Revision(filename string) (int, error)
- func Rollback(db *sql.DB, directory string, steps int) error
- func ShouldRun(tx *sql.Tx, migration string, direction Direction, desiredVersion int) bool
- func UpdateRollback(tx *sql.Tx, path string) error
- func UpdateRollbacks(tx *sql.Tx, directory string) error
- func Upgrade(tx *sql.Tx, directory string) error
- type AsyncRequest
- type AsyncResult
- type DefaultLogger
- type Direction
- type DiskReader
- type Logger
- type Modifiers
- type NilLogger
- type Options
- type Queryable
- type Reader
- type RequestChannel
- type ResultChannel
- type SQL
- type SQLParser
- type SortDown
- type SortUp
Constants ¶
const ( // Latest migrates to the latest migration. Latest int = -1 // Up direction. Up Direction = "up" // Down direction. Down Direction = "down" // None direction. None Direction = "none" )
const EnvMigrations = "MIGRATIONS"
EnvMigrations is the environment variable that can be used to point to the directory of SQL migrations.
Variables ¶
var ErrNoCommand = errors.New("no SQL command found")
var ErrNoState = errors.New("no SQL parser state")
var ErrStopped = errors.New("stopped rollback due to /stop modifier")
ErrStopped returned if the migration couldn't rollback due to a /stop modifier
Functions ¶
func Applied ¶ added in v2.1.0
Applied returns the list of migrations that have already been applied to this database.
func Apply ¶ added in v2.1.0
Apply any SQL migrations to the database using the default options.
Any files that don't have entries in the migrations table will be run to bring the database to the indicated version. Should the migrations in the database exceed the version indicated, the rollback or "down" migrations are applied to restore the database to the previous versions. By default the database is migrated to the latest available version indicated by the SQL migration files.
If the migrations table does not exist, this function automatically creates it.
func ApplyRollbacks ¶ added in v2.1.0
ApplyRollbacks collects any migrations stored in the database that are higher than the desired revision and runs the "down" migration to roll them back.
func Available ¶
Available returns the list of SQL migration paths in order. If direction is Down, returns the migrations in reverse order (migrating down).
func CopyMigrations ¶ added in v2.1.0
CopyMigrations copies the migrations from the schema_migrations table to the migrations.applied table.
func CreateMigrationsApplied ¶ added in v2.1.0
CreateMigrationsApplied creates the migrations.applied table in the database if it doesn't already exist.
func CreateMigrationsRollbacks ¶ added in v2.1.0
CreateMigrationsRollbacks creates the migrations.rollbacks table in the database if it doesn't already exist.
func CreateMigrationsSchema ¶ added in v2.1.0
CreateMigrationsSchema creates the "migrations" schema for storing the migrations state.
func CreateSchemaMigrations ¶
CreateSchemaMigrations creates the schema_migrations table in the database if it doesn't already exist.
func Downgrade ¶ added in v2.1.0
Downgrade rolls your database back from migrations/v2 to a migrations/v1-compatible database, or specifically, recreate schema_migrations and copy migrations.applied into the schema_migrations table and drop the "migrations" schema.
func HandleAsync ¶ added in v2.1.0
func HandleAsync(db *sql.DB, requests RequestChannel, results ResultChannel)
HandleAsync should be run in the background to listen for asynchronous migration requests. These requests are run in order, within a transaction, but the main synchronous migrations will not wait for these to complete before continuing.
func HandleEmbeddedRollbacks ¶ added in v2.1.0
HandleEmbeddedRollbacks updates the rollbacks and then applies any missing and necessary rollbacks to get the database to the implied versions.
func InitializeDB ¶ added in v2.1.0
InitializeDB prepares the tables in the database required to manage migrations.
func IsMigrated ¶
IsMigrated checks the migration has been applied to the database, i.e. is it in the migrations.applied table?
func LatestMigration ¶
LatestMigration returns the name of the latest migration run against the database.
func LatestRevision ¶
LatestRevision returns the latest revision available from the SQL files in the migrations directory.
func Migrate ¶
Migrate runs the indicated SQL migration files against the database.
This function is provided for backwards compatibility with the older migrations/v1 package. The new v2 approach is to call `Apply()` with any options supplied separately.
Any files that don't have entries in the schema_migrations table will be run to bring the database to the indicated version. If the schema_migrations table does not exist, this function will automatically create it.
Indicate the version to roll towards, either forwards or backwards (rollback). By default, we roll forwards to the current time, i.e. run all the migrations.
func MissingMigrationsApplied ¶ added in v2.1.0
MissingMigrationsApplied returns true if there is no migrations.applied table in the database.
func MissingMigrationsRollbacks ¶ added in v2.1.0
MissingMigrationsRollbacks returns true if there is no migrations.rollbacks table in the database.
func MissingMigrationsSchema ¶ added in v2.1.0
MissingMigrationsSchema returns true if there's no "migrations" schema in the database.
func MissingSchemaMigrations ¶
MissingSchemaMigrations returns true if there is no schema_migrations table in the database.
func Rollback ¶
Rollback a number of migrations. If steps is less than 2, rolls back the last migration.
func ShouldRun ¶
ShouldRun decides if the migration should be applied or removed, based on the direction and desired version to reach.
func UpdateRollback ¶ added in v2.1.0
UpdateRollback adds the migration's "down" SQL to the rollbacks table.
func UpdateRollbacks ¶ added in v2.1.0
UpdateRollbacks copies all the "down" parts of the migrations into the migrations.rollbacks table for any migrations missing from that table. Helps migrate older applications to use the newer in-database rollback functionality.
Types ¶
type AsyncRequest ¶ added in v2.1.0
type AsyncRequest struct { Migration string // Full path to the migration Direction Direction // The direction to run SQL SQL // The SQL to run (parsed from the migration) Target int // The desired revision number to migration to }
AsyncRequest is submitted to the background asynchronous migration processor.
type AsyncResult ¶ added in v2.1.0
type AsyncResult struct { Migration string // The migration filename Err error // Is nil if the migration succeeded Command SQL // The SQL command that failed if the migration failed; blank otherwise }
AsyncResult is returned by asynchronous SQL migration commands on the Results channel
type DefaultLogger ¶
type DefaultLogger struct{}
DefaultLogger implements Logger. It outputs to stdout for debug messages and stderr for error messages.
func (*DefaultLogger) Debugf ¶
func (log *DefaultLogger) Debugf(format string, args ...interface{})
Debugf outputs debug messages to stdout.
func (*DefaultLogger) Infof ¶
func (log *DefaultLogger) Infof(format string, args ...interface{})
Infof outputs info or error messages to stderr.
type DiskReader ¶
type DiskReader struct { }
DiskReader outputs to disk, the Migrations default.
type Logger ¶
type Logger interface { Debugf(format string, args ...interface{}) Infof(format string, args ...interface{}) }
Logger is a simple interface for logging in migrations.
var ( // Log outputs log messages to any object supporting the Logger // interface. Replace at any time to a logger compatible with your // system. Log Logger )
type Modifiers ¶ added in v2.1.0
type Modifiers []string
Modifiers collects the modification flags passed in from the SQL "up" and "down" lines. For example:
# --- !Down /stop
These modifications are parsed and returned with the SQL from ReadSQL.
func (Modifiers) Has ¶ added in v2.1.0
Has looks for the migration modification passed in from the SQL. Mods should be indicated like so:
# --- !Up insert into sample (name) values ('abc'); # --- !Down /stop delete from sample where name = 'abc';
The only modification supported currently is `/norollback`, which warns when a down migration can't be rolled back programmatically (must restore from backup).
type NilLogger ¶ added in v2.1.0
type NilLogger struct{}
NilLogger hides migration logging output.
type Options ¶ added in v2.1.0
type Options struct { // Revision is the revision to forcibly move to. Defaults to the latest revision as // indicated by the available SQL files (which could be a rollback if the applied // migrations exceed the latest SQL file. Revision int // Directory is the directory containing the SQL files. Defaults to the "./sql" directory. Directory string // EmbeddedRollbacks enables embedded rollbacks. Defaults to true. EmbeddedRollbacks bool }
func DefaultOptions ¶ added in v2.1.0
func DefaultOptions() Options
DefaultOptions returns the defaults for the migrations package. Revision defaults to the latest revision, and the directory defaults to what's defined in the MIGRATIONS environment variable, or "./sql" if the environment variable was not defined..
func DisableEmbeddedRollbacks ¶ added in v2.1.0
func DisableEmbeddedRollbacks() Options
DisableEmbeddedRollbacks disables the embedded rollbacks functionality. Rollbacks must be triggered manually, using WithRevision.
func WithDirectory ¶ added in v2.1.0
WithDirectory points to the directory of SQL migrations files that should be used to migrate the database schema. Defaults to the "./sql" directory.
func WithRevision ¶ added in v2.1.0
WithRevision manually indicates the revision to migrate the database to. By default, the migrations to get the database to the revision indicated by the latest SQL migraiton file is used.
func (Options) Apply ¶ added in v2.1.0
Apply any SQL migrations to the database.
Any files that don't have entries in the migrations table will be run to bring the database to the indicated version. Should the migrations in the database exceed the version indicated, the rollback or "down" migrations are applied to restore the database to the previous versions. By default the database is migrated to the latest available version indicated by the SQL migration files.
If the migrations table does not exist, this function automatically creates it.
May return an ErrStopped if rolling back migrations and the Down portion has a /stop modifier.
func (Options) DisableEmbeddedRollbacks ¶ added in v2.1.0
DisableEmbeddedRollbacks disables the embedded rollbacks functionality. Rollbacks must be triggered manually, using WithRevision.
func (Options) WithDirectory ¶ added in v2.1.0
WithDirectory points to the directory of SQL migrations files that should be used to migrate the database schema. Defaults to the "./sql" directory.
func (Options) WithRevision ¶ added in v2.1.0
WithRevision manually indicates the revision to migrate the database to. By default, the migrations to get the database to the revision indicated by the latest SQL migraiton file is used.
type Reader ¶
type Reader interface { // Files returns the files in a directory or remote path. Files(directory string) ([]string, error) // Read the SQL from the migration. Read(path string) (io.Reader, error) }
Reader interface allows the migrations to be read from different sources, such as an S3 bucket or another data store.
type RequestChannel ¶ added in v2.1.0
type RequestChannel chan AsyncRequest
RequestChannel is the channel for submitting asynchronous migration requests. Asynchronous migrations are run in the background, and must complete in order, but they do not wait for synchronous migrations to complete.
type ResultChannel ¶ added in v2.1.0
type ResultChannel chan AsyncResult
ResultChannel is the channel on which asynchronous migrations return their results (did they succeed or fail). The MigrateAsync function returns this channel, so your application can listen for the background migrations to complete before reporting completion.
type SQL ¶ added in v2.1.0
type SQL string
SQL contains SQL commands or a migration.
func ParseSQL ¶ added in v2.1.0
ParseSQL breaks the SQL document apart into individual commands, so we can submit them to the database one at a time.
func RunIsolated ¶ added in v2.1.0
func RunIsolated(db *sql.DB, req AsyncRequest) (SQL, error)
RunIsolated breaks apart a SQL migration into separate commands and runs each in a single transaction. Helps asynchronous migrations return additional details about failures.
type SQLParser ¶ added in v2.1.0
type SQLParser struct {
// contains filtered or unexported fields
}
SQLParser breaks apart a document of SQL commands into their individual commands.
func NewSQLParser ¶ added in v2.1.0
NewSQLParser creats a new SQL parser.