# infra/jpa/postgres

Server-side settings the JPA platform's contracts assume, and why each one matters.

The contract suites start their own containers through
`dev.caskeleton.adapter.outbound.persistence.testkit.postgresql.PostgreSqlContainerFactory`, so
nothing here is needed to run them. This directory records what a *deployed* PostgreSQL has to look
like for the platform's guarantees to hold, because several of them are server settings rather than
application code.

## Settings the platform depends on

| Setting | Why the platform cares |
|---|---|
| `statement_timeout` | The last bound on a runaway statement. The platform sets transaction timeouts, but a single statement inside a transaction can still outlive the request that asked for it. |
| `idle_in_transaction_session_timeout` | An idle open transaction holds its locks and its snapshot indefinitely, which blocks writers and prevents vacuum. This is what turns "someone left a transaction open" into a bounded incident. |
| `lock_timeout` | A cluster-wide floor under the per-request lock bounds in `PostgreSqlLockOptions`. |
| `max_connections` | The number `app.jpa-platform.datasource.maximum-pool-size` must be sized against — across every instance, and allowing for `REQUIRES_NEW` taking a second connection while pinning the first. |
| `default_transaction_isolation` | Left at `read committed`. The platform selects `repeatable read` or `serializable` per transaction profile; changing the default would silently change every transaction that did not ask. |

## Suggested baseline

```conf
statement_timeout = '30s'
idle_in_transaction_session_timeout = '60s'
lock_timeout = '10s'
default_transaction_isolation = 'read committed'
```

These are starting points, not recommendations: the right `statement_timeout` depends on the
slowest legitimate query in the application, and setting it below that turns a working report into
an error. Measure before pinning.

## What is deliberately not configured here

- **Roles.** Credential separation lives in [`../roles/runtime-roles.sql`](../roles/runtime-roles.sql).
- **Schema.** Flyway owns it (design §31). Nothing in this directory creates a table.
- **Extensions.** The platform's PostgreSQL support — JSONB, arrays, ranges, `SKIP LOCKED`,
  `ON CONFLICT` — is all core PostgreSQL. No extension is required, and none should be assumed.