@steadybrew/postgresjs 4.2.0-rc1 → 4.3.0

package/README.md

@@ -1121,6 +1121,58 @@ There are no guarantees about queries executing in order unless using a transact
 
 Since this library automatically creates prepared statements, it also has a default max lifetime for connections to prevent memory bloat on the database itself. This is a random interval for each connection between 45 and 90 minutes. This allows multiple connections to independently come up and down without affecting the service.
 
+### Pool stats
+
+`sql.stats()` returns a snapshot of the pool as a plain object, ready to log, serialise from a health endpoint or map to metrics gauges:
+
+```js
+sql.stats()
+// { max: 10, totalCount: 7, idleCount: 2, waitingCount: 3,
+//   activeCount: 4, availableCount: 5,
+//   busyCount: 3, reservedCount: 1, connectingCount: 1, closingCount: 0,
+//   executingCount: 4, listenCount: 1, subscribeCount: 0 }
+```
+
+| Field | Meaning |
+|---|---|
+| `max` | The `max` option |
+| `totalCount` | Connections that exist: connecting, idle or in use |
+| `idleCount` | Connections with a live session that are not in use. A connection released while its reserved handle still has queries in flight is idle with `executingCount` above 0 |
+| `waitingCount` | Issued queries and `reserve()` or `begin()` calls that are not running yet: those in the pool queue, those held by a connection that is still opening, those pipelined behind a connection's running query, and those a reserved handle or transaction has queued behind its own connection |
+| `activeCount` | `busyCount + reservedCount`, connections in use |
+| `availableCount` | `idleCount` plus the slots the pool can still open (`max - totalCount - closingCount`): connections a query can get without waiting behind other work |
+| `busyCount` | Pool connections running queries, including connections at the pipeline limit |
+| `reservedCount` | Connections held by `reserve()` or `begin()` |
+| `connectingCount` | Connections opening a session |
+| `closingCount` | Connections draining or closing. They are not in `totalCount`, but still hold a pool slot until closed |
+| `executingCount` | Queries the server is running right now, at most one per connection, on pool and reserved connections alike. It includes the queries the driver runs while a connection starts, and a `COPY` for its whole duration |
+| `listenCount` | Connections held by the internal `sql.listen()` pool (0 or 1) |
+| `subscribeCount` | Connections held by the internal `sql.subscribe()` pool (0 or 1) |
+
+`totalCount` and `idleCount` have the same meaning as in node-postgres. `waitingCount` is node-postgres's `waitingCount` extended to queries pipelined on connections and queued in leases, and it includes queries sent with `sql` directly, as `pool.query()` does there. Once the pool is at `max`, Postgres.js pipelines new queries onto busy connections, so waiting work can sit on a connection rather than in the pool queue; `waitingCount` counts it too, so `executingCount + waitingCount` covers all issued work that has not finished. Every snapshot satisfies `totalCount === idleCount + busyCount + reservedCount + connectingCount` and `totalCount + closingCount <= max`, the remainder being slots the pool has not opened.
+
+`listenCount` and `subscribeCount` are counted outside `max`, and the other fields only describe the `max` pool connections. A reserved connection's `stats()` returns the same snapshot, but `sql` inside `sql.begin()` and savepoints has no `stats()`, so call it on the main `sql`.
+
+The pool is saturated when `waitingCount > 0 && availableCount === 0`: every connection is in use and more work is waiting. Saturation alone is not a reason to fail a health check, because a single pipelined query on a fully used pool, including a transaction pipelining its own statements, is enough to meet it. A health endpoint should compare `waitingCount` against a limit the application chooses:
+
+```js
+import http from 'node:http'
+
+const MAX_WAITING = 100
+
+http.createServer((req, res) => {
+  const stats = sql.stats()
+  const overloaded = stats.availableCount === 0 && stats.waitingCount > MAX_WAITING
+
+  res.writeHead(overloaded ? 503 : 200, { 'content-type': 'application/json' })
+  res.end(JSON.stringify(stats))
+}).listen(8080)
+```
+
+How much waiting work is acceptable depends on the query durations and the latency the application can tolerate, so the limit has no universal value.
+
+Change events and a running total of finished queries are planned together with the diagnostics events, so for now take snapshots on a timer or on request.
+
 ### Connection timeout
 
 By default, connections will not close until `.end()` is called. However, it may be useful to have them close automatically when:

package/cf/src/connection.js

@@ -224,6 +224,9 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
     },
     expired: () => idleTimer.expired() || lifeTimer.expired(),
     owner: null,
+    get active() { return query ? 1 : 0 },
+    get pipelined() { return sent.length },
+    get acquiring() { return acquisition && !acquisition.owner.cancelled ? 1 : 0 },
     count: 0,
     id
   }
@@ -529,9 +532,9 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
         && !q.cursorFn
         && sent.length < max_pipeline
     } catch (error) {
-      sent.length === 0 && write(Sync)
-      errored(error)
-      return true
+      sent.remove(q) || write(Sync)
+      queryError(q, error)
+      return sent.length < max_pipeline
     }
   }
 

package/cf/src/index.js

@@ -82,6 +82,7 @@ function Postgres(a, b) {
     PostgresError,
     options,
     reserve,
+    stats,
     listen,
     begin,
     close,
@@ -151,6 +152,56 @@ function Postgres(a, b) {
     }
   }
 
+  function stats() {
+    let idleCount = 0
+      , busyCount = 0
+      , reservedCount = 0
+      , connectingCount = 0
+      , closingCount = 0
+      , executingCount = 0
+      , waitingCount = queries.length
+
+    for (const c of connections) {
+      executingCount += c.active
+      waitingCount += c.pipelined + c.acquiring + (c.owner ? c.owner.queue.length : 0)
+      c.queue === open
+        ? idleCount++
+        : c.queue === connecting
+          ? connectingCount++
+          : c.queue === ended
+            ? closingCount++
+            : c.queue === reserved
+              ? reservedCount++
+              : (c.queue === busy || c.queue === full) && (c.owner ? reservedCount++ : busyCount++)
+    }
+
+    const totalCount = idleCount + busyCount + reservedCount + connectingCount
+
+    return {
+      max: options.max,
+      totalCount,
+      idleCount,
+      waitingCount,
+      activeCount: busyCount + reservedCount,
+      availableCount: idleCount + options.max - totalCount - closingCount,
+      busyCount,
+      reservedCount,
+      connectingCount,
+      closingCount,
+      executingCount,
+      listenCount: pooled(listen.sql),
+      subscribeCount: pooled(subscribe.sql)
+    }
+  }
+
+  function pooled(sql) {
+    if (!sql)
+      return 0
+
+    const s = sql.stats()
+    return s.totalCount + s.closingCount
+  }
+
   async function listen(name, fn, onlisten) {
     const listener = { fn, onlisten }
 
@@ -245,7 +296,7 @@ function Postgres(a, b) {
     const c = l.connection
     l.state === expected
       ? c.queue === full
-        ? l.queue.push(q)
+        ? (q.queue = l.queue, l.queue.push(q))
         : c.execute(q) || move(c, full)
       : q.reject(leaseError(l.state))
   }
@@ -276,6 +327,7 @@ function Postgres(a, b) {
     const l = await lease(false)
     const sql = Sql(q => send(l, q))
     sql.release = () => settle(l, Lease.Released)
+    sql.stats = stats
     return sql
   }
 
@@ -436,7 +488,7 @@ function Postgres(a, b) {
       if (query.state) {
         query.cancelled = { resolve, reject }
       } else {
-        queries.remove(query)
+        (query.queue || queries).remove(query)
         query.cancelled = true
         query.reject(Errors.generic('57014', 'canceling statement due to user request'))
         resolve()

package/cjs/src/connection.js

@@ -222,6 +222,9 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
     },
     expired: () => idleTimer.expired() || lifeTimer.expired(),
     owner: null,
+    get active() { return query ? 1 : 0 },
+    get pipelined() { return sent.length },
+    get acquiring() { return acquisition && !acquisition.owner.cancelled ? 1 : 0 },
     count: 0,
     id
   }
@@ -527,9 +530,9 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
         && !q.cursorFn
         && sent.length < max_pipeline
     } catch (error) {
-      sent.length === 0 && write(Sync)
-      errored(error)
-      return true
+      sent.remove(q) || write(Sync)
+      queryError(q, error)
+      return sent.length < max_pipeline
     }
   }
 

package/cjs/src/index.js

@@ -81,6 +81,7 @@ function Postgres(a, b) {
     PostgresError,
     options,
     reserve,
+    stats,
     listen,
     begin,
     close,
@@ -150,6 +151,56 @@ function Postgres(a, b) {
     }
   }
 
+  function stats() {
+    let idleCount = 0
+      , busyCount = 0
+      , reservedCount = 0
+      , connectingCount = 0
+      , closingCount = 0
+      , executingCount = 0
+      , waitingCount = queries.length
+
+    for (const c of connections) {
+      executingCount += c.active
+      waitingCount += c.pipelined + c.acquiring + (c.owner ? c.owner.queue.length : 0)
+      c.queue === open
+        ? idleCount++
+        : c.queue === connecting
+          ? connectingCount++
+          : c.queue === ended
+            ? closingCount++
+            : c.queue === reserved
+              ? reservedCount++
+              : (c.queue === busy || c.queue === full) && (c.owner ? reservedCount++ : busyCount++)
+    }
+
+    const totalCount = idleCount + busyCount + reservedCount + connectingCount
+
+    return {
+      max: options.max,
+      totalCount,
+      idleCount,
+      waitingCount,
+      activeCount: busyCount + reservedCount,
+      availableCount: idleCount + options.max - totalCount - closingCount,
+      busyCount,
+      reservedCount,
+      connectingCount,
+      closingCount,
+      executingCount,
+      listenCount: pooled(listen.sql),
+      subscribeCount: pooled(subscribe.sql)
+    }
+  }
+
+  function pooled(sql) {
+    if (!sql)
+      return 0
+
+    const s = sql.stats()
+    return s.totalCount + s.closingCount
+  }
+
   async function listen(name, fn, onlisten) {
     const listener = { fn, onlisten }
 
@@ -244,7 +295,7 @@ function Postgres(a, b) {
     const c = l.connection
     l.state === expected
       ? c.queue === full
-        ? l.queue.push(q)
+        ? (q.queue = l.queue, l.queue.push(q))
         : c.execute(q) || move(c, full)
       : q.reject(leaseError(l.state))
   }
@@ -275,6 +326,7 @@ function Postgres(a, b) {
     const l = await lease(false)
     const sql = Sql(q => send(l, q))
     sql.release = () => settle(l, Lease.Released)
+    sql.stats = stats
     return sql
   }
 
@@ -435,7 +487,7 @@ function Postgres(a, b) {
       if (query.state) {
         query.cancelled = { resolve, reject }
       } else {
-        queries.remove(query)
+        (query.queue || queries).remove(query)
         query.cancelled = true
         query.reject(Errors.generic('57014', 'canceling statement due to user request'))
         resolve()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steadybrew/postgresjs",
-  "version": "4.2.0-rc1",
+  "version": "4.3.0",
   "description": "PostgreSQL client for Node.js and Deno, independently maintained by Steady Brew",
   "type": "module",
   "module": "src/index.js",

package/src/connection.js

@@ -222,6 +222,9 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
     },
     expired: () => idleTimer.expired() || lifeTimer.expired(),
     owner: null,
+    get active() { return query ? 1 : 0 },
+    get pipelined() { return sent.length },
+    get acquiring() { return acquisition && !acquisition.owner.cancelled ? 1 : 0 },
     count: 0,
     id
   }
@@ -527,9 +530,9 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
         && !q.cursorFn
         && sent.length < max_pipeline
     } catch (error) {
-      sent.length === 0 && write(Sync)
-      errored(error)
-      return true
+      sent.remove(q) || write(Sync)
+      queryError(q, error)
+      return sent.length < max_pipeline
     }
   }
 

package/src/index.js

@@ -81,6 +81,7 @@ function Postgres(a, b) {
     PostgresError,
     options,
     reserve,
+    stats,
     listen,
     begin,
     close,
@@ -150,6 +151,56 @@ function Postgres(a, b) {
     }
   }
 
+  function stats() {
+    let idleCount = 0
+      , busyCount = 0
+      , reservedCount = 0
+      , connectingCount = 0
+      , closingCount = 0
+      , executingCount = 0
+      , waitingCount = queries.length
+
+    for (const c of connections) {
+      executingCount += c.active
+      waitingCount += c.pipelined + c.acquiring + (c.owner ? c.owner.queue.length : 0)
+      c.queue === open
+        ? idleCount++
+        : c.queue === connecting
+          ? connectingCount++
+          : c.queue === ended
+            ? closingCount++
+            : c.queue === reserved
+              ? reservedCount++
+              : (c.queue === busy || c.queue === full) && (c.owner ? reservedCount++ : busyCount++)
+    }
+
+    const totalCount = idleCount + busyCount + reservedCount + connectingCount
+
+    return {
+      max: options.max,
+      totalCount,
+      idleCount,
+      waitingCount,
+      activeCount: busyCount + reservedCount,
+      availableCount: idleCount + options.max - totalCount - closingCount,
+      busyCount,
+      reservedCount,
+      connectingCount,
+      closingCount,
+      executingCount,
+      listenCount: pooled(listen.sql),
+      subscribeCount: pooled(subscribe.sql)
+    }
+  }
+
+  function pooled(sql) {
+    if (!sql)
+      return 0
+
+    const s = sql.stats()
+    return s.totalCount + s.closingCount
+  }
+
   async function listen(name, fn, onlisten) {
     const listener = { fn, onlisten }
 
@@ -244,7 +295,7 @@ function Postgres(a, b) {
     const c = l.connection
     l.state === expected
       ? c.queue === full
-        ? l.queue.push(q)
+        ? (q.queue = l.queue, l.queue.push(q))
         : c.execute(q) || move(c, full)
       : q.reject(leaseError(l.state))
   }
@@ -275,6 +326,7 @@ function Postgres(a, b) {
     const l = await lease(false)
     const sql = Sql(q => send(l, q))
     sql.release = () => settle(l, Lease.Released)
+    sql.stats = stats
     return sql
   }
 
@@ -435,7 +487,7 @@ function Postgres(a, b) {
       if (query.state) {
         query.cancelled = { resolve, reject }
       } else {
-        queries.remove(query)
+        (query.queue || queries).remove(query)
         query.cancelled = true
         query.reject(Errors.generic('57014', 'canceling statement due to user request'))
         resolve()

package/types/index.d.ts

@@ -704,6 +704,35 @@ declare namespace postgres {
     json(value: JSONValue): Parameter;
   }
 
+  interface PoolStats {
+    /** The configured maximum number of pool connections */
+    max: number;
+    /** Pool connections that exist: connecting, idle or in use */
+    totalCount: number;
+    /** Pool connections with a live session that are not in use */
+    idleCount: number;
+    /** Issued queries and reserve or begin calls that are not running yet, whether queued in the pool, held by an opening connection, pipelined or queued on a reserved connection */
+    waitingCount: number;
+    /** Pool connections in use: busyCount plus reservedCount */
+    activeCount: number;
+    /** Connections a query can get without waiting behind other work: idleCount plus the slots the pool can still open */
+    availableCount: number;
+    /** Pool connections running queries, including those at the pipeline limit */
+    busyCount: number;
+    /** Pool connections held by reserve() or begin() */
+    reservedCount: number;
+    /** Pool connections opening a session */
+    connectingCount: number;
+    /** Pool connections draining or closing, not included in totalCount */
+    closingCount: number;
+    /** Queries the server is running right now, at most one per connection, startup queries and COPY included */
+    executingCount: number;
+    /** Connections held by the internal listen pool, outside max */
+    listenCount: number;
+    /** Connections held by the internal subscribe pool, outside max */
+    subscribeCount: number;
+  }
+
   interface Sql<TTypes extends Record<string, unknown> = {}> extends ISql<TTypes> {
     CLOSE: {};
     END: this['CLOSE'];
@@ -724,6 +753,9 @@ declare namespace postgres {
     begin<T>(options: string, cb: (sql: TransactionSql<TTypes>) => T | Promise<T>): Promise<UnwrapPromiseArray<T>>;
 
     reserve(): Promise<ReservedSql<TTypes>>
+
+    /** Returns a snapshot of the pool's connection and query counts */
+    stats(): PoolStats;
   }
 
   interface TransactionSql<TTypes extends Record<string, unknown> = {}> extends ISql<TTypes>  {