turbine-orm 0.15.0 → 0.18.0

package/dist/cjs/cli/observe.js

@@ -0,0 +1,242 @@
+"use strict";
+/**
+ * turbine-orm CLI — Observe
+ *
+ * A local, read-only dashboard for viewing query metrics stored in
+ * _turbine_metrics. Same security model as Studio: loopback binding,
+ * random token, HttpOnly cookie, CSP headers, read-only transactions.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startObserve = startObserve;
+const node_crypto_1 = require("node:crypto");
+const node_http_1 = require("node:http");
+const pg_1 = __importDefault(require("pg"));
+const observe_ui_js_1 = require("./observe-ui.js");
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+async function startObserve(options) {
+    const pool = new pg_1.default.Pool({
+        connectionString: options.url,
+        max: 2,
+        idleTimeoutMillis: 10_000,
+    });
+    const probe = await pool.connect();
+    try {
+        await probe.query('SELECT 1');
+    }
+    finally {
+        probe.release();
+    }
+    const authToken = (0, node_crypto_1.randomBytes)(24).toString('hex');
+    const server = (0, node_http_1.createServer)((req, res) => {
+        handleRequest(req, res, pool, options, authToken).catch((err) => {
+            sendJson(res, 500, { error: err instanceof Error ? err.message : String(err) });
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(options.port, options.host, () => {
+            server.off('error', reject);
+            resolve();
+        });
+    });
+    const hostPart = options.host.includes(':') && !options.host.startsWith('[') ? `[${options.host}]` : options.host;
+    const url = `http://${hostPart}:${options.port}/?token=${authToken}`;
+    if (options.openBrowser) {
+        openUrl(url);
+    }
+    return {
+        authToken,
+        url,
+        dispose: async () => {
+            await new Promise((resolve) => server.close(() => resolve()));
+            await pool.end();
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Request routing
+// ---------------------------------------------------------------------------
+async function handleRequest(req, res, pool, options, authToken) {
+    const hostPart = options.host.includes(':') && !options.host.startsWith('[') ? `[${options.host}]` : options.host;
+    const expectedOrigin = `http://${hostPart}:${options.port}`;
+    const origin = req.headers.origin;
+    if (origin && origin !== expectedOrigin) {
+        sendJson(res, 403, { error: 'cross-origin requests not allowed' });
+        return;
+    }
+    const url = new URL(req.url ?? '/', expectedOrigin);
+    const pathname = url.pathname;
+    if (pathname === '/' || pathname === '/index.html') {
+        if (req.method !== 'GET' && req.method !== 'HEAD') {
+            sendText(res, 405, 'Method Not Allowed');
+            return;
+        }
+        const queryToken = url.searchParams.get('token');
+        if (queryToken && constantTimeEqual(queryToken, authToken)) {
+            res.writeHead(302, {
+                Location: '/',
+                'Set-Cookie': `turbine_observe_token=${authToken}; Path=/; HttpOnly; SameSite=Strict`,
+            });
+            res.end();
+            return;
+        }
+        sendHtml(res, 200, observe_ui_js_1.OBSERVE_HTML);
+        return;
+    }
+    if (!isAuthorized(req, authToken)) {
+        sendJson(res, 401, { error: 'unauthorized' });
+        return;
+    }
+    if (pathname === '/api/latency' && req.method === 'GET') {
+        return apiLatency(res, pool, url.searchParams);
+    }
+    if (pathname === '/api/models' && req.method === 'GET') {
+        return apiModels(res, pool, url.searchParams);
+    }
+    sendJson(res, 404, { error: 'not found' });
+}
+// ---------------------------------------------------------------------------
+// Auth
+// ---------------------------------------------------------------------------
+function isAuthorized(req, expectedToken) {
+    const headerToken = req.headers['x-turbine-token'];
+    if (typeof headerToken === 'string' && constantTimeEqual(headerToken, expectedToken)) {
+        return true;
+    }
+    const cookieHeader = req.headers.cookie ?? '';
+    const match = /turbine_observe_token=([a-f0-9]+)/.exec(cookieHeader);
+    if (match?.[1] && constantTimeEqual(match[1], expectedToken)) {
+        return true;
+    }
+    return false;
+}
+function constantTimeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let result = 0;
+    for (let i = 0; i < a.length; i++) {
+        result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    }
+    return result === 0;
+}
+// ---------------------------------------------------------------------------
+// API handlers
+// ---------------------------------------------------------------------------
+function rangeToInterval(range) {
+    switch (range) {
+        case '6h':
+            return '6 hours';
+        case '24h':
+            return '24 hours';
+        case '7d':
+            return '7 days';
+        default:
+            return '1 hour';
+    }
+}
+async function apiLatency(res, pool, params) {
+    const range = params.get('range') ?? '1h';
+    const interval = rangeToInterval(range);
+    const client = await pool.connect();
+    try {
+        await client.query('BEGIN READ ONLY');
+        await client.query(`SET LOCAL statement_timeout = '30s'`);
+        const result = await client.query(`SELECT bucket, SUM(count) as count,
+              SUM(avg_ms * count) / NULLIF(SUM(count), 0) as avg_ms,
+              MAX(p95_ms) as p95_ms,
+              MAX(p99_ms) as p99_ms
+       FROM _turbine_metrics
+       WHERE bucket >= NOW() - $1::interval
+       GROUP BY bucket
+       ORDER BY bucket`, [interval]);
+        await client.query('COMMIT');
+        sendJson(res, 200, result.rows);
+    }
+    catch (err) {
+        try {
+            await client.query('ROLLBACK');
+        }
+        catch { }
+        sendJson(res, 500, { error: err instanceof Error ? err.message : String(err) });
+    }
+    finally {
+        client.release();
+    }
+}
+async function apiModels(res, pool, params) {
+    const range = params.get('range') ?? '1h';
+    const interval = rangeToInterval(range);
+    const client = await pool.connect();
+    try {
+        await client.query('BEGIN READ ONLY');
+        await client.query(`SET LOCAL statement_timeout = '30s'`);
+        const result = await client.query(`SELECT model, action,
+              SUM(count)::int as count,
+              SUM(avg_ms * count) / NULLIF(SUM(count), 0) as avg_ms,
+              MAX(p95_ms) as p95_ms,
+              MAX(p99_ms) as p99_ms,
+              SUM(error_count)::int as error_count
+       FROM _turbine_metrics
+       WHERE bucket >= NOW() - $1::interval
+       GROUP BY model, action
+       ORDER BY MAX(p95_ms) DESC
+       LIMIT 50`, [interval]);
+        await client.query('COMMIT');
+        sendJson(res, 200, result.rows);
+    }
+    catch (err) {
+        try {
+            await client.query('ROLLBACK');
+        }
+        catch { }
+        sendJson(res, 500, { error: err instanceof Error ? err.message : String(err) });
+    }
+    finally {
+        client.release();
+    }
+}
+// ---------------------------------------------------------------------------
+// Response helpers
+// ---------------------------------------------------------------------------
+const SECURITY_HEADERS = {
+    'X-Content-Type-Options': 'nosniff',
+    'X-Frame-Options': 'DENY',
+    'Referrer-Policy': 'no-referrer',
+    'Content-Security-Policy': "default-src 'self'; script-src 'unsafe-inline'; style-src 'unsafe-inline'",
+};
+function sendJson(res, status, body) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, { ...SECURITY_HEADERS, 'Content-Type': 'application/json' });
+    res.end(payload);
+}
+function sendHtml(res, status, html) {
+    res.writeHead(status, { ...SECURITY_HEADERS, 'Content-Type': 'text/html; charset=utf-8' });
+    res.end(html);
+}
+function sendText(res, status, text) {
+    res.writeHead(status, { ...SECURITY_HEADERS, 'Content-Type': 'text/plain' });
+    res.end(text);
+}
+// ---------------------------------------------------------------------------
+// Browser open
+// ---------------------------------------------------------------------------
+function openUrl(url) {
+    const { platform: os } = process;
+    const { spawn } = require('node:child_process');
+    try {
+        if (os === 'darwin')
+            spawn('open', [url], { stdio: 'ignore', detached: true }).unref();
+        else if (os === 'win32')
+            spawn('cmd', ['/c', 'start', '', url], { stdio: 'ignore', detached: true }).unref();
+        else
+            spawn('xdg-open', [url], { stdio: 'ignore', detached: true }).unref();
+    }
+    catch {
+        // Best effort
+    }
+}

package/dist/cjs/cli/studio.js

@@ -75,7 +75,11 @@ async function startStudio(options) {
     const authToken = (0, node_crypto_1.randomBytes)(24).toString('hex');
     const stateDir = (0, node_path_1.resolve)(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();

package/dist/cjs/client.js

@@ -30,8 +30,12 @@ exports.TurbineClient = exports.TransactionClient = void 0;
 exports.withRetry = withRetry;
 const pg_1 = __importDefault(require("pg"));
 const errors_js_1 = require("./errors.js");
+const observe_js_1 = require("./observe.js");
 const pipeline_js_1 = require("./pipeline.js");
 const index_js_1 = require("./query/index.js");
+const utils_js_1 = require("./query/utils.js");
+const realtime_js_1 = require("./realtime.js");
+const typed_sql_js_1 = require("./typed-sql.js");
 async function withRetry(fn, options) {
     const maxAttempts = options?.maxAttempts ?? 3;
     const baseDelay = options?.baseDelay ?? 50;
@@ -63,6 +67,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
 // ---------------------------------------------------------------------------
@@ -191,9 +202,13 @@ class TurbineClient {
     logging;
     tableCache = new Map();
     middlewares = [];
+    queryListeners = new Set();
     queryOptions;
+    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.
@@ -225,12 +240,27 @@ class TurbineClient {
         this.schema = schema;
         // Respect env var kill switch
         const envDisablePrepared = typeof process !== 'undefined' && process.env?.TURBINE_DISABLE_PREPARED === '1';
+        this.errorMessagesSafe = (config.errorMessages ?? 'safe') === 'safe';
         this.queryOptions = {
             defaultLimit: config.defaultLimit,
             warnOnUnlimited: config.warnOnUnlimited,
             preparedStatements: envDisablePrepared ? false : (config.preparedStatements ?? !config.pool),
             sqlCache: config.sqlCache ?? true,
             dialect: config.dialect,
+            _onQuery: (event) => {
+                if (this.queryListeners.size === 0)
+                    return;
+                const emitted = this.errorMessagesSafe ? { ...event, params: event.params.map(() => '[REDACTED]') } : event;
+                for (const listener of this.queryListeners) {
+                    try {
+                        listener(emitted);
+                    }
+                    catch (e) {
+                        if (this.logging)
+                            console.error('[turbine] Query listener error:', e);
+                    }
+                }
+            },
         };
         // Apply NotFoundError message redaction mode (default: safe — values are
         // stripped from messages to avoid leaking PII into error logs).
@@ -283,6 +313,11 @@ class TurbineClient {
                 });
             }
         }
+        // Auto-start observability from env var
+        const observeUrl = typeof process !== 'undefined' ? process.env?.TURBINE_OBSERVE_URL : undefined;
+        if (observeUrl) {
+            this.$observe({ connectionString: observeUrl }).catch(() => { });
+        }
     }
     // -------------------------------------------------------------------------
     // Middleware — intercept all queries
@@ -324,6 +359,37 @@ class TurbineClient {
         this.tableCache.clear();
     }
     // -------------------------------------------------------------------------
+    // Event emitter — subscribe to query lifecycle events
+    // -------------------------------------------------------------------------
+    $on(_event, listener) {
+        this.queryListeners.add(listener);
+    }
+    $off(_event, listener) {
+        this.queryListeners.delete(listener);
+    }
+    // -------------------------------------------------------------------------
+    // Observability — automatic metrics collection
+    // -------------------------------------------------------------------------
+    observeEngine;
+    async $observe(config) {
+        if (this.observeEngine) {
+            await this.observeEngine.stop();
+            this.$off('query', this.observeEngine.getListener());
+        }
+        const engine = new observe_js_1.ObserveEngine(config);
+        this.observeEngine = engine;
+        await engine.init();
+        this.$on('query', engine.getListener());
+        return {
+            stop: async () => {
+                this.$off('query', engine.getListener());
+                await engine.stop();
+                if (this.observeEngine === engine)
+                    this.observeEngine = undefined;
+            },
+        };
+    }
+    // -------------------------------------------------------------------------
     // Table accessor — creates QueryInterface for any table
     // -------------------------------------------------------------------------
     /**
@@ -414,6 +480,40 @@ class TurbineClient {
             throw (0, errors_js_1.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 } = (0, typed_sql_js_1.buildTypedSql)(strings, values);
+        return new typed_sql_js_1.TypedSqlQuery(this.pool, sql, params, this.logging);
+    }
     // -------------------------------------------------------------------------
     // Transaction support (raw — legacy)
     // -------------------------------------------------------------------------
@@ -496,6 +596,21 @@ 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 errors_js_1.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
@@ -567,6 +682,94 @@ 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) {
+        (0, realtime_js_1.validateChannel)(channel);
+        const quoted = (0, utils_js_1.quoteIdent)(channel);
+        if (this.logging) {
+            console.log(`[turbine] LISTEN ${quoted}`);
+        }
+        const sub = await (0, realtime_js_1.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) {
+        (0, realtime_js_1.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 (0, errors_js_1.wrapPgError)(err);
+        }
+    }
     // -------------------------------------------------------------------------
     // Retry — automatic retry for retryable errors (deadlock, serialization)
     // -------------------------------------------------------------------------
@@ -614,6 +817,21 @@ 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/cjs/errors.js

@@ -211,7 +211,13 @@ 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}`;
         }
@@ -233,7 +239,13 @@ 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}`;
         }
@@ -254,7 +266,13 @@ 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}`;
         }
@@ -342,7 +360,13 @@ 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}`;
         }
@@ -362,7 +386,13 @@ 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}`;
         }

package/dist/cjs/generate.js

@@ -156,7 +156,8 @@ function generateTypes(schema) {
             lines.push(`export interface ${typeName}Relations {`);
             for (const [relName, rel] of Object.entries(table.relations)) {
                 const targetType = entityName(rel.to);
-                const cardinality = rel.type === 'hasMany' ? "'many'" : "'one'";
+                // manyToMany is a collection too → 'many' cardinality (same as hasMany).
+                const cardinality = rel.type === 'hasMany' || rel.type === 'manyToMany' ? "'many'" : "'one'";
                 const targetRelations = tablesWithRelations.has(rel.to) ? `${targetType}Relations` : '{}';
                 lines.push(`  ${relName}: RelationDescriptor<${targetType}, ${cardinality}, ${targetRelations}>;`);
             }
@@ -165,7 +166,7 @@ function generateTypes(schema) {
             // --- Legacy per-relation interfaces (kept for backward compatibility) ---
             for (const [relName, rel] of Object.entries(table.relations)) {
                 const targetType = entityName(rel.to);
-                if (rel.type === 'hasMany') {
+                if (rel.type === 'hasMany' || rel.type === 'manyToMany') {
                     lines.push(`/** ${typeName} with \`${relName}\` relation loaded (${rel.type}: ${rel.to}) */`);
                     lines.push(`export interface ${typeName}With${(0, schema_js_1.snakeToPascal)(relName)} extends ${typeName} {`);
                     lines.push(`  ${relName}: ${targetType}[];`);
@@ -332,7 +333,17 @@ function generateMetadata(schema) {
             const refLiteral = Array.isArray(rel.referenceKey)
                 ? `[${rel.referenceKey.map((c) => `'${escSQ(c)}'`).join(', ')}]`
                 : `'${escSQ(rel.referenceKey)}'`;
-            lines.push(`        ${relName}: { type: '${escSQ(rel.type)}', name: '${escSQ(rel.name)}', from: '${escSQ(rel.from)}', to: '${escSQ(rel.to)}', foreignKey: ${fkLiteral}, referenceKey: ${refLiteral} },`);
+            // manyToMany relations carry a `through` junction descriptor — emit it so
+            // the runtime query builder can JOIN through the junction table.
+            let throughLiteral = '';
+            if (rel.through) {
+                const keyLiteral = (k) => Array.isArray(k) ? `[${k.map((c) => `'${escSQ(c)}'`).join(', ')}]` : `'${escSQ(k)}'`;
+                throughLiteral =
+                    `, through: { table: '${escSQ(rel.through.table)}', ` +
+                        `sourceKey: ${keyLiteral(rel.through.sourceKey)}, ` +
+                        `targetKey: ${keyLiteral(rel.through.targetKey)} }`;
+            }
+            lines.push(`        ${relName}: { type: '${escSQ(rel.type)}', name: '${escSQ(rel.name)}', from: '${escSQ(rel.from)}', to: '${escSQ(rel.to)}', foreignKey: ${fkLiteral}, referenceKey: ${refLiteral}${throughLiteral} },`);
         }
         lines.push('      },');
         // indexes