@steadybrew/postgresjs 3.4.9 → 4.0.0

package/README.md

@@ -13,6 +13,22 @@ This is an independently maintained fork of [Postgres.js](https://github.com/por
 
 <br>
 
+## 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.
+
+| 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 |
+| 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.
+
+Supabase PostgreSQL and Supabase Edge are separate environments. Deno 1.46.3 coverage does not imply Deno 2 or hosted Supabase Edge certification.
+
 ## Getting started
 
 <br>
@@ -1139,11 +1155,15 @@ compatibility_flags = ["nodejs_compat"]
 
 ### Auto fetching of array types
 
-Postgres.js will automatically fetch table/array-type information when it first connects to a database.
+Postgres.js automatically fetches array-type information when each connection initializes.
 
 If you have revoked access to `pg_catalog` this feature will no longer work and will need to be disabled.
 
-You can disable this feature by setting `fetch_types` to `false`.
+You can disable catalog discovery by setting `fetch_types` to `false`. A fixed set of 22 common built-in array types still supports parsing and serialization, including text, numeric, boolean, JSON, date, UUID, and byte arrays. This changes earlier `fetch_types: false` behavior, which returned built-in arrays as raw strings. Other built-in, user-defined, and extension arrays still require discovery or explicit type handlers.
+
+SQL `NULL` elements are returned as JavaScript `null`; a quoted text element `"NULL"` remains a string. Explicit array parsers and serializers are preserved independently. Catalog discovery with `fetch_types: true` remains per connection; this change does not cache catalog metadata.
+
+Column, value, and row transforms apply to application query results; initialization metadata retains its original shape.
 
 ### Environmental variables
 
@@ -1326,6 +1346,8 @@ This error is thrown if the connection was closed without an error. This should
 
 This error is thrown if the user has called [`sql.end()`](#teardown--cleanup) and performed a query afterward.
 
+A reserved `sql` used after `release()`, or a transaction `sql` used after `begin()` has committed, rolled back or prepared, also rejects with `CONNECTION_ENDED`.
+
 ##### CONNECTION_DESTROYED
 > write CONNECTION_DESTROYED host:port
 
@@ -1334,7 +1356,9 @@ This error is thrown for any queries that were pending when the timeout to [`sql
 ##### CONNECT_TIMEOUT
 > write CONNECT_TIMEOUT host:port
 
-This error is thrown if the startup phase of the connection (tcp, protocol negotiation, and auth) took more than the default 30 seconds or what was specified using `connect_timeout` or `PGCONNECT_TIMEOUT`.
+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.
+
+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.
 
 ##### COPY_IN_PROGRESS
 > You cannot execute queries during copy

package/cf/polyfills.js

@@ -3,6 +3,7 @@ import { Buffer } from 'node:buffer'
 
 const Crypto = globalThis.crypto
 
+const noop = () => undefined
 let ids = 1
 const tasks = new Set()
 
@@ -115,8 +116,8 @@ export const tls = {
     tcp.readyState = 'upgrading'
     tcp.raw = tcp.raw.startTls({ servername })
     tcp.raw.closed.then(
-      () => tcp.emit('close'),
-      (e) => tcp.emit('error', e)
+      () => tcp.close(),
+      (e) => (tcp.closing || tcp.emit('error', e), tcp.close())
     )
     tcp.writer = tcp.raw.writable.getWriter()
     tcp.reader = tcp.raw.readable.getReader()
@@ -139,7 +140,8 @@ function Socket() {
     write,
     end,
     destroy,
-    read
+    read,
+    close
   })
 
   return tcp
@@ -148,14 +150,19 @@ function Socket() {
     try {
       tcp.readyState = 'opening'
       const { connect } = await import('cloudflare:sockets')
-      tcp.raw = connect(host + ':' + port, tcp.ssl ? { secureTransport: 'starttls' } : {})
+      const raw = connect(host + ':' + port, tcp.ssl ? { secureTransport: 'starttls' } : {})
+      if (tcp.destroyed || tcp.closing) {
+        raw.closed.catch(noop)
+        return Promise.resolve(raw.close()).catch(noop)
+      }
+      tcp.raw = raw
       tcp.raw.closed.then(
         () => {
           tcp.readyState !== 'upgrade'
             ? close()
             : ((tcp.readyState = 'open'), tcp.emit('secureConnect'))
         },
-        (e) => tcp.emit('error', e)
+        (e) => (tcp.closing || tcp.emit('error', e), close())
       )
       tcp.writer = tcp.raw.writable.getWriter()
       tcp.reader = tcp.raw.readable.getReader()
@@ -184,6 +191,10 @@ function Socket() {
   }
 
   function end(data) {
+    tcp.closing = true
+    if (!tcp.raw)
+      return close()
+
     return data
       ? tcp.write(data, () => tcp.raw.close())
       : tcp.raw.close()
@@ -206,13 +217,20 @@ function Socket() {
   }
 
   async function readFirst() {
-    const { value } = await tcp.reader.read()
-    tcp.emit('data', Buffer.from(value))
+    try {
+      const { done, value } = await tcp.reader.read()
+      if (done)
+        return close()
+
+      tcp.emit('data', Buffer.from(value))
+    } catch (err) {
+      error(err)
+    }
   }
 
   function error(err) {
-    tcp.emit('error', err)
-    tcp.emit('close')
+    tcp.closing || tcp.emit('error', err)
+    close()
   }
 }