turbine-orm 0.79.1 → 0.80.0

package/README.md

@@ -18,7 +18,7 @@ Turbine is **pre-1.0** (`0.x`). Which surfaces hold steady across minors, which
 
 Six reasons, each with the mechanism that makes it true:
 
-1. **One dependency.** `dependencies` is `{ "pg": "^8.13.1" }`. No engine binary, no WASM compiler, no adapter packages in lockstep. The optional engines (SQLite, MySQL, SQL Server, PowDB, all tiered Experimental in [STABILITY.md](STABILITY.md)) are peer dependencies or Node builtins you install only if you use them.
+1. **One dependency.** `dependencies` is `{ "pg": "^8.15.0" }`. No engine binary, no WASM compiler, no adapter packages in lockstep. The optional engines (SQLite, MySQL, SQL Server, PowDB, all tiered Experimental in [STABILITY.md](STABILITY.md)) are peer dependencies or Node builtins you install only if you use them.
 2. **Written from scratch.** Turbine is not a layer over Knex or a query-builder library. Query compilation is plain string building with an FNV-1a shape fingerprint into a bounded LRU of SQL templates, so there is no plan cache to size and no compiler running on your event loop.
 3. **Nested relations in one statement.** A `with` clause compiles to correlated `json_agg` subqueries, so users with posts with comments is one round trip, typed end to end: `users[0].posts[0].comments[0].author.name` autocompletes with no annotation.
 4. **Close to raw SQL.** In the last published run, Turbine's overhead over a hand-written `pg` control was 1.08x by geometric mean. The table is below; the losses are stated with the wins.
@@ -272,7 +272,7 @@ Going deep on one database means the parts other ORMs push to raw SQL are typed
 
 ## Serverless and edge
 
-The core is driver-agnostic: hand any pg-compatible pool to `turbineHttp()` and Turbine runs on Vercel Edge, Cloudflare Workers, Deno Deploy, or anywhere else without TCP. The main entry's import graph is held under **91 kB brotli** (edge entry under **72 kB**) with `pg` external, enforced by `size-limit` in CI at those exact numbers; run `npm run size` for the current figure.
+The core is driver-agnostic: hand any pg-compatible pool to `turbineHttp()` and Turbine runs on Vercel Edge, Cloudflare Workers, Deno Deploy, or anywhere else without TCP. The main entry's import graph is held under **93 kB brotli** (edge entry under **74 kB**) with `pg` external, enforced by `size-limit` in CI at those exact numbers; run `npm run size` for the current figure.
 
 ```typescript
 import { Pool } from '@neondatabase/serverless';
@@ -359,11 +359,11 @@ It is also built to be extended rather than wrapped. All SQL generation routes t
 |---|---|---|---|---|
 | **Engine / runtime** | No engine binary (`pg` only) | Client + TS/WASM query compiler | No engine | No engine |
 | **Runtime deps** | 1 (`pg`) | `@prisma/client` + required driver adapter | 0 | 0 |
-| **Main bundle (brotli)** | under 91 kB import graph (CI-enforced), `pg` external | ~1.6 MB client (TS/WASM compiler) | ~7 KB core | small |
+| **Main bundle (brotli)** | under 93 kB import graph (CI-enforced), `pg` external | ~1.6 MB client (TS/WASM compiler) | ~7 KB core | small |
 | **Studio** | Read-only by default | Full CRUD, cloud-hosted | Full CRUD; [Gateway](https://gateway.drizzle.team/) self-hosted, free | None |
 | **Error PII safety** | Keys only by default | Values in messages | Raw pg errors | Raw pg errors |
 | **Migrations** | SQL-first, SHA-256 checksums | DSL-generated, shadow DB | SQL or Drizzle Kit | None |
-| **Edge runtime** | One import swap, under 72 kB brotli (CI-enforced) | Driver adapter + WASM compiler | Native | Native |
+| **Edge runtime** | One import swap, under 74 kB brotli (CI-enforced) | Driver adapter + WASM compiler | Native | Native |
 | **Pipeline batching** | Parse/Bind/Execute protocol | Sequential in txn | Sequential | Manual |
 | **Typed errors** | `isRetryable` discriminant | Error codes only | None | None |
 | **Nested relations** | 1 query, deep type inference | 1 query per relation by default; single-query `relationJoins` is Preview | 1 query, `relations()` re-declaration | Manual (`jsonArrayFrom`) |

package/dist/checkout.d.ts

@@ -0,0 +1,53 @@
+/**
+ * turbine-orm, checking a connection out of a pool for a unit of work
+ *
+ * Every path that holds a pooled connection across awaits (`$transaction`,
+ * `transaction()`, nested writes, cursor streams, `connect()`) starts the same
+ * way: `pool.connect()`, a typed error if that fails, and a guard for the
+ * checkout window (connection-guard.ts). They share this module so they cannot
+ * drift apart on any of the three.
+ *
+ * {@link openCheckout} adds the one recovery that is always safe. A unit of
+ * work opens with a statement that has no effect of its own (`BEGIN`, or the
+ * `SELECT 1` of a connectivity check). If THAT statement fails because the
+ * connection had already been closed by the server, nothing has run, so the
+ * connection is destroyed and the statement is sent once more on a fresh one.
+ * This is the write-path counterpart of the query builder's read retry: a
+ * write cannot be resent after a lost connection, because nobody can tell
+ * whether it committed first, but a transaction that has not begun holds no
+ * write to lose.
+ */
+import { type CheckoutGuard } from './connection-guard.js';
+import type { PgCompatPool, PgCompatPoolClient } from './pg-types.js';
+export interface Checkout {
+    client: PgCompatPoolClient;
+    /** Release through this, never `client.release()`, so the guard comes off. */
+    checkout: CheckoutGuard;
+}
+/**
+ * Check a connection out, as a typed Turbine error when that fails.
+ *
+ * `pool.connect()` is where the first-run failures actually land: wrong
+ * password (SQLSTATE 28P01), no such database (3D000), nothing listening
+ * (ECONNREFUSED), an unverifiable TLS certificate. Unwrapped, every one of
+ * those left `$transaction`, `transaction()` and `connect()` as a raw pg
+ * `DatabaseError` carrying a SQLSTATE in `.code`, the same property Turbine
+ * puts `TURBINE_E0NN` in.
+ *
+ * Query paths need no equivalent: `pool.query()` opens the connection itself
+ * and rejects with the connect error, which the query boundary already wraps.
+ */
+export declare function acquireConnection(pool: PgCompatPool): Promise<Checkout>;
+/**
+ * Check a connection out and run `opening` on it, retrying ONCE on a fresh
+ * connection when `opening` fails with {@link isStaleConnectionError}.
+ *
+ * `opening` must be a statement with no effect (`BEGIN`, `SELECT 1`): the
+ * retry is safe only because a failure there leaves nothing behind. Before the
+ * retry the event loop runs one poll phase, so any other connection the server
+ * closed alongside this one has been evicted from the idle list rather than
+ * lent out again. On success the caller owns the checkout; on failure it has
+ * already been released and the error (the retry's, if there was one) is
+ * rethrown as {@link explainConnectionLoss} reports it.
+ */
+export declare function openCheckout(pool: PgCompatPool, opening: (client: PgCompatPoolClient) => Promise<unknown>): Promise<Checkout>;

package/dist/checkout.js

@@ -0,0 +1,78 @@
+/**
+ * turbine-orm, checking a connection out of a pool for a unit of work
+ *
+ * Every path that holds a pooled connection across awaits (`$transaction`,
+ * `transaction()`, nested writes, cursor streams, `connect()`) starts the same
+ * way: `pool.connect()`, a typed error if that fails, and a guard for the
+ * checkout window (connection-guard.ts). They share this module so they cannot
+ * drift apart on any of the three.
+ *
+ * {@link openCheckout} adds the one recovery that is always safe. A unit of
+ * work opens with a statement that has no effect of its own (`BEGIN`, or the
+ * `SELECT 1` of a connectivity check). If THAT statement fails because the
+ * connection had already been closed by the server, nothing has run, so the
+ * connection is destroyed and the statement is sent once more on a fresh one.
+ * This is the write-path counterpart of the query builder's read retry: a
+ * write cannot be resent after a lost connection, because nobody can tell
+ * whether it committed first, but a transaction that has not begun holds no
+ * write to lose.
+ */
+import { guardCheckout, settleEventLoop } from './connection-guard.js';
+import { explainConnectionLoss, isStaleConnectionError, wrapPgError } from './errors.js';
+/**
+ * Check a connection out, as a typed Turbine error when that fails.
+ *
+ * `pool.connect()` is where the first-run failures actually land: wrong
+ * password (SQLSTATE 28P01), no such database (3D000), nothing listening
+ * (ECONNREFUSED), an unverifiable TLS certificate. Unwrapped, every one of
+ * those left `$transaction`, `transaction()` and `connect()` as a raw pg
+ * `DatabaseError` carrying a SQLSTATE in `.code`, the same property Turbine
+ * puts `TURBINE_E0NN` in.
+ *
+ * Query paths need no equivalent: `pool.query()` opens the connection itself
+ * and rejects with the connect error, which the query boundary already wraps.
+ */
+export async function acquireConnection(pool) {
+    let client;
+    try {
+        client = await pool.connect();
+    }
+    catch (err) {
+        throw wrapPgError(err);
+    }
+    return { client, checkout: guardCheckout(client) };
+}
+/**
+ * Check a connection out and run `opening` on it, retrying ONCE on a fresh
+ * connection when `opening` fails with {@link isStaleConnectionError}.
+ *
+ * `opening` must be a statement with no effect (`BEGIN`, `SELECT 1`): the
+ * retry is safe only because a failure there leaves nothing behind. Before the
+ * retry the event loop runs one poll phase, so any other connection the server
+ * closed alongside this one has been evicted from the idle list rather than
+ * lent out again. On success the caller owns the checkout; on failure it has
+ * already been released and the error (the retry's, if there was one) is
+ * rethrown as {@link explainConnectionLoss} reports it.
+ */
+export async function openCheckout(pool, opening) {
+    for (let attempt = 0;; attempt++) {
+        const held = await acquireConnection(pool);
+        try {
+            await opening(held.client);
+            return held;
+        }
+        catch (err) {
+            const lostWith = held.checkout.lostWith;
+            if (attempt === 0 && isStaleConnectionError(err)) {
+                // Released WITH the error so pg-pool destroys it: the close that made
+                // it fail may not have been read yet, and a connection the pool still
+                // believes is queryable goes back to the idle list.
+                held.checkout.release(err instanceof Error ? err : true);
+                await settleEventLoop();
+                continue;
+            }
+            held.checkout.release();
+            throw explainConnectionLoss(err, lostWith);
+        }
+    }
+}

package/dist/cjs/checkout.d.ts

@@ -0,0 +1,53 @@
+/**
+ * turbine-orm, checking a connection out of a pool for a unit of work
+ *
+ * Every path that holds a pooled connection across awaits (`$transaction`,
+ * `transaction()`, nested writes, cursor streams, `connect()`) starts the same
+ * way: `pool.connect()`, a typed error if that fails, and a guard for the
+ * checkout window (connection-guard.ts). They share this module so they cannot
+ * drift apart on any of the three.
+ *
+ * {@link openCheckout} adds the one recovery that is always safe. A unit of
+ * work opens with a statement that has no effect of its own (`BEGIN`, or the
+ * `SELECT 1` of a connectivity check). If THAT statement fails because the
+ * connection had already been closed by the server, nothing has run, so the
+ * connection is destroyed and the statement is sent once more on a fresh one.
+ * This is the write-path counterpart of the query builder's read retry: a
+ * write cannot be resent after a lost connection, because nobody can tell
+ * whether it committed first, but a transaction that has not begun holds no
+ * write to lose.
+ */
+import { type CheckoutGuard } from './connection-guard.js';
+import type { PgCompatPool, PgCompatPoolClient } from './pg-types.js';
+export interface Checkout {
+    client: PgCompatPoolClient;
+    /** Release through this, never `client.release()`, so the guard comes off. */
+    checkout: CheckoutGuard;
+}
+/**
+ * Check a connection out, as a typed Turbine error when that fails.
+ *
+ * `pool.connect()` is where the first-run failures actually land: wrong
+ * password (SQLSTATE 28P01), no such database (3D000), nothing listening
+ * (ECONNREFUSED), an unverifiable TLS certificate. Unwrapped, every one of
+ * those left `$transaction`, `transaction()` and `connect()` as a raw pg
+ * `DatabaseError` carrying a SQLSTATE in `.code`, the same property Turbine
+ * puts `TURBINE_E0NN` in.
+ *
+ * Query paths need no equivalent: `pool.query()` opens the connection itself
+ * and rejects with the connect error, which the query boundary already wraps.
+ */
+export declare function acquireConnection(pool: PgCompatPool): Promise<Checkout>;
+/**
+ * Check a connection out and run `opening` on it, retrying ONCE on a fresh
+ * connection when `opening` fails with {@link isStaleConnectionError}.
+ *
+ * `opening` must be a statement with no effect (`BEGIN`, `SELECT 1`): the
+ * retry is safe only because a failure there leaves nothing behind. Before the
+ * retry the event loop runs one poll phase, so any other connection the server
+ * closed alongside this one has been evicted from the idle list rather than
+ * lent out again. On success the caller owns the checkout; on failure it has
+ * already been released and the error (the retry's, if there was one) is
+ * rethrown as {@link explainConnectionLoss} reports it.
+ */
+export declare function openCheckout(pool: PgCompatPool, opening: (client: PgCompatPoolClient) => Promise<unknown>): Promise<Checkout>;

package/dist/cjs/checkout.js

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * turbine-orm, checking a connection out of a pool for a unit of work
+ *
+ * Every path that holds a pooled connection across awaits (`$transaction`,
+ * `transaction()`, nested writes, cursor streams, `connect()`) starts the same
+ * way: `pool.connect()`, a typed error if that fails, and a guard for the
+ * checkout window (connection-guard.ts). They share this module so they cannot
+ * drift apart on any of the three.
+ *
+ * {@link openCheckout} adds the one recovery that is always safe. A unit of
+ * work opens with a statement that has no effect of its own (`BEGIN`, or the
+ * `SELECT 1` of a connectivity check). If THAT statement fails because the
+ * connection had already been closed by the server, nothing has run, so the
+ * connection is destroyed and the statement is sent once more on a fresh one.
+ * This is the write-path counterpart of the query builder's read retry: a
+ * write cannot be resent after a lost connection, because nobody can tell
+ * whether it committed first, but a transaction that has not begun holds no
+ * write to lose.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.acquireConnection = acquireConnection;
+exports.openCheckout = openCheckout;
+const connection_guard_js_1 = require("./connection-guard.js");
+const errors_js_1 = require("./errors.js");
+/**
+ * Check a connection out, as a typed Turbine error when that fails.
+ *
+ * `pool.connect()` is where the first-run failures actually land: wrong
+ * password (SQLSTATE 28P01), no such database (3D000), nothing listening
+ * (ECONNREFUSED), an unverifiable TLS certificate. Unwrapped, every one of
+ * those left `$transaction`, `transaction()` and `connect()` as a raw pg
+ * `DatabaseError` carrying a SQLSTATE in `.code`, the same property Turbine
+ * puts `TURBINE_E0NN` in.
+ *
+ * Query paths need no equivalent: `pool.query()` opens the connection itself
+ * and rejects with the connect error, which the query boundary already wraps.
+ */
+async function acquireConnection(pool) {
+    let client;
+    try {
+        client = await pool.connect();
+    }
+    catch (err) {
+        throw (0, errors_js_1.wrapPgError)(err);
+    }
+    return { client, checkout: (0, connection_guard_js_1.guardCheckout)(client) };
+}
+/**
+ * Check a connection out and run `opening` on it, retrying ONCE on a fresh
+ * connection when `opening` fails with {@link isStaleConnectionError}.
+ *
+ * `opening` must be a statement with no effect (`BEGIN`, `SELECT 1`): the
+ * retry is safe only because a failure there leaves nothing behind. Before the
+ * retry the event loop runs one poll phase, so any other connection the server
+ * closed alongside this one has been evicted from the idle list rather than
+ * lent out again. On success the caller owns the checkout; on failure it has
+ * already been released and the error (the retry's, if there was one) is
+ * rethrown as {@link explainConnectionLoss} reports it.
+ */
+async function openCheckout(pool, opening) {
+    for (let attempt = 0;; attempt++) {
+        const held = await acquireConnection(pool);
+        try {
+            await opening(held.client);
+            return held;
+        }
+        catch (err) {
+            const lostWith = held.checkout.lostWith;
+            if (attempt === 0 && (0, errors_js_1.isStaleConnectionError)(err)) {
+                // Released WITH the error so pg-pool destroys it: the close that made
+                // it fail may not have been read yet, and a connection the pool still
+                // believes is queryable goes back to the idle list.
+                held.checkout.release(err instanceof Error ? err : true);
+                await (0, connection_guard_js_1.settleEventLoop)();
+                continue;
+            }
+            held.checkout.release();
+            throw (0, errors_js_1.explainConnectionLoss)(err, lostWith);
+        }
+    }
+}

package/dist/cjs/cli/index.js

@@ -92,6 +92,7 @@ const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const node_url_1 = require("node:url");
+const connection_guard_js_1 = require("../connection-guard.js");
 const connection_url_js_1 = require("../connection-url.js");
 const errors_js_1 = require("../errors.js");
 const generate_js_1 = require("../generate.js");
@@ -1018,6 +1019,7 @@ async function probeDatabase(url, schema) {
     try {
         const { default: pg } = await Promise.resolve().then(() => __importStar(require('pg')));
         const client = new pg.Client({ connectionString: url });
+        (0, connection_guard_js_1.guardConnection)(client);
         await client.connect();
         let tableCount = 0;
         try {
@@ -3041,6 +3043,7 @@ async function seedConnectionString(config) {
     (0, migrate_js_1.assertPinnableSchema)(schema);
     const { default: pg } = await Promise.resolve().then(() => __importStar(require('pg')));
     const probe = new pg.Client({ connectionString: config.url });
+    (0, connection_guard_js_1.guardConnection)(probe);
     await probe.connect();
     let inherited;
     try {
@@ -3112,6 +3115,7 @@ async function runSeedPlan(plan, config) {
         const url = seedUrl ?? requireUrl(config);
         const { default: pg } = await Promise.resolve().then(() => __importStar(require('pg')));
         const client = new pg.Client({ connectionString: url });
+        (0, connection_guard_js_1.guardConnection)(client);
         await client.connect();
         try {
             await client.query((0, node_fs_1.readFileSync)(plan.file, 'utf-8'));

package/dist/cjs/cli/mcp.js

@@ -12,6 +12,7 @@ const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const pg_1 = __importDefault(require("pg"));
+const connection_guard_js_1 = require("../connection-guard.js");
 const index_advisor_js_1 = require("../index-advisor.js");
 const index_stats_js_1 = require("../index-stats.js");
 const introspect_js_1 = require("../introspect.js");
@@ -299,6 +300,9 @@ function startMcpServer(options, transport = {}) {
     ctx.pool.on?.('error', (err) => {
         process.stderr.write(`[turbine] mcp pool error: ${(0, ui_js_1.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.
+    (0, connection_guard_js_1.absorbCheckedOutErrors)(ctx.pool);
     announcePiiTags(options);
     let buffer = '';
     let disposed = false;

package/dist/cjs/cli/migrate.js

@@ -63,6 +63,7 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const pg_1 = __importDefault(require("pg"));
 const index_js_1 = require("../adapters/index.js");
+const connection_guard_js_1 = require("../connection-guard.js");
 const connection_url_js_1 = require("../connection-url.js");
 const dialect_js_1 = require("../dialect.js");
 const errors_js_1 = require("../errors.js");
@@ -882,6 +883,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_1.default.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).
+    (0, connection_guard_js_1.guardConnection)(client);
     await client.connect();
     return { client, connectionString: pinned };
 }
@@ -894,6 +898,7 @@ async function probeConnectionSchemas(connectionString, schema) {
     // so in those terms, see assertPinnableSchema.
     assertPinnableSchema(schema);
     const probe = new pg_1.default.Client({ connectionString });
+    (0, connection_guard_js_1.guardConnection)(probe);
     await probe.connect();
     try {
         await assertSchemaExists(probe, schema);
@@ -907,6 +912,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_1.default.Client({ connectionString });
+    (0, connection_guard_js_1.guardConnection)(client);
     await client.connect();
     return client;
 }

package/dist/cjs/cli/observe.js

@@ -15,8 +15,10 @@ exports.handleRequest = handleRequest;
 const node_crypto_1 = require("node:crypto");
 const node_http_1 = require("node:http");
 const pg_1 = __importDefault(require("pg"));
+const connection_guard_js_1 = require("../connection-guard.js");
 const observe_ui_js_1 = require("./observe-ui.js");
 const rate_limit_js_1 = require("./rate-limit.js");
+const ui_js_1 = require("./ui.js");
 // ---------------------------------------------------------------------------
 // Main entry point
 // ---------------------------------------------------------------------------
@@ -26,6 +28,12 @@ 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: ${(0, ui_js_1.redactUrl)(err.message)}`);
+    });
+    (0, connection_guard_js_1.absorbCheckedOutErrors)(pool);
     const probe = await pool.connect();
     try {
         await probe.query('SELECT 1');

package/dist/cjs/cli/studio.js

@@ -62,6 +62,7 @@ const node_http_1 = require("node:http");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const pg_1 = __importDefault(require("pg"));
+const connection_guard_js_1 = require("../connection-guard.js");
 const errors_js_1 = require("../errors.js");
 const introspect_js_1 = require("../introspect.js");
 const index_js_1 = require("../query/index.js");
@@ -77,6 +78,7 @@ const pii_tags_js_1 = require("./pii-tags.js");
 const rate_limit_js_1 = require("./rate-limit.js");
 const studio_demo_js_1 = require("./studio-demo.js");
 const studio_ui_generated_js_1 = require("./studio-ui.generated.js");
+const ui_js_1 = require("./ui.js");
 // ---------------------------------------------------------------------------
 // Main entry point
 // ---------------------------------------------------------------------------
@@ -121,11 +123,21 @@ async function startStudio(options) {
         (0, utils_js_1.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_1.default.Pool({
+        const pgPool = new pg_1.default.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: ${(0, ui_js_1.redactUrl)(err.message)}`);
+        });
+        (0, connection_guard_js_1.absorbCheckedOutErrors)(pgPool);
+        pool = pgPool;
         // Verify connectivity before starting the server, fail fast.
         const probe = await pool.connect();
         try {

package/dist/cjs/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.
      *