@steadybrew/postgresjs 4.0.0 → 4.2.0-rc1

package/README.md

@@ -11,24 +11,35 @@ This is an independently maintained fork of [Postgres.js](https://github.com/por
 - 🏄‍♀️ Simple surface API
 - 🖊️ Dynamic query support
 
-<br>
+<br clear="all">
 
 ## Compatibility policy
 
-The next release raises the npm package's minimum Node.js version to **24**. This is a breaking compatibility change for applications using older Node versions. The minimum stays at Node 24 until an explicit policy change; newly maintained Node majors are tested before compatibility is claimed.
+**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 target | CI jobs | Validation status |
 | --- | --- | ---: | --- |
-| Node 24, ESM and CJS | 15, 16, 17, 18 | 4 | Locally validated |
-| Node 26, ESM and CJS | 15, 16, 17, 18 | 4 | Configured; local execution pending |
-| Deno 1.46.3 | 17 | 1 | Validated legacy runtime; no Deno 2 claim |
-| Cloudflare workerd, Wrangler 4.123.0 | 17 | 1 | Configured; startup/array, timer, `sql.end()` and TLS gates; #1202 "Stream was cancelled" still open |
+| 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 core Node matrix has eight jobs. Deno and Cloudflare run independently, so they do not multiply that matrix. PostgreSQL versions below 15 are outside the next release's supported matrix.
+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.
 
 Supabase PostgreSQL and Supabase Edge are separate environments. Deno 1.46.3 coverage does not imply Deno 2 or hosted Supabase Edge certification.
 
+## 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:
+
+- Upgrade to **Node.js 24 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.
+
 ## Getting started
 
 <br>
@@ -92,6 +103,7 @@ const { default: postgres } = await import('@steadybrew/postgresjs')
 
 ## Table of Contents
 
+* [Upgrading to 4.0.0](#upgrading-to-400)
 * [Connection](#connection)
 * [Queries](#queries)
 * [Building queries](#building-queries)
@@ -713,11 +725,13 @@ sql.begin('read write', async sql => {
 ```
 
 
-#### PREPARE TRANSACTION `await sql.prepare([name]) -> fn()`
+#### PREPARE TRANSACTION `sql.prepare(name)`
 
 Indicates that the transactions should be prepared using the [`PREPARE TRANSACTION [NAME]`](https://www.postgresql.org/docs/current/sql-prepare-transaction.html) statement
 instead of being committed.
 
+The name must be a non-empty string without NUL characters; invalid names throw `INVALID_TRANSACTION_NAME`. Quotes and backslashes in valid names are preserved.
+
 ```js
 sql.begin('read write', async sql => {
   const [user] = await sql`
@@ -1017,6 +1031,7 @@ const sql = postgres('postgres://username:password@host:port/database', {
   types                : [],            // Array of custom types, see more below
   onnotice             : fn,            // Default console.log, set false to silence NOTICE
   onparameter          : fn,            // (key, value) when server param change
+  onidle               : fn,            // (connId) when a connection returns to the pool idle
   debug                : fn,            // Is called with (connection, query, params, types)
   socket               : fn,            // fn returning custom socket to use
   transform            : {
@@ -1114,7 +1129,7 @@ By default, connections will not close until `.end()` is called. However, it may
 - using Postgres.js in a Serverless environment (Lambda, etc.)
 - using Postgres.js with a database service that automatically closes connections after some time (see [`ECONNRESET` issue](https://github.com/porsager/postgres/issues/179))
 
-This can be done using the `idle_timeout` or `max_lifetime` options. These configuration options specify the number of seconds to wait before automatically closing an idle connection and the maximum time a connection can exist, respectively.
+This can be done using the `idle_timeout` or `max_lifetime` options. These configuration options specify the number of seconds to wait before automatically closing an idle connection and the maximum time a connection can exist, respectively. Both are also checked when an idle connection is handed out, so an idle connection that is past either limit (for example after a serverless instance was frozen) is closed instead of being used.
 
 For example, to close a connection that has either been idle for 20 seconds or existed for more than 30 minutes:
 
@@ -1125,6 +1140,21 @@ const sql = postgres({
 })
 ```
 
+### Vercel Fluid Compute
+
+On Vercel's Fluid Compute an instance can be suspended while a connection sits idle and before `idle_timeout` has closed it, which leaves the connection open on the server. `attachDatabasePool` from `@vercel/functions` keeps the instance alive until idle connections have closed. Pass it the pool through `vercelPool`:
+
+```js
+import postgres from '@steadybrew/postgresjs'
+import { vercelPool } from '@steadybrew/postgresjs/vercel'
+import { attachDatabasePool } from '@vercel/functions'
+
+const sql = postgres({ idle_timeout: 5 })
+attachDatabasePool(vercelPool(sql))
+```
+
+`vercelPool` requires `idle_timeout` to be a number of seconds. It hooks into the `onidle` option, which is called with the connection id each time a connection returns to the pool idle and its idle timer starts, and it keeps any `onidle` you set yourself. If `onidle` throws, the error is rethrown as an uncaught exception and the connection is not affected. A connection that was frozen past `idle_timeout` anyway is closed when it is next handed out (see [Connection timeout](#connection-timeout)).
+
 ### Cloudflare Workers support
 
 Postgres.js has built-in support for the [TCP socket API](https://developers.cloudflare.com/workers/runtime-apis/tcp-sockets/) in Cloudflare Workers, which is [on-track](https://github.com/wintercg/proposal-sockets-api) to be standardized and adopted in Node.js and other JavaScript runtimes, such as Deno.
@@ -1291,6 +1321,8 @@ await reserved.release()
 
 Once you have finished with the reserved connection, call `release` to add it back to the pool.
 
+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
 
 Errors are all thrown to related queries and never globally. Errors coming from database itself are always in the [native Postgres format](https://www.postgresql.org/docs/current/errcodes-appendix.html), and the same goes for any [Node.js errors](https://nodejs.org/api/errors.html#errors_common_system_errors) eg. coming from the underlying connection.
@@ -1331,6 +1363,16 @@ When using SASL authentication the server responds with a signature at the end o
 
 Making queries has to be done using the sql function as a [tagged template](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_templates). This is to ensure parameters are serialized and passed to Postgres as query parameters with correct types and to avoid SQL injection.
 
+##### SSL_NOT_SUPPORTED
+> The server does not support SSL connections
+
+The server answered the SSL request with a refusal while `ssl` is set to `require` (or another mode that does not fall back to plain text). The attempt fails at once for a single host. Use `ssl: 'prefer'` to fall back to an unencrypted connection, or enable SSL on the server.
+
+##### TARGET_SESSION_ATTRS
+> No host matched target_session_attrs=read-write: localhost:5432 is read-only
+
+No host satisfied [`target_session_attrs`](#connection-details). This error is the `cause` of the `CONNECTION_CLOSED` error the query rejects with, so retry logic keyed on `CONNECTION_CLOSED` keeps working; read `err.cause.code` and `err.cause.message` for the reason. The message names the requested value and each host with the reason it was rejected. With several hosts, the connection fails at once when every host answered and none matched; if any host failed for another reason (refused, closed, timed out), the client keeps retrying until `connect_timeout` instead, since a failover may be in progress. With a single host, the client keeps retrying until `connect_timeout` before failing, because a single endpoint that is read-only is often in the middle of a failover, for example a cluster DNS name that still points at the old primary.
+
 ##### AUTH_TYPE_NOT_IMPLEMENTED
 > Auth type X not implemented
 
@@ -1339,7 +1381,7 @@ Postgres supports many different authentication types. This one is not supported
 ##### CONNECTION_CLOSED
 > write CONNECTION_CLOSED host:port
 
-This error is thrown if the connection was closed without an error. This should not happen during normal operations, so please create an issue if this was unexpected.
+This error is thrown if the connection was closed, or could not be opened, without an error of its own. When the server or the network ended the session, or no host matched `target_session_attrs`, the underlying error is available as `err.cause`.
 
 ##### CONNECTION_ENDED
 > write CONNECTION_ENDED host:port
@@ -1356,7 +1398,7 @@ This error is thrown for any queries that were pending when the timeout to [`sql
 ##### CONNECT_TIMEOUT
 > write CONNECT_TIMEOUT host:port
 
-The timeout applies to each connection attempt and covers socket creation, TCP and TLS negotiation, authentication, session checks and type discovery. When an attempt times out, the next host is tried. The acquisition as a whole is bounded by `connect_timeout` multiplied by the number of hosts, measured from the first attempt; time spent waiting on an inherited reconnect delay is not counted. Set it with `connect_timeout` or `PGCONNECT_TIMEOUT` (30 seconds by default); zero disables both limits.
+The timeout applies to each connection attempt and covers socket creation, TCP and TLS negotiation, authentication, session checks and type discovery. When an attempt times out, the next host is tried. The acquisition as a whole is bounded by `connect_timeout` multiplied by the number of hosts, measured from the first attempt; time spent waiting on an inherited reconnect delay is not counted. Set it with `connect_timeout` or `PGCONNECT_TIMEOUT` (30 seconds by default); zero disables both limits. The same value also bounds a graceful close: if the server does not close the socket within `connect_timeout` seconds after `end()` sends Terminate, the connection is closed anyway; zero leaves a graceful close unbounded.
 
 If the only attempt times out, the error is `CONNECT_TIMEOUT`. Once earlier attempts have failed, exhausting the overall budget reports the earlier error, such as the last server error or `CONNECTION_CLOSED`. With a single host, a socket or socket factory error rejects the query once; with several hosts, errors keep cycling through the hosts with backoff until the budget is spent. Queries already sent to the server are not replayed.