@steadybrew/postgresjs 4.1.0 → 4.2.0-rc1

package/README.md

@@ -1031,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            : {
@@ -1139,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.

package/cf/src/index.js

@@ -160,6 +160,7 @@ function Postgres(a, b) {
       idle_timeout: null,
       max_lifetime: null,
       fetch_types: false,
+      onidle: null,
       onclose() {
         Object.entries(listen.channels).forEach(([name, { listeners }]) => {
           delete listen.channels[name]
@@ -369,11 +370,19 @@ function Postgres(a, b) {
     queue.push(c)
     c.queue = queue
     queue === open
-      ? c.idleTimer.start()
+      ? (c.idleTimer.start(), callback(options.onidle, c.id))
       : c.idleTimer.cancel()
     return c
   }
 
+  function callback(fn, ...args) {
+    try {
+      fn && fn(...args)
+    } catch (e) {
+      queueMicrotask(() => { throw e })
+    }
+  }
+
   function json(x) {
     return new Parameter(x, 3802)
   }
@@ -616,6 +625,7 @@ function parseOptions(a, b) {
     onnotice        : o.onnotice,
     onnotify        : o.onnotify,
     onclose         : o.onclose,
+    onidle          : o.onidle,
     onparameter     : o.onparameter,
     socket          : o.socket,
     transform       : parseTransform(o.transform || { undefined: undefined }),

package/cf/src/subscribe.js

@@ -17,6 +17,7 @@ export default function Subscribe(postgres, options) {
     fetch_types: false,
     idle_timeout: null,
     max_lifetime: null,
+    onidle: null,
     connection: {
       ...options.connection,
       replication: 'database'

package/cf/src/vercel.js

@@ -0,0 +1,20 @@
+export function vercelPool(sql) {
+  const idle_timeout = sql.options.idle_timeout
+  if (typeof idle_timeout !== 'number' || !(idle_timeout > 0))
+    throw new Error('vercelPool requires idle_timeout to be a positive number of seconds')
+
+  return {
+    options: {
+      idleTimeoutMillis: idle_timeout * 1000
+    },
+    on(event, fn) {
+      if (event !== 'release')
+        return
+
+      const previous = sql.options.onidle
+      sql.options.onidle = previous
+        ? id => (fn(), previous(id))
+        : () => fn()
+    }
+  }
+}

package/cjs/src/index.js

@@ -159,6 +159,7 @@ function Postgres(a, b) {
       idle_timeout: null,
       max_lifetime: null,
       fetch_types: false,
+      onidle: null,
       onclose() {
         Object.entries(listen.channels).forEach(([name, { listeners }]) => {
           delete listen.channels[name]
@@ -368,11 +369,19 @@ function Postgres(a, b) {
     queue.push(c)
     c.queue = queue
     queue === open
-      ? c.idleTimer.start()
+      ? (c.idleTimer.start(), callback(options.onidle, c.id))
       : c.idleTimer.cancel()
     return c
   }
 
+  function callback(fn, ...args) {
+    try {
+      fn && fn(...args)
+    } catch (e) {
+      queueMicrotask(() => { throw e })
+    }
+  }
+
   function json(x) {
     return new Parameter(x, 3802)
   }
@@ -615,6 +624,7 @@ function parseOptions(a, b) {
     onnotice        : o.onnotice,
     onnotify        : o.onnotify,
     onclose         : o.onclose,
+    onidle          : o.onidle,
     onparameter     : o.onparameter,
     socket          : o.socket,
     transform       : parseTransform(o.transform || { undefined: undefined }),

package/cjs/src/subscribe.js

@@ -16,6 +16,7 @@ module.exports = Subscribe;function Subscribe(postgres, options) {
     fetch_types: false,
     idle_timeout: null,
     max_lifetime: null,
+    onidle: null,
     connection: {
       ...options.connection,
       replication: 'database'

package/cjs/src/vercel.js

@@ -0,0 +1,20 @@
+module.exports.vercelPool = vercelPool;function vercelPool(sql) {
+  const idle_timeout = sql.options.idle_timeout
+  if (typeof idle_timeout !== 'number' || !(idle_timeout > 0))
+    throw new Error('vercelPool requires idle_timeout to be a positive number of seconds')
+
+  return {
+    options: {
+      idleTimeoutMillis: idle_timeout * 1000
+    },
+    on(event, fn) {
+      if (event !== 'release')
+        return
+
+      const previous = sql.options.onidle
+      sql.options.onidle = previous
+        ? id => (fn(), previous(id))
+        : () => fn()
+    }
+  }
+}

package/package.json

@@ -1,16 +1,25 @@
 {
   "name": "@steadybrew/postgresjs",
-  "version": "4.1.0",
+  "version": "4.2.0-rc1",
   "description": "PostgreSQL client for Node.js and Deno, independently maintained by Steady Brew",
   "type": "module",
   "module": "src/index.js",
   "main": "cjs/src/index.js",
   "exports": {
-    "types": "./types/index.d.ts",
-    "bun": "./src/index.js",
-    "workerd": "./cf/src/index.js",
-    "import": "./src/index.js",
-    "default": "./cjs/src/index.js"
+    ".": {
+      "types": "./types/index.d.ts",
+      "bun": "./src/index.js",
+      "workerd": "./cf/src/index.js",
+      "import": "./src/index.js",
+      "default": "./cjs/src/index.js"
+    },
+    "./vercel": {
+      "types": "./types/vercel.d.ts",
+      "bun": "./src/vercel.js",
+      "workerd": "./cf/src/vercel.js",
+      "import": "./src/vercel.js",
+      "default": "./cjs/src/vercel.js"
+    }
   },
   "types": "types/index.d.ts",
   "typings": "types/index.d.ts",
@@ -44,7 +53,10 @@
   ],
   "author": "Rasmus Porsager <rasmus@porsager.com> (https://www.porsager.com)",
   "license": "Unlicense",
-  "repository": "github:steadybrew/postgresjs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/steadybrew/postgresjs.git"
+  },
   "homepage": "https://github.com/steadybrew/postgresjs",
   "bugs": "https://github.com/steadybrew/postgresjs/issues",
   "keywords": [

package/src/index.js

@@ -159,6 +159,7 @@ function Postgres(a, b) {
       idle_timeout: null,
       max_lifetime: null,
       fetch_types: false,
+      onidle: null,
       onclose() {
         Object.entries(listen.channels).forEach(([name, { listeners }]) => {
           delete listen.channels[name]
@@ -368,11 +369,19 @@ function Postgres(a, b) {
     queue.push(c)
     c.queue = queue
     queue === open
-      ? c.idleTimer.start()
+      ? (c.idleTimer.start(), callback(options.onidle, c.id))
       : c.idleTimer.cancel()
     return c
   }
 
+  function callback(fn, ...args) {
+    try {
+      fn && fn(...args)
+    } catch (e) {
+      queueMicrotask(() => { throw e })
+    }
+  }
+
   function json(x) {
     return new Parameter(x, 3802)
   }
@@ -615,6 +624,7 @@ function parseOptions(a, b) {
     onnotice        : o.onnotice,
     onnotify        : o.onnotify,
     onclose         : o.onclose,
+    onidle          : o.onidle,
     onparameter     : o.onparameter,
     socket          : o.socket,
     transform       : parseTransform(o.transform || { undefined: undefined }),

package/src/subscribe.js

@@ -16,6 +16,7 @@ export default function Subscribe(postgres, options) {
     fetch_types: false,
     idle_timeout: null,
     max_lifetime: null,
+    onidle: null,
     connection: {
       ...options.connection,
       replication: 'database'

package/src/vercel.js

@@ -0,0 +1,20 @@
+export function vercelPool(sql) {
+  const idle_timeout = sql.options.idle_timeout
+  if (typeof idle_timeout !== 'number' || !(idle_timeout > 0))
+    throw new Error('vercelPool requires idle_timeout to be a positive number of seconds')
+
+  return {
+    options: {
+      idleTimeoutMillis: idle_timeout * 1000
+    },
+    on(event, fn) {
+      if (event !== 'release')
+        return
+
+      const previous = sql.options.onidle
+      sql.options.onidle = previous
+        ? id => (fn(), previous(id))
+        : () => fn()
+    }
+  }
+}

package/types/index.d.ts

@@ -119,6 +119,8 @@ interface BaseOptions<T extends Record<string, postgres.PostgresType>> {
    */
   publications: string
   onclose: (connId: number) => void;
+  /** Called with the connection id each time a connection returns to the pool idle and its idle timer starts */
+  onidle: (connId: number) => void;
   backoff: boolean | ((attemptNum: number) => number);
   max_lifetime: number | null;
   keep_alive: number | null;

package/types/vercel.d.ts

@@ -0,0 +1,8 @@
+import postgres from './index.js'
+
+export interface VercelPool {
+  options: { idleTimeoutMillis: number };
+  on(event: string, listener: () => void): void;
+}
+
+export function vercelPool(sql: postgres.Sql<any>): VercelPool;