README
¶
migrator
import "github.com/brpaz/lib-go/db/migrator"
Package migrator runs database schema migrations using goose.
Basic usage
Pass an *sql.DB and an fs.FS containing SQL files under a "migrations/" sub-path. Callers typically embed the files and pass the resulting embed.FS:
//go:embed migrations/*.sql
var migrationsFS embed.FS
m, err := migrator.NewMigrator(db, migrationsFS)
Migrator.Migrate applies all pending UP migrations. Migrator.Rollback reverts the last applied migration. Migrator.Status logs the current applied/pending state.
Logging
By default the migrator discards all output. Supply a Logger via WithLogger to route migration output to your preferred sink:
m, err := migrator.NewMigrator(db, fsys,
migrator.WithLogger(migrator.NewLibLogger(appLogger)),
)
NewLibLogger wraps a github.com/brpaz/lib\-go/logging.Logger. NewNopLogger discards output. Any value that implements Logger (Printf + Fatalf) is accepted, so adapters for zap, logrus, or other libraries can be plugged in directly.
Concurrency
goose uses package-level global state (base FS, dialect, table name). Avoid running multiple Migrator instances concurrently with different options.
Index
Constants
const (
DialectPostgres = "postgres"
DialectSqlite = "sqlite3"
)
type Logger
Logger is the logging interface consumed by Migrator. It mirrors the goose.Logger contract so any adapter that satisfies goose also satisfies this interface.
type Logger interface {
Printf(format string, v ...any)
Fatalf(format string, v ...any)
}
func NewLibLogger
func NewLibLogger(l *logging.Logger) Logger
NewLibLogger returns a Logger backed by a [logging.Logger]. Printf maps to Info; Fatalf maps to Error followed by os.Exit(1).
func NewNopLogger
func NewNopLogger() Logger
NewNopLogger returns a Logger that discards all output.
type Migrator
Migrator runs database schema migrations using goose.
Note: goose uses package-level global state (base FS, dialect, table name). Avoid running multiple Migrator instances concurrently with different options.
type Migrator struct {
// contains filtered or unexported fields
}
func NewMigrator
func NewMigrator(db *sql.DB, fsys fs.FS, opts ...Option) (*Migrator, error)
NewMigrator constructs a Migrator. fsys must contain the SQL migration files. By default migrations are read from the root of fsys; use WithMigrationsDir to specify a sub-directory (e.g. when using //go:embed migrations/*.sql from a parent package).
func (*Migrator) Migrate
func (m *Migrator) Migrate(ctx context.Context) error
Migrate runs all pending UP migrations.
func (*Migrator) Rollback
func (m *Migrator) Rollback(ctx context.Context) error
Rollback rolls back the last applied migration.
func (*Migrator) Status
func (m *Migrator) Status(ctx context.Context) error
Status logs the current applied/pending state of all migrations.
type Option
Option is a functional option for configuring the Migrator.
type Option func(*Migrator)
func WithDialect
func WithDialect(dialect string) Option
WithDialect sets the SQL dialect used by goose. Defaults to "postgres". Valid values are the dialect names accepted by goose.SetDialect.
func WithLogger
func WithLogger(logger Logger) Option
WithLogger sets the logger used for migration output. Use NewLibLogger or NewNopLogger, or supply any Logger implementation.
func WithMigrationsDir
func WithMigrationsDir(dir string) Option
WithMigrationsDir sets the directory within fsys that contains the SQL files. Defaults to "." (root of fsys). Use this when the embed FS contains a named sub-directory, e.g. WithMigrationsDir("migrations").
func WithSchemaTableName
func WithSchemaTableName(name string) Option
Generated by gomarkdoc
Documentation
¶
Overview ¶
Package migrator runs database schema migrations using goose.
Basic usage ¶
Pass an *sql.DB and an fs.FS containing SQL files under a "migrations/" sub-path. Callers typically embed the files and pass the resulting embed.FS:
//go:embed migrations/*.sql var migrationsFS embed.FS m, err := migrator.NewMigrator(db, migrationsFS)
Migrator.Migrate applies all pending UP migrations. Migrator.Rollback reverts the last applied migration. Migrator.Status logs the current applied/pending state.
Logging ¶
By default the migrator discards all output. Supply a Logger via WithLogger to route migration output to your preferred sink:
m, err := migrator.NewMigrator(db, fsys,
migrator.WithLogger(migrator.NewLibLogger(appLogger)),
)
NewLibLogger wraps a github.com/brpaz/lib-go/logging.Logger. NewNopLogger discards output. Any value that implements Logger (Printf + Fatalf) is accepted, so adapters for zap, logrus, or other libraries can be plugged in directly.
Concurrency ¶
goose uses package-level global state (base FS, dialect, table name). Avoid running multiple Migrator instances concurrently with different options.
Index ¶
Constants ¶
const ( DialectPostgres = "postgres" DialectSqlite = "sqlite3" )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Logger ¶
Logger is the logging interface consumed by Migrator. It mirrors the goose.Logger contract so any adapter that satisfies goose also satisfies this interface.
func NewLibLogger ¶
NewLibLogger returns a Logger backed by a logging.Logger. Printf maps to Info; Fatalf maps to Error followed by os.Exit(1).
func NewNopLogger ¶
func NewNopLogger() Logger
NewNopLogger returns a Logger that discards all output.
type Migrator ¶
type Migrator struct {
// contains filtered or unexported fields
}
Migrator runs database schema migrations using goose.
Note: goose uses package-level global state (base FS, dialect, table name). Avoid running multiple Migrator instances concurrently with different options.
func NewMigrator ¶
NewMigrator constructs a Migrator. fsys must contain the SQL migration files. By default migrations are read from the root of fsys; use WithMigrationsDir to specify a sub-directory (e.g. when using //go:embed migrations/*.sql from a parent package).
type Option ¶
type Option func(*Migrator)
Option is a functional option for configuring the Migrator.
func WithDialect ¶
WithDialect sets the SQL dialect used by goose. Defaults to "postgres". Valid values are the dialect names accepted by goose.SetDialect.
func WithLogger ¶
WithLogger sets the logger used for migration output. Use NewLibLogger or NewNopLogger, or supply any Logger implementation.
func WithMigrationsDir ¶
WithMigrationsDir sets the directory within fsys that contains the SQL files. Defaults to "." (root of fsys). Use this when the embed FS contains a named sub-directory, e.g. WithMigrationsDir("migrations").
Source Files