Documentation
¶
Overview ¶
Package postgres provides the shared PostgreSQL database infrastructure.
Index ¶
- Constants
- func LoadMigrationFS(path string) (fs.FS, error)
- func OperationCreationUnitOfWork(ctx context.Context, db *gorm.DB, fn func(*gorm.DB, *sql.Tx) error) error
- func RunMigrations(ctx context.Context, db *sql.DB, migrationFS fs.FS) error
- func RunMigrationsDown(ctx context.Context, db *sql.DB, migrationFS fs.FS, steps int) error
- func ValidateDSN(dsn string) error
- func WithConnection(ctx context.Context, db *sql.DB, fn func(*sql.Conn) error) error
- type AdvisoryLock
- type Database
Constants ¶
const MigrationSource = "migrations"
MigrationSource is the filesystem containing ordered *.up.sql and *.down.sql files.
Variables ¶
This section is empty.
Functions ¶
func LoadMigrationFS ¶
LoadMigrationFS loads migrations from a filesystem directory for CLI/tests.
func OperationCreationUnitOfWork ¶
func OperationCreationUnitOfWork(ctx context.Context, db *gorm.DB, fn func(*gorm.DB, *sql.Tx) error) error
OperationCreationUnitOfWork executes fn with a GORM transaction. Raw SQL that must be atomic with GORM writes must use tx.Statement.ConnPool as a *sql.Tx.
func RunMigrations ¶
RunMigrations runs all pending PostgreSQL migrations. ErrNoChange is success; dirty state and all other failures are returned as migration_failed.
func RunMigrationsDown ¶
RunMigrationsDown rolls back the requested number of schema versions. It is intended for explicit operator rollback, never normal service startup.
func ValidateDSN ¶
ValidateDSN validates a PostgreSQL URL without returning credentials.
Types ¶
type AdvisoryLock ¶
type AdvisoryLock struct {
// contains filtered or unexported fields
}
AdvisoryLock holds a PostgreSQL session-level advisory lock. The lock is released automatically when Unlock is called or when the underlying connection returns to the pool.
func AcquireAdvisoryLock ¶
AcquireAdvisoryLock acquires a connection from the shared db pool and obtains a session-level advisory lock on the same connection. Call Unlock to release the lock and return the connection.
func TryAcquireAdvisoryLock ¶
func TryAcquireAdvisoryLock(ctx context.Context, db *sql.DB, key int64) (*AdvisoryLock, bool, error)
TryAcquireAdvisoryLock attempts to acquire a session-level advisory lock without blocking. Returns the lock and true on success, or nil and false if the lock is already held by another session.
func (*AdvisoryLock) Unlock ¶
func (l *AdvisoryLock) Unlock(ctx context.Context) error
Unlock releases the advisory lock and returns the connection to the pool. It is safe to call multiple times; subsequent calls are no-ops.
The caller owns the context: a session-level advisory lock must be released even when the request that acquired it has already timed out, so a request-scoped caller should pass context.WithoutCancel(ctx) rather than the cancellable context itself.
type Database ¶
type Database struct {
// contains filtered or unexported fields
}
Database owns one physical database/sql pool and a GORM wrapper over it.
func Open ¶
Open validates configuration, opens the shared pgx stdlib pool, waits for the server to answer, and wraps the same pool with GORM. It never logs or returns the DSN.
The wait is bounded and only retries transport-level failures (TASK-351): a pod that starts before kube-router has admitted its address to the postgres NetworkPolicy gets ECONNREFUSED for a few hundred milliseconds, and a single ping would turn that window into exit 1 plus a CrashLoopBackOff restart. A server that answers with an error is reported without retrying.
Source Files