# 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 |