v1.0.0

code.nochebuena.dev/go/postgres

Overview

postgres v1.0.0 commits the database client API as stable. All v0.9.0 roadmap items are
resolved. The module ships a pgx v5-native PostgreSQL client that integrates with the launcher
lifecycle and health check systems, maps PostgreSQL errors to portable xerrors codes, and
provides UnitOfWork for transactional repository patterns via context injection.

What Changed Since v0.9.0

New in Client interface

BeginTx(ctx context.Context, opts pgx.TxOptions) (Tx, error) — starts a transaction with
explicit isolation level and read-only options using pgx-native pgx.TxOptions. Begin(ctx)
is now a convenience wrapper calling BeginTx(ctx, pgx.TxOptions{}).

tx, err := db.BeginTx(ctx, pgx.TxOptions{
    IsoLevel:   pgx.Serializable,
    AccessMode: pgx.ReadWrite,
})

New in Component interface

Stats() *pgxpool.Stat — exposes connection pool metrics for observability. Returns a
zero-value *pgxpool.Stat when called before OnInit. Useful for Prometheus gauges or
health dashboards:

stats := db.Stats()
// stats.TotalConns(), stats.IdleConns(), stats.AcquiredConns(), stats.MaxConns()

Dependency bumps

All micro-lib dependencies promoted to v1.0.0: logz, health, launcher, xerrors.

Roadmap items resolved

Item	Resolution
`BeginTx(ctx, opts)` for serialisable isolation	✅ Added to `Client` with `pgx.TxOptions`; `Begin` refactored as wrapper
`Stats()` for pool observability	✅ Added `Stats() *pgxpool.Stat` to `Component`
`SELECT 1` health check option	❌ No — `pgxpool.Ping` already acquires a real connection and does a round-trip; SELECT 1 adds no additional signal
Production feedback on pool defaults	✅ Validated as-is — `MaxConns=5`, `MinConns=2`, `1h`/`30m`/`1m` confirmed in production

Full API (stable)

Executor — Exec, Query, QueryRow using pgx v5 native types (pgconn.CommandTag, pgx.Rows, pgx.Row).

Tx — extends Executor with Commit(ctx) error, Rollback(ctx) error.

Client — GetExecutor(ctx) Executor, Begin(ctx) (Tx, error), BeginTx(ctx, pgx.TxOptions) (Tx, error), Ping(ctx) error, HandleError(err) error.

Component — launcher.Component + health.Checkable + Client + Stats() *pgxpool.Stat.

UnitOfWork — Do(ctx, fn) error; injects active pgx.Tx via context.

Config — Host, Port, User, Password, Name, SSLMode, Timezone, MaxConns, MinConns, MaxConnLifetime, MaxConnIdleTime, HealthCheckPeriod; env-tag support.

New(logger logz.Logger, cfg Config) Component — constructor; pool created in OnInit.

NewUnitOfWork(logger logz.Logger, client Client) UnitOfWork — wraps a Client for transactional Do semantics.

HandleError(err error) error — maps pgx/PostgreSQL errors to xerrors: UniqueViolation → ErrAlreadyExists; ForeignKeyViolation/CheckViolation → ErrInvalidInput; pgx.ErrNoRows → ErrNotFound; others → ErrInternal.

Migration from v0.9.0

BeginTx is a new method on Client. Any type that implements Client must now also
implement BeginTx. The existing Begin behavior is unchanged.

Stats is a new method on Component. Any type that implements Component must now also
implement Stats.

go get code.nochebuena.dev/go/postgres@v1.0.0

Downloads

2 Releases 3 Tags

Release v1.0.0 Stable