turbine-orm 0.81.0-next.d9b06dd → 0.90.0

package/dist/cjs/cli/config.d.ts

@@ -24,12 +24,22 @@ export interface TurbineCliConfig {
      * to hand-edit every call site. A typo here is an error, not a silent no-op.
      */
     relationNames?: Record<string, Record<string, string>>;
+    /**
+     * TypeScript type overrides for generated row and input types, as
+     * `{ '<table>.<column>': '<type>' }` with database names. The main use is a
+     * `json` / `jsonb` column, which otherwise generates as `unknown`:
+     * `{ 'users.settings': '{ theme: string; beta?: boolean }' }`. The type text
+     * is emitted verbatim. A key naming no table or column is an error, not a
+     * silent no-op. A code-first column's `tsType` feeds the same map.
+     */
+    columnTypes?: Record<string, string>;
     /**
      * Extension for the generated `index.ts` sibling imports (F3):
-     * `'js'` (`./types.js`), `'none'` (`./types`), or `'auto'` (default:
-     * tsconfig-detected, falling back to `'js'`).
+     * `'js'` (`./types.js`), `'ts'` (`./types.ts`, for Node's native type
+     * stripping), `'none'` (`./types`), or `'auto'` (default: tsconfig-detected,
+     * falling back to `'js'`; never picks `'ts'`).
      */
-    importExtension?: 'js' | 'none' | 'auto';
+    importExtension?: 'js' | 'ts' | 'none' | 'auto';
     /**
      * Keep raw database column names as generated field names (snake_case)
      * instead of camelCase (F4). Opt-in; default `false`.
@@ -54,7 +64,11 @@ export interface TurbineCliConfig {
      * are set.
      */
     seed?: string;
-    /** Schema builder file path (for push command) */
+    /**
+     * The `defineSchema()` file (default `./turbine/schema.ts`): what `push` applies,
+     * and where `generate` reads the `pii` / `updatedAt` / `maxLength` tags the
+     * database cannot store.
+     */
     schemaFile?: string;
     /**
      * Database adapter for PostgreSQL-compatible databases that need
@@ -159,14 +173,22 @@ export interface ResolvedConfig {
     migrationsDir: string;
     seedFile?: string;
     schemaFile: string;
+    /**
+     * True when `--schema-file` or the config `schemaFile` key named the file, as
+     * opposed to the `./turbine/schema.ts` default. A named file that is missing is
+     * an error; a missing default just means a database-first project.
+     */
+    schemaFileConfigured?: boolean;
     /** Resolved generator import-extension mode (F3). */
-    importExtension: 'js' | 'none' | 'auto';
+    importExtension: 'js' | 'ts' | 'none' | 'auto';
     /** Resolved keep-column-names generator flag (F4). */
     keepColumnNames: boolean;
     /** Resolved opt-out of the unique-FK → hasOne introspection flip (F2). */
     legacyToManyUniques: boolean;
     /** Resolved derived-relation rename map, or undefined when none is declared. */
     relationNames?: Record<string, Record<string, string>>;
+    /** Column type overrides for the generator, or undefined when none is declared. */
+    columnTypes?: Record<string, string>;
 }
 export interface CliOverrides {
     url?: string;
@@ -176,10 +198,17 @@ export interface CliOverrides {
     schemaFile?: string;
     include?: string[];
     exclude?: string[];
-    importExtension?: 'js' | 'none' | 'auto';
+    importExtension?: 'js' | 'ts' | 'none' | 'auto';
     keepColumnNames?: boolean;
     legacyToManyUniques?: boolean;
 }
+/**
+ * The first candidate that is a non-blank string. An empty or whitespace-only
+ * value counts as unset, because an exported-but-empty variable (`DATABASE_URL=`
+ * in a shell profile or a `.env` template) is how "not configured" is usually
+ * spelled, and `??` would let it beat a real value further down the chain.
+ */
+export declare function firstNonEmpty(...candidates: Array<string | undefined>): string | undefined;
 /**
  * Merge config file values with CLI overrides and env vars.
  * Priority: CLI flags > env vars > config file > defaults.

package/dist/cjs/cli/config.js

@@ -46,6 +46,7 @@ exports.unwrapConfigModule = unwrapConfigModule;
 exports.loadConfigResult = loadConfigResult;
 exports.loadConfig = loadConfig;
 exports.findConfigFile = findConfigFile;
+exports.firstNonEmpty = firstNonEmpty;
 exports.resolveConfig = resolveConfig;
 exports.resolveSeedFile = resolveSeedFile;
 exports.connectionStringHasPassword = connectionStringHasPassword;
@@ -195,23 +196,38 @@ function findConfigFile(cwd) {
     }
     return null;
 }
+/**
+ * The first candidate that is a non-blank string. An empty or whitespace-only
+ * value counts as unset, because an exported-but-empty variable (`DATABASE_URL=`
+ * in a shell profile or a `.env` template) is how "not configured" is usually
+ * spelled, and `??` would let it beat a real value further down the chain.
+ */
+function firstNonEmpty(...candidates) {
+    for (const value of candidates) {
+        if (typeof value === 'string' && value.trim() !== '')
+            return value;
+    }
+    return undefined;
+}
 /**
  * Merge config file values with CLI overrides and env vars.
  * Priority: CLI flags > env vars > config file > defaults.
  */
 function resolveConfig(fileConfig, overrides) {
     return {
-        url: overrides.url ?? process.env.DATABASE_URL ?? fileConfig.url ?? '',
+        url: firstNonEmpty(overrides.url, process.env.DATABASE_URL, fileConfig.url) ?? '',
         out: overrides.out ?? fileConfig.out ?? './generated/turbine',
         schema: overrides.schema ?? fileConfig.schema ?? 'public',
         include: overrides.include ?? fileConfig.include ?? [],
         relationNames: fileConfig.relationNames,
+        columnTypes: fileConfig.columnTypes,
         exclude: overrides.exclude ?? fileConfig.exclude ?? [],
         migrationsDir: fileConfig.migrationsDir ?? './turbine/migrations',
         // `seedFile` is canonical (what the docs and `turbine init` use); `seed` is a
         // back-compat alias kept working for configs scaffolded before 0.50.
         seedFile: fileConfig.seedFile ?? fileConfig.seed,
         schemaFile: overrides.schemaFile ?? fileConfig.schemaFile ?? './turbine/schema.ts',
+        schemaFileConfigured: (overrides.schemaFile ?? fileConfig.schemaFile) !== undefined,
         importExtension: overrides.importExtension ?? fileConfig.importExtension ?? 'auto',
         keepColumnNames: overrides.keepColumnNames ?? fileConfig.keepColumnNames ?? false,
         legacyToManyUniques: overrides.legacyToManyUniques ?? fileConfig.legacyToManyUniques ?? false,

package/dist/cjs/cli/destructive.d.ts

@@ -19,16 +19,19 @@
  * the optional-`COLUMN` shorthand (`ALTER TABLE t DROP email`), data-modifying
  * CTEs (`WITH d AS (DELETE ...) SELECT ...`), `MERGE ... THEN DELETE`, dynamic
  * SQL inside a `DO`/function body, an `UPDATE` whose only WHERE sits inside a
- * subquery (which restricts nothing), a `DROP ... CASCADE` of a non-table
- * object (which takes dependent COLUMNS with it), a detached partition, and an
- * `EXPLAIN ANALYZE` of any of the above (which really executes it).
+ * subquery (which restricts nothing) or is a constant-true predicate (`WHERE
+ * true`, `WHERE 1 = 1`), a `DROP ... CASCADE` of a non-table object (which takes
+ * dependent COLUMNS with it), a detached partition, an `ON CONFLICT DO UPDATE`
+ * with no `WHERE` (it rewrites every conflicting row), a `PREPARE`d destructive
+ * statement, `lo_unlink` (it deletes large objects), and an `EXPLAIN ANALYZE` of
+ * any of the above (which really executes it).
  *
  * The lexing, "where does a statement end" and "which characters are code",
  * is NOT done here: it lives in `sql-statements.ts` and is shared with the
  * migration runner. Two lexers is how this guard came to disagree with the
  * executor about what a file contained (see that module's header).
  */
-export type DestructiveKind = 'drop-table' | 'drop-schema' | 'drop-database' | 'drop-owned' | 'drop-matview' | 'drop-column' | 'drop-cascade' | 'detach-partition' | 'truncate' | 'delete' | 'update-without-where' | 'alter-column-type' | 'merge-delete' | 'rename' | 'rewrite-rule' | 'dynamic-destructive' | 'dynamic-unclassified';
+export type DestructiveKind = 'drop-table' | 'drop-schema' | 'drop-database' | 'drop-owned' | 'drop-matview' | 'drop-column' | 'drop-cascade' | 'detach-partition' | 'truncate' | 'delete' | 'update-without-where' | 'overwrite-on-conflict' | 'large-object-unlink' | 'alter-column-type' | 'merge-delete' | 'rename' | 'rewrite-rule' | 'dynamic-destructive' | 'dynamic-unclassified';
 export interface DestructiveStatement {
     /** The offending SQL statement (trimmed, possibly long, display truncated) */
     statement: string;

package/dist/cjs/cli/destructive.js

@@ -20,9 +20,12 @@
  * the optional-`COLUMN` shorthand (`ALTER TABLE t DROP email`), data-modifying
  * CTEs (`WITH d AS (DELETE ...) SELECT ...`), `MERGE ... THEN DELETE`, dynamic
  * SQL inside a `DO`/function body, an `UPDATE` whose only WHERE sits inside a
- * subquery (which restricts nothing), a `DROP ... CASCADE` of a non-table
- * object (which takes dependent COLUMNS with it), a detached partition, and an
- * `EXPLAIN ANALYZE` of any of the above (which really executes it).
+ * subquery (which restricts nothing) or is a constant-true predicate (`WHERE
+ * true`, `WHERE 1 = 1`), a `DROP ... CASCADE` of a non-table object (which takes
+ * dependent COLUMNS with it), a detached partition, an `ON CONFLICT DO UPDATE`
+ * with no `WHERE` (it rewrites every conflicting row), a `PREPARE`d destructive
+ * statement, `lo_unlink` (it deletes large objects), and an `EXPLAIN ANALYZE` of
+ * any of the above (which really executes it).
  *
  * The lexing, "where does a statement end" and "which characters are code",
  * is NOT done here: it lives in `sql-statements.ts` and is shared with the
@@ -45,7 +48,9 @@ exports.DESTRUCTIVE_KIND_LABEL = {
     'detach-partition': 'detaches a partition, every row in it leaves the table',
     truncate: 'deletes every row',
     delete: 'deletes rows',
-    'update-without-where': 'rewrites every row (no WHERE clause)',
+    'update-without-where': 'rewrites every row (no WHERE clause, or one that is always true)',
+    'overwrite-on-conflict': 'overwrites every conflicting row (ON CONFLICT DO UPDATE with no restricting WHERE)',
+    'large-object-unlink': 'permanently deletes large objects (lo_unlink)',
     'alter-column-type': 'rewrites a column type (cast may truncate or fail)',
     'merge-delete': 'deletes matched rows (MERGE ... THEN DELETE)',
     rename: 'renames a table or column, every query and view referencing the old name breaks',
@@ -56,6 +61,12 @@ exports.DESTRUCTIVE_KIND_LABEL = {
 /** Unquote a "quoted" identifier for display. */
 const ident = (raw) => (raw ?? '?').replace(/^"|"$/g, '');
 const IDENT = String.raw `("[^"]+"|[a-zA-Z_][\w$]*)(\.("[^"]+"|[a-zA-Z_][\w$]*))?`;
+/**
+ * Ends an `IDENT` match. Not `\b`: after a closing `"` the next character is
+ * not a word character either, so `\b` fails and `UPDATE "users" SET ...` was
+ * never matched.
+ */
+const NOT_IDENT_CHAR = String.raw `(?![\w$])`;
 /**
  * Render one `IDENT` capture triple (name, `.qualifier`, qualifier) as text,
  * where `base` is the 1-based index of the triple's first group.
@@ -106,10 +117,11 @@ const RULES = [
         // CASCADE these are safe: Postgres refuses the drop while a dependency
         // exists. With it, the dependents go too, and a dependent of a TYPE or a
         // DOMAIN is typically a COLUMN, so `DROP TYPE order_status CASCADE`
-        // silently removes `orders.status` and every value in it. The presence of
-        // CASCADE is therefore the whole rule, not an extra detail.
+        // silently removes `orders.status` and every value in it, and a dependent of
+        // a VIEW can be a materialized view, whose stored rows go with it. The
+        // presence of CASCADE is therefore the whole rule, not an extra detail.
         kind: 'drop-cascade',
-        regex: new RegExp(String.raw `^DROP\s+(TYPE|DOMAIN|EXTENSION|SEQUENCE|FUNCTION|PROCEDURE|ROUTINE|AGGREGATE)\s+(IF\s+EXISTS\s+)?${IDENT}${OUTSIDE_QUOTES}\bCASCADE\b`, 'i'),
+        regex: new RegExp(String.raw `^DROP\s+(TYPE|DOMAIN|EXTENSION|SEQUENCE|FUNCTION|PROCEDURE|ROUTINE|AGGREGATE|VIEW)\s+(IF\s+EXISTS\s+)?${IDENT}${OUTSIDE_QUOTES}\bCASCADE\b`, 'i'),
         target: (m) => `${m[1].toUpperCase()} ${qualified(m, 3)}`,
     },
     {
@@ -145,16 +157,43 @@ const RULES = [
     {
         // MERGE's DELETE action removes rows from the target table.
         kind: 'merge-delete',
-        regex: new RegExp(String.raw `^MERGE\s+INTO\s+(ONLY\s+)?${IDENT}\b${OUTSIDE_QUOTES}\bTHEN\s+DELETE\b`, 'i'),
+        regex: new RegExp(String.raw `^MERGE\s+INTO\s+(ONLY\s+)?${IDENT}${NOT_IDENT_CHAR}${OUTSIDE_QUOTES}\bTHEN\s+DELETE\b`, 'i'),
         target: (m) => (m[4] ? `${ident(m[2])}.${ident(m[4])}` : ident(m[2])),
     },
     {
         // A WHERE inside a scalar subquery (`SET x = (SELECT ... WHERE ...)`) does
-        // NOT restrict the rows updated, so the guard tests only the TOP level.
+        // NOT restrict the rows updated, so the guard tests only the TOP level, and
+        // a top-level WHERE that is always true restricts nothing either.
         kind: 'update-without-where',
-        regex: new RegExp(String.raw `^UPDATE\s+(ONLY\s+)?${IDENT}\b`, 'i'),
+        regex: new RegExp(String.raw `^UPDATE\s+(ONLY\s+)?${IDENT}${NOT_IDENT_CHAR}`, 'i'),
         target: (m) => (m[4] ? `${ident(m[2])}.${ident(m[4])}` : ident(m[2])),
-        also: (stmt) => !hasTopLevelWhere(stmt),
+        also: (stmt) => !hasRestrictingWhere(stmt),
+    },
+    {
+        // `INSERT ... ON CONFLICT ... DO UPDATE SET ...` rewrites every row the
+        // insert conflicts with. The WHERE that narrows it sits AFTER `DO UPDATE`;
+        // the one before it is the conflict target's index predicate and restricts
+        // nothing. Add `WHERE t.col IS DISTINCT FROM EXCLUDED.col` to say which rows
+        // may change.
+        kind: 'overwrite-on-conflict',
+        regex: new RegExp(String.raw `^INSERT\s+INTO\s+${IDENT}${NOT_IDENT_CHAR}`, 'i'),
+        target: (m) => (m[3] ? `${ident(m[1])}.${ident(m[3])}` : ident(m[1])),
+        also: (stmt) => {
+            const code = stmt.replace(/"(?:[^"]|"")*"/g, '""');
+            if (!/\bON\s+CONFLICT\b/i.test(code))
+                return false;
+            const at = code.search(/\bDO\s+UPDATE\b/i);
+            return at !== -1 && !hasRestrictingWhere(code.slice(at));
+        },
+    },
+    {
+        // `SELECT lo_unlink(oid) FROM pg_largeobject_metadata` deletes the large
+        // objects whatever they hold, and there is no WHERE to look for. Statements
+        // that only NAME the function (GRANT, COMMENT, ALTER, DROP) call nothing.
+        kind: 'large-object-unlink',
+        regex: /\blo_unlink\s*\(/i,
+        target: () => 'large objects',
+        also: (stmt) => !/^(?:GRANT|REVOKE|COMMENT|ALTER|DROP)\b/i.test(stmt),
     },
     {
         // `CREATE RULE r AS ON INSERT TO t DO INSTEAD DELETE FROM u`. The rule
@@ -173,7 +212,7 @@ const RULES = [
         // that appears in ordinary migrations. DELETE, TRUNCATE and DROP stay
         // unconditional: a DELETE inside a rule destroys on every matching
         // statement whether or not it is narrowed, and the other two take no WHERE.
-        also: (stmt) => !/\bDO\s+(?:ALSO\s+|INSTEAD\s+)?\(?\s*UPDATE\b/i.test(stmt) || !hasTopLevelWhere(stmt),
+        also: (stmt) => !/\bDO\s+(?:ALSO\s+|INSTEAD\s+)?\(?\s*UPDATE\b/i.test(stmt) || !hasRestrictingWhere(stmt),
     },
     // Renames come LAST: they destroy no data, so any statement that is BOTH a
     // rename and a data-loss operation should report the data loss instead.
@@ -195,21 +234,165 @@ const RULES = [
         target: (m) => `${qualified(m, 3)}.${qualified(m, 7)}`,
     },
 ];
-/** True when the statement has a `WHERE` outside every parenthesized group. */
-function hasTopLevelWhere(stmt) {
-    const re = /[()]|\bWHERE\b/gi;
+/**
+ * The predicate of the statement's top-level `WHERE` (outside every
+ * parenthesized group), up to a top-level `RETURNING` or the end, or `null` when
+ * there is none.
+ */
+function topLevelWherePredicate(stmt) {
+    // A quoted identifier is consumed whole, so a column named "where" is not one.
+    const re = /"(?:[^"]|"")*"|[()]|\bWHERE\b|\bRETURNING\b/gi;
     let depth = 0;
+    let from = -1;
     let m = re.exec(stmt);
     while (m !== null) {
-        if (m[0] === '(')
+        if (m[0].startsWith('"')) {
+            // not a keyword
+        }
+        else if (m[0] === '(')
             depth++;
         else if (m[0] === ')')
             depth = Math.max(0, depth - 1);
-        else if (depth === 0)
-            return true;
+        else if (depth === 0) {
+            if (from === -1 && /^WHERE$/i.test(m[0]))
+                from = m.index + m[0].length;
+            else if (from !== -1 && /^RETURNING$/i.test(m[0]))
+                return stmt.slice(from, m.index).trim();
+        }
         m = re.exec(stmt);
     }
-    return false;
+    return from === -1 ? null : stmt.slice(from).trim();
+}
+/**
+ * True when the statement has a top-level `WHERE` that can leave some rows out.
+ * A predicate proven always true (`true`, `1 = 1`, `x OR true`) restricts nothing
+ * and counts as no WHERE. A predicate this cannot read is assumed to restrict,
+ * and that statement is then NOT flagged, so only a proof of constant-true may
+ * turn a WHERE into none.
+ */
+function hasRestrictingWhere(stmt) {
+    const predicate = topLevelWherePredicate(stmt);
+    return predicate !== null && constantValue(predicate) !== true;
+}
+/**
+ * Split on a top-level (paren depth 0, outside `CASE ... END`) `AND` or `OR`.
+ * The `AND` of a `BETWEEN a AND b` belongs to the BETWEEN and splits nothing.
+ */
+function splitTopLevel(text, keyword) {
+    const re = /"(?:[^"]|"")*"|[()]|\b(?:AND|OR|BETWEEN|CASE|END)\b/gi;
+    const parts = [];
+    let depth = 0;
+    let caseDepth = 0;
+    let betweenOpen = 0;
+    let last = 0;
+    let m = re.exec(text);
+    while (m !== null) {
+        const token = m[0].toUpperCase();
+        if (token.startsWith('"')) {
+            // a quoted identifier, never a keyword
+        }
+        else if (token === '(')
+            depth++;
+        else if (token === ')')
+            depth = Math.max(0, depth - 1);
+        else if (depth === 0) {
+            if (token === 'CASE')
+                caseDepth++;
+            else if (token === 'END')
+                caseDepth = Math.max(0, caseDepth - 1);
+            else if (caseDepth === 0) {
+                if (token === 'BETWEEN')
+                    betweenOpen++;
+                else if (token === 'AND' && betweenOpen > 0)
+                    betweenOpen--;
+                else if (token === keyword) {
+                    parts.push(text.slice(last, m.index));
+                    last = m.index + m[0].length;
+                }
+            }
+        }
+        m = re.exec(text);
+    }
+    parts.push(text.slice(last));
+    return parts.map((part) => part.trim());
+}
+/** Strip parentheses that wrap the WHOLE text: `((a = 1))` becomes `a = 1`. */
+function unwrapParens(text) {
+    let out = text.trim();
+    while (out.startsWith('(') && closingParenIndex(out, 0) === out.length - 1)
+        out = out.slice(1, -1).trim();
+    return out;
+}
+const NUMBER_LITERAL = String.raw `[+-]?\d+(?:\.\d+)?`;
+const COMPARISON = new RegExp(String.raw `^(${NUMBER_LITERAL}|'')\s*(=|<>|!=|<=|>=|<|>)\s*(${NUMBER_LITERAL}|'')$`);
+const SELF_COMPARISON = new RegExp(String.raw `^(${IDENT})\s*(=|<>|!=|<=|>=|<|>)\s*(${IDENT})$`);
+/**
+ * The truth value of a predicate when it does not depend on any row: `true`,
+ * `false`, or `undefined` when it does (or when this cannot tell). Strings reach
+ * here already emptied to `''`, so two string literals compare equal; the only
+ * mistake that costs is calling a false predicate true, a prompt on a statement
+ * that updates nothing.
+ */
+function constantValue(predicate) {
+    const text = unwrapParens(predicate);
+    if (text === '')
+        return undefined;
+    const ors = splitTopLevel(text, 'OR');
+    if (ors.length > 1) {
+        const values = ors.map(constantValue);
+        if (values.includes(true))
+            return true;
+        return values.every((v) => v === false) ? false : undefined;
+    }
+    const ands = splitTopLevel(text, 'AND');
+    if (ands.length > 1) {
+        const values = ands.map(constantValue);
+        if (values.includes(false))
+            return false;
+        return values.every((v) => v === true) ? true : undefined;
+    }
+    const negated = /^NOT\s+([\s\S]+)$/i.exec(text);
+    if (negated) {
+        const inner = constantValue(negated[1]);
+        return inner === undefined ? undefined : !inner;
+    }
+    if (/^TRUE$/i.test(text))
+        return true;
+    if (/^(?:FALSE|NULL)$/i.test(text))
+        return false;
+    const literals = COMPARISON.exec(text);
+    if (literals)
+        return compareConstants(literals[1], literals[2], literals[3]);
+    // `id = id` is true for every row whose id is not null; calling it true errs
+    // toward the prompt, which is the safe side.
+    const self = SELF_COMPARISON.exec(text);
+    if (self && self[1].toLowerCase() === self[6].toLowerCase())
+        return compareConstants('0', self[5], '0');
+    return undefined;
+}
+/** Compare two literals, where two `''` (emptied strings) are taken as equal. */
+function compareConstants(left, op, right) {
+    const a = left === "''" ? 0 : Number(left);
+    const b = right === "''" ? 0 : Number(right);
+    if (Number.isNaN(a) || Number.isNaN(b))
+        return undefined;
+    switch (op) {
+        case '=':
+            return a === b;
+        case '<>':
+        case '!=':
+            return a !== b;
+        case '<':
+            return a < b;
+        case '<=':
+            return a <= b;
+        case '>':
+            return a > b;
+        case '>=':
+            return a >= b;
+        default:
+            return undefined;
+    }
 }
 /**
  * A leading CTE list is a prefix, not a statement: `WITH c AS (SELECT 1) DELETE
@@ -269,6 +452,25 @@ function copySubstatements(stmt) {
     // above rather than being judged as one blob here.
     return /^(?:DELETE|UPDATE|INSERT|MERGE|WITH)\b/i.test(inner) ? [inner] : [];
 }
+/**
+ * The statement a `PREPARE name [(types)] AS <statement>` stores. Nothing runs at
+ * PREPARE time, but `EXECUTE name` runs it later on the same connection, so the
+ * stored statement is judged as if it had been written out. A prepared `DELETE`
+ * or unrestricted `UPDATE` followed by `EXECUTE` was reported as clean.
+ */
+function prepareSubstatements(stmt) {
+    const head = /^PREPARE\s+(?:"[^"]+"|[A-Za-z_][\w$]*)\s*/i.exec(stmt);
+    if (!head)
+        return [];
+    let rest = stmt.slice(head[0].length);
+    if (rest.startsWith('('))
+        rest = rest.slice(closingParenIndex(rest, 0) + 1).trimStart();
+    const as = /^AS\s+/i.exec(rest);
+    if (!as)
+        return [];
+    const inner = rest.slice(as[0].length);
+    return [stripLeadingCtes(inner), ...cteSubstatements(inner)];
+}
 /**
  * Data-modifying CTE bodies: `WITH d AS (DELETE FROM t ...) SELECT ...` runs a
  * real DELETE even though the statement reads as a SELECT. Each candidate is cut
@@ -338,7 +540,8 @@ function proceduralCandidates(body) {
         // Literals have to survive: they are where dynamic SQL keeps its payload,
         // and `stripped` would have emptied exactly them.
         const text = statement.code;
-        const re = /\b(?:DROP|TRUNCATE|DELETE|ALTER|UPDATE|MERGE)\s/gi;
+        // `DO UPDATE` is the tail of an `ON CONFLICT` clause, judged with its INSERT.
+        const re = /\b(?:(?:DROP|TRUNCATE|DELETE|ALTER|MERGE|INSERT)\s|(?<!\bDO\s+)UPDATE\s|lo_unlink\s*\()/gi;
         let m = re.exec(text);
         while (m !== null) {
             out.push({ text: text.slice(m.index), before: text.slice(0, m.index), statementCode: text });
@@ -370,6 +573,7 @@ function scanDestructiveSql(sql) {
             stripLeadingCtes(body),
             ...cteSubstatements(body),
             ...copySubstatements(body).flatMap((inner) => [inner, ...cteSubstatements(inner)]),
+            ...prepareSubstatements(body),
         ].map((text) => ({
             text,
             display,

package/dist/cjs/cli/error-catalog.js

@@ -107,11 +107,13 @@ const CATALOG = {
             'TLS: a self-signed or expired certificate, or a hostname the certificate does not cover.',
             'The connection string is malformed, or points at a pooler port the server is not on.',
             'The server closed an idle pooled connection (proxy idle timeout, restart, failover).',
+            'A transaction-pooling endpoint (PgBouncer in transaction mode, a managed `-pooler` host, port 6432 or 6543) with named prepared statements: sqlstate 42P05 or 26000.',
         ],
         howToFix: [
             'Read `err.sqlstate` and the hint in the message: each driver code carries its own next step.',
             'Check the host, port and database name; for TLS, supply the CA via `ssl: { ca }` rather than disabling verification.',
             'For a serverless driver, pass the external pool on `TurbineConfig.pool` instead of a connection string.',
+            'For 42P05 / 26000 behind a pooler, connect to the direct endpoint, set `preparedStatements: false`, or run PgBouncer 1.21+ with `max_prepared_statements` above 0.',
         ],
         properties: ['sqlstate'],
     },
@@ -349,6 +351,40 @@ const CATALOG = {
         ],
         properties: ['reason'],
     },
+    TURBINE_E019: {
+        className: 'TransactionRolledBackError',
+        retryable: false,
+        origin: 'turbine',
+        whenThrown: 'A transaction callback returned or committed after work inside it had already failed, so the server rolled the transaction back.',
+        likelyCauses: [
+            'The callback caught an error from a statement (a unique violation, a timeout) and carried on, then returned. PostgreSQL refuses every later statement in an aborted transaction and answers COMMIT with ROLLBACK.',
+            'A query inside `$transaction` hit its per-query `timeout`; the transaction cannot continue after the cancel.',
+            'Raw `transaction()`: a statement failed and the code returned without a SAVEPOINT around it.',
+        ],
+        howToFix: [
+            'Let the first error propagate so the whole transaction fails with its own class, or wrap the step that may fail in a nested `tx.$transaction` (a SAVEPOINT) and catch around that.',
+            'On raw `transaction()`, issue `SAVEPOINT` before the statement that may fail and `ROLLBACK TO SAVEPOINT` when it does.',
+            'Deadlock, serialization and lock-not-available failures keep their own classes and stay retryable; E019 is not, because retrying the same callback repeats the same swallowed failure.',
+        ],
+        properties: [],
+    },
+    TURBINE_E020: {
+        className: 'InvariantError',
+        retryable: false,
+        origin: 'turbine',
+        whenThrown: 'Turbine caught a bug in itself before sending a statement it knew was wrong: two internal paths that must agree did not, or a branch no argument can reach was reached.',
+        likelyCauses: [
+            '`invariant: "sql-cache-lockstep"`: the SQL-template cache built a statement whose parameters, or whose cached text, disagree with what a fresh build of the same query produces.',
+            '`invariant: "sql-cache-param-count"`: a cached statement was about to run with a different number of parameters than its placeholders.',
+            'Any other `invariant` id names one internal rule; the message says which two things disagreed.',
+        ],
+        howToFix: [
+            'Report it at https://github.com/zvndev/turbine-orm/issues with the message and `err.invariant`. The message carries the query shape and no row or parameter value.',
+            'Nothing in the call is wrong, so rewriting the arguments is a workaround at best. There is no option that turns these checks off: each one fires only where Turbine would otherwise have sent the wrong SQL or the wrong parameters.',
+            'Do not retry: the same call fails the same way.',
+        ],
+        properties: ['invariant'],
+    },
 };
 /** Every code in the catalog, in code order. */
 exports.CATALOGUED_ERROR_CODES = Object.keys(CATALOG).sort();

package/dist/cjs/cli/error-text.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The text the CLI prints for a caught error. A zero-import leaf, so every
+ * command can use it.
+ *
+ * Reading `.message` alone is not enough. When `localhost` resolves to both
+ * `::1` and `127.0.0.1` and both refuse, Node's `net` rejects with an
+ * `AggregateError` whose message is EMPTY: the reasons are on its `errors`.
+ * Every command then printed its prefix and nothing else ("Failed to start
+ * Studio: "), and the top-level handler, which classifies by message text,
+ * could not tell that it was a refused connection.
+ *
+ * Order: the error's own message; else the messages of the errors it
+ * aggregates (each once); else its `cause`; else its `code`; else its name.
+ */
+export declare function errorText(err: unknown, depth?: number): string;

package/dist/cjs/cli/error-text.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.errorText = errorText;
+/**
+ * The text the CLI prints for a caught error. A zero-import leaf, so every
+ * command can use it.
+ *
+ * Reading `.message` alone is not enough. When `localhost` resolves to both
+ * `::1` and `127.0.0.1` and both refuse, Node's `net` rejects with an
+ * `AggregateError` whose message is EMPTY: the reasons are on its `errors`.
+ * Every command then printed its prefix and nothing else ("Failed to start
+ * Studio: "), and the top-level handler, which classifies by message text,
+ * could not tell that it was a refused connection.
+ *
+ * Order: the error's own message; else the messages of the errors it
+ * aggregates (each once); else its `cause`; else its `code`; else its name.
+ */
+function errorText(err, depth = 0) {
+    if (!(err instanceof Error))
+        return String(err);
+    if (err.message)
+        return err.message;
+    if (depth < 4) {
+        const inner = err.errors;
+        if (Array.isArray(inner)) {
+            const parts = [...new Set(inner.map((e) => errorText(e, depth + 1)).filter((t) => t !== ''))];
+            if (parts.length > 0)
+                return parts.join('; ');
+        }
+        if (err.cause !== undefined) {
+            const cause = errorText(err.cause, depth + 1);
+            if (cause !== '')
+                return cause;
+        }
+    }
+    const code = err.code;
+    if (typeof code === 'string' && code !== '')
+        return code;
+    return err.name || 'Error';
+}