Documentation
¶
Overview ¶
Package migrate applies SQL schema migrations from an embedded filesystem.
It wraps github.com/pressly/goose using goose's Provider API, so callers never touch goose's process-global state (SetBaseFS/SetDialect) and several migrators can coexist in one process (e.g. app vs tests). Migrations are read from an fs.FS — typically an embed.FS of `*.sql` files — so they ship inside the binary.
Usage ¶
//go:embed *.sql
var migrationsFS embed.FS
m, err := migrate.New(migrate.Postgres, db.DB, migrationsFS)
if err != nil {
return err
}
defer m.Close()
if err := m.Up(ctx); err != nil {
return err
}
New takes a *sql.DB opened with a driver matching the dialect (e.g. a pgx connection for migrate.Postgres). It does not take ownership of db; Close releases only the provider, never the handle. Use fs.Sub if the migrations live in a subdirectory of the embedded FS.
Operations ¶
- Up applies every pending migration in version order (a no-op when current).
- Down rolls back the most recently applied migration.
- Version returns the current applied schema version (0 before any migration).
- Status returns the applied state of every known migration, ordered by version, as []MigrationStatus.
Dialects ¶
The supported dialects are re-exported so callers need not import goose: Postgres, MySQL, SQLite3. Dialect is an alias for goose.Dialect.
Index ¶
Constants ¶
const ( Postgres = goose.DialectPostgres MySQL = goose.DialectMySQL SQLite3 = goose.DialectSQLite3 )
Supported dialects, re-exported so callers need not import goose directly.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type MigrationStatus ¶
MigrationStatus is the applied state of a single migration.
type Migrator ¶
type Migrator struct {
// contains filtered or unexported fields
}
Migrator applies goose migrations against a database/sql handle. Construct it with New and release it with Close. It is safe to reuse across calls.
func New ¶
New builds a Migrator for the given dialect, database handle and migration filesystem. fsys is usually an embed.FS rooted at the `*.sql` files; pass the embedded FS directly (use fs.Sub if the migrations live in a subdirectory).
The handle must be opened with a driver matching dialect — e.g. a pgx/lib-pq connection for migrate.Postgres. New does not take ownership of db; Close releases only the provider.
func (*Migrator) Close ¶
Close releases the provider's resources. It does not close the underlying database handle passed to New.
func (*Migrator) Status ¶
func (m *Migrator) Status(ctx context.Context) ([]MigrationStatus, error)
Status returns the applied state of every known migration, ordered by version.
Source Files