Documentation
¶
Overview ¶
Package migrate runs versioned schema migrations in batches, Knex-style.
Index ¶
- func DropAllTables(ctx context.Context, db *migro.DB) error
- func Register(d Definition)
- func RegisterAs(name string, d Definition)
- func ResetRegistry()
- func SplitStatements(src string) []string
- type ConnectionPinned
- type Definition
- type Dump
- type Event
- type EventKind
- type Func
- type Migration
- type Migrator
- func (m *Migrator) Add(ms ...Migration) error
- func (m *Migrator) AddRegistered() error
- func (m *Migrator) DB() *migro.DB
- func (m *Migrator) Dump(ctx context.Context) (Dump, error)
- func (m *Migrator) Fresh(ctx context.Context) (Result, error)
- func (m *Migrator) Install(ctx context.Context) error
- func (m *Migrator) Latest(ctx context.Context) (Result, error)
- func (m *Migrator) LoadDump(ctx context.Context, d Dump) error
- func (m *Migrator) Refresh(ctx context.Context) (Result, error)
- func (m *Migrator) Reset(ctx context.Context) (Result, error)
- func (m *Migrator) Revert(ctx context.Context, opts RevertOptions) (Result, error)
- func (m *Migrator) Rollback(ctx context.Context) (Result, error)
- func (m *Migrator) RollbackSteps(ctx context.Context, n int) (Result, error)
- func (m *Migrator) RollbackToBatch(ctx context.Context, batch int) (Result, error)
- func (m *Migrator) Run(ctx context.Context, opts RunOptions) (Result, error)
- func (m *Migrator) Status(ctx context.Context) ([]Status, error)
- func (m *Migrator) Unlock(ctx context.Context) error
- type Option
- type Result
- type RevertOptions
- type RunOptions
- type Status
- type TransactionOptOut
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DropAllTables ¶
DropAllTables removes every table, retrying so foreign-key order does not matter.
func Register ¶
func Register(d Definition)
Register records a migration whose name is taken from the calling file's name. Invalid or duplicate names are reported by Registered / AddRegistered, never by panicking in init().
func RegisterAs ¶
func RegisterAs(name string, d Definition)
RegisterAs registers a migration under an explicit name.
func SplitStatements ¶
SplitStatements splits SQL on semicolons, ignoring those in quotes and -- comments.
Types ¶
type ConnectionPinned ¶
type ConnectionPinned interface{ Connection() string }
ConnectionPinned pins a migration to a named connection (Lucid's `connection`).
type Definition ¶
type Definition interface {
Up(ctx context.Context, s *schema.Builder) error
Down(ctx context.Context, s *schema.Builder) error
}
Definition is a Lucid-style migration class: put one in each file named <yyyymmddhhmmss>_<snake_case_name>.go and register it from init().
func init() { migrate.Register(&CreateUsersTable{}) }
type Dump ¶
Dump is a squashed schema: the SQL every migration would run on an empty database, plus the names of those migrations. Loading it into a fresh database replaces running them one by one, so old migration files can be retired without losing the ability to build a new database.
A dump is built by running each migration in pretend mode, so it needs no external tool (no pg_dump or mysqldump) and is portable only within the dialect it was generated for.
type Func ¶
Func is one direction of a migration. It receives a schema builder bound to the migration's transaction (when the dialect supports transactional DDL).
type Migration ¶
type Migration struct {
Name string
Up Func
Down Func
// DisableTransaction runs the migration without a wrapping transaction.
DisableTransaction bool
// Checksum is optional; when set, edits to an applied migration are detected.
Checksum string
// Connection pins the migration to a named connection; "" means the default one.
Connection string
}
Migration is a named, ordered unit of change. Names sort lexicographically (use a timestamp prefix such as 20240101120000_create_users).
func FromFS ¶
FromFS loads "<name>.up.sql" / "<name>.down.sql" pairs from dir in fsys. Statements are split on ";" (outside quotes and -- comments); stored procedures with inner semicolons need a Go migration instead.
func Registered ¶
Registered returns every registered migration sorted by name, or the registration errors.
type Migrator ¶
type Migrator struct {
// contains filtered or unexported fields
}
Migrator applies and rolls back migrations, recording them in a table.
func (*Migrator) AddRegistered ¶
AddRegistered adds every migration registered through Register.
func (*Migrator) Dump ¶
Dump squashes the migrator's migrations. Nothing is written to the database. Run it against an empty database: a migration that inspects the existing schema (HasTable, ...) would otherwise record a different history.
func (*Migrator) Fresh ¶
Fresh drops every table in the database (not just migrated ones), then applies all migrations. It is destructive: callers decide whether it is allowed.
func (*Migrator) Install ¶
Install creates the migration bookkeeping tables. Every other method does this on demand; call Install to do it explicitly (migration:install).
func (*Migrator) LoadDump ¶
LoadDump executes the dump and records its migrations as applied in one batch.
func (*Migrator) RollbackSteps ¶
RollbackSteps reverts the n most recently applied migrations.
func (*Migrator) RollbackToBatch ¶
RollbackToBatch reverts every migration applied after batch.
type Option ¶
type Option func(*Migrator)
Option customises a Migrator.
func WithConnection ¶
WithConnection restricts the Migrator to migrations pinned to connection selected, plus unpinned ones when selected is the default connection.
func WithDump ¶
WithDump makes Run load the dump into a database that has no applied migrations, then run only the migrations the dump does not cover.
func WithObserver ¶
WithObserver receives an Event before and after every migration step.
type Result ¶
type Result struct {
Batch int
Names []string
// SQL holds, per migration, the statements that would run. Only set by pretend runs.
SQL map[string][]string
}
Result lists the migrations a call applied or reverted.
type RevertOptions ¶
type RevertOptions struct {
// Steps reverts the N most recently applied migrations (Laravel's --step).
Steps int
// ToBatch reverts every migration applied after the given batch; 0 reverts everything (Adonis' --batch).
ToBatch *int
All bool
Pretend bool
}
RevertOptions select what to roll back. Set at most one of Steps, ToBatch, All; with none set the most recent batch is reverted.
type RunOptions ¶
type RunOptions struct {
// Step puts every migration in its own batch so each can be rolled back on its own.
Step bool
// Pretend returns the SQL each migration would run and changes nothing.
Pretend bool
}
RunOptions tune Run.
type TransactionOptOut ¶
type TransactionOptOut interface{ DisableTransaction() bool }
TransactionOptOut opts a migration out of the wrapping transaction.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package diff compares GORM models with a live database and writes the difference as migration files (the same .up.sql / .down.sql format migrate.FromFS reads).
|
Package diff compares GORM models with a live database and writes the difference as migration files (the same .up.sql / .down.sql format migrate.FromFS reads). |