
louise
Clone avec HTTPS, un jeton personnel en mot de passe, ou avec SSH, une clé ajoutée dans vos paramètres.
ADR 0052: The postgres package — wire protocol, connection actors, pool, sql effect
Status: Proposed (2026-10-18, issue #145); needs engineering review (#44).
Context
DDD applications keep their state in PostgreSQL. The persistence layer must fit Louise's model: sockets are non-blocking and park only the actor that waits (ADR 0012), domain code reaches the database through effects (ports) that tests handle in memory, and a C binding (libpq) would run each call on the blocking pool (ADR 0005) — one OS thread per call in flight.
Decision
packages/postgres speaks the PostgreSQL wire protocol (3.0) in Louise,
over std/net and std/tls:
- The codec is pure Louise (
protocol.lse,binary.lse): messages to and fromBytes, big-endian, length-checked before allocation. Unit-tested against recorded byte transcripts on both backends; no database needed. - Extended query protocol only. Values always travel as parameters
(
$1), binary per type where a codec exists, so the API has no way to build an injection. Thesqltagged template (ADR 0048) writes real SQL with holes becoming parameters. Statements are prepared once per connection (Parse + Describe, cached by SQL text). - Authentication: trust, cleartext (over TLS or localhost only), and SCRAM-SHA-256 (RFC 5802/7677) over ADR 0050's primitives. MD5 is not supported, as PostgreSQL deprecates it.
- One actor per connection owns its socket and protocol state, so a
connection is never used by two requests at once. A pool actor
hands connections out:
size,min_idle,idle_timeout,max_lifetime, and a liveness check — a connection idle pastcheck_afteris pinged (a bareSync, which also proves no transaction is open) before handout, so a stale connection is replaced instead of failing a borrower's first query. Timeouts are in milliseconds, evaluated on the pool'stick: the pool maintains itself when quiet, which is when reaping matters, and checks handouts and returns per message. Borrowers and connections are monitored: a dead borrower frees its connection (closed, not reused), a dead connection frees its slot, waiters queue with a caller-side acquire timeout. - Transactions check a connection out exclusively:
pg.transaction(pool, action)sends BEGIN, runsaction, COMMITs; onErrorit ROLLBACKs.pg.transaction_retryre-runs serialization failures (40001) and deadlocks (40P01);pg.savepointnests.pg.cancelsends a CancelRequest on a fresh connection with the backend key data from the handshake.pg.listen/pg.unlistenrun a dedicated listener connection outside the pool for LISTEN/NOTIFY. - The
sqleffect is the ambient API, handled bypg.with_connectionandpg.transaction: adapters are written againstsqland tested with an in-memory handler; domain code sees only its own ports.
Deviations from the issue's sketch, and why
- No
defer-driven rollback. Cleanups may not performproc(E0506), so cleanup is explicit on the normal paths; an unwind crashes the borrower, which the pool's monitor sees (the connection is closed, not reused). Afinal ctlpast the block is the documented hole. row.int("id")by name, errors naming the column and the types;@derive(FromRow)waits on the producer derives #140 asks of ADR 0019.numericreads asStringuntil std has a decimal type.- TLS upgrade per
sslmodewith ADR 0038'sstd/tlsafter the protocol'sSslRequest;requirerefuses a plain answer. - The pool runs under no supervisor: supervise the caller and start it again on a crash, rather than a supervisor per pool.
Naming wart, for the review
The effect sql and the sql template function share a name in the
package's root. Effect operations resolve as module items
(pg.query(...)), so both are usable — but import postgres.{sql}
brings the template function, and import postgres.{type sql} the
effect, which reads badly at call sites. Renaming one (the effect to
db?) is a review question; the wart is documented, not settled.
Consequences
- No C dependency; a parked query parks only its actor.
- The package is live-tested against PostgreSQL in a container when
LOUISE_PG_URLis set (skipped otherwise): authentication, the types and NULL, SQLSTATE errors, rollback on error and on a killed borrower, cancellation, LISTEN/NOTIFY, and the pool's reaping, recycling and stale-connection replacement. examples/event_storeis the reference consumer: theevent_storeeffect with an in-memory handler (tests) and a PostgreSQL one (production), optimistic concurrency asConflictfrom SQLSTATE23505, and the outbox in the same transaction withpg_notifywaking the projection.- Not yet:
COPY, pipelining, replication, the simple query protocol (BEGIN/COMMIT/ROLLBACK use extended), Unix-domain sockets.
Alternatives considered
- libpq over FFI. Rejected: one blocking-pool thread per call in flight, a C dependency, and C error shapes instead of Louise's.
- Wall-clock timeouts (
std/time) in the pool. The pool counts ticks instead: pool timeouts are coarse, the effect rows ofstart_pooland friends stay<io, proc, random>(noclock), and reaping matters exactly when the pool is quiet, which is when ticks fire. - Pinging on every handout. Rejected: a round trip per acquire on a
hot pool, to catch a case (a long-idle stale connection) that
check_aftercatches with one ping per long-idle connection.