turbine-orm 0.81.0 → 0.90.0

package/dist/cli/destructive.js

@@ -19,9 +19,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
@@ -41,7 +44,9 @@ export const 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',
@@ -52,6 +57,12 @@ export const 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.
@@ -102,10 +113,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)}`,
     },
     {
@@ -141,16 +153,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
@@ -169,7 +208,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.
@@ -191,21 +230,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
@@ -265,6 +448,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
@@ -334,7 +536,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 });
@@ -366,6 +569,7 @@ export function scanDestructiveSql(sql) {
             stripLeadingCtes(body),
             ...cteSubstatements(body),
             ...copySubstatements(body).flatMap((inner) => [inner, ...cteSubstatements(inner)]),
+            ...prepareSubstatements(body),
         ].map((text) => ({
             text,
             display,

package/dist/cli/error-catalog.js

@@ -102,11 +102,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'],
     },
@@ -344,6 +346,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. */
 export const CATALOGUED_ERROR_CODES = Object.keys(CATALOG).sort();

package/dist/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/cli/error-text.js

@@ -0,0 +1,37 @@
+/**
+ * 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 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';
+}

package/dist/cli/index.d.ts

@@ -25,6 +25,8 @@
  *   npx turbine init --url postgres://...
  *   npx turbine migrate create add_users_table
  */
+import { type SchemaMetadata } from '../schema.js';
+import { type AppliedColumnTags } from './code-first-tags.js';
 import type { CliOverrides, ConfigLoadError, ResolvedConfig, TurbineCliConfig } from './config.js';
 import { type PrismaSchemaAst, type ResolvedPrismaDatasourceUrl } from './prisma-schema.js';
 export interface CliArgs {
@@ -59,6 +61,15 @@ export interface CliArgs {
     allowDrift?: boolean;
     allowEmpty?: boolean;
     allowDestructive?: boolean;
+    /** `migrate create --auto|--from-diff --allow-pending`: diff even while migrations are pending. */
+    allowPending?: boolean;
+    /**
+     * `push --dry-run --exit-code` / `migrate status --exit-code`: exit 2 when the
+     * database differs from the schema file / the migration history is not clean.
+     */
+    exitCode?: boolean;
+    /** `migrate deploy --wait[=seconds]`: seconds to wait for a concurrent deploy's lock. */
+    wait?: number;
     /** `migrate create --recipe <name>` scaffold selector. */
     recipe?: string;
     fix?: boolean;
@@ -76,7 +87,7 @@ export interface CliArgs {
     metricsUrl?: string;
     /** `doctor --no-plan-divergence`: skip the cached-plan divergence section (and its pg_stats read). */
     noPlanDivergence?: boolean;
-    /** `doctor --allow-pooler`: run even when the connection string looks like a transaction pooler. */
+    /** `doctor` / `migrate up|deploy|down --allow-pooler`: run even when the connection string looks like a transaction pooler. */
     allowPooler?: boolean;
     /** `init --yes`/`-y`: accept every step's default non-interactively. */
     yes?: boolean;
@@ -98,8 +109,8 @@ export interface CliArgs {
     includeViews?: boolean;
     /** Omit the `Generated at:` header line for reproducible (diff-stable) output. */
     noTimestamp?: boolean;
-    /** `generate --import-ext <js|none|auto>`: sibling-import extension mode (F3). */
-    importExtension?: 'js' | 'none' | 'auto';
+    /** `generate --import-ext <js|ts|none|auto>`: sibling-import extension mode (F3). */
+    importExtension?: 'js' | 'ts' | 'none' | 'auto';
     /** `generate --keep-column-names`: keep raw DB column names as field names (F4). */
     keepColumnNames?: boolean;
     /** `generate --legacy-to-many-uniques`: opt out of the unique-FK → hasOne flip (F2). */
@@ -133,6 +144,8 @@ export interface CliArgs {
     /** `skill --dir <path>`: the skills root to install into (default `.claude/skills`). */
     dir?: string;
 }
+/** How long a bare `migrate deploy --wait` waits for a concurrent deploy to finish. */
+export declare const DEFAULT_LOCK_WAIT_SECONDS = 300;
 /**
  * The canonical name of `command`, or undefined when nothing dispatches it.
  *
@@ -490,6 +503,43 @@ export declare function initEnvNotice(input: {
 export declare function refuseSchemaFilePath(config: Pick<ResolvedConfig, 'schema' | 'schemaFile'>, options?: {
     escapeHatch?: string;
 }): void;
+/**
+ * Overlay the column tags the defineSchema() file declares (`pii`, `updatedAt`,
+ * `maxLength`) onto an introspected schema, before it is generated.
+ *
+ * Introspection reads the database, and the database has no column for these
+ * flags, so a client generated from introspection alone returns PII by default,
+ * never stamps `updatedAt`, and leaves Studio and the MCP server with nothing to
+ * redact. The schema file is the only place the tags exist.
+ *
+ * Loaded when the file was named (`--schema-file` / config `schemaFile`) or sits
+ * at the default path. A named file that is missing, or any file that cannot be
+ * loaded, fails the command: carrying on would generate the unredacted client
+ * this exists to prevent. Only a missing DEFAULT file is skipped, which is a
+ * database-first project with no schema file at all.
+ *
+ * Returns what was applied, or `null` when there was no schema file to read.
+ *
+ * @internal exported for tests.
+ */
+export declare function overlayCodeFirstTags(schema: SchemaMetadata, config: Pick<ResolvedConfig, 'schemaFile' | 'schemaFileConfigured' | 'include' | 'exclude'>): Promise<AppliedColumnTags | null>;
+/**
+ * The generator's `columnTypes`: the schema file's `tsType` declarations, then
+ * the config file's `columnTypes`, which wins on the same key. A config key
+ * whose table the run's include / exclude filters leave out is dropped, since
+ * that table has no generated type to override; every other key goes to the
+ * generator, which rejects one naming no table or column.
+ *
+ * An `include` list leaves out every table it does not name, so a misspelt
+ * table looks exactly like a real table that was left out. `databaseTables`
+ * (every table the schema holds, before filtering) tells them apart: only a
+ * table the database has is dropped, and a name it does not have goes on to the
+ * generator, which names the closest match. Without it every key outside the
+ * filters is dropped.
+ *
+ * @internal exported for tests.
+ */
+export declare function generatorColumnTypes(applied: Pick<AppliedColumnTags, 'columnTypes'> | null, config: Pick<ResolvedConfig, 'columnTypes' | 'include' | 'exclude'>, schema: Pick<SchemaMetadata, 'tables'>, databaseTables?: ReadonlySet<string>): Record<string, string> | undefined;
 /**
  * `turbine migrate-from-prisma --schema prisma/schema.prisma` parses a Prisma
  * schema, resolve its models/fields/relations/compound-uniques against the live
@@ -557,6 +607,11 @@ export type SeedExecutionPlan = {
     file: string;
 };
 export declare function getSeedExecutionPlan(seedFile: string): SeedExecutionPlan;
+/**
+ * Why `migrate up`, `deploy` and `down` refuse a pooled endpoint. The reason is
+ * the migration lock, not the doctor's session-state argument.
+ */
+export declare const MIGRATE_POOLER_EXPLANATION: readonly string[];
 /**
  * Refuse a `doctor` run whose connection string points at a transaction pooler.
  *
@@ -578,7 +633,10 @@ export declare function getSeedExecutionPlan(seedFile: string): SeedExecutionPla
  * Exported for the unit test only (like {@link isLoopbackHost}): a gate whose
  * failure path is `process.exit` is untestable through the command itself.
  */
-export declare function refusePoolerConnection(url: string, args: CliArgs): void;
+export declare function refusePoolerConnection(url: string, args: CliArgs, refusal?: {
+    command: string;
+    explanation?: readonly string[];
+}): void;
 /**
  * True when `host` is a loopback address Studio/Observe may bind without
  * `--allow-remote`. Accepts IPv4, IPv6, and the common bracket form.