turbine-orm 0.79.1 → 0.80.0

package/dist/cjs/realtime.js

@@ -25,10 +25,23 @@
  *   (Neon HTTP, Vercel Postgres over fetch) cannot hold such a connection, so
  *   `$listen` will surface a clear error rather than hang. `$notify` works
  *   everywhere, it's a single round-trip `SELECT pg_notify(...)`.
+ *
+ * Connection loss:
+ *
+ *   A subscription's connection is held indefinitely with no query in flight,
+ *   so a database restart, failover or `pg_terminate_backend` reaches it only
+ *   as an `'error'` event. That event used to have no listener, which exits the
+ *   process. It is now guarded (connection-guard.ts), and the subscription
+ *   RECONNECTS by default: the dead connection is destroyed, a fresh one is
+ *   checked out with exponential backoff, and `LISTEN` is re-issued. Postgres
+ *   does not queue notifications for a listener that is not connected, so
+ *   anything NOTIFYed during the gap is gone for good; `onReconnect` is the
+ *   caller's cue to resynchronise from the source of truth.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateChannel = validateChannel;
 exports.createSubscription = createSubscription;
+const connection_guard_js_1 = require("./connection-guard.js");
 const errors_js_1 = require("./errors.js");
 // ---------------------------------------------------------------------------
 // Identifier validation
@@ -62,17 +75,12 @@ function validateChannel(channel) {
             '(letters, digits, underscores; cannot start with a digit)');
     }
 }
+const DEFAULT_RECONNECT = { initialDelayMs: 100, maxDelayMs: 30_000 };
 /**
- * Acquire a dedicated connection, run `LISTEN "channel"`, and wire the handler.
- *
- * @param pool        the pg-compatible pool to check a long-lived client out of
- * @param channel     channel name, MUST already be validated by the caller
- * @param quotedChannel  the channel run through quoteIdent (interpolated into SQL)
- * @param handler     called with each notification's payload
- * @param onClosed    invoked when the subscription releases, so the client can
- *                    drop it from its active-subscription registry
+ * Check out a dedicated connection, wire the handler and run `LISTEN`. Throws
+ * (typed) on failure, having given the connection back.
  */
-async function createSubscription(pool, channel, quotedChannel, handler, onClosed) {
+async function openListenConnection(pool, channel, quotedChannel, handler, onLost) {
     let client;
     try {
         client = (await pool.connect());
@@ -85,11 +93,12 @@ async function createSubscription(pool, channel, quotedChannel, handler, onClose
     // forever waiting for messages that can never arrive, so fail loudly now and
     // give the connection straight back.
     if (typeof client.on !== 'function') {
-        client.release?.();
+        client.release();
         throw new errors_js_1.ConnectionError('$listen requires a persistent connection that can push notifications. ' +
             'The configured pool returned a client with no event support (stateless HTTP drivers ' +
             'like Neon HTTP / Vercel Postgres cannot LISTEN). Use a TCP pg.Pool for LISTEN/NOTIFY.');
     }
+    const checkout = (0, connection_guard_js_1.guardCheckout)(client, onLost);
     const onNotification = (msg) => {
         // pg delivers ALL notifications for the connection to every listener; a
         // dedicated connection only ever LISTENs on one channel, but guard anyway.
@@ -103,43 +112,139 @@ async function createSubscription(pool, channel, quotedChannel, handler, onClose
     }
     catch (err) {
         client.removeListener?.('notification', onNotification);
-        client.release?.();
+        checkout.release(err instanceof Error ? err : true);
         throw (0, errors_js_1.wrapPgError)(err);
     }
+    return { client, checkout, onNotification };
+}
+/**
+ * Acquire a dedicated connection, run `LISTEN "channel"`, and wire the handler.
+ * A failure here is thrown to the `$listen` caller; only a connection lost
+ * AFTER the subscription is established is retried.
+ *
+ * @param pool        the pg-compatible pool to check a long-lived client out of
+ * @param channel     channel name, MUST already be validated by the caller
+ * @param quotedChannel  the channel run through quoteIdent (interpolated into SQL)
+ * @param handler     called with each notification's payload
+ * @param onClosed    invoked when the subscription ends, so the client can
+ *                    drop it from its active-subscription registry
+ * @param options     reconnect policy and loss/reconnect callbacks
+ */
+async function createSubscription(pool, channel, quotedChannel, handler, onClosed, options = {}) {
+    const backoff = options.reconnect === false
+        ? undefined
+        : { ...DEFAULT_RECONNECT, ...(typeof options.reconnect === 'object' ? options.reconnect : {}) };
+    const reportError = options.onError ??
+        ((err) => {
+            console.error(`[turbine] $listen "${channel}": ${err.message}${backoff && !closed ? ', reconnecting' : ''}`);
+        });
     let closed = false;
+    let current;
+    let timer;
+    let delay = backoff?.initialDelayMs ?? 0;
+    /** Let go of the held connection. A lost one is destroyed, never pooled. */
+    const dropCurrent = (destroy) => {
+        const conn = current;
+        if (!conn)
+            return;
+        current = undefined;
+        conn.client.removeListener?.('notification', conn.onNotification);
+        conn.checkout.release(destroy);
+    };
+    const scheduleReconnect = () => {
+        if (closed || !backoff)
+            return;
+        timer = setTimeout(() => {
+            timer = undefined;
+            void attemptReconnect();
+        }, delay);
+        // A process with nothing else to do should not stay alive just to retry.
+        timer.unref?.();
+        delay = Math.min(delay * 2, backoff.maxDelayMs);
+    };
+    const onLost = (err) => {
+        if (closed || !current)
+            return;
+        dropCurrent(err);
+        const lost = (0, errors_js_1.wrapPgError)(err);
+        reportError(lost instanceof Error ? lost : err);
+        if (!backoff) {
+            closed = true;
+            onClosed(sub);
+            return;
+        }
+        delay = backoff.initialDelayMs;
+        scheduleReconnect();
+    };
+    const attemptReconnect = async () => {
+        if (closed)
+            return;
+        let conn;
+        try {
+            conn = await openListenConnection(pool, channel, quotedChannel, handler, onLost);
+        }
+        catch (err) {
+            if (closed)
+                return;
+            reportError(err instanceof Error ? err : new Error(String(err)));
+            scheduleReconnect();
+            return;
+        }
+        if (closed) {
+            // unsubscribe() or disconnect() ran while this attempt was in flight.
+            conn.client.removeListener?.('notification', conn.onNotification);
+            conn.checkout.release(true);
+            return;
+        }
+        current = conn;
+        if (backoff)
+            delay = backoff.initialDelayMs;
+        options.onReconnect?.();
+    };
+    current = await openListenConnection(pool, channel, quotedChannel, handler, onLost);
+    const stop = () => {
+        closed = true;
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            timer = undefined;
+        }
+    };
     const sub = {
         channel,
         async unsubscribe() {
             if (closed)
                 return;
-            closed = true;
+            stop();
+            const conn = current;
+            if (!conn) {
+                // Between connections: nothing is LISTENing, so there is nothing to undo.
+                onClosed(sub);
+                return;
+            }
             try {
-                await client.query(`UNLISTEN ${quotedChannel}`);
+                await conn.client.query(`UNLISTEN ${quotedChannel}`);
             }
             catch (err) {
                 // Best-effort: the connection may already be dead. Still detach +
                 // release below so we don't leak the pool slot.
-                client.removeListener?.('notification', onNotification);
-                client.release?.();
+                dropCurrent(true);
                 onClosed(sub);
                 throw (0, errors_js_1.wrapPgError)(err);
             }
-            client.removeListener?.('notification', onNotification);
-            client.release?.();
+            dropCurrent(undefined);
             onClosed(sub);
         },
         _forceRelease() {
             if (closed)
                 return;
-            closed = true;
-            client.removeListener?.('notification', onNotification);
+            stop();
             // Destroy the connection (release(true)) rather than return it to the pool:
             // we skip UNLISTEN here (the pool is being torn down), so a recycled
             // connection would otherwise carry a stale LISTEN registration. Destroying
             // it guarantees no pooled backend keeps receiving NOTIFY traffic. Matters
             // most for external/serverless pools, where disconnect() is a no-op and the
             // pool outlives this client.
-            client.release?.(true);
+            dropCurrent(true);
             onClosed(sub);
         },
     };

package/dist/cjs/schema-sql.js

@@ -25,6 +25,7 @@ exports.schemaPush = schemaPush;
 exports.schemaToSQLString = schemaToSQLString;
 const pg_1 = __importDefault(require("pg"));
 const destructive_js_1 = require("./cli/destructive.js");
+const connection_guard_js_1 = require("./connection-guard.js");
 const dialect_js_1 = require("./dialect.js");
 const errors_js_1 = require("./errors.js");
 const introspect_js_1 = require("./introspect.js");
@@ -616,6 +617,9 @@ async function schemaDiff(schema, connectionString, options = {}) {
     // `pgSchema` because `schema` is already the SchemaDef in this function.
     const pgSchema = options.schema ?? 'public';
     const client = new pg_1.default.Client({ connectionString });
+    // A bare client with no 'error' listener exits the process if the server
+    // drops it mid-diff; guarded, the pending query rejects instead.
+    (0, connection_guard_js_1.guardConnection)(client);
     await client.connect();
     try {
         // Get existing tables in the target schema
@@ -1636,6 +1640,8 @@ async function schemaPush(schema, connectionString, options = {}) {
     }
     // Execute all statements in a transaction
     const client = new pg_1.default.Client({ connectionString });
+    // Same as schemaDiff: a dropped connection must reject the push, not exit.
+    (0, connection_guard_js_1.guardConnection)(client);
     await client.connect();
     try {
         await client.query('BEGIN');

package/dist/cli/index.js

@@ -29,6 +29,7 @@ import { appendFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFi
 import { tmpdir } from 'node:os';
 import { basename, dirname, extname, join, relative, resolve, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { guardConnection } from '../connection-guard.js';
 import { detectPooler, parseSearchPathValue, poolerRefusalMessage } from '../connection-url.js';
 import { ValidationError } from '../errors.js';
 import { generate, generatePrismaMap, resolveImportExtension } from '../generate.js';
@@ -955,6 +956,7 @@ async function probeDatabase(url, schema) {
     try {
         const { default: pg } = await import('pg');
         const client = new pg.Client({ connectionString: url });
+        guardConnection(client);
         await client.connect();
         let tableCount = 0;
         try {
@@ -2978,6 +2980,7 @@ async function seedConnectionString(config) {
     assertPinnableSchema(schema);
     const { default: pg } = await import('pg');
     const probe = new pg.Client({ connectionString: config.url });
+    guardConnection(probe);
     await probe.connect();
     let inherited;
     try {
@@ -3049,6 +3052,7 @@ async function runSeedPlan(plan, config) {
         const url = seedUrl ?? requireUrl(config);
         const { default: pg } = await import('pg');
         const client = new pg.Client({ connectionString: url });
+        guardConnection(client);
         await client.connect();
         try {
             await client.query(readFileSync(plan.file, 'utf-8'));

package/dist/cli/mcp.js

@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto';
 import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import pg from 'pg';
+import { absorbCheckedOutErrors } from '../connection-guard.js';
 import { findMissingRelationIndexes } from '../index-advisor.js';
 import { formatBytes } from '../index-stats.js';
 import { deriveCatalogRelations, indexKeyColumn, parseIndexKeyEntries } from '../introspect.js';
@@ -289,6 +290,9 @@ export function startMcpServer(options, transport = {}) {
     ctx.pool.on?.('error', (err) => {
         process.stderr.write(`[turbine] mcp pool error: ${redactUrl(err.message)}\n`);
     });
+    // The same event on a CHECKED-OUT client (a tool call mid-query when the
+    // server restarts) has no pool listener to fall back on; see connection-guard.ts.
+    absorbCheckedOutErrors(ctx.pool);
     announcePiiTags(options);
     let buffer = '';
     let disposed = false;

package/dist/cli/migrate.js

@@ -16,6 +16,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from
 import { join } from 'node:path';
 import pg from 'pg';
 import { postgresql } from '../adapters/index.js';
+import { guardConnection } from '../connection-guard.js';
 import { isPlainSchemaIdentifier, parseSearchPathValue, withSearchPathOption } from '../connection-url.js';
 import { postgresDialect } from '../dialect.js';
 import { MigrationError, ValidationError } from '../errors.js';
@@ -841,6 +842,9 @@ async function connectMigrationClient(connectionString, schema) {
     const inherited = schema === undefined || schema === '' ? [] : await probeConnectionSchemas(connectionString, schema);
     const pinned = connectionStringForSchema(connectionString, schema, inherited);
     const client = new pg.Client({ connectionString: pinned });
+    // Held for the whole run: a server restart must fail the migration with a
+    // message, not exit through an unheard 'error' event (connection-guard.ts).
+    guardConnection(client);
     await client.connect();
     return { client, connectionString: pinned };
 }
@@ -853,6 +857,7 @@ async function probeConnectionSchemas(connectionString, schema) {
     // so in those terms, see assertPinnableSchema.
     assertPinnableSchema(schema);
     const probe = new pg.Client({ connectionString });
+    guardConnection(probe);
     await probe.connect();
     try {
         await assertSchemaExists(probe, schema);
@@ -866,6 +871,7 @@ async function probeConnectionSchemas(connectionString, schema) {
 /** Open the second, lock-only connection. Separated so tests can fake it. */
 async function openLockConnection(connectionString) {
     const client = new pg.Client({ connectionString });
+    guardConnection(client);
     await client.connect();
     return client;
 }

package/dist/cli/observe.js

@@ -8,8 +8,10 @@
 import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
 import { createServer } from 'node:http';
 import pg from 'pg';
+import { absorbCheckedOutErrors } from '../connection-guard.js';
 import { OBSERVE_HTML } from './observe-ui.js';
 import { callerKey, checkRateLimit } from './rate-limit.js';
+import { redactUrl } from './ui.js';
 // ---------------------------------------------------------------------------
 // Main entry point
 // ---------------------------------------------------------------------------
@@ -19,6 +21,12 @@ export async function startObserve(options) {
         max: 2,
         idleTimeoutMillis: 10_000,
     });
+    // Idle-client errors surface on the pool, checked-out ones on the client;
+    // with no listener either one exits the dashboard (see connection-guard.ts).
+    pool.on('error', (err) => {
+        console.error(`[turbine] observe pool error: ${redactUrl(err.message)}`);
+    });
+    absorbCheckedOutErrors(pool);
     const probe = await pool.connect();
     try {
         await probe.query('SELECT 1');

package/dist/cli/studio.js

@@ -43,6 +43,7 @@ import { createServer } from 'node:http';
 import { platform } from 'node:os';
 import { dirname, resolve as pathResolve } from 'node:path';
 import pg from 'pg';
+import { absorbCheckedOutErrors } from '../connection-guard.js';
 import { ValidationError } from '../errors.js';
 import { introspect } from '../introspect.js';
 import { QueryInterface, quoteIdent } from '../query/index.js';
@@ -58,6 +59,7 @@ import { applyPiiTags, loadPiiTags } from './pii-tags.js';
 import { callerKey, checkRateLimit } from './rate-limit.js';
 import { createDemoContext } from './studio-demo.js';
 import { STUDIO_HTML } from './studio-ui.generated.js';
+import { redactUrl } from './ui.js';
 // ---------------------------------------------------------------------------
 // Main entry point
 // ---------------------------------------------------------------------------
@@ -102,11 +104,21 @@ export async function startStudio(options) {
         registerUtcTemporalParsers();
         // pg.Pool satisfies the PgCompatPool contract (same as the external-pool
         // seam in client.ts); the cast keeps one typed pool field for both modes.
-        pool = new pg.Pool({
+        const pgPool = new pg.Pool({
             connectionString: options.url,
             max: 4, // small pool, single-user tool
             idleTimeoutMillis: 10_000,
         });
+        // A connection that dies while idle emits 'error' on the POOL, and one that
+        // dies mid-request emits it on the checked-out client. Neither had a
+        // listener, so a database restart exited Studio. Now the pending request
+        // fails and the server keeps running. The message is redacted because pg
+        // can echo the connection string into connection failures.
+        pgPool.on('error', (err) => {
+            console.error(`[turbine] studio pool error: ${redactUrl(err.message)}`);
+        });
+        absorbCheckedOutErrors(pgPool);
+        pool = pgPool;
         // Verify connectivity before starting the server, fail fast.
         const probe = await pool.connect();
         try {

package/dist/client.d.ts

@@ -27,7 +27,7 @@ import { type ObserveConfig, type ObserveHandle } from './observe.js';
 import type { PgCompatPool, PgCompatPoolClient } from './pg-types.js';
 import { type PipelineOptions, type PipelineResults } from './pipeline.js';
 import { type DeferredQuery, type GlobalFilters, type JsonEncoding, type QueryEventListener, QueryInterface, type QueryInterfaceOptions, type RelationLoadStrategy, type TemporalInfinityReading } from './query/index.js';
-import { type NotificationHandler, type Subscription } from './realtime.js';
+import { type ListenOptions, type NotificationHandler, type Subscription } from './realtime.js';
 import type { SchemaMetadata } from './schema.js';
 import { TypedSqlQuery } from './typed-sql.js';
 export interface RetryOptions {
@@ -1206,17 +1206,27 @@ export declare class TurbineClient {
      * cannot do this, `$listen` throws a `ConnectionError` rather than hang.
      * `$notify` works on every driver.
      *
+     * **Connection loss:** if the subscription's connection dies (a restart,
+     * failover, compute suspend, `pg_terminate_backend`), it reconnects with
+     * exponential backoff and re-issues `LISTEN`; `options.reconnect: false`
+     * ends it instead. Postgres does not hold notifications for a disconnected
+     * listener, so anything sent during the gap is lost: use
+     * `options.onReconnect` to resynchronise. `options.onError` receives the loss
+     * and each failed attempt (default: one `console.error` line each).
+     *
      * @example
      * ```ts
      * const sub = await db.$listen('order_created', (payload) => {
      *   const order = JSON.parse(payload);
      *   console.log('new order', order.id);
+     * }, {
+     *   onReconnect: () => refreshOrdersFromDatabase(),
      * });
      * // ...later
      * await sub.unsubscribe();
      * ```
      */
-    $listen(channel: string, handler: NotificationHandler): Promise<Subscription>;
+    $listen(channel: string, handler: NotificationHandler, options?: ListenOptions): Promise<Subscription>;
     /**
      * Send a Postgres NOTIFY on `channel` with an optional payload string.
      *