Documentation
¶
Index ¶
- type Migration
- type Option
- type Registry
- func (r *Registry) Down(ctx context.Context, db *den.DB) error
- func (r *Registry) DownOne(ctx context.Context, db *den.DB) error
- func (r *Registry) Register(version string, m Migration)
- func (r *Registry) Up(ctx context.Context, db *den.DB) error
- func (r *Registry) UpOne(ctx context.Context, db *den.DB) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Migration ¶
type Migration struct {
Forward func(ctx context.Context, tx *den.Tx) error
Backward func(ctx context.Context, tx *den.Tx) error
}
Migration defines a forward and optional backward migration function. Both receive a transaction for atomic execution.
type Option ¶ added in v0.11.0
type Option func(*Registry)
Option configures a Registry at construction time.
func WithLogger ¶ added in v0.11.0
WithLogger sets the slog.Logger that receives migration lifecycle events. When unset, the Registry uses slog.Default().
Events emitted (all with the migration's version attached as "version" and the direction as "direction" = "up" | "down"):
- "migration_start" — a migration is about to run
- "migration_success" — migration completed; "duration_ms" attached
- "migration_failure" — migration failed; "duration_ms" and "error" attached (the error is NOT re-logged at the caller's log site — the error value still bubbles up through the return chain)
- "ensure_table_failure" — the one-time migration-log setup failed; "error" attached. Subsequent calls reuse the cached failure, so this event fires at most once per Registry.
Passing a nil logger is treated as "use slog.Default()" — keeps callers honest if they accidentally thread nil through a config struct.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry holds registered migrations and provides the runner API.
A Registry caches the result of its one-time migration-log setup: the first Up/UpOne/Down/DownOne caller runs EnsureCollection for the internal _den_migrations collection, and every subsequent call on the same Registry reuses that outcome — success OR error. This keeps concurrent in-process starters from racing CREATE INDEX CONCURRENTLY on PostgreSQL, but it also means startup errors are sticky: if EnsureCollection fails (wrong credentials, missing permissions, unreachable backend), every subsequent call returns the same cached error even after the underlying problem is fixed. To retry, construct a fresh Registry with NewRegistry and re- Register every migration; there is no Reset by design — tests that need a clean slate should rebuild the Registry.
func NewRegistry ¶
NewRegistry creates a new migration registry. Optional arguments configure the registry; see WithLogger.
func (*Registry) Down ¶
Down rolls back all applied migrations in reverse order, each in its own transaction.
See the Registry godoc for the one-time migration-log setup and the sticky-error caveat that affects repeated calls.
func (*Registry) DownOne ¶
DownOne rolls back the last applied migration in a transaction.
See the Registry godoc for the one-time migration-log setup and the sticky-error caveat that affects repeated calls.
func (*Registry) Register ¶
Register adds a migration with the given version identifier. Versions are sorted lexicographically for execution order.
func (*Registry) Up ¶
Up runs all pending forward migrations, each in its own transaction. Concurrent starters serialize on an advisory lock; every registered migration runs exactly once across processes.
See the Registry godoc for the one-time migration-log setup and the sticky-error caveat that affects repeated calls.
func (*Registry) UpOne ¶
UpOne runs the next pending forward migration in a transaction. Loads the current applied set to find the first pending version; the actual "apply exactly once" guarantee comes from the lock in runForward.
See the Registry godoc for the one-time migration-log setup and the sticky-error caveat that affects repeated calls.
Source Files