@steve31415/baselib 3.6.0 → 3.7.0

package/dist/db.d.ts

@@ -20,10 +20,27 @@ export interface PoolOptions {
      *  default is to wait forever, which turns pool starvation into a silent
      *  hang instead of an error). */
     connectionTimeoutMillis?: number;
+    /** Server-side cap on any single SQL statement, sent in each connection's
+     *  startup packet (default DEFAULT_STATEMENT_TIMEOUT_MS; 0 disables). */
+    statementTimeoutMillis?: number;
     /** Receives idle-client errors (see logPoolErrors). Without one they go to
      *  stderr — on the Cloud Logging backstop, but not in Axiom. */
     logger?: Logger;
 }
+/** Why a fleet-wide statement timeout (mirror, 2026-09-08): a transaction an
+ * app deliberately holds open across an application await (mirror's job
+ * claims) can sit in a lock cycle whose closing edge lives in Node —
+ * invisible to Postgres's deadlock detector, so it is never broken, and
+ * every statement queued behind it waits forever (mirror's twitter
+ * ingestion was silently down ~12 h). With the cap, blocked statements
+ * abort (SQLSTATE 57014), their transactions roll back, and the pile-up
+ * self-heals. 10 minutes is deliberately far above any healthy statement in
+ * the fleet (milliseconds to seconds): never cancel legitimate work, just
+ * bound the pathological case (Steve, 2026-09-08). A migration that
+ * legitimately needs longer (huge index build) should start with
+ * `set local statement_timeout = 0` — migrate() runs each file in its own
+ * transaction, so the override scopes to that migration. */
+export declare const DEFAULT_STATEMENT_TIMEOUT_MS: number;
 /** pg-pool re-emits an idle client's socket error as its own 'error' event —
  * in production "Connection terminated unexpectedly" when Cloud SQL closes an
  * idle connection. Unhandled, that event throws and takes the process down

package/dist/db.js

@@ -30,6 +30,20 @@ export async function cloudSqlClientOptions(instance, auth) {
     });
     return { options, connector };
 }
+/** Why a fleet-wide statement timeout (mirror, 2026-09-08): a transaction an
+ * app deliberately holds open across an application await (mirror's job
+ * claims) can sit in a lock cycle whose closing edge lives in Node —
+ * invisible to Postgres's deadlock detector, so it is never broken, and
+ * every statement queued behind it waits forever (mirror's twitter
+ * ingestion was silently down ~12 h). With the cap, blocked statements
+ * abort (SQLSTATE 57014), their transactions roll back, and the pile-up
+ * self-heals. 10 minutes is deliberately far above any healthy statement in
+ * the fleet (milliseconds to seconds): never cancel legitimate work, just
+ * bound the pathological case (Steve, 2026-09-08). A migration that
+ * legitimately needs longer (huge index build) should start with
+ * `set local statement_timeout = 0` — migrate() runs each file in its own
+ * transaction, so the override scopes to that migration. */
+export const DEFAULT_STATEMENT_TIMEOUT_MS = 10 * 60_000;
 /** pg-pool re-emits an idle client's socket error as its own 'error' event —
  * in production "Connection terminated unexpectedly" when Cloud SQL closes an
  * idle connection. Unhandled, that event throws and takes the process down
@@ -51,6 +65,10 @@ export async function createPool(opts = {}) {
     return pool;
 }
 async function newPool(opts) {
+    // pg sends statement_timeout in the startup packet of every connection —
+    // server-enforced, no per-connection SET. A 0 is falsy, so pg omits it and
+    // the server default (no timeout) applies.
+    const statement_timeout = opts.statementTimeoutMillis ?? DEFAULT_STATEMENT_TIMEOUT_MS;
     const instance = process.env.CLOUD_SQL_INSTANCE;
     if (instance) {
         const { options: clientOpts } = await cloudSqlClientOptions(instance);
@@ -60,12 +78,18 @@ async function newPool(opts) {
             database: opts.database ?? requireEnv('DB_NAME'),
             max: opts.max ?? 3, // shared instance: default max_connections is low
             connectionTimeoutMillis: opts.connectionTimeoutMillis,
+            statement_timeout,
         });
     }
     const url = new URL(requireEnv('DATABASE_URL'));
     if (opts.database)
         url.pathname = `/${opts.database}`;
-    return new pg.Pool({ connectionString: url.toString(), max: opts.max ?? 5, connectionTimeoutMillis: opts.connectionTimeoutMillis });
+    return new pg.Pool({
+        connectionString: url.toString(),
+        max: opts.max ?? 5,
+        connectionTimeoutMillis: opts.connectionTimeoutMillis,
+        statement_timeout,
+    });
 }
 /** End a pool and resolve only once every client's connection has actually
  * closed. pg-pool's own `end()` resolves as soon as it has *asked* its idle

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steve31415/baselib",
-  "version": "3.6.0",
+  "version": "3.7.0",
   "description": "Plasticine new-world shared platform library: logging, auth, service-to-service auth, db, HTTP, sync, app updates",
   "type": "module",
   "license": "MIT",