Documentation
¶
Overview ¶
Package pgmigrate provides a PostgreSQL-specific migration executor for the Grove migration system.
Index ¶
- func Render(op migrate.Operation) ([]string, error)
- type Executor
- func (e *Executor) AcquireLock(ctx context.Context, lockedBy string) error
- func (e *Executor) BeginTx(ctx context.Context) error
- func (e *Executor) CommitTx(ctx context.Context) error
- func (e *Executor) DriverName() string
- func (e *Executor) EnsureLockTable(ctx context.Context) error
- func (e *Executor) EnsureMigrationTable(ctx context.Context) error
- func (e *Executor) Exec(ctx context.Context, query string, args ...any) (driver.Result, error)
- func (e *Executor) ListApplied(ctx context.Context) ([]*migrate.AppliedMigration, error)
- func (e *Executor) LockInfo(ctx context.Context) (*migrate.LockInfo, error)
- func (e *Executor) Query(ctx context.Context, query string, args ...any) (driver.Rows, error)
- func (e *Executor) RecordApplied(ctx context.Context, m *migrate.Migration) error
- func (e *Executor) ReleaseLock(ctx context.Context) error
- func (e *Executor) RemoveApplied(ctx context.Context, m *migrate.Migration) error
- func (e *Executor) RollbackTx(ctx context.Context) error
- type Renderer
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Executor ¶
type Executor struct {
// contains filtered or unexported fields
}
Executor implements migrate.Executor for PostgreSQL.
When the underlying driver supports driver.ConnAcquirer, the executor acquires a dedicated connection in [AcquireLock] and routes ALL subsequent operations through it until [ReleaseLock]. This guarantees that the session-level pg_try_advisory_lock is acquired and released on the same connection, preventing advisory-lock leaks in pooled environments.
That same connection carries the transaction a migration runs in (see Executor.BeginTx), which is why the transaction lives here and not with the caller: every statement has to land on the session that holds the lock.
func (*Executor) AcquireLock ¶
AcquireLock attempts to acquire the distributed migration lock using PostgreSQL advisory locks for immediate feedback.
If the driver implements driver.ConnAcquirer, a dedicated connection is acquired first so that the advisory lock and all subsequent migration operations share the same session. This prevents lock leaks when using connection pools.
func (*Executor) BeginTx ¶ added in v1.10.0
BeginTx opens a transaction on the connection that holds the migration lock. Exec, Query, RecordApplied and RemoveApplied all prefer that connection, so until CommitTx or RollbackTx they run inside the transaction.
Without a dedicated connection the transaction and the lock can't share a session, so BeginTx returns migrate.ErrTxUnsupported and the migration runs without one.
func (*Executor) DriverName ¶ added in v1.10.0
DriverName reports the driver this executor runs on. The builders use it to pick the schema renderer registered for Postgres.
func (*Executor) EnsureLockTable ¶
EnsureLockTable creates the grove_migration_locks table if it doesn't exist.
func (*Executor) EnsureMigrationTable ¶
EnsureMigrationTable creates the grove_migrations table if it doesn't exist.
func (*Executor) ListApplied ¶
ListApplied returns all migrations that have been applied, ordered by migrated_at ascending.
func (*Executor) LockInfo ¶
LockInfo reports the current migration lock holder recorded in the lock table. It satisfies migrate.LockInspector, letting the orchestrator produce a diagnosable error when the lock-wait budget is exhausted.
func (*Executor) RecordApplied ¶
RecordApplied records that a migration was successfully applied.
func (*Executor) ReleaseLock ¶
ReleaseLock releases the distributed migration lock. If a dedicated connection was acquired in [AcquireLock], the advisory lock is released on that same connection before the connection is returned to the pool.
func (*Executor) RemoveApplied ¶
RemoveApplied removes the record of an applied migration (for rollback).
func (*Executor) RollbackTx ¶ added in v1.10.0
RollbackTx abandons the transaction BeginTx opened. It returns nil when none is open. After a failed CommitTx the transaction still counts as open, so it sends ROLLBACK anyway, which Postgres answers with a warning, not an error, when the server has already ended the transaction.
type Renderer ¶ added in v1.10.0
type Renderer struct{}
Renderer applies schema operations to Postgres. It is what the pg executor registers with the migrate package, so a migration's builders reach it.
Source Files