Guard nextWrite against a closed socket - fixes #1208

[XavierGeerinck]

Fixes #1208.

The defect

closed() sets socket = null and only reconnects on a later timer, so a connection can sit with no socket across ticks. nextWrite() is the one consumer of socket in connection.js without a guard — terminate() has if (socket), end() has socket && … — and it is also the one reached from the 'data' handler, where a throw has no query to reject and escapes as an uncaughtException that takes the process down.

A pooled connection hides this, because the pool rotates the dead connection away. A reserved one is pinned and cannot be rotated, so every subsequent write on it is fatal. That is why it shows up as an unrecoverable crash loop for reserve() users — in our case an advisory-lock helper, roughly one process exit every 8 minutes in production.

The fix

Guard nextWrite() and settle rather than drop. Returning false alone is not enough — the write vanishes and the caller awaits forever (verified: the query hangs). error(...) rejects query/initial and drains sent via queryError, so the caller gets a catchable CONNECTION_CLOSED and the process survives.

The test

pg_terminate_backend turned out to be the wrong trigger for a portable test: on Linux the backend's close arrives as an RST, so closed(hadError=true) runs, the pending query rejects with ECONNRESET, and the next one merely hangs. On macOS the same kill arrives as a clean FIN, hadError is false, and you get the crash. The defect is really about the clean-close path, so the test drives that directly with a small TCP proxy that end()s the client side — deterministic on both platforms, and it does not depend on how the OS reports a killed backend.

Without the fix it crashes the test runner outright:

TypeError: Cannot read properties of null (reading 'write')
    at Immediate.nextWrite (src/connection.js:255:22)
    at process.processImmediate (node:internal/timers:574:21)

Verification

Full ESM suite in a container replicating .github/workflows/test.yml (Debian, PostgreSQL 17, pg_hba.conf from tests/, ssl on, wal_level=logical, second cluster on 5433):

	result
upstream/master	264 passed, 0 failed 🎉
this branch	265 passed, 0 failed 🎉

Exactly the one added test, no regressions. npm run test:cjs (transpiled) also passes. The original issue repro was additionally confirmed on Node 23.10.0 and Bun 1.2.23 / 1.3.14 / 1.4.0 — same defect on all four, and all four fixed by this change.

One thing I did not touch

sql.end() hangs on a pool whose reserved connection was killed. It reproduces identically on upstream/master without this patch (I checked before assuming it was mine), so it looks like a separate defect and I kept it out of this PR rather than widen the diff. The test therefore does not call end(). Happy to look at it separately if you want it filed or fixed.

🤖 Generated with Claude Code

https://claude.ai/code/session_012njhLokwkVZMjV7KcHsbA5

[JakeThomson]

We hit #1208 in production on postgres 3.4.8 / Node 24, behind PgBouncer in transaction mode. When our Postgres restarted, the uncaught exception took down our API processes:

TypeError: Cannot read properties of null (reading 'write')
    at Immediate.nextWrite (node_modules/postgres/src/connection.js:255:22)
    at process.processImmediate (node:internal/timers:574:21)

Because it's thrown from a setImmediate, no application-level handling can catch it, so the only fix is in the driver.

We're shipping this PR as-is as a local patch. A regression test modelled on yours, using a reserved connection whose socket the server ends, fails on unpatched 3.4.8 with exactly this trace and passes with the patch; the query now rejects with CONNECTION_CLOSED.

+1 for merging. This is the same bug as #1066 and #1154, and #1168 is an earlier PR for it, so landing one of them would close all three issues.

[realies]

Another way to hit the same crash, which this PR also fixes: end the client while an async pass function is still pending.

let release
const sql = postgres({ ...options, pass: () => new Promise(r => release = r) })
const query = sql`select 1`.catch(e => e.code)
// once pass() has been called:
await sql.end({ timeout: 0 })
release('password')
// -> uncaughtException: Cannot read properties of null (reading 'write')
//    at nextWrite (src/connection.js)

The server closes on the Terminate message and closed() clears the socket. When the password resolves, the SCRAM or md5 step writes and the deferred nextWrite hits the null socket.

On master 411429e this crashes in 5 of 5 runs each with SCRAM and md5 (Postgres 17, Node 24). With only this PR's src/connection.js change applied, all 10 runs are clean: no uncaught exception, and the query rejects with CONNECTION_DESTROYED.