Documentation
¶
Overview ¶
Package migrate applies versioned SQL migrations, in the file format and with the version table that goose uses — so a project that has been migrating with the goose binary can switch to `dbc migrate` without rewriting a single file or touching its goose_db_version table.
A migration file is NNN_name.sql with two annotated sections:
-- +goose Up CREATE TABLE users (...); -- +goose Down DROP TABLE users;
Statements are split on semicolons by the same scanner the editor uses, so a $$-quoted function body is one statement without help. For anything the scanner cannot know is one statement, the goose escape hatch still works:
-- +goose StatementBegin ... verbatim, semicolons and all ... -- +goose StatementEnd
`-- +goose NO TRANSACTION` at the top runs the file's statements outside a transaction, for DDL that refuses to run inside one (CREATE INDEX CONCURRENTLY, say).
Index ¶
- Constants
- Variables
- func Create(dir, name string) (string, error)
- type Dialect
- type Migration
- type Migrator
- func (m *Migrator) Down(ctx context.Context) ([]Migration, error)
- func (m *Migrator) DownTo(ctx context.Context, target int64) ([]Migration, error)
- func (m *Migrator) Migrations() []Migration
- func (m *Migrator) Redo(ctx context.Context) error
- func (m *Migrator) Statuses(ctx context.Context) ([]Status, error)
- func (m *Migrator) Up(ctx context.Context) ([]Migration, error)
- func (m *Migrator) UpByOne(ctx context.Context) ([]Migration, error)
- func (m *Migrator) UpTo(ctx context.Context, target int64) ([]Migration, error)
- func (m *Migrator) Version(ctx context.Context) (int64, error)
- type Status
Constants ¶
const VersionTable = "goose_db_version"
VersionTable is the bookkeeping table. The name and columns are goose's, so a database goose has been migrating carries straight over: its history is read as-is, and goose could even be pointed back at it later.
Variables ¶
var ( // Postgres: the exact DDL goose uses, minus the now() default which is // not needed since tstamp is always written explicitly. Postgres = Dialect{Name: "postgres", /* contains filtered or unexported fields */} MySQL = Dialect{Name: "mysql", /* contains filtered or unexported fields */} SQLite = Dialect{Name: "sqlite", /* contains filtered or unexported fields */} // bytdb speaks the Postgres dialect but runs DDL outside transactions. BytDB = Dialect{Name: "bytdb", /* contains filtered or unexported fields */} )
Functions ¶
Types ¶
type Dialect ¶
type Dialect struct {
Name string
// contains filtered or unexported fields
}
Dialect is the little that differs per engine: how to spell the version table, how to spell a placeholder, and whether DDL may run in a transaction.
func DialectFor ¶
DialectFor maps a driver name — a config `driver` value or the canonical database/sql driver name the manager resolves it to — to its Dialect.
type Migration ¶
type Migration struct {
Version int64 // leading number of the file name; the ordering key
Name string // file name, e.g. 20170419004813_CreateUsersTable.sql
Path string // where it was read from
Up []string
Down []string
NoTx bool // run outside a transaction (-- +goose NO TRANSACTION)
}
Migration is one parsed migration file.
func Load ¶
Load reads every migration in dir, sorted by version. Files that do not look like migrations and subdirectories are ignored, so a stash of ad-hoc SQL beside the migrations does not break the run. Two files sharing a version is an error: with one applied and the other not, status would be a lie.
type Migrator ¶
type Migrator struct {
// AllowMissing lets `up` apply a migration whose version is lower than
// one already applied. That happens when two branches each add a
// migration and merge; goose refuses by default because the lower one was
// not tested on top of the higher one, and so do we.
AllowMissing bool
// Log receives a line per migration applied or rolled back. Nil is silent.
Log func(string)
// contains filtered or unexported fields
}
Migrator runs a set of migrations against one database.
func NewWith ¶
NewWith builds a Migrator from already-parsed migrations; they are sorted by version here so callers need not.
func (*Migrator) Down ¶
Down rolls back the most recently applied migration (by version), and returns it.
func (*Migrator) DownTo ¶
DownTo rolls back every applied migration with version > target, newest first. DownTo(0) undoes everything.
func (*Migrator) Migrations ¶
Migrations returns the loaded migrations in version order.
func (*Migrator) Redo ¶
Redo rolls back the latest migration and applies it again — the quickest way to iterate on a migration being written.
func (*Migrator) Statuses ¶
Statuses reports every loaded migration with its applied state, in version order — the `status` command.
func (*Migrator) Up ¶
Up applies every pending migration in version order and returns the ones it applied.
Source Files