README
¶
simplemigrations helps you run ordered database migrations in Go while
staying agnostic to the underlying transport. You provide transactional
primitives and the package coordinates schema upgrades.
core ideas
- implement
MinimalTx- it executes migration statements and records schema versions
- you can optionally implement
TxandDBfor integration with PostgreSQL- when present, the library can create schemas and manage retries through
MigrateToLatestWithSchema
- when present, the library can create schemas and manage retries through
- you can also supply a
Loggerto observe migration progressNopLoggeris available when you do not need logging
MigrateToLatest is the general entry point. Use
MigrateToLatestWithSchema only with PostgreSQL-backed implementations
that expose the additional DB/Tx methods.
getting started
- implement
MinimalTx(and optionallyTx,DB,Logger) - build a slice of
Migrationvalues ordered by version - call
MigrateToLatestwith your transaction, migrations, and logger of choice
See simplemigrations_test.go for a runnable example showing the
expected behaviours.
Documentation
¶
Overview ¶
Package simplemigrations provides helpers for applying ordered migrations against transactional backends.
Index ¶
- func MigrateToLatest(ctx context.Context, log Logger, tx MinimalTx, migrations []Migration, ...) error
- func MigrateToLatestWithSchema(ctx context.Context, log Logger, db DB, schema string, temporary bool, ...) (cleanup func() error, err error)
- func RollbackUnlessCommitted(ctx context.Context, log Logger, tx Tx) error
- func SetSearchPathTo(ctx context.Context, tx MinimalTx, schema string) error
- type DB
- type Dialect
- type Logger
- type Migration
- type MinimalTx
- type NopLogger
- type Tx
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func MigrateToLatest ¶
func MigrateToLatest(ctx context.Context, log Logger, tx MinimalTx, migrations []Migration, freshDB bool) error
MigrateToLatest runs pending migrations within the provided transaction.
func MigrateToLatestWithSchema ¶
func MigrateToLatestWithSchema(ctx context.Context, log Logger, db DB, schema string, temporary bool, migrations []Migration, shouldRetry func(err error) bool) (cleanup func() error, err error)
MigrateToLatestWithSchema runs pending migrations, optionally creating an isolated schema.
func RollbackUnlessCommitted ¶
RollbackUnlessCommitted rolls back the transaction unless it has already been committed.
Types ¶
type DB ¶
type DB interface {
Dialect() Dialect
Open(ctx context.Context) (Tx, error)
ExecContext(ctx context.Context, query string, args ...any) error
}
DB opens transactional connections and reports the active dialect.
type Dialect ¶
type Dialect string
Dialect identifies the database dialect supported by simplemigrations.
const ( // DialectPostgres identifies the PostgreSQL dialect. DialectPostgres Dialect = "postgres" )
type Logger ¶
type Logger interface {
Debug(ctx context.Context, msg string, args ...any)
Info(ctx context.Context, msg string, args ...any)
Warn(ctx context.Context, msg string, args ...any)
}
Logger records diagnostic messages about migration progress.
type MinimalTx ¶
type MinimalTx interface {
ExecContext(ctx context.Context, query string, args ...any) error
LatestSchemaVersion(ctx context.Context) (int, error)
CreateSchema(ctx context.Context, version int, comment string) error
}
MinimalTx executes migration queries and manages schema versions.
Source Files
Directories