Documentation
¶
Overview ¶
Package db owns the Postgres connection lifecycle. S01 ships the open/healthcheck/transaction helpers; later sprints add domain-specific wrappers but always go through this package for the pool.
Index ¶
- Variables
- func FromContext(ctx context.Context) int64
- func Healthcheck(ctx context.Context, pool *pgxpool.Pool) error
- func Migrate(ctx context.Context, cfg Config, action MigrateAction) error
- func Open(ctx context.Context, cfg Config) (*pgxpool.Pool, error)
- func SetMigrationsFS(fsys fs.FS)
- func WithCounter(ctx context.Context) context.Context
- func WithTx(ctx context.Context, pool *pgxpool.Pool, fn func(pgx.Tx) error) (err error)
- type Config
- type MigrateAction
- type QueryCounter
Constants ¶
This section is empty.
Variables ¶
var ErrNoURL = errors.New("db: no DATABASE_URL configured (set SHITHUB_DATABASE_URL)")
ErrNoURL is returned by Open when neither cfg.URL nor SHITHUB_DATABASE_URL is set.
Functions ¶
func FromContext ¶
FromContext reports how many tracer events have fired against ctx. Returns 0 when WithCounter wasn't called on this context.
func Healthcheck ¶
Healthcheck performs a fast SELECT 1 against the pool with a short timeout. Used by /readyz.
func Migrate ¶
func Migrate(ctx context.Context, cfg Config, action MigrateAction) error
Migrate runs the requested goose action against the pool's underlying database. We reuse the pool's connection config rather than opening a fresh sql.DB from scratch, so the same DSN env-var-driven configuration applies to migrations.
goose requires `database/sql`. We bridge from pgx's connection config using `pgx/v5/stdlib`.
func Open ¶
Open creates a new pgx pool from cfg. The caller owns the pool's lifecycle and must call pool.Close() on shutdown.
func SetMigrationsFS ¶
SetMigrationsFS registers the migrations filesystem. The repo's `internal/migrationsfs` package embeds and registers it; tests can swap it for a fixture FS.
func WithCounter ¶
WithCounter returns a derived context that records query counts. Pair with Read.
Types ¶
type Config ¶
type Config struct {
URL string
MaxConns int32
MinConns int32
ConnectTimeout time.Duration
StatementCancel time.Duration
}
Config carries the pool's connection settings. S03 will populate this from the layered config loader; for S01 we accept an optional explicit URL or fall back to SHITHUB_DATABASE_URL.
type MigrateAction ¶
type MigrateAction string
MigrateAction is one of the migrate operations the CLI exposes.
const ( MigrateUp MigrateAction = "up" MigrateDown MigrateAction = "down" MigrateStatus MigrateAction = "status" MigrateVersion MigrateAction = "version" MigrateRedo MigrateAction = "redo" MigrateReset MigrateAction = "reset" )
type QueryCounter ¶
type QueryCounter struct{}
QueryCounter is a pgx QueryTracer that increments a per-context counter on every Query/QueryRow/Exec. The counter lives on the request context, so the tracer is safe to install at pool-config time even when most requests don't care.
Use case: handler integration tests assert "this route does ≤ N DB queries." The tracer + WithCounter / FromContext + a tiny middleware (web/middleware/query_count_assert.go) make that assertion a one-liner.
Production runs leave the tracer installed but never call WithCounter; the per-conn overhead is one atomic-load per query (the tracer reads the context value but the counter is nil so no Add fires).
func (QueryCounter) TraceQueryEnd ¶
func (QueryCounter) TraceQueryEnd(context.Context, *pgx.Conn, pgx.TraceQueryEndData)
TraceQueryEnd implements pgx.QueryTracer. No-op; the start tick is the meaningful event.
func (QueryCounter) TraceQueryStart ¶
func (QueryCounter) TraceQueryStart(ctx context.Context, _ *pgx.Conn, _ pgx.TraceQueryStartData) context.Context
TraceQueryStart implements pgx.QueryTracer. The counter increments at start, not end, so a slow query still counts.
Source Files