turbine-orm 0.16.0 → 0.19.0

package/dist/cli/studio.js

@@ -60,7 +60,11 @@ export async function startStudio(options) {
     const authToken = randomBytes(24).toString('hex');
     const stateDir = pathResolve(options.stateDir ?? '.turbine');
     const statementTimeout = options.adapter?.statementTimeout?.(30) ?? {
-        sql: `SET LOCAL statement_timeout = $1`,
+        // Postgres rejects parameters in `SET LOCAL` (`SET LOCAL ... = $1` is a
+        // syntax error). `set_config(name, value, is_local=true)` is the
+        // parameterizable, transaction-local equivalent and works on every
+        // Postgres-compatible engine.
+        sql: `SELECT set_config('statement_timeout', $1, true)`,
         params: ['30s'],
     };
     const rateLimiter = new Map();
@@ -136,6 +140,13 @@ async function handleRequest(req, res, ctx) {
         sendHtml(res, 200, STUDIO_HTML);
         return;
     }
+    // Favicon — answered before the auth gate so the browser's automatic request
+    // doesn't 401/404 on every load. No icon body needed (204).
+    if (pathname === '/favicon.ico') {
+        res.writeHead(204, { 'Content-Length': '0' });
+        res.end();
+        return;
+    }
     // API routes — all require auth.
     if (!isAuthorized(req, ctx.authToken)) {
         sendJson(res, 401, { error: 'unauthorized — use the URL printed in the terminal' });
@@ -156,9 +167,6 @@ async function handleRequest(req, res, ctx) {
         const rawName = decodeURIComponent(pathname.slice('/api/tables/'.length));
         return apiTableRows(res, ctx, rawName, url.searchParams);
     }
-    if (pathname === '/api/query' && req.method === 'POST') {
-        return apiQuery(req, res, ctx);
-    }
     if (pathname === '/api/builder' && req.method === 'POST') {
         return apiBuilder(req, res, ctx);
     }
@@ -218,6 +226,15 @@ function constantTimeEqual(a, b) {
     }
     return result === 0;
 }
+/**
+ * Build a helpful "unknown table" error that lists the available tables so the
+ * caller can spot a typo or schema mismatch immediately.
+ */
+function unknownTableMessage(name, ctx) {
+    const available = Object.keys(ctx.metadata.tables);
+    const list = available.length ? available.join(', ') : '(none)';
+    return `[turbine] Unknown table "${name}" in schema "${ctx.options.schema}". Available: ${list}`;
+}
 // ---------------------------------------------------------------------------
 // API: /api/schema
 // ---------------------------------------------------------------------------
@@ -250,7 +267,9 @@ async function apiSchema(res, ctx) {
      WHERE n.nspname = $1 AND c.relkind = 'r'`, [ctx.options.schema]);
     const counts = new Map();
     for (const row of countsResult.rows) {
-        counts.set(row.relname, Number(row.reltuples));
+        // pg_class.reltuples is -1 on PG14+ until a table is ANALYZEd; clamp so the
+        // sidebar never shows a negative estimate.
+        counts.set(row.relname, Math.max(0, Number(row.reltuples)));
     }
     sendJson(res, 200, {
         schema: ctx.options.schema,
@@ -264,7 +283,7 @@ async function apiSchema(res, ctx) {
 export async function apiTableRows(res, ctx, rawTableName, params) {
     const table = ctx.metadata.tables[rawTableName];
     if (!table) {
-        sendJson(res, 404, { error: `unknown table: ${rawTableName}` });
+        sendJson(res, 404, { error: unknownTableMessage(rawTableName, ctx) });
         return;
     }
     const limit = clampInt(params.get('limit'), 50, 1, 500);
@@ -359,54 +378,6 @@ export function escapeLikePattern(s) {
     return s.replace(/\\/g, '\\\\').replace(/%/g, '\\%').replace(/_/g, '\\_');
 }
 // ---------------------------------------------------------------------------
-// API: /api/query — read-only SELECT/WITH runner
-// ---------------------------------------------------------------------------
-async function apiQuery(req, res, ctx) {
-    const body = await readJsonBody(req);
-    const rawSql = typeof body?.sql === 'string' ? body.sql.trim() : '';
-    if (!rawSql) {
-        sendJson(res, 400, { error: 'missing sql' });
-        return;
-    }
-    if (rawSql.length > 10_000) {
-        sendJson(res, 400, { error: 'query too long — maximum 10,000 characters allowed' });
-        return;
-    }
-    if (!isReadOnlyStatement(rawSql)) {
-        sendJson(res, 400, {
-            error: 'only SELECT / WITH statements are allowed in Studio — use the CLI for writes',
-        });
-        return;
-    }
-    const client = await ctx.pool.connect();
-    try {
-        await client.query('BEGIN READ ONLY');
-        await client.query(ctx.statementTimeout.sql, ctx.statementTimeout.params);
-        const started = Date.now();
-        const result = await client.query(rawSql);
-        const elapsedMs = Date.now() - started;
-        await client.query('COMMIT');
-        sendJson(res, 200, {
-            columns: result.fields.map((f) => ({ name: f.name, dataTypeID: f.dataTypeID })),
-            rows: result.rows.map((r) => serializeRow(r)),
-            rowCount: result.rowCount ?? result.rows.length,
-            elapsedMs,
-        });
-    }
-    catch (err) {
-        try {
-            await client.query('ROLLBACK');
-        }
-        catch {
-            /* ignore */
-        }
-        sendJson(res, 400, { error: err instanceof Error ? err.message : String(err) });
-    }
-    finally {
-        client.release();
-    }
-}
-// ---------------------------------------------------------------------------
 // API: /api/builder — Turbine ORM findMany spec runner
 // ---------------------------------------------------------------------------
 export async function apiBuilder(req, res, ctx) {
@@ -414,7 +385,7 @@ export async function apiBuilder(req, res, ctx) {
     const tableName = typeof body?.table === 'string' ? body.table : '';
     const args = (body?.args ?? {});
     if (!tableName || !ctx.metadata.tables[tableName]) {
-        sendJson(res, 400, { error: `unknown table: ${tableName}` });
+        sendJson(res, 400, { error: unknownTableMessage(tableName, ctx) });
         return;
     }
     let deferred;
@@ -471,7 +442,9 @@ function loadSavedQueries(ctx) {
         const parsed = JSON.parse(raw);
         if (!parsed.queries || !Array.isArray(parsed.queries))
             return { version: 1, queries: [] };
-        return { version: 1, queries: parsed.queries };
+        // Drop any legacy raw-SQL entries — Studio is builder-only now.
+        const queries = parsed.queries.filter((q) => q && q.kind === 'builder');
+        return { version: 1, queries };
     }
     catch {
         return { version: 1, queries: [] };
@@ -494,27 +467,17 @@ export async function apiCreateSavedQuery(req, res, ctx) {
     const body = await readJsonBody(req);
     const table = typeof body?.table === 'string' ? body.table : '';
     const name = typeof body?.name === 'string' ? body.name.trim() : '';
-    const kind = body?.kind === 'builder' ? 'builder' : body?.kind === 'sql' ? 'sql' : null;
     if (!table || !ctx.metadata.tables[table]) {
-        sendJson(res, 400, { error: `unknown table: ${table}` });
+        sendJson(res, 400, { error: unknownTableMessage(table, ctx) });
         return;
     }
     if (!name) {
         sendJson(res, 400, { error: 'name is required' });
         return;
     }
-    if (!kind) {
-        sendJson(res, 400, { error: 'kind must be "sql" or "builder"' });
-        return;
-    }
-    const sql = kind === 'sql' && typeof body?.sql === 'string' ? body.sql : undefined;
-    const args = kind === 'builder' ? body?.args : undefined;
-    if (kind === 'sql' && !sql) {
-        sendJson(res, 400, { error: 'sql is required for kind=sql' });
-        return;
-    }
-    if (kind === 'sql' && sql && !isReadOnlyStatement(sql)) {
-        sendJson(res, 400, { error: 'saved sql must be SELECT/WITH only' });
+    // Studio only persists visual-builder queries (no raw SQL surface).
+    if (body?.kind !== 'builder') {
+        sendJson(res, 400, { error: 'kind must be "builder"' });
         return;
     }
     const data = loadSavedQueries(ctx);
@@ -522,9 +485,8 @@ export async function apiCreateSavedQuery(req, res, ctx) {
         id: randomUUID(),
         table,
         name,
-        kind,
-        sql,
-        args,
+        kind: 'builder',
+        args: body?.args,
         createdAt: new Date().toISOString(),
     };
     data.queries.push(entry);

package/dist/client.d.ts

@@ -27,7 +27,9 @@ import { type ErrorMessageMode } from './errors.js';
 import { type ObserveConfig, type ObserveHandle } from './observe.js';
 import { type PipelineOptions, type PipelineResults } from './pipeline.js';
 import { type DeferredQuery, type QueryEventListener, QueryInterface, type QueryInterfaceOptions } from './query/index.js';
+import { type NotificationHandler, type Subscription } from './realtime.js';
 import type { SchemaMetadata } from './schema.js';
+import { TypedSqlQuery } from './typed-sql.js';
 export interface RetryOptions {
     maxAttempts?: number;
     baseDelay?: number;
@@ -172,6 +174,30 @@ export interface TransactionOptions {
     timeout?: number;
     /** Isolation level for the transaction */
     isolationLevel?: 'ReadUncommitted' | 'ReadCommitted' | 'RepeatableRead' | 'Serializable';
+    /**
+     * Transaction-local session GUCs to set after BEGIN. The canonical use case
+     * is multi-tenant Postgres row-level security (RLS): your policies filter on
+     * `current_setting('app.current_tenant')`, and you set that value here so
+     * every query inside the transaction sees it.
+     *
+     * Each entry is applied via `SELECT set_config($1, $2, true)` — `is_local=true`
+     * scopes the value to this transaction, so it auto-resets on COMMIT/ROLLBACK
+     * and never leaks onto the pooled connection. Both the name and value are
+     * bound parameters (never interpolated); the GUC name is additionally
+     * validated against a strict identifier regex.
+     *
+     * @example
+     * ```ts
+     * await db.$transaction(
+     *   async (tx) => {
+     *     // every query here sees current_setting('app.current_tenant') = '42'
+     *     return tx.invoices.findMany();
+     *   },
+     *   { sessionContext: { 'app.current_tenant': '42', 'app.current_user': userId } },
+     * );
+     * ```
+     */
+    sessionContext?: Record<string, string | number | boolean>;
 }
 /**
  * A transaction-scoped client that provides the same table accessor API as TurbineClient.
@@ -225,6 +251,8 @@ export declare class TurbineClient {
     private readonly errorMessagesSafe;
     /** True when Turbine created the pool and is responsible for tearing it down */
     private readonly ownsPool;
+    /** Active LISTEN subscriptions — torn down on disconnect() so it never hangs */
+    private readonly activeSubscriptions;
     constructor(config: TurbineConfig | undefined, schema: SchemaMetadata);
     /**
      * Register a middleware function that runs before/after every query.
@@ -298,6 +326,37 @@ export declare class TurbineClient {
      * ```
      */
     raw<T extends Record<string, unknown> = Record<string, unknown>>(strings: TemplateStringsArray, ...values: unknown[]): Promise<T[]>;
+    /**
+     * Execute a **typed** raw SQL query — Turbine's answer to Prisma's TypedSQL.
+     *
+     * Like {@link raw}, every interpolated `${value}` becomes a `$N` parameter
+     * (never string-concatenated), so it is injection-safe by construction. The
+     * difference is the caller-supplied row type and the chainable result: the
+     * returned {@link TypedSqlQuery} can be `await`ed directly for `T[]`, or
+     * refined with `.one()` (→ `T | null`) or `.scalar<V>()` (→ `V | null`).
+     *
+     * Rows are returned as-is — no snake→camel mapping (matching `raw()`). Alias
+     * columns in SQL if you want camelCase keys.
+     *
+     * @example
+     * ```ts
+     * // rows
+     * const rows = await db.sql<{ id: number; name: string }>`
+     *   SELECT id, name FROM users WHERE org_id = ${orgId}
+     * `;
+     *
+     * // single row or null
+     * const user = await db.sql<{ id: number; name: string }>`
+     *   SELECT id, name FROM users WHERE id = ${userId}
+     * `.one();
+     *
+     * // scalar
+     * const total = await db.sql<{ count: number }>`
+     *   SELECT COUNT(*)::int AS count FROM users
+     * `.scalar();
+     * ```
+     */
+    sql<T extends Record<string, unknown> = Record<string, unknown>>(strings: TemplateStringsArray, ...values: unknown[]): TypedSqlQuery<T>;
     /**
      * Execute a function within a database transaction (raw pg.PoolClient).
      * For the typed API, use `$transaction()` instead.
@@ -330,6 +389,67 @@ export declare class TurbineClient {
      * ```
      */
     $transaction<R>(fn: (tx: TransactionClient) => Promise<R>, options?: TransactionOptions): Promise<R>;
+    /**
+     * Convenience wrapper around `$transaction` for the multi-tenant / RLS case:
+     * runs `fn` inside a transaction with the given session GUCs applied via
+     * `set_config(..., is_local=true)`. Equivalent to
+     * `$transaction(fn, { sessionContext: context })`.
+     *
+     * @example
+     * ```ts
+     * const invoices = await db.$withSession(
+     *   { 'app.current_tenant': tenantId },
+     *   (tx) => tx.invoices.findMany(),
+     * );
+     * ```
+     */
+    $withSession<R>(context: Record<string, string | number | boolean>, fn: (tx: TransactionClient) => Promise<R>): Promise<R>;
+    /**
+     * Subscribe to a Postgres NOTIFY channel. The handler fires with each
+     * notification's payload string (the empty string when a payload-less
+     * NOTIFY is sent) for as long as the subscription is active.
+     *
+     * Each `$listen` checks out its OWN dedicated long-lived connection from the
+     * pool and runs `LISTEN "channel"` on it; `subscription.unsubscribe()`
+     * UNLISTENs, detaches the handler, and releases that connection. Active
+     * subscriptions are tracked and force-released on `disconnect()` so shutdown
+     * never hangs.
+     *
+     * The channel name CANNOT be a bound parameter (`LISTEN $1` is a syntax
+     * error), so it is validated against a strict identifier regex AND quoted via
+     * `quoteIdent` before interpolation — it is the only identifier this method
+     * places into SQL text.
+     *
+     * **Serverless caveat:** LISTEN needs a persistent connection that can push
+     * async notifications. Stateless HTTP drivers (Neon HTTP, Vercel Postgres)
+     * cannot do this — `$listen` throws a `ConnectionError` rather than hang.
+     * `$notify` works on every driver.
+     *
+     * @example
+     * ```ts
+     * const sub = await db.$listen('order_created', (payload) => {
+     *   const order = JSON.parse(payload);
+     *   console.log('new order', order.id);
+     * });
+     * // ...later
+     * await sub.unsubscribe();
+     * ```
+     */
+    $listen(channel: string, handler: NotificationHandler): Promise<Subscription>;
+    /**
+     * Send a Postgres NOTIFY on `channel` with an optional payload string.
+     *
+     * Issued as `SELECT pg_notify($1, $2)` — both the channel and payload are
+     * BOUND parameters (no quoting/injection concern). The channel is still
+     * validated against the identifier regex for parity with `$listen` and to
+     * catch typos loudly. Works on every driver, including serverless HTTP pools.
+     *
+     * @example
+     * ```ts
+     * await db.$notify('order_created', JSON.stringify({ id: 7 }));
+     * ```
+     */
+    $notify(channel: string, payload?: string): Promise<void>;
     /**
      * Execute an async function with automatic retry on retryable errors.
      *

package/dist/client.js

@@ -22,10 +22,13 @@
  * ```
  */
 import pg from 'pg';
-import { setErrorMessageMode, TimeoutError, wrapPgError } from './errors.js';
+import { setErrorMessageMode, TimeoutError, ValidationError, wrapPgError } from './errors.js';
 import { ObserveEngine } from './observe.js';
 import { executePipeline, pipelineSupported } from './pipeline.js';
 import { QueryInterface, } from './query/index.js';
+import { quoteIdent } from './query/utils.js';
+import { createSubscription, validateChannel, } from './realtime.js';
+import { buildTypedSql, TypedSqlQuery } from './typed-sql.js';
 export async function withRetry(fn, options) {
     const maxAttempts = options?.maxAttempts ?? 3;
     const baseDelay = options?.baseDelay ?? 50;
@@ -57,6 +60,13 @@ const ISOLATION_LEVELS = {
     RepeatableRead: 'REPEATABLE READ',
     Serializable: 'SERIALIZABLE',
 };
+/**
+ * Strict GUC (session variable) name: an optionally namespaced identifier such
+ * as `app.current_tenant` or `search_path`. Even though the name is passed as a
+ * bound parameter to `set_config`, a malformed name is a programmer error worth
+ * rejecting loudly before it reaches the database.
+ */
+const GUC_NAME_REGEX = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$/;
 // ---------------------------------------------------------------------------
 // TransactionClient — provides typed table accessors within a transaction
 // ---------------------------------------------------------------------------
@@ -189,6 +199,8 @@ export class TurbineClient {
     errorMessagesSafe;
     /** True when Turbine created the pool and is responsible for tearing it down */
     ownsPool = true;
+    /** Active LISTEN subscriptions — torn down on disconnect() so it never hangs */
+    activeSubscriptions = new Set();
     constructor(config = {}, schema) {
         /**
          * Parse int8 (bigint, OID 20) as JavaScript number instead of string.
@@ -460,6 +472,40 @@ export class TurbineClient {
             throw wrapPgError(err);
         }
     }
+    /**
+     * Execute a **typed** raw SQL query — Turbine's answer to Prisma's TypedSQL.
+     *
+     * Like {@link raw}, every interpolated `${value}` becomes a `$N` parameter
+     * (never string-concatenated), so it is injection-safe by construction. The
+     * difference is the caller-supplied row type and the chainable result: the
+     * returned {@link TypedSqlQuery} can be `await`ed directly for `T[]`, or
+     * refined with `.one()` (→ `T | null`) or `.scalar<V>()` (→ `V | null`).
+     *
+     * Rows are returned as-is — no snake→camel mapping (matching `raw()`). Alias
+     * columns in SQL if you want camelCase keys.
+     *
+     * @example
+     * ```ts
+     * // rows
+     * const rows = await db.sql<{ id: number; name: string }>`
+     *   SELECT id, name FROM users WHERE org_id = ${orgId}
+     * `;
+     *
+     * // single row or null
+     * const user = await db.sql<{ id: number; name: string }>`
+     *   SELECT id, name FROM users WHERE id = ${userId}
+     * `.one();
+     *
+     * // scalar
+     * const total = await db.sql<{ count: number }>`
+     *   SELECT COUNT(*)::int AS count FROM users
+     * `.scalar();
+     * ```
+     */
+    sql(strings, ...values) {
+        const { sql, params } = buildTypedSql(strings, values);
+        return new TypedSqlQuery(this.pool, sql, params, this.logging);
+    }
     // -------------------------------------------------------------------------
     // Transaction support (raw — legacy)
     // -------------------------------------------------------------------------
@@ -542,6 +588,21 @@ export class TurbineClient {
                     beginSQL += ` ISOLATION LEVEL ${level}`;
             }
             await client.query(beginSQL);
+            // Apply transaction-local session context (RLS / multi-tenant GUCs).
+            // Order matters: BEGIN -> isolation level (above) -> set_config loop ->
+            // user fn. Any error here propagates to the catch below and rolls back
+            // like any other transaction failure. We use set_config(name, value,
+            // is_local=true) — the parameterizable, transaction-scoped equivalent of
+            // SET LOCAL — so both name and value are BOUND params, never interpolated.
+            if (options?.sessionContext) {
+                for (const [name, value] of Object.entries(options.sessionContext)) {
+                    if (!GUC_NAME_REGEX.test(name)) {
+                        throw new ValidationError(`[turbine] Invalid session-context GUC name "${name}" — must match ` +
+                            '/^[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)?$/ (optionally namespaced, e.g. "app.current_tenant")');
+                    }
+                    await client.query('SELECT set_config($1, $2, true)', [name, String(value)]);
+                }
+            }
             // Create the transaction client with typed table accessors
             const tx = new TransactionClient(client, this.schema, this.middlewares, this.queryOptions);
             // Dynamically attach table accessors to tx
@@ -613,6 +674,94 @@ export class TurbineClient {
             releaseOnce();
         }
     }
+    /**
+     * Convenience wrapper around `$transaction` for the multi-tenant / RLS case:
+     * runs `fn` inside a transaction with the given session GUCs applied via
+     * `set_config(..., is_local=true)`. Equivalent to
+     * `$transaction(fn, { sessionContext: context })`.
+     *
+     * @example
+     * ```ts
+     * const invoices = await db.$withSession(
+     *   { 'app.current_tenant': tenantId },
+     *   (tx) => tx.invoices.findMany(),
+     * );
+     * ```
+     */
+    async $withSession(context, fn) {
+        return this.$transaction(fn, { sessionContext: context });
+    }
+    // -------------------------------------------------------------------------
+    // LISTEN / NOTIFY — Postgres realtime pub/sub
+    // -------------------------------------------------------------------------
+    /**
+     * Subscribe to a Postgres NOTIFY channel. The handler fires with each
+     * notification's payload string (the empty string when a payload-less
+     * NOTIFY is sent) for as long as the subscription is active.
+     *
+     * Each `$listen` checks out its OWN dedicated long-lived connection from the
+     * pool and runs `LISTEN "channel"` on it; `subscription.unsubscribe()`
+     * UNLISTENs, detaches the handler, and releases that connection. Active
+     * subscriptions are tracked and force-released on `disconnect()` so shutdown
+     * never hangs.
+     *
+     * The channel name CANNOT be a bound parameter (`LISTEN $1` is a syntax
+     * error), so it is validated against a strict identifier regex AND quoted via
+     * `quoteIdent` before interpolation — it is the only identifier this method
+     * places into SQL text.
+     *
+     * **Serverless caveat:** LISTEN needs a persistent connection that can push
+     * async notifications. Stateless HTTP drivers (Neon HTTP, Vercel Postgres)
+     * cannot do this — `$listen` throws a `ConnectionError` rather than hang.
+     * `$notify` works on every driver.
+     *
+     * @example
+     * ```ts
+     * const sub = await db.$listen('order_created', (payload) => {
+     *   const order = JSON.parse(payload);
+     *   console.log('new order', order.id);
+     * });
+     * // ...later
+     * await sub.unsubscribe();
+     * ```
+     */
+    async $listen(channel, handler) {
+        validateChannel(channel);
+        const quoted = quoteIdent(channel);
+        if (this.logging) {
+            console.log(`[turbine] LISTEN ${quoted}`);
+        }
+        const sub = await createSubscription(this.pool, channel, quoted, handler, (closed) => {
+            this.activeSubscriptions.delete(closed);
+        });
+        this.activeSubscriptions.add(sub);
+        return sub;
+    }
+    /**
+     * Send a Postgres NOTIFY on `channel` with an optional payload string.
+     *
+     * Issued as `SELECT pg_notify($1, $2)` — both the channel and payload are
+     * BOUND parameters (no quoting/injection concern). The channel is still
+     * validated against the identifier regex for parity with `$listen` and to
+     * catch typos loudly. Works on every driver, including serverless HTTP pools.
+     *
+     * @example
+     * ```ts
+     * await db.$notify('order_created', JSON.stringify({ id: 7 }));
+     * ```
+     */
+    async $notify(channel, payload) {
+        validateChannel(channel);
+        if (this.logging) {
+            console.log(`[turbine] NOTIFY ${channel}`);
+        }
+        try {
+            await this.pool.query('SELECT pg_notify($1, $2)', [channel, payload ?? '']);
+        }
+        catch (err) {
+            throw wrapPgError(err);
+        }
+    }
     // -------------------------------------------------------------------------
     // Retry — automatic retry for retryable errors (deadlock, serialization)
     // -------------------------------------------------------------------------
@@ -660,6 +809,21 @@ export class TurbineClient {
      * method is a no-op — the caller is responsible for the pool's lifecycle.
      */
     async disconnect() {
+        // Tear down any live LISTEN subscriptions first. Each holds a dedicated
+        // pooled connection checked out; if we ended the pool (or returned for an
+        // external pool) without releasing them, pool.end() would wait forever for
+        // those connections to return. _forceRelease() detaches the handler and
+        // releases the client WITHOUT issuing UNLISTEN (pointless if we're ending
+        // the pool / the connection is going away anyway). This runs for both
+        // owned and external pools so subscriptions never leak.
+        if (this.activeSubscriptions.size > 0) {
+            // _forceRelease mutates activeSubscriptions via the onClosed callback,
+            // so iterate a snapshot.
+            for (const sub of [...this.activeSubscriptions]) {
+                sub._forceRelease();
+            }
+            this.activeSubscriptions.clear();
+        }
         if (!this.ownsPool) {
             if (this.logging) {
                 console.log('[turbine] disconnect() skipped — external pool is not owned by Turbine');

package/dist/errors.js

@@ -197,7 +197,13 @@ export class UniqueConstraintError extends TurbineError {
             const constraintPart = constraint ? ` on ${constraint}` : '';
             const columnsPart = columns && columns.length > 0 ? ` (${columns.join(', ')})` : '';
             message = `[turbine] Unique constraint violation${constraintPart}${columnsPart}`;
-            const detail = detailFromCause(cause);
+            // PII-safe by default: the raw pg `detail` string contains the
+            // conflicting row VALUES (e.g. `Key (email)=(alice@x.com) already
+            // exists.`). Only append it in 'verbose' mode. In 'safe' mode the
+            // message carries keys/constraint/column names only — the structured
+            // `.columns`/`.constraint`/`.column` fields and `.cause` still expose
+            // the full detail for programmatic use.
+            const detail = errorMessageMode === 'verbose' ? detailFromCause(cause) : undefined;
             if (detail)
                 message += `: ${detail}`;
         }
@@ -218,7 +224,13 @@ export class ForeignKeyError extends TurbineError {
         if (!message) {
             const constraintPart = constraint ? ` on ${constraint}` : '';
             message = `[turbine] Foreign key constraint violation${constraintPart}`;
-            const detail = detailFromCause(cause);
+            // PII-safe by default: the raw pg `detail` string contains the
+            // conflicting row VALUES (e.g. `Key (email)=(alice@x.com) already
+            // exists.`). Only append it in 'verbose' mode. In 'safe' mode the
+            // message carries keys/constraint/column names only — the structured
+            // `.columns`/`.constraint`/`.column` fields and `.cause` still expose
+            // the full detail for programmatic use.
+            const detail = errorMessageMode === 'verbose' ? detailFromCause(cause) : undefined;
             if (detail)
                 message += `: ${detail}`;
         }
@@ -238,7 +250,13 @@ export class NotNullViolationError extends TurbineError {
         if (!message) {
             const columnPart = column ? ` on column "${column}"` : '';
             message = `[turbine] NOT NULL constraint violation${columnPart}`;
-            const detail = detailFromCause(cause);
+            // PII-safe by default: the raw pg `detail` string contains the
+            // conflicting row VALUES (e.g. `Key (email)=(alice@x.com) already
+            // exists.`). Only append it in 'verbose' mode. In 'safe' mode the
+            // message carries keys/constraint/column names only — the structured
+            // `.columns`/`.constraint`/`.column` fields and `.cause` still expose
+            // the full detail for programmatic use.
+            const detail = errorMessageMode === 'verbose' ? detailFromCause(cause) : undefined;
             if (detail)
                 message += `: ${detail}`;
         }
@@ -323,7 +341,13 @@ export class CheckConstraintError extends TurbineError {
         if (!message) {
             const constraintPart = constraint ? ` on ${constraint}` : '';
             message = `[turbine] Check constraint violation${constraintPart}`;
-            const detail = detailFromCause(cause);
+            // PII-safe by default: the raw pg `detail` string contains the
+            // conflicting row VALUES (e.g. `Key (email)=(alice@x.com) already
+            // exists.`). Only append it in 'verbose' mode. In 'safe' mode the
+            // message carries keys/constraint/column names only — the structured
+            // `.columns`/`.constraint`/`.column` fields and `.cause` still expose
+            // the full detail for programmatic use.
+            const detail = errorMessageMode === 'verbose' ? detailFromCause(cause) : undefined;
             if (detail)
                 message += `: ${detail}`;
         }
@@ -342,7 +366,13 @@ export class ExclusionConstraintError extends TurbineError {
         if (!message) {
             const constraintPart = constraint ? ` on ${constraint}` : '';
             message = `[turbine] Exclusion constraint violation${constraintPart}`;
-            const detail = detailFromCause(cause);
+            // PII-safe by default: the raw pg `detail` string contains the
+            // conflicting row VALUES (e.g. `Key (email)=(alice@x.com) already
+            // exists.`). Only append it in 'verbose' mode. In 'safe' mode the
+            // message carries keys/constraint/column names only — the structured
+            // `.columns`/`.constraint`/`.column` fields and `.cause` still expose
+            // the full detail for programmatic use.
+            const detail = errorMessageMode === 'verbose' ? detailFromCause(cause) : undefined;
             if (detail)
                 message += `: ${detail}`;
         }