@steadybrew/postgresjs 4.4.1 → 4.5.0-rc1

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,122 @@ 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.
 
-**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.
+| 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 |
 
-| 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 |
+[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.
 
-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.
+## Switching from Postgres.js
+
+```sh
+npm install postgres@npm:@steadybrew/postgresjs@^4
+```
 
-Supabase PostgreSQL and Supabase Edge are separate environments. Deno 1.46.3 coverage does not imply Deno 2 or hosted Supabase Edge certification.
+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.
+
+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:
+
+```js
+// sentry-postgres.mjs
+import { SENTRY_RUNTIME_INSTRUMENTATIONS } from '@sentry/server-utils/orchestrion/config'
+
+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
+```
+
+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
+
+Upstream issues on [porsager/postgres](https://github.com/porsager/postgres/issues) that this fork fixes, and the version that fixed them. Each fix has a test that reproduces the report. The [changelog](./CHANGELOG.md) has the details.
+
+<details>
+<summary>40 bugs and 4 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 can't run on a reconnected session, so it can't read another user's rows through RLS | 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 never handed to another transaction | 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 |
+
+**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 | 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 |
+
+**Crashes**
+
+| Issue | What happens now | Since |
+| --- | --- | --- |
+| [#1066](https://github.com/porsager/postgres/issues/1066), [#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 handle whose backend died rejects its statements instead of throwing an uncaught exception | 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 |
+
+**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 |
+| [#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` 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 |
+
+**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 with `fetch_types: false` | 4.0.0 |
+
+</details>
+
 ## Getting started
 
 <br>
@@ -113,6 +206,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 +245,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.
 
@@ -977,6 +1071,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.
@@ -1057,10 +1248,12 @@ const sql = postgres('postgres://username:password@host:port/database', {
                                         // ensure only connecting to primary
   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.
 
@@ -1276,11 +1469,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 +1522,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 +1555,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 +1593,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'
@@ -216,7 +216,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'),
@@ -540,7 +543,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 +581,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 +609,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++ : '' }
@@ -691,7 +697,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 },
@@ -1215,20 +1221,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 +1243,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/index.js

@@ -87,7 +87,8 @@ function Postgres(a, b) {
     listen,
     begin,
     close,
-    end
+    end,
+    ...Symbol.asyncDispose && { [Symbol.asyncDispose]: () => end() }
   })
 
   return sql
@@ -328,10 +329,17 @@ function Postgres(a, b) {
 
   async function reserve() {
     const l = await lease(false)
-    const sql = Sql(q => send(l, q))
+    const sql = Sql(handler)
     sql.release = () => settle(l, Lease.Released)
+    Symbol.dispose && (sql[Symbol.dispose] = () => sql.release())
+    Symbol.asyncDispose && (sql[Symbol.asyncDispose] = async() => sql.release())
     sql.stats = stats
     return sql
+
+    // dd-trace starts query spans only inside function declarations named handler
+    function handler(q) {
+      send(l, q)
+    }
   }
 
   async function begin(options, fn) {
@@ -348,7 +356,7 @@ function Postgres(a, b) {
     }
 
     async function transaction() {
-      await Sql(q => send(l, q)).unsafe('begin ' + options.replace(/[^a-z ]/ig, ''), []).execute().catch(e => {
+      await Sql(handler).unsafe('begin ' + options.replace(/[^a-z ]/ig, ''), []).execute().catch(e => {
         e instanceof PostgresError && settle(l, Lease.Released)
         throw e
       })
@@ -359,7 +367,7 @@ function Postgres(a, b) {
       let result
       l.state = Lease.Settling
       try {
-        result = await statement(Sql(q => send(l, q, Lease.Settling)))
+        result = await statement(Sql(q => handler(q, Lease.Settling)))
       } catch (e) {
         settle(l, Lease.Discarded)
         throw e
@@ -369,7 +377,7 @@ function Postgres(a, b) {
     }
 
     async function scope(fn, name) {
-      const sql = Sql(handler)
+      const sql = Sql(track)
       sql.savepoint = savepoint
       sql.prepare = x => {
         if (typeof x !== 'string' || !x || x.includes('\0'))
@@ -423,11 +431,16 @@ function Postgres(a, b) {
         return scope(fn, 's' + savepoints++ + (name ? '_' + name : ''))
       }
 
-      function handler(q) {
+      function track(q) {
         q.catch(e => uncaughtError || (uncaughtError = e))
-        send(l, q)
+        handler(q)
       }
     }
+
+    // dd-trace starts query spans only inside function declarations named handler
+    function handler(q, expected) {
+      send(l, q, expected)
+    }
   }
 
   function move(c, queue) {
@@ -675,6 +688,7 @@ function parseOptions(a, b) {
     prepare         : true,
     debug           : false,
     fetch_types     : true,
+    parameter_types : 'server',
     publications    : 'alltables',
     target_session_attrs: null
   }
@@ -705,11 +719,13 @@ function parseOptions(a, b) {
     },
     types           : o.types || {},
     target_session_attrs: tsa(o, url, env),
+    parameter_types : parameterTypes(o, url, env),
     onnotice        : o.onnotice,
     onnotify        : o.onnotify,
     onclose         : o.onclose,
     onidle          : o.onidle,
     onparameter     : o.onparameter,
+    ontypemismatch  : o.ontypemismatch,
     socket          : o.socket,
     transform       : parseTransform(o.transform || { undefined: undefined }),
     parameters      : {},
@@ -729,6 +745,14 @@ function tsa(o, url, env) {
   throw new Error('target_session_attrs ' + x + ' is not supported')
 }
 
+function parameterTypes(o, url, env) {
+  const x = o.parameter_types || url.searchParams.get('parameter_types') || env.PGPARAMETER_TYPES || 'server'
+  if (['server', 'client', 'warn'].includes(x))
+    return x
+
+  throw new Error('parameter_types ' + x + ' is not supported')
+}
+
 function max_lifetime() {
   return 60 * (30 + Math.random() * 30)
 }

package/cf/src/query.js

@@ -23,16 +23,9 @@ export class Query extends Promise {
     this.state = null
     this.statement = null
 
-    this.resolve = x => {
-      this.active = false
-      this.settled = true
-      resolve(x)
-    }
-    this.reject = x => {
-      this.active = false
-      this.settled = true
-      reject(x)
-    }
+    // dd-trace's load-time rewrite only accepts single-expression arrows here
+    this.resolve = x => (this.active = false, this.settled = true, resolve(x))
+    this.reject = x => (this.active = false, this.settled = true, reject(x))
 
     this.active = false
     this.settled = false

package/cf/src/types.js

@@ -249,6 +249,11 @@ export const inferType = function inferType(x) {
   )
 }
 
+export function clientSerialize(x) {
+  const proto = typeof x === 'object' && Object.getPrototypeOf(x)
+  return proto === Object.prototype || proto === null ? JSON.stringify(x) : '' + x
+}
+
 const escapeBackslash = /\\/g
 const escapeQuote = /"/g
 

package/cjs/src/connection.js

@@ -4,7 +4,7 @@ const crypto = require('crypto')
 const Stream = require('stream')
 const { performance } = require('perf_hooks')
 
-const { stringify, handleValue, addArrayType } = require('./types.js')
+const { stringify, handleValue, addArrayType, clientSerialize } = require('./types.js')
 const { Errors, callback } = require('./errors.js')
 const Result = require('./result.js')
 const Queue = require('./queue.js')
@@ -214,7 +214,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'),
@@ -538,7 +541,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) {
@@ -576,7 +579,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
@@ -604,8 +607,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++ : '' }
@@ -689,7 +695,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 },
@@ -1213,20 +1219,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)
@@ -1234,7 +1241,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/cjs/src/index.js

@@ -86,7 +86,8 @@ function Postgres(a, b) {
     listen,
     begin,
     close,
-    end
+    end,
+    ...Symbol.asyncDispose && { [Symbol.asyncDispose]: () => end() }
   })
 
   return sql
@@ -327,10 +328,17 @@ function Postgres(a, b) {
 
   async function reserve() {
     const l = await lease(false)
-    const sql = Sql(q => send(l, q))
+    const sql = Sql(handler)
     sql.release = () => settle(l, Lease.Released)
+    Symbol.dispose && (sql[Symbol.dispose] = () => sql.release())
+    Symbol.asyncDispose && (sql[Symbol.asyncDispose] = async() => sql.release())
     sql.stats = stats
     return sql
+
+    // dd-trace starts query spans only inside function declarations named handler
+    function handler(q) {
+      send(l, q)
+    }
   }
 
   async function begin(options, fn) {
@@ -347,7 +355,7 @@ function Postgres(a, b) {
     }
 
     async function transaction() {
-      await Sql(q => send(l, q)).unsafe('begin ' + options.replace(/[^a-z ]/ig, ''), []).execute().catch(e => {
+      await Sql(handler).unsafe('begin ' + options.replace(/[^a-z ]/ig, ''), []).execute().catch(e => {
         e instanceof PostgresError && settle(l, Lease.Released)
         throw e
       })
@@ -358,7 +366,7 @@ function Postgres(a, b) {
       let result
       l.state = Lease.Settling
       try {
-        result = await statement(Sql(q => send(l, q, Lease.Settling)))
+        result = await statement(Sql(q => handler(q, Lease.Settling)))
       } catch (e) {
         settle(l, Lease.Discarded)
         throw e
@@ -368,7 +376,7 @@ function Postgres(a, b) {
     }
 
     async function scope(fn, name) {
-      const sql = Sql(handler)
+      const sql = Sql(track)
       sql.savepoint = savepoint
       sql.prepare = x => {
         if (typeof x !== 'string' || !x || x.includes('\0'))
@@ -422,11 +430,16 @@ function Postgres(a, b) {
         return scope(fn, 's' + savepoints++ + (name ? '_' + name : ''))
       }
 
-      function handler(q) {
+      function track(q) {
         q.catch(e => uncaughtError || (uncaughtError = e))
-        send(l, q)
+        handler(q)
       }
     }
+
+    // dd-trace starts query spans only inside function declarations named handler
+    function handler(q, expected) {
+      send(l, q, expected)
+    }
   }
 
   function move(c, queue) {
@@ -674,6 +687,7 @@ function parseOptions(a, b) {
     prepare         : true,
     debug           : false,
     fetch_types     : true,
+    parameter_types : 'server',
     publications    : 'alltables',
     target_session_attrs: null
   }
@@ -704,11 +718,13 @@ function parseOptions(a, b) {
     },
     types           : o.types || {},
     target_session_attrs: tsa(o, url, env),
+    parameter_types : parameterTypes(o, url, env),
     onnotice        : o.onnotice,
     onnotify        : o.onnotify,
     onclose         : o.onclose,
     onidle          : o.onidle,
     onparameter     : o.onparameter,
+    ontypemismatch  : o.ontypemismatch,
     socket          : o.socket,
     transform       : parseTransform(o.transform || { undefined: undefined }),
     parameters      : {},
@@ -728,6 +744,14 @@ function tsa(o, url, env) {
   throw new Error('target_session_attrs ' + x + ' is not supported')
 }
 
+function parameterTypes(o, url, env) {
+  const x = o.parameter_types || url.searchParams.get('parameter_types') || env.PGPARAMETER_TYPES || 'server'
+  if (['server', 'client', 'warn'].includes(x))
+    return x
+
+  throw new Error('parameter_types ' + x + ' is not supported')
+}
+
 function max_lifetime() {
   return 60 * (30 + Math.random() * 30)
 }

package/cjs/src/query.js

@@ -23,16 +23,9 @@ const Query = module.exports.Query = class Query extends Promise {
     this.state = null
     this.statement = null
 
-    this.resolve = x => {
-      this.active = false
-      this.settled = true
-      resolve(x)
-    }
-    this.reject = x => {
-      this.active = false
-      this.settled = true
-      reject(x)
-    }
+    // dd-trace's load-time rewrite only accepts single-expression arrows here
+    this.resolve = x => (this.active = false, this.settled = true, resolve(x))
+    this.reject = x => (this.active = false, this.settled = true, reject(x))
 
     this.active = false
     this.settled = false

package/cjs/src/types.js

@@ -248,6 +248,11 @@ const inferType = module.exports.inferType = function inferType(x) {
   )
 }
 
+module.exports.clientSerialize = clientSerialize;function clientSerialize(x) {
+  const proto = typeof x === 'object' && Object.getPrototypeOf(x)
+  return proto === Object.prototype || proto === null ? JSON.stringify(x) : '' + x
+}
+
 const escapeBackslash = /\\/g
 const escapeQuote = /"/g
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steadybrew/postgresjs",
-  "version": "4.4.1",
+  "version": "4.5.0-rc1",
   "description": "PostgreSQL client for Node.js and Deno, independently maintained by Steady Brew",
   "type": "module",
   "module": "src/index.js",
@@ -24,7 +24,7 @@
   "types": "types/index.d.ts",
   "typings": "types/index.d.ts",
   "engines": {
-    "node": ">=24"
+    "node": ">=22"
   },
   "scripts": {
     "build": "npm run build:cjs && npm run build:deno && npm run build:cf",
@@ -34,6 +34,7 @@
     "test": "npm run test:startup && npm run test:esm && npm run test:cjs && npm run test:deno",
     "test:esm": "node tests-startup/run.js --integration && node tests/index.js",
     "test:startup": "node tests-startup/run.js",
+    "test:tracing": "node tests-tracing/run.js",
     "test:cjs": "npm run build:cjs && node tests-startup/run.js --integration --cjs && cd cjs/tests && node index.js && cd ../../",
     "test:deno": "npm run test:deno-socket && npm run build:deno && cd deno/tests && deno run --no-lock --allow-all --unsafely-ignore-certificate-errors index.js && cd ../../",
     "lint": "eslint src && eslint tests && eslint tests-startup --ext .js,.mjs",

package/src/connection.js

@@ -4,7 +4,7 @@ import crypto from 'crypto'
 import Stream from 'stream'
 import { performance } from 'perf_hooks'
 
-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'
@@ -214,7 +214,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'),
@@ -538,7 +541,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) {
@@ -576,7 +579,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
@@ -604,8 +607,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++ : '' }
@@ -689,7 +695,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 },
@@ -1213,20 +1219,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)
@@ -1234,7 +1241,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/src/index.js

@@ -86,7 +86,8 @@ function Postgres(a, b) {
     listen,
     begin,
     close,
-    end
+    end,
+    ...Symbol.asyncDispose && { [Symbol.asyncDispose]: () => end() }
   })
 
   return sql
@@ -327,10 +328,17 @@ function Postgres(a, b) {
 
   async function reserve() {
     const l = await lease(false)
-    const sql = Sql(q => send(l, q))
+    const sql = Sql(handler)
     sql.release = () => settle(l, Lease.Released)
+    Symbol.dispose && (sql[Symbol.dispose] = () => sql.release())
+    Symbol.asyncDispose && (sql[Symbol.asyncDispose] = async() => sql.release())
     sql.stats = stats
     return sql
+
+    // dd-trace starts query spans only inside function declarations named handler
+    function handler(q) {
+      send(l, q)
+    }
   }
 
   async function begin(options, fn) {
@@ -347,7 +355,7 @@ function Postgres(a, b) {
     }
 
     async function transaction() {
-      await Sql(q => send(l, q)).unsafe('begin ' + options.replace(/[^a-z ]/ig, ''), []).execute().catch(e => {
+      await Sql(handler).unsafe('begin ' + options.replace(/[^a-z ]/ig, ''), []).execute().catch(e => {
         e instanceof PostgresError && settle(l, Lease.Released)
         throw e
       })
@@ -358,7 +366,7 @@ function Postgres(a, b) {
       let result
       l.state = Lease.Settling
       try {
-        result = await statement(Sql(q => send(l, q, Lease.Settling)))
+        result = await statement(Sql(q => handler(q, Lease.Settling)))
       } catch (e) {
         settle(l, Lease.Discarded)
         throw e
@@ -368,7 +376,7 @@ function Postgres(a, b) {
     }
 
     async function scope(fn, name) {
-      const sql = Sql(handler)
+      const sql = Sql(track)
       sql.savepoint = savepoint
       sql.prepare = x => {
         if (typeof x !== 'string' || !x || x.includes('\0'))
@@ -422,11 +430,16 @@ function Postgres(a, b) {
         return scope(fn, 's' + savepoints++ + (name ? '_' + name : ''))
       }
 
-      function handler(q) {
+      function track(q) {
         q.catch(e => uncaughtError || (uncaughtError = e))
-        send(l, q)
+        handler(q)
       }
     }
+
+    // dd-trace starts query spans only inside function declarations named handler
+    function handler(q, expected) {
+      send(l, q, expected)
+    }
   }
 
   function move(c, queue) {
@@ -674,6 +687,7 @@ function parseOptions(a, b) {
     prepare         : true,
     debug           : false,
     fetch_types     : true,
+    parameter_types : 'server',
     publications    : 'alltables',
     target_session_attrs: null
   }
@@ -704,11 +718,13 @@ function parseOptions(a, b) {
     },
     types           : o.types || {},
     target_session_attrs: tsa(o, url, env),
+    parameter_types : parameterTypes(o, url, env),
     onnotice        : o.onnotice,
     onnotify        : o.onnotify,
     onclose         : o.onclose,
     onidle          : o.onidle,
     onparameter     : o.onparameter,
+    ontypemismatch  : o.ontypemismatch,
     socket          : o.socket,
     transform       : parseTransform(o.transform || { undefined: undefined }),
     parameters      : {},
@@ -728,6 +744,14 @@ function tsa(o, url, env) {
   throw new Error('target_session_attrs ' + x + ' is not supported')
 }
 
+function parameterTypes(o, url, env) {
+  const x = o.parameter_types || url.searchParams.get('parameter_types') || env.PGPARAMETER_TYPES || 'server'
+  if (['server', 'client', 'warn'].includes(x))
+    return x
+
+  throw new Error('parameter_types ' + x + ' is not supported')
+}
+
 function max_lifetime() {
   return 60 * (30 + Math.random() * 30)
 }

package/src/query.js

@@ -23,16 +23,9 @@ export class Query extends Promise {
     this.state = null
     this.statement = null
 
-    this.resolve = x => {
-      this.active = false
-      this.settled = true
-      resolve(x)
-    }
-    this.reject = x => {
-      this.active = false
-      this.settled = true
-      reject(x)
-    }
+    // dd-trace's load-time rewrite only accepts single-expression arrows here
+    this.resolve = x => (this.active = false, this.settled = true, resolve(x))
+    this.reject = x => (this.active = false, this.settled = true, reject(x))
 
     this.active = false
     this.settled = false

package/src/types.js

@@ -248,6 +248,11 @@ export const inferType = function inferType(x) {
   )
 }
 
+export function clientSerialize(x) {
+  const proto = typeof x === 'object' && Object.getPrototypeOf(x)
+  return proto === Object.prototype || proto === null ? JSON.stringify(x) : '' + x
+}
+
 const escapeBackslash = /\\/g
 const escapeQuote = /"/g
 

package/types/index.d.ts

@@ -110,6 +110,10 @@ interface BaseOptions<T extends Record<string, postgres.PostgresType>> {
    * @default true
    */
   fetch_types: boolean;
+  /** How values whose type cannot be told from the JavaScript value are serialized: 'server' (default) asks PostgreSQL for the placeholder's type first, 'client' sends their text for PostgreSQL to parse, 'warn' does the same as 'server' and reports values 'client' would send differently */
+  parameter_types: 'server' | 'client' | 'warn';
+  /** Called in parameter_types: 'warn' mode with each query whose values would be sent differently, console.warn by default; if it throws, the error is rethrown as an uncaught exception */
+  ontypemismatch: (report: postgres.TypeMismatchReport) => void;
   /**
    * Publications to subscribe to (only relevant when calling `sql.subscribe()`)
    * @default 'alltables'
@@ -411,6 +415,23 @@ declare namespace postgres {
     };
   }
 
+  interface TypeMismatchReport {
+    query: string;
+    parameters: TypeMismatch[];
+  }
+
+  interface TypeMismatch {
+    /** The `$n` number of the placeholder */
+    position: number;
+    /** The type OID PostgreSQL inferred for the placeholder */
+    oid: number;
+    typeof: string;
+    /** Only set when debug is enabled */
+    serverText?: string;
+    /** Only set when debug is enabled; the error is what the 'client' mode would throw */
+    clientText?: string | globalThis.Error;
+  }
+
   interface Notice {
     [field: string]: string;
   }
@@ -742,6 +763,9 @@ declare namespace postgres {
 
     end(options?: { timeout?: number | undefined } | undefined): Promise<void>;
 
+    /** Calls `end()` with no timeout when an `await using` scope exits */
+    [Symbol.asyncDispose](): Promise<void>;
+
     listen(channel: string, onnotify: (value: string) => void, onlisten?: (() => void) | undefined): ListenRequest;
 
     /** `onerror` receives replication connection errors and errors thrown while a change is decoded; such a change is skipped. */
@@ -767,6 +791,12 @@ declare namespace postgres {
 
   interface ReservedSql<TTypes extends Record<string, unknown> = {}> extends Sql<TTypes> {
     release(): void;
+
+    /** Calls `release()` when a `using` scope exits */
+    [Symbol.dispose](): void;
+
+    /** Calls `release()` when an `await using` scope exits */
+    [Symbol.asyncDispose](): Promise<void>;
   }
 }
 

package/types/package.json

@@ -1,5 +1,5 @@
 {
   "devDependencies": {
-    "@types/node": "^16"
+    "@types/node": "^22"
   }
 }