Documentation
¶
Overview ¶
Package rivermigrate provides a Go API for running migrations as alternative to migrating via the bundled CLI.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// Logger is the structured logger to use for logging purposes. If none is
// specified, logs will be emitted to STDOUT with messages at warn level
// or higher.
Logger *slog.Logger
}
Config contains configuration for Migrator.
type MigrateOpts ¶
type MigrateOpts struct {
// MaxSteps is the maximum number of migrations to apply either up or down.
// When migrating in the up direction, migrates an unlimited number of steps
// by default. When migrating in the down direction, migrates only a single
// step by default (set TargetVersion to -1 to apply unlimited steps down).
// Set to -1 to apply no migrations (for testing/checking purposes).
MaxSteps int
// TargetVersion is a specific migration version to apply migrations to. The
// version must exist and it must be in the possible list of migrations to
// apply. e.g. If requesting an up migration with version 3, version 3 must
// not already be applied.
//
// When applying migrations up, migrations are applied including the target
// version, so when starting at version 0 and requesting version 3, versions
// 1, 2, and 3 would be applied. When applying migrations down, down
// migrations are applied excluding the target version, so when starting at
// version 5 an requesting version 3, down migrations for versions 5 and 4
// would be applied, leaving the final schema at version 3.
//
// When migrating down, TargetVersion can be set to the special value of -1
// to apply all down migrations (i.e. River schema is removed completely).
TargetVersion int
}
MigrateOpts are options for a migrate operation.
type MigrateResult ¶
type MigrateResult struct {
// Versions are migration versions that were added (for up migrations) or
// removed (for down migrations) for this run.
Versions []MigrateVersion
}
MigrateResult is the result of a migrate operation.
type MigrateVersion ¶
type MigrateVersion struct {
// Version is the version of the migration applied.
Version int
}
MigrateVersion is the result for a single applied migration.
type Migrator ¶
type Migrator[TTx any] struct { baseservice.BaseService // contains filtered or unexported fields }
Migrator is a database migration tool for River which can run up or down migrations in order to establish the schema that the queue needs to run.
func New ¶
func New[TTx any](driver riverdriver.Driver[TTx], config *Config) *Migrator[TTx]
New returns a new migrator with the given database driver and configuration. The config parameter may be omitted as nil.
Currently only one driver is supported, which is Pgx v5. See package riverpgxv5.
The function takes a generic parameter TTx representing a transaction type, but it can be omitted because it'll generally always be inferred from the driver. For example:
import "github.com/riverqueue/river/riverdriver/riverpgxv5"
import "github.com/riverqueue/rivermigrate"
...
dbPool, err := pgxpool.New(ctx, os.Getenv("DATABASE_URL"))
if err != nil {
// handle error
}
defer dbPool.Close()
migrator, err := rivermigrate.New(riverpgxv5.New(dbPool), nil)
if err != nil {
// handle error
}
func (*Migrator[TTx]) Migrate ¶
func (m *Migrator[TTx]) Migrate(ctx context.Context, direction Direction, opts *MigrateOpts) (*MigrateResult, error)
Migrate migrates the database in the given direction (up or down). The opts parameter may be omitted for convenience.
By default, applies all outstanding migrations when moving in the up direction, but for safety, only one step when moving in the down direction. To migrate more than one step down, MigrateOpts.MaxSteps or MigrateOpts.TargetVersion are available. Setting MigrateOpts.TargetVersion to -1 will apply every available downstep so that River's schema is removed completely.
res, err := migrator.Migrate(ctx, rivermigrate.DirectionUp, nil)
if err != nil {
// handle error
}
func (*Migrator[TTx]) MigrateTx ¶
func (m *Migrator[TTx]) MigrateTx(ctx context.Context, tx TTx, direction Direction, opts *MigrateOpts) (*MigrateResult, error)
Migrate migrates the database in the given direction (up or down). The opts parameter may be omitted for convenience.
By default, applies all outstanding migrations when moving in the up direction, but for safety, only one step when moving in the down direction. To migrate more than one step down, MigrateOpts.MaxSteps or MigrateOpts.TargetVersion are available. Setting MigrateOpts.TargetVersion to -1 will apply every available downstep so that River's schema is removed completely.
res, err := migrator.MigrateTx(ctx, tx, rivermigrate.DirectionUp, nil)
if err != nil {
// handle error
}
This variant lets a caller run migrations within a transaction. Postgres DDL is transactional, so migration changes aren't visible until the transaction commits, and are rolled back if the transaction rolls back.
Source Files