@steadybrew/postgresjs 4.4.1 → 4.5.0

package/README.md

@@ -1,6 +1,10 @@
 # Postgres.js by Steady Brew
 
-This is an independently maintained fork of [Postgres.js](https://github.com/porsager/postgres), the PostgreSQL client for Node.js and Deno created by [Rasmus Porsager](https://github.com/porsager). [Steady Brew](https://github.com/steadybrew) aims to fix bugs and improve the library through community contributions, regression tests, and careful architectural review, while preserving its simple API.
+A maintained fork of [Postgres.js](https://github.com/porsager/postgres), the PostgreSQL client created by [Rasmus Porsager](https://github.com/porsager), with the same API.
+
+- **Fixes reported Postgres.js bugs:** 40 open upstream issues, from queries receiving another query's rows to hung pools and crashed processes, each covered by a regression test. See [the list](#fixed-postgresjs-issues).
+- **Built for serverless and connection poolers:** bounded connection retries with backoff, idle connections replaced when a frozen instance resumes, pool statistics from `sql.stats()`, and an adapter for Vercel Fluid. Query timeouts and cancellable pool waits are next on the [roadmap](ROADMAP.md).
+- **Switch with one line:** your code and the libraries that import `postgres` keep working. See [Switching from Postgres.js](#switching-from-postgresjs).
 
 ---
 
@@ -13,33 +17,142 @@ This is an independently maintained fork of [Postgres.js](https://github.com/por
 
 <br clear="all">
 
-## Compatibility policy
+## Compatibility
+
+[![test](https://github.com/steadybrew/postgresjs/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/steadybrew/postgresjs/actions/workflows/test.yml?query=branch%3Amain)
+
+**Version 4 runs on Node.js 22 or newer** and supports PostgreSQL 15–18. Every release passes the full test matrix before it is published.
+
+| Runtime | PostgreSQL | Notes |
+| --- | --- | --- |
+| Node 22, 24 and 26, ESM and CJS | 15–18 | |
+| Deno 1.46.3 | 17 | No Deno 2 claim |
+| Cloudflare Workers (workerd) | 17 | A "Stream was cancelled" rejection on socket close remains ([#1196](https://github.com/porsager/postgres/issues/1196), [#1202](https://github.com/porsager/postgres/issues/1202)) |
+| Bun | | Best effort, not tested in CI |
+
+[The test workflow](https://github.com/steadybrew/postgresjs/blob/main/.github/workflows/test.yml) defines which pairs run on each push. Supabase PostgreSQL and Supabase Edge are separate environments; Deno 1.46.3 coverage does not imply Deno 2 or hosted Supabase Edge.
+
+## Switching from Postgres.js
+
+```sh
+npm install postgres@npm:@steadybrew/postgresjs@^4
+```
+
+This installs the fork under the name `postgres`, so `import postgres from 'postgres'` stays as it is, and so do libraries that import it, such as `drizzle-orm/postgres-js`, `drizzle-kit` and `kysely-postgres-js`. Then read [Upgrading to 4.0.0](#upgrading-to-400) for the behaviour changes.
 
-**Version 4 requires Node.js 24 or newer** and supports PostgreSQL 15–18. Version 4.0.0 raised the minimum Node.js version from 12. The minimum stays at Node 24 until an explicit policy change; newly maintained Node majors are tested before compatibility is claimed.
+Tracing: from 4.5.0, dd-trace records the same database spans as with Postgres.js when the fork is installed under the `postgres` name. Sentry's automatic integration instruments `postgres` versions below 4 only, so widen its range before Sentry loads:
 
-| Runtime | PostgreSQL target | CI jobs | Validation status |
-| --- | --- | ---: | --- |
-| Node 24, ESM and CJS | 15, 16, 17, 18 | 4 | Passed release-candidate CI |
-| Node 26, ESM and CJS | 15, 16, 17, 18 | 4 | Passed release-candidate CI |
-| Deno 1.46.3 | 17 | 1 | Passed release-candidate CI; no Deno 2 claim |
-| Cloudflare workerd, Wrangler 4.123.0 | 17 | 1 | Passed release-candidate CI; known "Stream was cancelled" rejection remains |
-| Bun export | No dedicated target | 0 | Retained as best effort; unverified, without dedicated CI |
+```js
+// sentry-postgres.mjs
+import { SENTRY_RUNTIME_INSTRUMENTATIONS } from '@sentry/server-utils/orchestrion/config'
 
-All ten [CI jobs](https://github.com/steadybrew/postgresjs/actions/runs/37943516565) passed for 4.1.0. The core Node matrix has eight jobs; Deno and Cloudflare run independently. PostgreSQL versions below 15 are outside the supported matrix. See the [release notes](./CHANGELOG.md#v410---2026-10-09) for validation details and [known limitations](./CHANGELOG.md#known-limitations), including the Cloudflare cancellation rejection tolerated by its CI gate.
+for (const instrumentation of SENTRY_RUNTIME_INSTRUMENTATIONS) {
+  if (instrumentation.module.name === 'postgres')
+    instrumentation.module.versionRange = '>=3.0.0 <5'
+}
+```
+
+```sh
+node --import ./sentry-postgres.mjs --import @sentry/node/import app.js
+```
 
-Supabase PostgreSQL and Supabase Edge are separate environments. Deno 1.46.3 coverage does not imply Deno 2 or hosted Supabase Edge certification.
+This covers Sentry's runtime hook, not its bundler plugins. With pnpm, add `@sentry/server-utils` at the same version as `@sentry/node` so the file can import it.
 
 ## Upgrading to 4.0.0
 
-Version 4.0.0 fixes connection startup, reservations, reconnects, shutdown, transaction ownership, and built-in array handling. When upgrading from `@steadybrew/postgresjs` 3.x:
+Version 4.0.0 fixes connection startup, reservations, reconnects, shutdown, transaction ownership, and built-in array handling. When upgrading from Postgres.js 3.4 or `@steadybrew/postgresjs` 3.x:
 
-- Upgrade to **Node.js 24 or newer** before installing.
+- Upgrade to **Node.js 22 or newer** before installing.
 - Keep queries within the reservation or transaction that owns them. Reserved handles used after `release()`, and transaction handles used after completion, reject with `CONNECTION_ENDED`. A handle whose connection has closed cannot run queries on a reconnected session.
 - Pass a non-empty string without NUL characters to transaction `sql.prepare(name)`. Invalid names throw `INVALID_TRANSACTION_NAME`.
 - If you use `fetch_types: false`, review code that expects built-in arrays as raw strings: supported built-in arrays are now decoded as JavaScript arrays. SQL `NULL` elements become JavaScript `null`; quoted `"NULL"` text remains a string.
 
 See the [changelog](./CHANGELOG.md#breaking-changes-and-migration) for the full migration notes and fixes.
 
+## Fixed Postgres.js issues
+
+Bugs and feature requests from [porsager/postgres](https://github.com/porsager/postgres) that this fork fixes, whether reported in an issue or in a pull request suggesting a fix, and the version that fixed them. Each fix has a test that reproduces the report, except [#1100](https://github.com/porsager/postgres/issues/1100), which rests on a production measurement, and [#1154](https://github.com/porsager/postgres/issues/1154), whose test reproduces the reported stack without a known trigger. The [changelog](./CHANGELOG.md) has the details.
+
+<details>
+<summary>54 bugs and 7 feature requests</summary>
+
+**Wrong results and data safety**
+
+| Issue | What happens now | Since |
+| --- | --- | --- |
+| [#1082](https://github.com/porsager/postgres/issues/1082), [#729](https://github.com/porsager/postgres/issues/729) | A query whose values fail to serialize rejects on its own; the query running alongside no longer gets its error, and the next query no longer gets another query's rows | 4.3.0 |
+| [#1216](https://github.com/porsager/postgres/issues/1216) | A transaction handle whose connection closed rejects with `CONNECTION_CLOSED` instead of running inside the next user's transaction, so it can't read their rows through row-level security. | 4.0.0 |
+| [#1248](https://github.com/porsager/postgres/issues/1248) | Statements in a `sql.begin()` callback after its connection closes reject instead of running outside the transaction | 4.0.0 |
+| [#1204](https://github.com/porsager/postgres/issues/1204) | A transaction's connection is not handed to another `sql.begin()` when its socket drains late, so one transaction's `COMMIT` can't commit another's unfinished writes. | 4.0.0 |
+| [#1217](https://github.com/porsager/postgres/issues/1217) | `sql.begin()` rejects with `TRANSACTION_ROLLED_BACK` when the server rolled back the COMMIT | 4.4.0 |
+| [#1249](https://github.com/porsager/postgres/issues/1249), [#1226](https://github.com/porsager/postgres/issues/1226), [#1223](https://github.com/porsager/postgres/issues/1223) | The first query after a reconnect no longer rejects with an error from the closed session | 4.0.0 |
+| [#789](https://github.com/porsager/postgres/issues/789) | `sql.array()` infers the right array type on first use | 4.0.0 |
+| [#1049](https://github.com/porsager/postgres/issues/1049), [#1124](https://github.com/porsager/postgres/issues/1124) | `NULL` elements in arrays parse as `null`, not `NaN` or the string `"NULL"` | 4.0.0 |
+| [#1252](https://github.com/porsager/postgres/issues/1252) | Cancelling a pipelined query that hasn't started no longer gives the next query its result | 4.1.0 |
+| [#1253](https://github.com/porsager/postgres/issues/1253), [#1181](https://github.com/porsager/postgres/issues/1181), [#1119](https://github.com/porsager/postgres/issues/1119) | A query no longer gets empty slots at the start of its result after the previous query on the connection failed or was cancelled partway through its rows | 4.5.0 |
+
+**Hangs**
+
+| Issue | What happens now | Since |
+| --- | --- | --- |
+| [#751](https://github.com/porsager/postgres/issues/751), [#1219](https://github.com/porsager/postgres/issues/1219), [#1203](https://github.com/porsager/postgres/issues/1203) | `sql.reserve()` on a pool that hasn't opened a connection yet resolves, with or without `fetch_types` and on Cloudflare Workers | 4.0.0 |
+| [#1195](https://github.com/porsager/postgres/issues/1195), [#1199](https://github.com/porsager/postgres/issues/1199) | A reservation survives its connection being terminated by the server, and the pool recovers after it is released | 4.0.0 |
+| [#1186](https://github.com/porsager/postgres/issues/1186) | Queries queued on a reserved or transaction handle settle when its connection closes | 4.0.0 |
+| [#1097](https://github.com/porsager/postgres/issues/1097), [#1130](https://github.com/porsager/postgres/issues/1130), [#1242](https://github.com/porsager/postgres/issues/1242), [#861](https://github.com/porsager/postgres/issues/861) | `sql.end()` resolves after a disconnect, after a failed query and after a connection closes inside `sql.begin()`, and waits for queries queued in the pool | 4.0.0 |
+| [#1246](https://github.com/porsager/postgres/issues/1246) | A query sent between a socket error and its close settles, and a transaction reset mid-statement no longer loses a pool connection | 4.1.0 |
+| [#1193](https://github.com/porsager/postgres/issues/1193) | A connection closed during startup settles its first query instead of reconnecting in a tight loop | 4.0.0 |
+| [#1234](https://github.com/porsager/postgres/issues/1234) | Concurrent queries in `sql.begin()` after a column type change roll the transaction back and return the connection to the pool | 4.4.0 |
+| [#1255](https://github.com/porsager/postgres/issues/1255), [#1261](https://github.com/porsager/postgres/issues/1261) | A reserved connection whose `max_lifetime` passed is closed when released, and `sql.end()` called before the release resolves | 4.0.0 |
+| [#1016](https://github.com/porsager/postgres/pull/1016) | Queries no longer hang after a `COPY ... TO STDOUT` whose reader fell behind | 4.5.0 |
+
+**Crashes**
+
+| Issue | What happens now | Since |
+| --- | --- | --- |
+| [#1154](https://github.com/porsager/postgres/issues/1154), [#1208](https://github.com/porsager/postgres/issues/1208), [#1133](https://github.com/porsager/postgres/issues/1133) | A reserved or transaction connection that the server or network closes rejects its later statements, and `sql.begin()`'s own `ROLLBACK` or `COMMIT`, with `CONNECTION_CLOSED` instead of crashing the process with `Cannot read properties of null (reading 'write')`. | 4.0.0 |
+| [#1192](https://github.com/porsager/postgres/issues/1192), [#1205](https://github.com/porsager/postgres/issues/1205), [#1086](https://github.com/porsager/postgres/issues/1086) | A failed or cancelled type query at startup rejects the query instead of crashing the process | 4.0.0 |
+| [#1088](https://github.com/porsager/postgres/issues/1088) | Timers no longer fail on Cloudflare Workers | 4.0.0 |
+| [#1227](https://github.com/porsager/postgres/issues/1227) | Assigning `err.stack` on a query error no longer throws on Node 22 and newer | 4.5.0 |
+| [#1009](https://github.com/porsager/postgres/pull/1009) | The `camel` and `pascal` transforms no longer throw on a column name ending with an underscore | 4.5.0 |
+
+**Reconnects and failover**
+
+| Issue | What happens now | Since |
+| --- | --- | --- |
+| [#1179](https://github.com/porsager/postgres/issues/1179) | Failed connection attempts back off instead of the whole pool retrying at once | 4.0.0 |
+| [#1250](https://github.com/porsager/postgres/issues/1250) | A connection closed with a statement still buffered reconnects, instead of failing every later statement with `CONNECT_TIMEOUT` | 4.0.0 |
+| [#1174](https://github.com/porsager/postgres/issues/1174), [#815](https://github.com/porsager/postgres/issues/815), [#988](https://github.com/porsager/postgres/issues/988) | With several hosts, retries move to the next host, a connect timeout fails over, and `prefer-standby` falls back to a primary | 4.0.0 |
+
+**Transactions, notices and subscriptions**
+
+| Issue | What happens now | Since |
+| --- | --- | --- |
+| [#823](https://github.com/porsager/postgres/issues/823), [#1189](https://github.com/porsager/postgres/issues/1189), [#1210](https://github.com/porsager/postgres/issues/1210) | `sql.begin()` no longer fails with `UNSAFE_TRANSACTION` or sends a second `BEGIN` on a busy connection when transactions and queries run concurrently, at the pipeline limit, under write backpressure or with `max_pipeline: 0` | 4.0.0 |
+| [#1063](https://github.com/porsager/postgres/issues/1063) | `onnotice: false` silences notices | 4.4.0 |
+| [#1087](https://github.com/porsager/postgres/issues/1087) | `sql.subscribe()` no longer adds a listener on each subscribe or loses changes after a transform throws | 4.4.0 |
+
+**TypeScript**
+
+| Issue | What happens now | Since |
+| --- | --- | --- |
+| [#1158](https://github.com/porsager/postgres/issues/1158), [#1177](https://github.com/porsager/postgres/pull/1177) | `sslnegotiation` is in the option types | 4.5.0 |
+| [#968](https://github.com/porsager/postgres/pull/968) | `socket` is in the option types | 4.5.0 |
+| [#703](https://github.com/porsager/postgres/issues/703), [#1194](https://github.com/porsager/postgres/pull/1194) | `new PostgresError('message')` sets the message, as with `Error`, and the types declare both the message and the fields forms | 4.5.0 |
+
+**Feature requests**
+
+| Issue | What you get | Since |
+| --- | --- | --- |
+| [#443](https://github.com/porsager/postgres/issues/443), [#908](https://github.com/porsager/postgres/issues/908) | `sql.stats()` reports connections in use and idle, and queries waiting | 4.3.0 |
+| [#1100](https://github.com/porsager/postgres/issues/1100) | An `onidle` callback and the `@steadybrew/postgresjs/vercel` adapter | 4.2.0 |
+| [#1164](https://github.com/porsager/postgres/issues/1164) | Built-in array types are decoded, and plain JavaScript arrays are sent, with `fetch_types: false` | 4.0.0 |
+| [#886](https://github.com/porsager/postgres/issues/886), [#1094](https://github.com/porsager/postgres/issues/1094) | `await using` ends a pool and releases a reserved connection when it goes out of scope | 4.5.0 |
+| [#1225](https://github.com/porsager/postgres/issues/1225) | Queries with values in one round trip instead of two, opt-in with `parameter_types: 'client'` | 4.5.0 |
+
+Bun isn't tested here, so Bun-only reports such as [#1066](https://github.com/porsager/postgres/issues/1066) aren't listed; the same crash on Node is [#1208](https://github.com/porsager/postgres/issues/1208).
+
+</details>
+
 ## Getting started
 
 <br>
@@ -113,6 +226,7 @@ const { default: postgres } = await import('@steadybrew/postgresjs')
 * [Listen & notify](#listen--notify)
 * [Realtime subscribe](#realtime-subscribe)
 * [Numbers, bigint, numeric](#numbers-bigint-numeric)
+* [Parameter types](#parameter-types)
 * [Result Array](#result-array)
 * [Connection details](#connection-details)
 * [Custom Types](#custom-types)
@@ -151,7 +265,7 @@ Postgres.js utilizes [Tagged template functions](https://developer.mozilla.org/e
 1. **Enforcing** safe query generation
 2. Giving the ` sql`` ` function powerful [utility](#dynamic-inserts) and [query building](#building-queries) features.
 
-Any generic value will be serialized according to an inferred type, and replaced by a PostgreSQL protocol placeholder `$1, $2, ...`. The parameters are then sent separately to the database which handles escaping & casting.
+Any generic value will be serialized as described in [Parameter types](#parameter-types), and replaced by a PostgreSQL protocol placeholder `$1, $2, ...`. The values are then sent separately to PostgreSQL, which handles escaping & casting.
 
 All queries will return a `Result` array, with objects mapping column names to each row.
 
@@ -599,11 +713,13 @@ A `COPY` holds its connection until it finishes. Postgres.js cannot tell that a
 Postgres.js supports, [canceling queries in progress](https://www.postgresql.org/docs/7.1/protocol-protocol.html#AEN39000). It works by opening a new connection with a protocol level startup message to cancel the current query running on a specific connection. That means there is no guarantee that the query will be canceled, and due to the possible race conditions it might even result in canceling another query. This is fine for long running queries, but in the case of high load and fast queries it might be better to simply ignore results instead of canceling.
 
 ```js
-const query = sql`select pg_sleep 100`.execute()
+const query = sql`select pg_sleep(100)`.execute()
 setTimeout(() => query.cancel(), 100)
 const result = await query
 ```
 
+A cancelled query rejects with code `57014`. A cancel can arrive too late, in which case the query may still complete, or fail with its own error. `query.cancel()` resolves once the cancel request has been sent. A cancelled query you don't await does not cause an unhandled rejection.
+
 ### Execute
 
 #### ```await sql``.execute()```
@@ -977,6 +1093,103 @@ const sql = postgres({
 
 There is currently no guaranteed way to handle `numeric` / `decimal` types in native Javascript. **These [and similar] types will be returned as a `string`**. The best way in this case is to use  [custom types](#custom-types).
 
+## Parameter types
+
+A `$1` placeholder has a type that PostgreSQL infers from the SQL around it (the column it is compared to or inserted into, a function argument, a cast). Postgres.js has to turn each JavaScript value into text for that type, and `parameter_types` chooses how.
+
+Some values carry a type Postgres.js can tell from the JavaScript value: `Date`, `Buffer` / `Uint8Array`, booleans, `bigint`, and anything wrapped in `sql.typed(value, oid)`, `sql.types.*`, `sql.json` or `sql.array` with elements. They are serialized for that type and sent in a single round trip, in every mode. Everything else (strings, numbers, plain objects, `sql.typed(value)` without an OID, an empty `sql.array([])`, arrays) has no such type. `null` is always SQL `NULL`.
+
+### `parameter_types: 'server'` (default)
+
+For a value whose type Postgres.js cannot tell, it first asks PostgreSQL for the type of the placeholder, which costs an extra round trip on every query with `prepare: false` and the first time each connection runs that SQL with `prepare: true`, and then serializes the value for that type. This has consequences worth knowing:
+
+- a string sent to a `json` or `jsonb` placeholder is sent as JSON, so `'{"a":1}'` is stored as a JSON string, not an object
+- a string or number sent to a `date`, `timestamp` or `timestamptz` placeholder goes through `new Date(x).toISOString()`, where a date-only string such as `'2020-01-02'` is read as UTC and a date-and-time string without an offset such as `'2020-01-02T10:00'` is read in the Node.js process time zone (`TZ`)
+- anything other than `true` sent to a `boolean` placeholder is stored as `false`, including the strings `'true'` and `'t'` and the number `1`
+- a string sent to a `bytea` placeholder is sent as hex of its UTF-8 bytes
+- a custom type registered in `types` with a `from` list runs its `serialize` function
+
+### `parameter_types: 'client'`
+
+The JavaScript value decides how it is serialized and PostgreSQL parses the text, so a query with values is one round trip:
+
+- a string is sent unchanged as text
+- a number is sent as its JavaScript text (`'' + n`)
+- a plain object (prototype `Object.prototype` or `null`) is sent as `JSON.stringify(x)`
+- any other object (Decimal, Luxon, moment, URL, class instances) is sent as `'' + x`
+- `null` is SQL `NULL`; `undefined` is handled as before
+- a value with a type Postgres.js can tell from the JavaScript value is serialized for that type, as with `'server'`
+- an array whose elements have no such type still makes Postgres.js ask PostgreSQL for the placeholder's type first, because only PostgreSQL knows whether the placeholder is an array, JSON or a custom type; that query takes the extra round trip
+
+What this changes compared to `'server'`:
+
+| Value | Type PostgreSQL infers for the placeholder | `'server'` | `'client'` |
+| --- | --- | --- | --- |
+| string | json, jsonb | sent as JSON: stores a JSON string | parsed as JSON; text that is not JSON is rejected |
+| string | boolean | always `false` | PostgreSQL boolean input (`'t'`, `'yes'`, `'on'`, `'1'` are true); invalid text is rejected |
+| string | date, timestamp, timestamptz | `new Date(s).toISOString()`: date-only strings are read as UTC, date-and-time strings without an offset in the Node.js process time zone (`TZ`) | parsed by PostgreSQL in the PostgreSQL session's `TimeZone` setting; `date` and `timestamp` ignore an explicit offset |
+| string | bytea | hex of the UTF-8 bytes | bytea text input; differs only for strings containing backslashes |
+| string, number | a custom type registered in `types` with a `from` list | the type's `serialize` | sent unchanged as text |
+| number | json, jsonb | `JSON.stringify` (`NaN` and `Infinity` become `null`) | the number's text (`NaN` and `Infinity` are rejected) |
+| number | boolean | `false` | `1` is true, `0` is false, anything else is rejected |
+| number | date, timestamp, timestamptz | `new Date(ms)` | rejected, except `Infinity`; a 6- or 8-digit number is read as a `YYMMDD` or `YYYYMMDD` date |
+| plain object | json, jsonb | `JSON.stringify` or your json `serialize` | `JSON.stringify` |
+| plain object | text | `[object Object]` | JSON text |
+| plain object | a custom type registered in `types` with a `from` list | the type's `serialize` | JSON text, normally rejected |
+| class instance | json, jsonb | `JSON.stringify`, so `toJSON` applies | `'' + x` |
+| class instance | date, timestamp, timestamptz | `new Date(x)` | `'' + x`, normally rejected |
+
+`time`, `timetz` and `interval` placeholders have no serializer in either mode: strings and numbers are sent unchanged as text.
+
+In practice:
+
+- pass `new Date(ms)` for epoch numbers, and set `connection: { timezone }` so date strings are read in the time zone you expect
+- pass `sql.json(s)` for a JSON string value, and `sql.types.name(v)` or `sql.typed(v, oid)` for a custom type; a custom type's `serialize` also runs for a whole array bound to that type, never for a plain value
+- `NaN`, `Infinity` and `-0` are sent as `NaN`, `Infinity` and `0`, and PostgreSQL's input rules for the placeholder's type decide
+
+Run `'warn'` first to see which of your queries are affected.
+
+**Planned for 5.0:** `'client'` becomes the default. Pass `parameter_types: 'server'` to keep the 4.x behaviour.
+
+### `parameter_types: 'warn'`
+
+`'warn'` behaves exactly like `'server'`, and also reports every query in which a value would be sent differently by `'client'`. The report goes to `ontypemismatch`, or to `console.warn` when it is not set:
+
+```js
+const sql = postgres({
+  parameter_types: 'warn',
+  ontypemismatch: ({ query, parameters }) => {
+    // parameters: [{ position: 2, oid: 3802, typeof: 'string' }]
+    // position is the $n number, oid the type PostgreSQL inferred for the placeholder
+  }
+})
+```
+
+With `debug: true` each entry also carries `serverText` and `clientText`, the two texts that were compared; `clientText` is the error when the `'client'` mode would throw. A query is reported on every execution that has a difference; sample in `ontypemismatch` if that is too much. `'warn'` serializes each untyped value twice and compares the strings. The option can also be set with `?parameter_types=warn` in the connection URL or `PGPARAMETER_TYPES`.
+
+`'warn'` compares the serialized text, not the stored value, so a report does not always mean the stored value would change.
+
+These reported cases store the same value under both modes:
+
+- `0`, `'0'`, `'false'`, `'no'` and `'off'` sent to a `boolean` placeholder (the texts differ, both store `false`)
+- a date string with an explicit offset sent to a `timestamptz` placeholder, as long as it has no more than millisecond precision (`toISOString()` truncates microseconds, so a string with microseconds stores a different value under `'server'`)
+- a string without backslashes sent to a `bytea` placeholder
+
+These reported cases store a different value, or are rejected, under `'client'`:
+
+- `1`, `'t'`, `'true'`, `'yes'`, `'on'` and `'1'` sent to a `boolean` placeholder (stored `false` today, `true` under `'client'`)
+- a date string with an explicit offset sent to a `timestamp` or `date` placeholder (`'server'` converts to UTC first, `'client'` drops the offset)
+- a string sent to a `json` or `jsonb` placeholder, a plain object sent to a `text` placeholder, and a number sent to a date, timestamp or boolean placeholder
+- a string or number sent to a custom type registered in `types` with a `from` list, which skips its `serialize`
+
+Date strings without an explicit offset:
+
+| String | Placeholder | Stored the same under both modes when |
+| --- | --- | --- |
+| date and time, such as `'2020-01-02T10:00'` | `timestamptz` | the Node.js process time zone and the PostgreSQL session's `TimeZone` setting match |
+| date only, such as `'2020-01-02'` | `timestamptz` | the PostgreSQL session's `TimeZone` setting is UTC |
+| date and time | `timestamp` or `date` | the Node.js process runs in UTC (`'server'` stores the UTC wall time, `'client'` stores the text as written) |
+
 ## Result Array
 
 The `Result` Array returned from queries is a custom array allowing for easy destructuring or passing on directly to JSON.stringify or general Array usage. It includes the following properties.
@@ -1053,14 +1266,16 @@ const sql = postgres('postgres://username:password@host:port/database', {
     application_name   : 'postgres.js', // Default application_name
     ...                                 // Other connection parameters, see https://www.postgresql.org/docs/current/runtime-config-client.html
   },
-  target_session_attrs : null,          // Use 'read-write' with multiple hosts to
-                                        // ensure only connecting to primary
+  target_session_attrs : null,          // Which kind of server to connect to, see
+                                        // Multi-host connections below
   fetch_types          : true,          // Automatically fetches types on connect
                                         // on initial connection.
+  parameter_types      : 'server',      // 'client' or 'warn', see Parameter types (PGPARAMETER_TYPES)
+  ontypemismatch       : fn,            // Called by parameter_types: 'warn', default console.warn
 })
 ```
 
-The `onnotice`, `onparameter`, `onnotify`, `onclose`, `onidle` and `debug` callbacks passed in the options are called synchronously from inside the driver. If one throws, the error is rethrown as an uncaught exception and the connection and its queries are not affected; under Node's default handling that ends the process.
+The `onnotice`, `onparameter`, `ontypemismatch`, `onnotify`, `onclose`, `onidle` and `debug` callbacks passed in the options are called synchronously from inside the driver. If one throws, the error is rethrown as an uncaught exception and the connection and its queries are not affected; under Node's default handling that ends the process.
 
 Note that `max_lifetime = 60 * (30 + Math.random() * 30)` by default. This resolves to an interval between 30 and 60 minutes to optimize for the benefits of prepared statements **and** working nicely with Linux's OOM killer.
 
@@ -1099,7 +1314,20 @@ Multiple connection strings can be passed to `postgres()` in the form of `postgr
 
 Connections will be attempted in order of the specified hosts/ports. On a successful connection, all retries will be reset. This ensures that hosts can come up and down seamlessly.
 
-If you specify `target_session_attrs: 'primary'` or `PGTARGETSESSIONATTRS=primary` Postgres.js will only connect to the primary host, allowing for zero downtime failovers.
+`target_session_attrs` (or `PGTARGETSESSIONATTRS`) picks which kind of server to connect to. The values and their meaning are libpq's:
+
+| Value | Connects to |
+|---|---|
+| `null` (default) | any server |
+| `'read-write'` | a server that accepts writes: not a hot standby, and `default_transaction_read_only` off |
+| `'primary'` | a server that is not a hot standby, even if `default_transaction_read_only` is on |
+| `'read-only'` | a hot standby, or a server with `default_transaction_read_only` on |
+| `'standby'` | a hot standby |
+| `'prefer-standby'` | a hot standby if any host is one, otherwise any server |
+
+During a failover or an upgrade, `'read-write'` and `'primary'` wait for the promoted server instead of connecting to a standby whose writes would fail. Read traffic that should keep using standbys during the switch belongs on `'prefer-standby'` or no `target_session_attrs` at all.
+
+With several hosts, a host that answers but is the wrong kind is skipped and the next one is tried at once; if every host answers and none matches, the connection fails immediately with `TARGET_SESSION_ATTRS`. With a single host, or when some host fails to connect, it keeps retrying, bounded by `connect_timeout` per host, because a failover may be in progress.
 
 ### The Connection Pool
 
@@ -1276,11 +1504,14 @@ const sql = postgres()
 | `application_name` | `PGAPPNAME`              |
 | `idle_timeout`     | `PGIDLE_TIMEOUT`         |
 | `connect_timeout`  | `PGCONNECT_TIMEOUT`      |
+| `parameter_types`  | `PGPARAMETER_TYPES`      |
 
 ### Prepared statements
 
 Prepared statements will automatically be created for any queries where it can be inferred that the query is static. This can be disabled by using the `prepare: false` option. For instance — this is useful when [using PGBouncer in `transaction mode`](https://github.com/porsager/postgres/issues/93#issuecomment-656290493).
 
+With `prepare: false`, `parameter_types: 'client'` sends queries with values in one round trip, unless a value is an untyped array; see [Parameter types](#parameter-types).
+
 **update**: [since 1.21.0](https://www.pgbouncer.org/2023/10/pgbouncer-1-21-0)
 PGBouncer supports protocol-level named prepared statements when [configured
 properly](https://www.pgbouncer.org/config.html#max_prepared_statements)
@@ -1326,6 +1557,8 @@ const [custom] = await sql`
 
 ```
 
+With `parameter_types: 'client'` a type's `serialize` runs for `sql.typed.name(v)` and for a whole array bound to that type, not for a plain value; see [Parameter types](#parameter-types).
+
 ### Custom socket
 
 Easily do in-process ssh tunneling to your database by providing a custom socket for Postgres.js to use. The function (optionally async) must return a socket-like duplex stream.
@@ -1357,6 +1590,17 @@ To ensure proper teardown and cleanup on server restarts use `await sql.end()` b
 
 Calling `sql.end()` will reject new queries and return a Promise which resolves when all queries are finished and the underlying connections are closed. If a `{ timeout }` option is provided any pending queries will be rejected once the timeout (in seconds) is reached and the connections will be destroyed.
 
+With explicit resource management the pool ends itself at the end of a scope:
+
+```js
+async function main() {
+  await using sql = postgres()
+  await sql`select 1`
+}
+```
+
+This calls `sql.end()` when the scope exits, so it suits scripts and jobs, not a shared client at a module's top level. The syntax needs Node.js 24+ or TypeScript 5.2+.
+
 #### Sample shutdown using [Prexit](https://github.com/porsager/prexit)
 
 ```js
@@ -1384,6 +1628,13 @@ await reserved.release()
 
 Once you have finished with the reserved connection, call `release` to add it back to the pool.
 
+```js
+using reserved = await sql.reserve()
+await reserved`select * from users`
+```
+
+A `using` or `await using` declaration calls `release()` when the scope exits.
+
 After release, queries through that reserved handle reject with `CONNECTION_ENDED`. Call `sql.reserve()` again to acquire a new handle. A reserved handle whose connection has closed cannot be reused after reconnect.
 
 ## Error handling

package/cf/src/connection.js

@@ -6,7 +6,7 @@ import { crypto } from '../polyfills.js'
 import Stream from 'node:stream'
 import { performance } from '../polyfills.js'
 
-import { stringify, handleValue, addArrayType } from './types.js'
+import { stringify, handleValue, addArrayType, clientSerialize } from './types.js'
 import { Errors, callback } from './errors.js'
 import Result from './result.js'
 import Queue from './queue.js'
@@ -106,6 +106,7 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
     , hostIndex = 0
     , length = 0
     , rows = 0
+    , copyPaused = false
     , serverSignature = null
     , nextWriteTimer = null
     , incomings = null
@@ -216,7 +217,10 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
   const connection = {
     queue: queues.closed,
     idleTimer,
-    connect: request => dispatch('acquire', request),
+    // Sentry's hook wraps connect and reads the connection from this, so it must stay a method
+    connect(request) {
+      dispatch('acquire', request)
+    },
     terminate: () => dispatch('terminate'),
     execute,
     release: () => dispatch('release'),
@@ -461,6 +465,7 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
     query = results = errorResponse = chunk = nextWriteTimer = barrier = null
     result = new Result()
     rows = 0
+    copyPaused = false
     nonce = serverSignature = null
   }
 
@@ -540,7 +545,7 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
 
       build(q)
       const written = write(toBuffer(q))
-      if (q.describeFirst || q.cursorFn || mayCopy(q))
+      if (q.describeFirst || q.cursorFn || mayCopy(q) || (q.prepare && !q.prepared && !q.options.simple && q.parameters.length))
         barrier = q
       return written && accepting()
     } catch (error) {
@@ -578,7 +583,7 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
 
   function prepared(q) {
     return Buffer.concat([
-      Bind(q.parameters, q.statement.types, q.statement.name, q.cursorName),
+      Bind(q),
       q.cursorFn
         ? Execute('', q.cursorRows)
         : ExecuteUnnamed
@@ -606,8 +611,11 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
     q.signature = q.prepare && types + string
     q.onlyDescribe && (delete statements[q.signature])
     q.parameters = q.parameters || parameters
+    q.inferred = options.parameter_types === 'server' ? null : types.slice()
     q.prepared = q.prepare && q.signature in statements
-    q.describeFirst = q.onlyDescribe || (parameters.length && !q.prepared)
+    q.describeFirst = q.onlyDescribe || (!q.prepared && types.some((x, i) =>
+      !x && (options.parameter_types !== 'client' || Array.isArray(q.parameters[i]))
+    ))
     q.statement = q.prepared
       ? statements[q.signature]
       : { string, types, name: q.prepare ? statementId + statementCount++ : '' }
@@ -680,6 +688,7 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
 
   function errored(err) {
     stream && (stream.destroy(err), stream = null)
+    resumeCopy()
     query && queryError(query, err)
   }
 
@@ -691,7 +700,7 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
       err = new Error(err)
 
     'query' in err || 'parameters' in err || Object.defineProperties(err, {
-      stack: { value: err.stack + query.origin.replace(/.*\n/, '\n'), enumerable: options.debug },
+      stack: { value: err.stack + query.origin.replace(/.*\n/, '\n'), enumerable: options.debug, writable: true, configurable: true },
       query: { value: query.string, enumerable: options.debug },
       parameters: { value: query.parameters, enumerable: options.debug },
       args: { value: query.args, enumerable: options.debug },
@@ -796,7 +805,7 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
         query.prepared && retryRoutines.has(errorResponse.routine) && delete statements[query.signature]
         query.retried
           ? errored(query.retried)
-          : query.prepared && retryRoutines.has(errorResponse.routine) && query.owner === connection.owner && !barrier
+          : query.prepared && retryRoutines.has(errorResponse.routine) && query.owner === connection.owner && !barrier && !query.cancelled
             && (x[5] !== 69 || endsAbortedState.test(query.string))
             ? retry(query, errorResponse)
             : errored(errorResponse)
@@ -810,6 +819,7 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
 
     query = results = errorResponse = null
     result = new Result()
+    rows = 0
 
     dispatch('ready')
   }
@@ -1042,8 +1052,9 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
 
   function mismatchReason(x, xs) {
     return (
+      (x === 'read-write' && xs.in_hot_standby === 'on' && 'is a standby') ||
       (x === 'read-write' && xs.default_transaction_read_only === 'on' && 'is read-only') ||
-      (x === 'read-only' && xs.default_transaction_read_only === 'off' && 'is read-write') ||
+      (x === 'read-only' && xs.in_hot_standby === 'off' && xs.default_transaction_read_only === 'off' && 'is read-write') ||
       (x === 'primary' && xs.in_hot_standby === 'on' && 'is a standby') ||
       (x === 'standby' && xs.in_hot_standby === 'off' && 'is a primary') ||
       (x === 'prefer-standby' && xs.in_hot_standby === 'off' && standbyPass() && 'is a primary') ||
@@ -1142,7 +1153,7 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
 
   function CopyOutResponse() {
     stream = new Stream.Readable({
-      read() { socket.resume() }
+      read() { copyPaused = false; socket.resume() }
     })
     query.resolve(stream)
     connection.owner && connection.owner.next()
@@ -1152,7 +1163,7 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
   function CopyBothResponse() {
     stream = new Stream.Duplex({
       autoDestroy: true,
-      read() { socket.resume() },
+      read() { copyPaused = false; socket.resume() },
       /* c8 ignore next 11 */
       write(chunk, encoding, callback) {
         socket.write(b().d().raw(chunk).end(), callback)
@@ -1172,12 +1183,23 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
   }
 
   function CopyData(x) {
-    stream && (stream.push(x.subarray(5)) || socket.pause())
+    if (stream && !stream.push(x.subarray(5))) {
+      copyPaused = true
+      socket.pause()
+    }
   }
 
   function CopyDone() {
     stream && stream.push(null)
     stream = null
+    resumeCopy()
+  }
+
+  function resumeCopy() {
+    if (copyPaused) {
+      copyPaused = false
+      socket.resume()
+    }
   }
 
   function NoticeResponse(x) {
@@ -1215,20 +1237,21 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
   }
 
   /* Messages */
-  function Bind(parameters, types, statement = '', portal = '') {
+  function Bind(q) {
+    const differences = []
     let prev
       , type
 
-    b().B().str(portal + b.N).str(statement + b.N).i16(0).i16(parameters.length)
+    b().B().str((q.cursorName || '') + b.N).str(q.statement.name + b.N).i16(0).i16(q.parameters.length)
 
-    parameters.forEach((x, i) => {
+    q.parameters.forEach((x, i) => {
       if (x === null)
         return b.i32(0xFFFFFFFF)
 
-      type = types[i]
-      x = type in options.serializers
-        ? options.serializers[type](x)
-        : '' + x
+      type = q.statement.types[i]
+      x = !q.inferred || q.inferred[i] || Array.isArray(x)
+        ? serialize(x, type)
+        : options.parameter_types === 'client' ? clientSerialize(x) : compare(x, type, i, differences)
 
       prev = b.i
       b.inc(4).str(x).i32(b.i - prev - 4, prev)
@@ -1236,7 +1259,27 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
 
     b.i16(0)
 
-    return b.end()
+    const message = b.end()
+    differences.length && callback(options.ontypemismatch || console.warn, { query: q.string, parameters: differences }) // eslint-disable-line
+    return message
+  }
+
+  function serialize(x, type) {
+    return type in options.serializers
+      ? options.serializers[type](x)
+      : '' + x
+  }
+
+  function compare(x, type, i, differences) {
+    const serverText = serialize(x, type)
+    let clientText
+    try {
+      clientText = clientSerialize(x)
+    } catch (error) {
+      clientText = error
+    }
+    serverText === clientText || differences.push({ position: i + 1, oid: type, typeof: typeof x, ...options.debug && { serverText, clientText } })
+    return serverText
   }
 
   function Parse(str, parameters, types, name = '') {

package/cf/src/errors.js

@@ -1,8 +1,8 @@
 export class PostgresError extends Error {
   constructor(x) {
-    super(x.message)
+    super(typeof x === 'string' ? x : x.message)
     this.name = this.constructor.name
-    Object.assign(this, x)
+    typeof x === 'string' || Object.assign(this, x)
   }
 }