feat(postgres): initial stable release v0.9.0

pgx v5-native PostgreSQL client with launcher lifecycle, health check, unit-of-work via context injection, and structured error mapping.

What's included:
- Executor / Tx / Client / Component interfaces using pgx native types (pgconn.CommandTag, pgx.Rows, pgx.Row)
- New(logger, cfg) constructor; pgxpool initialised in OnInit
- Config struct with env-tag support for all pool tuning parameters
- UnitOfWork via context injection; GetExecutor(ctx) returns active Tx or pool
- HandleError mapping pgerrcode constants to xerrors codes (AlreadyExists, InvalidInput, NotFound, Internal)
- health.Checkable at LevelCritical; HealthCheck delegates to pgxpool.Ping

Tested-via: todo-api POC integration
Reviewed-against: docs/adr/
This commit is contained in:
2026-03-19 13:18:07 +00:00
commit 2baafa6a0c
16 changed files with 949 additions and 0 deletions

20
doc.go Normal file
View File

@@ -0,0 +1,20 @@
// Package postgres provides a pgx-backed PostgreSQL client with launcher and health integration.
//
// Usage:
//
// db := postgres.New(logger, cfg)
// lc.Append(db)
// r.Get("/health", health.NewHandler(logger, db))
//
// The component manages a pgxpool connection pool, implements launcher lifecycle hooks,
// and satisfies health.Checkable (priority: critical).
//
// Use [NewUnitOfWork] to wrap operations in a transaction:
//
// uow := postgres.NewUnitOfWork(logger, db)
// uow.Do(ctx, func(ctx context.Context) error {
// exec := db.GetExecutor(ctx) // returns the active transaction
// _, err := exec.Exec(ctx, "INSERT ...")
// return err
// })
package postgres