Documentation
¶
Overview ¶
Package db is the PostgreSQL access layer shared by all services (spec 02 §7, ADR-0004): a pgx connection pool, transactions, optimistic locking, forward-only migrations and pool metrics.
Every service owns its own database and role (REQ-PLT-080); nothing in this package crosses that boundary.
Index ¶
- Constants
- Variables
- func Check(pool *pgxpool.Pool) func(ctx context.Context) error
- func ExpectRow(tag pgconn.CommandTag, err error) error
- func InTx(ctx context.Context, b Beginner, opts pgx.TxOptions, fn func(tx pgx.Tx) error) (err error)
- func IsUniqueViolation(err error, constraint string) bool
- func Migrate(ctx context.Context, pool *pgxpool.Pool, fsys fs.FS) ([]string, error)
- func MigrateTable(ctx context.Context, pool *pgxpool.Pool, fsys fs.FS, versionTable string) ([]string, error)
- func Open(ctx context.Context, cfg Config) (*pgxpool.Pool, error)
- func ValidateMigrations(fsys fs.FS) error
- type Beginner
- type Config
- type PoolCollector
Constants ¶
const DefaultVersionTable = "goose_db_version"
DefaultVersionTable is goose's own version table, used by Migrate for a service's schema.
Variables ¶
var ErrConflict = errors.New("db: version conflict")
ErrConflict means an optimistic-locking update matched no row: the row was changed (version bumped) or deleted concurrently. Services map it to apierr.EtagMismatch.
Functions ¶
func ExpectRow ¶
func ExpectRow(tag pgconn.CommandTag, err error) error
ExpectRow checks the result of a versioned write such as
UPDATE instances SET ..., version = version + 1 WHERE id = $1 AND version = $2
and returns ErrConflict if no row was affected.
func InTx ¶
func InTx(ctx context.Context, b Beginner, opts pgx.TxOptions, fn func(tx pgx.Tx) error) (err error)
InTx runs fn in a transaction: committed if fn returns nil, rolled back if it returns an error or panics (the panic is re-raised).
func IsUniqueViolation ¶
IsUniqueViolation reports whether err is a unique-constraint violation, optionally on the named constraint (e.g. a resource name index).
func Migrate ¶
Migrate validates and applies all pending migrations from fsys and returns the names applied in this run.
func MigrateTable ¶
func MigrateTable(ctx context.Context, pool *pgxpool.Pool, fsys fs.FS, versionTable string) ([]string, error)
MigrateTable is Migrate with a separate version table. Shared libraries that ship tables into every service database (pkg/operation, pkg/outbox) number their migrations independently of the service and track them in their own table, e.g. "qs_operation_db_version".
func ValidateMigrations ¶
ValidateMigrations checks the migration files in fsys (embed.FS of a service's store/migrations): names are NNNN_name.sql with consecutive numbers from 0001, every file has an Up section and none has a non-empty Down section — migrations only go forward (spec 02 §7, expand/contract).
Types ¶
type Beginner ¶
Beginner is satisfied by *pgxpool.Pool and pgx.Tx (nested transactions become savepoints).
type Config ¶
type Config struct {
// DSN is a PostgreSQL URL or key/value string. It contains a password:
// never log it.
DSN string
// ApplicationName is reported to PostgreSQL (pg_stat_activity).
ApplicationName string
// MaxConns and MinConns bound the pool size; 0 keeps the pgx default.
MaxConns int32
MinConns int32
// MaxConnLifetime recycles connections, e.g. after a primary switchover.
MaxConnLifetime time.Duration
// ConnectTimeout bounds Open's initial ping; default 10s.
ConnectTimeout time.Duration
}
Config configures the connection pool.
type PoolCollector ¶
type PoolCollector struct {
// contains filtered or unexported fields
}
PoolCollector exports pgxpool statistics as qs_db_pool_* metrics (REQ-OBS-001).
func NewPoolCollector ¶
func NewPoolCollector(pool *pgxpool.Pool) *PoolCollector
NewPoolCollector returns a collector for pool; register it with prometheus.Registerer.MustRegister.
func (*PoolCollector) Collect ¶
func (c *PoolCollector) Collect(ch chan<- prometheus.Metric)
Collect implements prometheus.Collector.
func (*PoolCollector) Describe ¶
func (c *PoolCollector) Describe(ch chan<- *prometheus.Desc)
Describe implements prometheus.Collector.
Source Files