Rene Nochebuena
2baafa6a0c
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/
67 lines
1.5 KiB
Markdown
67 lines
1.5 KiB
Markdown
# postgres
|
|
|
|
pgx-backed PostgreSQL client with launcher lifecycle and health check integration.
|
|
|
|
## Install
|
|
|
|
```
|
|
go get code.nochebuena.dev/go/postgres
|
|
```
|
|
|
|
## Usage
|
|
|
|
```go
|
|
db := postgres.New(logger, cfg)
|
|
lc.Append(db)
|
|
r.Get("/health", health.NewHandler(logger, db))
|
|
```
|
|
|
|
## Querying
|
|
|
|
```go
|
|
exec := db.GetExecutor(ctx) // returns pool, or active Tx if inside Do()
|
|
|
|
rows, err := exec.Query(ctx, "SELECT id, name FROM users WHERE active = $1", true)
|
|
defer rows.Close()
|
|
```
|
|
|
|
## Unit of Work
|
|
|
|
```go
|
|
uow := postgres.NewUnitOfWork(logger, db)
|
|
|
|
err := uow.Do(ctx, func(ctx context.Context) error {
|
|
exec := db.GetExecutor(ctx) // returns the transaction
|
|
_, err := exec.Exec(ctx, "INSERT INTO orders ...")
|
|
return err
|
|
})
|
|
```
|
|
|
|
## Error mapping
|
|
|
|
```go
|
|
if err := db.HandleError(err); err != nil { ... }
|
|
// or package-level: postgres.HandleError(err)
|
|
```
|
|
|
|
| PostgreSQL error | xerrors code |
|
|
|---|---|
|
|
| `unique_violation` | `ErrAlreadyExists` |
|
|
| `foreign_key_violation` | `ErrInvalidInput` |
|
|
| `check_violation` | `ErrInvalidInput` |
|
|
| `pgx.ErrNoRows` | `ErrNotFound` |
|
|
| anything else | `ErrInternal` |
|
|
|
|
## Configuration
|
|
|
|
| Env var | Default | Description |
|
|
|---|---|---|
|
|
| `PG_HOST` | required | Database host |
|
|
| `PG_PORT` | `5432` | Database port |
|
|
| `PG_USER` | required | Username |
|
|
| `PG_PASSWORD` | required | Password |
|
|
| `PG_NAME` | required | Database name |
|
|
| `PG_SSL_MODE` | `disable` | SSL mode |
|
|
| `PG_MAX_CONNS` | `5` | Max pool connections |
|
|
| `PG_MIN_CONNS` | `2` | Min pool connections |
|