pg: survive lost connections and open TLS directly

[quentinnippert]

Summary

Three failures that took down long-running workers talking to a managed PostgreSQL over TLS:

Problem	Before	After
Connection dropped mid-transaction (failover, pg_terminate_backend, network)	Process crash: null is not an object (evaluating 'socket.write'), thrown outside any promise	The transaction rejects with the connection error; the process keeps running and the pool reconnects
Lock table full (SQLSTATE 53200)	out of shared memory, which reads like the server ran out of RAM	A [SixbPg] error naming the table, the setting that sizes it, and what to do
Large reads over TLS on Bun 1.4.0–1.4.2	Memory grows with every byte read, until the process is killed	Opt-in direct TLS (sslnegotiation=direct) keeps memory flat

1. Transactions survive a lost connection

postgres.js 3.4.9 writes to a connection without checking that its socket is still open:

• sql.begin answers a failed statement by sending ROLLBACK on the closed socket, and the process crashes;
• reserve().release() hands a dead connection back to the pool, and the next query crashes the same way.

runPgTransaction now drives the transaction itself on a reserved connection:

reserve ─► BEGIN [ISOLATION …] ─► callback ─► COMMIT ─► release
                                   │ throws
                                   ├─ statement error ─► ROLLBACK ─► release ─► rethrow
                                   └─ connection lost ─► (send nothing, never release) ─► rethrow

• "Lost" = porsager's closed/destroyed codes, socket resets, or any FATAL/PANIC server error (PostgreSQL always ends the session after those).
• The pool replaces a closed connection on its own, so skipping release() loses nothing.
• Migrations already ran their own transaction on a reserved connection; they now use the same helpers.
• New guard: when a statement fails and the callback swallows the error, PostgreSQL answers COMMIT with a ROLLBACK tag, not an error. We used to report that as a success with the writes discarded; it now throws.

Known limit: a connection that drops between two statements still crashes, because nothing reports the loss before the next write. The upstream fix is porsager/postgres#1209.

2. Explicit error for a full lock table

[SixbPg] PostgreSQL aborted the transaction because its shared predicate lock table is full
(SQLSTATE 53200 "out of shared memory"). The table holds max_pred_locks_per_transaction ×
(max_connections + max_prepared_transactions) entries shared by all sessions. A long
serializable transaction also keeps the predicate locks of every serializable transaction
that commits while it is open. Raise max_pred_locks_per_transaction (applied at server
restart) or shorten the transactions that overlap.

The table is identified from PostgreSQL's hint. A 53200 without a lock hint is a real out-of-memory error and passes through unchanged.

3. Direct TLS, opt-in

postgresql://user:pass@host:5432/db?sslmode=require&sslnegotiation=direct

	Classic (default)	sslnegotiation=direct
Handshake	SSLRequest on plain TCP, then tls.connect({ socket }) upgrade	tls.connect({ host, port }) with ALPN postgresql
Round trips before TLS	+1	0
Bun 1.4.0–1.4.2	keeps every received byte (+537 MB for 384 MB read)	flat (~100 MB whatever the volume)
Server	any	PostgreSQL 17+

• sslmode keeps its libpq meaning: require encrypts, verify-ca checks the chain, verify-full also checks the host name.
• Misconfigurations fail when the client is created: an sslmode that could fall back to plaintext, several hosts, or a Unix socket.
• A server that refuses direct TLS gets a [SixbPg] explanation, printed once, instead of a bare connection reset.

Why opt-in rather than "try direct, fall back": it matches libpq, and it leaves every existing deployment unchanged, including those behind a pooler or proxy. A fallback would add a probe and a second code path to work around a runtime bug that Bun 1.4.3 fixes.

Why the socket factory returns at once: with postgres.js 3.4.9, a factory that throws leaves its pool slot stuck forever, and a socket that is already dead stalls the slot's next attempt. Failures are reported through the socket's own error/close events, which porsager already handles.

Linked issue

None.

Scope

• @sixb/pg only. No public contract changes beyond the documented connection-string parameter.
• Left out on purpose:
  • a typed, retryable storage.unavailable failure. Nothing would read it yet; it comes with the run-lifecycle work, where attempts and last errors become visible.
  • a runtime guard on the Bun version. engines will move to >=1.4.3 once it is released.

Validation

• New e2e pg-connection-loss: pg_terminate_backend mid-transaction, run in a child process so that a crash cannot take down the runner. Proven by reverting: both sql.begin and releasing a lost connection bring back the exact crash.
• New e2e pg-direct-tls:
  • the session is encrypted;
  • verify-full rejects a self-signed certificate;
  • memory stays under half of what was read. Proven by reverting: the classic path fails it on Bun 1.4.2.
• Unit tests for the emitted statements, lost-connection handling, the COMMIT/ROLLBACK guard, 53200, and the client configuration errors.
• Checked by hand against PostgreSQL 16, which refuses direct TLS: the explanation is printed and the pool keeps working.
• bun run test:e2e in storage/pg (411 pass), bun run typecheck, and bun run check.

Notes

• Behavior change: if a callback catches a statement error and keeps using the transaction, it now gets PostgreSQL's own 25P02 (current transaction is aborted). sql.begin used to rethrow the first error at the end instead.
• Remaining upstream issue: when the server kills a session during a query, postgres.js 3.4.9 replays that 57P01 onto the next query of the reconnected slot. One extra query fails (classified as a lost connection), then the pool is healthy. Settle startup queries when their connection keeps closing - fixes #1223, fixes #1193 porsager/postgres#1241 fixes only the startup variant.
• Test database: it now runs with TLS on (the image's self-signed certificate); plain connections are still accepted.
• Test-writing trap: expect(sqlQuery).rejects never runs a porsager query, because the query only starts when its then is called, and Bun's matcher then waits forever. The new tests catch such errors explicitly.