turbine-orm 0.34.0 → 0.36.0

package/dist/cjs/cli/studio.js

@@ -2,36 +2,52 @@
 /**
  * turbine-orm CLI — Studio
  *
- * A local, read-only web UI for browsing databases, exploring relations,
- * and composing queries visually. ORM-native since v0.19: there is no
- * raw-SQL input surface — the Query tab builds `findMany` args that are
- * validated against introspected metadata and compiled by QueryInterface
- * (`/api/builder`). Pure Node (built-in `http` module), no runtime
- * dependencies beyond `pg`. CLI defaults to 127.0.0.1 and refuses non-loopback
- * hosts unless `npx turbine studio --allow-remote` is set.
+ * A local web UI for browsing databases, exploring relations, and composing
+ * queries visually. ORM-native since v0.19: there is no raw-SQL input surface.
+ * The Query tab builds `findMany` args that are validated against introspected
+ * metadata and compiled by QueryInterface (`/api/builder`). Pure Node (built-in
+ * `http` module), no runtime dependencies beyond `pg`. CLI defaults to 127.0.0.1
+ * and refuses non-loopback hosts unless `npx turbine studio --allow-remote`.
+ *
+ * Read-only by default. `turbine studio --write` opts in to single-row writes
+ * (see the write model below); without the flag the write API routes do not
+ * exist (they 404) and the UI renders no write affordances.
  *
  * Security model:
  *   • Loopback by default; CLI refuses non-loopback without --allow-remote
  *   • Random auth token generated per process, required in Cookie header
- *   • No SQL input surface at all — every identifier in a builder request is
- *     validated against the introspected schema; all values are $N params
- *   • Every query runs in a READ ONLY transaction (belt-and-suspenders)
+ *   • No SQL input surface at all: every identifier in a builder or write
+ *     request is validated against the introspected schema; all values are
+ *     $N params compiled through the query builders
+ *   • Read routes run in a READ ONLY transaction (belt-and-suspenders)
+ *   • Write routes (only when `--write` is set) run in a plain BEGIN/COMMIT
+ *     transaction, require a matching Origin header (CSRF), and target exactly
+ *     one row by its full primary key
  *   • 30s statement timeout via parameterized set_config()
- *   • Per-session rate limiting, CSP + security headers, cross-origin refusal
+ *   • Per-session rate limiting, cross-origin refusal, security headers, and a
+ *     per-request CSP nonce for the inline script (no `unsafe-inline`)
+ *
+ * PII: columns tagged `pii` in code-first metadata are redacted server-side in
+ * every row-bearing response (the literal `•• redacted ••`) unless the server
+ * was started with `--show-pii`.
  *
- * Not implemented (deliberately): row editing, DDL, destructive operations.
- * Studio is for inspection. Use the CLI, migrate, or raw SQL for writes.
+ * Write model (opt-in): update/insert/delete a single row. DDL and multi-row or
+ * unconditional writes are deliberately unsupported. Use the CLI or migrate for
+ * schema changes and bulk operations.
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PII_REDACTED = void 0;
 exports.startStudio = startStudio;
+exports.handleRequest = handleRequest;
 exports.apiTableRows = apiTableRows;
 exports.resolveColumnName = resolveColumnName;
 exports.isTextishType = isTextishType;
 exports.escapeLikePattern = escapeLikePattern;
 exports.apiBuilder = apiBuilder;
+exports.apiRowWrite = apiRowWrite;
 exports.apiListSavedQueries = apiListSavedQueries;
 exports.apiCreateSavedQuery = apiCreateSavedQuery;
 exports.apiDeleteSavedQuery = apiDeleteSavedQuery;
@@ -88,7 +104,17 @@ async function startStudio(options) {
         params: ['30s'],
     };
     const rateLimiter = new Map();
-    const ctx = { pool, metadata, options, authToken, stateDir, statementTimeout, rateLimiter };
+    const ctx = {
+        pool,
+        metadata,
+        options,
+        authToken,
+        stateDir,
+        statementTimeout,
+        rateLimiter,
+        writable: options.write === true,
+        showPii: options.showPii === true,
+    };
     const server = (0, node_http_1.createServer)((req, res) => {
         handleRequest(req, res, ctx).catch((err) => {
             sendJson(res, 500, { error: err instanceof Error ? err.message : String(err) });
@@ -157,7 +183,7 @@ async function handleRequest(req, res, ctx) {
             res.end();
             return;
         }
-        sendHtml(res, 200, studio_ui_generated_js_1.STUDIO_HTML);
+        sendHtml(res, 200, studio_ui_generated_js_1.STUDIO_HTML, cspNonce());
         return;
     }
     // Favicon — answered before the auth gate so the browser's automatic request
@@ -200,6 +226,26 @@ async function handleRequest(req, res, ctx) {
         const id = decodeURIComponent(pathname.slice('/api/saved-queries/'.length));
         return apiDeleteSavedQuery(res, ctx, id);
     }
+    // Write routes: ONLY exist in write mode. In read-only mode they fall through
+    // to the 404 below (deliberately not 403: a read-only Studio has no such API).
+    if (ctx.writable && pathname.startsWith('/api/row/') && req.method === 'POST') {
+        // CSRF: a state-changing request MUST carry a same-origin Origin header. The
+        // top-of-handler check already rejects a MISMATCHED origin (403); this also
+        // rejects an ABSENT one, which read (GET) routes tolerate for curl ergonomics
+        // but a browser always sends on a cross-scheme/site POST. `fetch` from the
+        // Studio page always sets it for same-origin, so the real UI is unaffected.
+        if (origin !== expectedOrigin) {
+            sendJson(res, 403, { error: 'a matching Origin header is required for write requests' });
+            return;
+        }
+        const op = pathname.slice('/api/row/'.length);
+        if (op === 'update')
+            return apiRowWrite(req, res, ctx, 'update');
+        if (op === 'insert')
+            return apiRowWrite(req, res, ctx, 'insert');
+        if (op === 'delete')
+            return apiRowWrite(req, res, ctx, 'delete');
+    }
     sendJson(res, 404, { error: 'not found' });
 }
 // ---------------------------------------------------------------------------
@@ -269,6 +315,7 @@ async function apiSchema(res, ctx) {
             nullable: col.nullable,
             hasDefault: col.hasDefault,
             isPrimaryKey: tbl.primaryKey.includes(col.name),
+            pii: col.pii === true,
         })),
         relations: Object.entries(tbl.relations).map(([name, rel]) => ({
             name,
@@ -294,6 +341,10 @@ async function apiSchema(res, ctx) {
         schema: ctx.options.schema,
         tables: tables.map((t) => ({ ...t, estimatedRows: counts.get(t.name) ?? 0 })),
         enums: ctx.metadata.enums,
+        // Client-config flags the UI reads to gate write affordances / PII masking.
+        // Read-only Studio reports `writable: false` so the UI renders no write UI.
+        writable: ctx.writable === true,
+        showPii: ctx.showPii === true,
     });
 }
 // ---------------------------------------------------------------------------
@@ -311,10 +362,14 @@ async function apiTableRows(res, ctx, rawTableName, params) {
     const dir = params.get('dir')?.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
     // orderBy — accept either the Postgres column name (snake) or the TS field
     // name (camel). Always emit the Postgres column in the SQL.
+    // When redaction is on, PII columns are excluded from orderBy (and from the
+    // search OR-set below): a redacted value must not be inferable through sort
+    // position or substring probing.
+    const redactedPii = ctx.showPii ? NO_PII_KEYS : piiKeysForTable(table);
     let orderByClause = '';
     if (orderByRaw) {
         const col = resolveColumnName(table, orderByRaw);
-        if (col)
+        if (col && !redactedPii.has(col))
             orderByClause = `ORDER BY ${(0, index_js_1.quoteIdent)(col)} ${dir}`;
     }
     if (!orderByClause && table.primaryKey.length > 0 && table.primaryKey[0]) {
@@ -324,7 +379,9 @@ async function apiTableRows(res, ctx, rawTableName, params) {
     // parameterized so injection is impossible. Each query gets its own
     // WHERE clause with parameter indices matching that query's param array.
     const search = params.get('search')?.trim() ?? '';
-    const textColumns = table.columns.filter((c) => isTextishType(c.pgType)).map((c) => c.name);
+    const textColumns = table.columns
+        .filter((c) => isTextishType(c.pgType) && !redactedPii.has(c.name))
+        .map((c) => c.name);
     const hasSearch = search.length > 0 && textColumns.length > 0;
     const pattern = hasSearch ? `%${escapeLikePattern(search)}%` : null;
     // Main query: $1 = limit, $2 = offset, $3 = pattern (if search)
@@ -356,7 +413,7 @@ async function apiTableRows(res, ctx, rawTableName, params) {
         sendJson(res, 200, {
             table: table.name,
             columns: result.fields.map((f) => ({ name: f.name, dataTypeID: f.dataTypeID })),
-            rows: result.rows.map((r) => serializeRow(r)),
+            rows: result.rows.map((r) => serializeRow(redactFlatRow(r, redactedPii))),
             total: Number(countResult.rows[0]?.count ?? 0),
             limit,
             offset,
@@ -433,10 +490,12 @@ async function apiBuilder(req, res, ctx) {
         const result = await client.query(deferred.sql, deferred.params);
         const elapsedMs = Date.now() - started;
         await client.query('COMMIT');
+        const rawRows = result.rows;
+        const redactedRows = ctx.showPii ? rawRows : redactBuilderRows(rawRows, tableName, args.with, ctx.metadata);
         sendJson(res, 200, {
             sql: deferred.sql,
             columns: result.fields.map((f) => ({ name: f.name, dataTypeID: f.dataTypeID })),
-            rows: result.rows.map((r) => serializeRow(r)),
+            rows: redactedRows.map((r) => serializeRow(r)),
             rowCount: result.rowCount ?? result.rows.length,
             elapsedMs,
         });
@@ -454,6 +513,163 @@ async function apiBuilder(req, res, ctx) {
         client.release();
     }
 }
+// ---------------------------------------------------------------------------
+// API: /api/row/update | /api/row/insert | /api/row/delete (single-row writes)
+//
+// Write mode only (the routes do not exist otherwise). Every column identifier
+// is validated against the introspected metadata and the statement is compiled
+// through the query builders (`buildUpdate`/`buildCreate`/`buildDelete`) so all
+// values are $N params; there is no raw SQL. update/delete require the caller
+// to supply the FULL primary key in `where`; the effective predicate is rebuilt
+// from those PK values alone, so a write can only ever touch one row.
+// ---------------------------------------------------------------------------
+async function apiRowWrite(req, res, ctx, op) {
+    const body = await readJsonBody(req);
+    const tableName = typeof body?.table === 'string' ? body.table : '';
+    const table = ctx.metadata.tables[tableName];
+    if (!table) {
+        sendJson(res, 400, { error: unknownTableMessage(tableName, ctx) });
+        return;
+    }
+    if (table.isView) {
+        sendJson(res, 400, { error: `[turbine] "${tableName}" is a view; Studio cannot write to it.` });
+        return;
+    }
+    const data = (body?.data && typeof body.data === 'object' ? body.data : {});
+    const rawWhere = (body?.where && typeof body.where === 'object' ? body.where : {});
+    // Validate every column name up front for a clean typed 400 (the builders
+    // would also reject unknowns, but an explicit check keeps the message clear).
+    if (op === 'insert' || op === 'update') {
+        const badKey = firstUnknownColumn(table, data);
+        if (badKey) {
+            sendJson(res, 400, { error: `[turbine] unknown column "${badKey}" on table "${tableName}"` });
+            return;
+        }
+        if (!Object.keys(data).some((k) => data[k] !== undefined)) {
+            sendJson(res, 400, { error: '[turbine] `data` must include at least one column' });
+            return;
+        }
+    }
+    // update/delete: require the table to have a PK and the caller to cover it.
+    let effectiveWhere = rawWhere;
+    if (op === 'update' || op === 'delete') {
+        if (table.primaryKey.length === 0) {
+            sendJson(res, 400, {
+                error: `[turbine] "${tableName}" has no primary key; single-row writes require one.`,
+            });
+            return;
+        }
+        const pk = extractPkWhere(table, rawWhere);
+        if ('error' in pk) {
+            sendJson(res, 400, { error: `[turbine] ${pk.error}` });
+            return;
+        }
+        // Empty-where can never happen by construction (PK covered above); assert.
+        if (Object.keys(pk.where).length === 0) {
+            sendJson(res, 400, { error: '[turbine] refusing a write with an empty predicate' });
+            return;
+        }
+        effectiveWhere = pk.where;
+    }
+    let deferred;
+    try {
+        const qi = new index_js_1.QueryInterface(ctx.pool, tableName, ctx.metadata, [], {
+            warnOnUnlimited: false,
+            sqlCache: false,
+            preparedStatements: false,
+        });
+        if (op === 'insert') {
+            deferred = qi.buildCreate({ data });
+        }
+        else if (op === 'update') {
+            deferred = qi.buildUpdate({ where: effectiveWhere, data });
+        }
+        else {
+            deferred = qi.buildDelete({ where: effectiveWhere });
+        }
+    }
+    catch (err) {
+        sendJson(res, 400, { error: err instanceof Error ? err.message : String(err) });
+        return;
+    }
+    const client = await ctx.pool.connect();
+    try {
+        // A real write transaction, NOT `READ ONLY`. Same parameterized
+        // statement-timeout + search_path pin as the read paths.
+        await client.query('BEGIN');
+        await client.query(ctx.statementTimeout.sql, ctx.statementTimeout.params);
+        await client.query(`SELECT set_config('search_path', $1, true)`, [ctx.options.schema]);
+        const result = await client.query(deferred.sql, deferred.params);
+        await client.query('COMMIT');
+        const row = result.rows[0];
+        if (!row) {
+            const msg = op === 'insert' ? 'insert returned no row' : 'no row matched the primary key';
+            sendJson(res, 404, { error: `[turbine] ${msg}` });
+            return;
+        }
+        // The echoed row is redacted the same way as any read (unless --show-pii),
+        // even though a write to a pii column is allowed.
+        const piiKeys = ctx.showPii ? NO_PII_KEYS : piiKeysForTable(table);
+        sendJson(res, 200, {
+            operation: op,
+            row: serializeRow(redactFlatRow(row, piiKeys)),
+            rowCount: result.rowCount ?? 1,
+        });
+    }
+    catch (err) {
+        try {
+            await client.query('ROLLBACK');
+        }
+        catch {
+            /* ignore */
+        }
+        sendJson(res, 400, { error: err instanceof Error ? err.message : String(err) });
+    }
+    finally {
+        client.release();
+    }
+}
+/**
+ * Return the first key in `obj` that does not resolve to a real column on
+ * `table` (accepting either the camelCase field or snake_case column name), or
+ * `null` when every key is valid. Skips `undefined` values.
+ */
+function firstUnknownColumn(table, obj) {
+    for (const k of Object.keys(obj)) {
+        if (obj[k] === undefined)
+            continue;
+        if (!resolveColumnName(table, k))
+            return k;
+    }
+    return null;
+}
+/**
+ * Build a primary-key-only `where` from the caller's `where`. Every PK column
+ * must be present (as its field or column name) with a scalar value; anything
+ * else is rejected so a write can only ever target one row. Keys are emitted as
+ * the camelCase field name (the query builder accepts field or column names).
+ */
+function extractPkWhere(table, where) {
+    const resolved = new Map();
+    for (const [k, v] of Object.entries(where)) {
+        const col = resolveColumnName(table, k);
+        if (col)
+            resolved.set(col, v);
+    }
+    const pkWhere = {};
+    for (const pkCol of table.primaryKey) {
+        if (!resolved.has(pkCol)) {
+            return { error: `\`where\` must fully cover the primary key (missing "${pkCol}")` };
+        }
+        const v = resolved.get(pkCol);
+        if (v === undefined || v === null || typeof v === 'object') {
+            return { error: `primary key "${pkCol}" must be a scalar value in \`where\`` };
+        }
+        const field = table.reverseColumnMap[pkCol] ?? pkCol;
+        pkWhere[field] = v;
+    }
+    return { where: pkWhere };
+}
 function savedQueriesPath(ctx) {
     return (0, node_path_1.resolve)(ctx.stateDir, 'studio-queries.json');
 }
@@ -541,6 +757,94 @@ function apiDeleteSavedQuery(res, ctx, id) {
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// PII redaction
+// ---------------------------------------------------------------------------
+/** The literal replacement value for a redacted PII cell. */
+exports.PII_REDACTED = '•• redacted ••';
+/** Shared empty key set for the `--show-pii` fast path (no redaction). */
+const NO_PII_KEYS = new Set();
+/**
+ * The set of keys (both snake_case column and camelCase field names) for the
+ * table's PII-tagged columns. Covering both spellings means the same set works
+ * for `SELECT *` rows (snake keys) and for json_build_object relation rows
+ * (camel keys).
+ */
+function piiKeysForTable(table) {
+    const keys = new Set();
+    for (const col of table.columns) {
+        if (col.pii === true) {
+            keys.add(col.name);
+            keys.add(col.field);
+        }
+    }
+    return keys;
+}
+/**
+ * Redact PII keys in a single flat row. Returns the row unchanged when there is
+ * nothing to redact (no allocation); otherwise a shallow copy with each present,
+ * non-null PII value replaced by {@link PII_REDACTED}. A null/undefined value
+ * carries no PII, so it is left as-is.
+ */
+function redactFlatRow(row, piiKeys) {
+    if (piiKeys.size === 0)
+        return row;
+    let out = null;
+    for (const k of Object.keys(row)) {
+        if (piiKeys.has(k) && row[k] !== null && row[k] !== undefined) {
+            if (!out)
+                out = { ...row };
+            out[k] = exports.PII_REDACTED;
+        }
+    }
+    return out ?? row;
+}
+/**
+ * Redact PII in builder result rows, walking the `with` tree so nested relation
+ * rows are redacted against THEIR target table's PII columns (relation rows
+ * arrive as parsed json objects keyed by camelCase field names).
+ */
+function redactBuilderRows(rows, tableName, withClause, metadata) {
+    const table = metadata.tables[tableName];
+    if (!table)
+        return rows;
+    const piiKeys = piiKeysForTable(table);
+    const relEntries = withClause && typeof withClause === 'object'
+        ? Object.entries(withClause).filter(([, v]) => v)
+        : [];
+    // Nothing to do at this level or below → return as-is.
+    if (piiKeys.size === 0 && relEntries.length === 0)
+        return rows;
+    return rows.map((row) => {
+        const out = { ...row };
+        for (const k of piiKeys) {
+            if (k in out && out[k] !== null && out[k] !== undefined)
+                out[k] = exports.PII_REDACTED;
+        }
+        for (const [relName, relVal] of relEntries) {
+            const rel = table.relations[relName];
+            if (!rel)
+                continue;
+            const nestedWith = relVal && typeof relVal === 'object' ? relVal.with : undefined;
+            const child = out[relName];
+            if (Array.isArray(child)) {
+                out[relName] = redactBuilderRows(child, rel.to, nestedWith, metadata);
+            }
+            else if (child && typeof child === 'object') {
+                out[relName] = redactBuilderRows([child], rel.to, nestedWith, metadata)[0];
+            }
+        }
+        return out;
+    });
+}
+/**
+ * A fresh CSP nonce for one HTML response. Base64 of 16 random bytes; the value
+ * is stamped into both the `Content-Security-Policy` header and the inline
+ * `<script nonce="...">` tag(s) so `unsafe-inline` can be dropped from script-src.
+ */
+function cspNonce() {
+    return (0, node_crypto_1.randomBytes)(16).toString('base64');
+}
 function clampInt(value, fallback, min, max) {
     if (value == null)
         return fallback;
@@ -596,7 +900,9 @@ function sendJson(res, status, body) {
         'Cache-Control': 'no-store',
         'X-Content-Type-Options': 'nosniff',
         'Referrer-Policy': 'no-referrer',
-        'Content-Security-Policy': "default-src 'none'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self'; font-src 'self'; frame-ancestors 'none'",
+        // JSON responses render no document; no inline script is needed, so keep
+        // script-src to 'self' with no 'unsafe-inline'.
+        'Content-Security-Policy': "default-src 'none'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self'; font-src 'self'; frame-ancestors 'none'",
     });
     res.end(payload);
 }
@@ -607,7 +913,10 @@ function sendText(res, status, body) {
     });
     res.end(body);
 }
-function sendHtml(res, status, body) {
+function sendHtml(res, status, template, nonce) {
+    // Stamp the per-request nonce into the inline <script nonce="__CSP_NONCE__">
+    // tag(s) so the CSP can use a nonce instead of 'unsafe-inline'.
+    const body = template.replaceAll('__CSP_NONCE__', nonce);
     res.writeHead(status, {
         'Content-Type': 'text/html; charset=utf-8',
         'Content-Length': Buffer.byteLength(body),
@@ -615,7 +924,9 @@ function sendHtml(res, status, body) {
         'X-Content-Type-Options': 'nosniff',
         'X-Frame-Options': 'DENY',
         'Referrer-Policy': 'no-referrer',
-        'Content-Security-Policy': "default-src 'none'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self'; font-src 'self'; frame-ancestors 'none'",
+        // style-src keeps 'unsafe-inline' (nonces don't cover style="" attributes,
+        // which the UI relies on); script-src moves to the per-request nonce.
+        'Content-Security-Policy': `default-src 'none'; script-src 'self' 'nonce-${nonce}'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self'; font-src 'self'; frame-ancestors 'none'`,
     });
     res.end(body);
 }

package/dist/cjs/cli/ui.js

@@ -229,5 +229,11 @@ function stripAnsi(s) {
 // Redact password from connection URL
 // ---------------------------------------------------------------------------
 function redactUrl(url) {
-    return url.replace(/:([^@/:]+)@/, ':***@');
+    return (url
+        // Userinfo credentials: `:secret@` in any authority (global: a string may
+        // carry more than one URL, e.g. a primary + replica connection pair).
+        .replace(/:([^@/:]+)@/g, ':***@')
+        // Query-string password params: `password=`, `sslpassword=`, and similar,
+        // case-insensitive. Value runs up to the next `&`, `#`, or end of string.
+        .replace(/([?&][^=&#]*password)=([^&#]*)/gi, '$1=***'));
 }

package/dist/cjs/client.js

@@ -111,15 +111,27 @@ class TransactionClient {
     schema;
     middlewares;
     queryOptions;
+    sourcePool;
     tableCache = new Map();
     savepointCounter = 0;
     /** Active SQL dialect — owns savepoint keywords and raw-SQL placeholders. */
     dialect;
-    constructor(client, schema, middlewares, queryOptions) {
+    constructor(client, schema, middlewares, queryOptions, 
+    /**
+     * The parent pool this transaction runs on. Only its `readonly` and
+     * `capabilities` are read (both PowDB-only flags), so the transaction-scoped
+     * proxy pool built by {@link createTxPool} carries them through: without this
+     * a read-only client's `$transaction` writes bypass the E018 guard, and an
+     * older-engine client falls back to ALL_POWDB_CAPABILITIES inside the tx
+     * (emitting join PowQL a pre-0.13 engine rejects). Undefined / absent flags
+     * for a plain pg pool leave the proxy unchanged.
+     */
+    sourcePool) {
         this.client = client;
         this.schema = schema;
         this.middlewares = middlewares;
         this.queryOptions = queryOptions;
+        this.sourcePool = sourcePool;
         this.dialect = queryOptions?.dialect ?? dialect_js_1.postgresDialect;
         // Auto-create typed table accessors for all tables in the schema
         for (const tableName of Object.keys(schema.tables)) {
@@ -199,7 +211,7 @@ class TransactionClient {
         const client = this.client;
         // Return a minimal pool-compatible object that routes queries
         // through the transaction client
-        return {
+        const txPool = {
             query: async (textOrConfig, values) => {
                 try {
                     if (typeof textOrConfig === 'string') {
@@ -216,6 +228,14 @@ class TransactionClient {
             },
             connect: () => Promise.resolve(client),
         };
+        // Carry the parent pool's PowDB-only flags through so a transaction-scoped
+        // PowqlInterface reads the same read-only guard and capabilities it would
+        // outside the transaction (a plain pg pool has neither, so nothing changes).
+        if (this.sourcePool?.readonly !== undefined)
+            txPool.readonly = this.sourcePool.readonly;
+        if (this.sourcePool?.capabilities !== undefined)
+            txPool.capabilities = this.sourcePool.capabilities;
+        return txPool;
     }
 }
 exports.TransactionClient = TransactionClient;
@@ -884,8 +904,10 @@ class TurbineClient {
                     await client.query(cfg.sql, cfg.params);
                 }
             }
-            // Create the transaction client with typed table accessors
-            const tx = new TransactionClient(client, this.schema, this.middlewares, this.queryOptions);
+            // Create the transaction client with typed table accessors. Pass the
+            // parent pool so its read-only guard + PowDB capabilities flow into the
+            // transaction-scoped proxy pool (see TransactionClient.createTxPool).
+            const tx = new TransactionClient(client, this.schema, this.middlewares, this.queryOptions, this.pool);
             // Dynamically attach table accessors to tx
             for (const tableName of Object.keys(this.schema.tables)) {
                 const camelName = tableName.replace(/_([a-z])/g, (_, c) => c.toUpperCase());

package/dist/cjs/dialect.js

@@ -59,6 +59,7 @@ exports.postgresDialect = {
     supportsRLS: true,
     supportsAdvisoryLock: true,
     supportsLateralJoin: true,
+    explainQuery: { prefix: 'EXPLAIN' },
     paramPlaceholder(index) {
         return `$${index}`;
     },
@@ -104,7 +105,7 @@ exports.postgresDialect = {
         return `COALESCE((${subquery}), ${fallback})`;
     },
     buildReturningClause(selection = '*') {
-        return ` RETURNING ${selection}`;
+        return ` RETURNING ${selection === '*' ? '*' : selection.join(', ')}`;
     },
     buildInsertStatement(input) {
         return `INSERT INTO ${input.table} (${input.columns.join(', ')}) VALUES (${input.valuePlaceholders.join(', ')})${this.buildReturningClause(input.returning)}`;

package/dist/cjs/errors.js

@@ -6,7 +6,7 @@
  * All Turbine errors extend TurbineError which includes a `code` property.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UnsupportedFeatureError = exports.OptimisticLockError = exports.PipelineError = exports.ExclusionConstraintError = exports.CheckConstraintError = exports.SerializationFailureError = exports.DeadlockError = exports.NotNullViolationError = exports.ForeignKeyError = exports.UniqueConstraintError = exports.CircularRelationError = exports.MigrationError = exports.RelationError = exports.ConnectionError = exports.ValidationError = exports.TimeoutError = exports.NotFoundError = exports.TurbineError = exports.TurbineErrorCode = void 0;
+exports.ReadOnlyError = exports.UnsupportedFeatureError = exports.OptimisticLockError = exports.PipelineError = exports.ExclusionConstraintError = exports.CheckConstraintError = exports.SerializationFailureError = exports.DeadlockError = exports.NotNullViolationError = exports.ForeignKeyError = exports.UniqueConstraintError = exports.CircularRelationError = exports.MigrationError = exports.RelationError = exports.ConnectionError = exports.ValidationError = exports.TimeoutError = exports.NotFoundError = exports.TurbineError = exports.TurbineErrorCode = void 0;
 exports.setErrorMessageMode = setErrorMessageMode;
 exports.getErrorMessageMode = getErrorMessageMode;
 exports.wrapPgError = wrapPgError;
@@ -29,6 +29,7 @@ exports.TurbineErrorCode = {
     OPTIMISTIC_LOCK: 'TURBINE_E015',
     EXCLUSION_VIOLATION: 'TURBINE_E016',
     UNSUPPORTED_FEATURE: 'TURBINE_E017',
+    READ_ONLY: 'TURBINE_E018',
 };
 /**
  * Prefix a human message with its stable error code so logs are greppable
@@ -503,6 +504,45 @@ class UnsupportedFeatureError extends TurbineError {
     }
 }
 exports.UnsupportedFeatureError = UnsupportedFeatureError;
+/**
+ * Thrown when a write or DDL statement is refused because the target is
+ * read-only. Two shapes reach here, both on PowDB:
+ *   - an embedded database opened read-only for snapshot serving refuses a write
+ *     with `readonly mode: statement requires a writer …`;
+ *   - a networked read-only role refuses a write with `permission denied: role
+ *     '<role>' cannot execute write statements` (translated by `wrapPowdbError`).
+ * It is also raised locally, before the wire, when a write is issued on a pool
+ * the caller marked read-only (fail-fast). The message carries the engine text
+ * plus a hint to route writes to a writable primary.
+ *
+ * NOT retryable: the same write against the same read-only target fails
+ * identically; route it to a writable primary instead.
+ */
+class ReadOnlyError extends TurbineError {
+    /**
+     * Why the write was refused. `'snapshot'`: the database itself is read-only
+     * (snapshot serving, an embedded `readonly: true` open, or the client-level
+     * fail-fast flag), so NOTHING can write here and writes must route to the
+     * primary. `'rbac'`: the database is writable but THIS connection's role may
+     * not write (per-connection permission), so re-authenticating may suffice.
+     */
+    reason;
+    /**
+     * @param detail human-readable description of the refused write (the engine
+     *   message, or a local fail-fast description). A "route writes to a writable
+     *   primary" hint is always appended.
+     * @param options optional driver `cause` to preserve when wrapping a refusal,
+     *   and the refusal `reason` (default `'snapshot'`).
+     */
+    constructor(detail, options) {
+        super(exports.TurbineErrorCode.READ_ONLY, `[turbine] ${detail} Route writes to a writable primary.`, {
+            cause: options?.cause,
+        });
+        this.name = 'ReadOnlyError';
+        this.reason = options?.reason ?? 'snapshot';
+    }
+}
+exports.ReadOnlyError = ReadOnlyError;
 /**
  * Parse column names out of a pg `detail` string like:
  *   "Key (email)=(foo@bar) already exists."