turbine-orm 0.77.1 → 0.78.0

package/README.md

@@ -8,6 +8,8 @@ Turbine compiles typed queries straight to SQL. There is no query engine, no WAS
 npm install turbine-orm
 ```
 
+Turbine is **pre-1.0** (`0.x`). Which surfaces hold steady across minors, which are Experimental, and what has to be true before 1.0: [STABILITY.md](STABILITY.md).
+
 **Docs: [turbineorm.dev](https://turbineorm.dev)** · [Quick Start](https://turbineorm.dev/quickstart) · [Why Turbine](https://turbineorm.dev/why-turbine) · [API Reference](https://turbineorm.dev/queries) · [Relations](https://turbineorm.dev/relations) · [AI Agents](https://turbineorm.dev/ai-agents) · [Benchmarks](https://turbineorm.dev/benchmarks) · [Errors](https://turbineorm.dev/errors)
 
 **Contents:** [Why Turbine](#why-turbine) · [Benchmarks](#benchmarks) · [Quick Start](#quick-start) · [Queries](#queries) · [Built for agents](#built-for-agents) · [Safety tooling](#safety-tooling) · [Postgres features](#postgres-features) · [Serverless and edge](#serverless-and-edge) · [Database engines](#database-engines) · [From scratch, and forkable](#from-scratch-and-forkable) · [Comparison](#comparison) · [Limitations](#limitations) · [Requirements](#requirements) · [Contributing](#contributing)
@@ -16,7 +18,7 @@ npm install turbine-orm
 
 Six reasons, each with the mechanism that makes it true:
 
-1. **One dependency.** `dependencies` is `{ "pg": "^8.13.1" }`. No engine binary, no WASM compiler, no adapter packages in lockstep. The optional engines (SQLite, MySQL, SQL Server, PowDB) are peer dependencies or Node builtins you install only if you use them.
+1. **One dependency.** `dependencies` is `{ "pg": "^8.13.1" }`. No engine binary, no WASM compiler, no adapter packages in lockstep. The optional engines (SQLite, MySQL, SQL Server, PowDB, all tiered Experimental in [STABILITY.md](STABILITY.md)) are peer dependencies or Node builtins you install only if you use them.
 2. **Written from scratch.** Turbine is not a layer over Knex or a query-builder library. Query compilation is plain string building with an FNV-1a shape fingerprint into a bounded LRU of SQL templates, so there is no plan cache to size and no compiler running on your event loop.
 3. **Nested relations in one statement.** A `with` clause compiles to correlated `json_agg` subqueries, so users with posts with comments is one round trip, typed end to end: `users[0].posts[0].comments[0].author.name` autocompletes with no annotation.
 4. **Close to raw SQL.** In the last published run, Turbine's overhead over a hand-written `pg` control was 1.08x by geometric mean. The table is below; the losses are stated with the wins.
@@ -58,6 +60,7 @@ Reproduce it: `cd benchmarks && npm install && npx prisma generate && DATABASE_U
 ```bash
 npm install turbine-orm
 npm install --save-dev tsx        # the CLI loads .ts config/schema files via tsx
+npm pkg set type=module           # the snippet below uses top-level await: ESM, or save it as a .mts file
 
 npx turbine init --url postgres://user:pass@localhost:5432/mydb
 npx turbine generate              # introspect the DB, emit a typed client
@@ -103,9 +106,9 @@ const users = await db.users.findMany({
 // users[0].posts[0].comments is typed, and this was one SQL statement
 ```
 
-Per-relation `where`, `orderBy`, `limit`, `select`, and `omit` work at every depth. Many-to-many junction tables are auto-detected during `generate`, and self-referencing FKs give you parent and children relations. Relation filters (`some` / `every` / `none`) filter parents by their children.
+Per-relation `where`, `orderBy`, `limit`, `select`, and `omit` work at every depth. Many-to-many junction tables are auto-detected during `generate`, and a self-referencing FK (`users.manager_id` referencing `users.id`) gives you both directions, named `user` (to-one) and `users` (to-many) by default and renameable in `turbine.config.ts`. Relation filters (`some` / `every` / `none`) filter parents by their children.
 
-Four load strategies produce identical rows: `join` (one statement), `batched` (one flat follow-up per relation), `flatten` (LEFT JOIN for eligible to-one relations), and `auto` (the default: the join plan, falling back to batched per relation when the correlation column has no covering index). A differential fuzz suite holds the strategies to byte-identical output. Details: [turbineorm.dev/relations](https://turbineorm.dev/relations).
+Four load strategies produce identical rows: `join` (one statement), `batched` (one flat follow-up per relation), `flatten` (LEFT JOIN for eligible to-one relations), and `auto` (the default: the join plan, falling back to batched per relation when the correlation column has no covering index). A differential fuzz suite holds `join`, `batched` and `auto` to byte-identical output on every release and nightly; `flatten` is held to the same parity by its own deterministic suite (`src/test/flatten-parity.integration.test.ts`). Details: [turbineorm.dev/relations](https://turbineorm.dev/relations).
 
 ### Writes, including atomic operators
 
@@ -214,7 +217,7 @@ try {
 }
 ```
 
-Every error extends `TurbineError` with a stable code (`TURBINE_E001` through `E018`) and a `docsUrl`. Error messages carry keys, never values: a `NotFoundError` says `where: { id, email }` without printing the email, so errors are safe to forward to a tracker without a scrubbing rule. Retryable failures (`DeadlockError`, `SerializationFailureError`) expose `isRetryable: true` as a typed const. Full table: [turbineorm.dev/errors](https://turbineorm.dev/errors).
+Every error Turbine raises extends `TurbineError` with a stable code (`TURBINE_E001` through `E018`) and a `docsUrl`; a driver error whose SQLSTATE Turbine does not map stays the driver's own error, carrying that SQLSTATE on `.code`. Error messages carry keys, never values: a `NotFoundError` says `where: { id, email }` without printing the email, so errors are safe to forward to a tracker without a scrubbing rule. Retryable failures (`DeadlockError`, `SerializationFailureError`) expose `isRetryable: true` as a typed const. `err.code` is the check that survives a mixed ESM/CJS module graph, where two copies of the package hold two copies of every class; since 0.78 `instanceof` works across copies too, through a cross-copy brand on every error. Full table: [turbineorm.dev/errors](https://turbineorm.dev/errors).
 
 ## Built for agents
 
@@ -269,7 +272,7 @@ Going deep on one database means the parts other ORMs push to raw SQL are typed
 
 ## Serverless and edge
 
-The core is driver-agnostic: hand any pg-compatible pool to `turbineHttp()` and Turbine runs on Vercel Edge, Cloudflare Workers, Deno Deploy, or anywhere else without TCP. The main entry's import graph is held under **87 kB brotli** (edge entry under **69 kB**) with `pg` external, enforced by `size-limit` in CI at those exact numbers; run `npm run size` for the current figure.
+The core is driver-agnostic: hand any pg-compatible pool to `turbineHttp()` and Turbine runs on Vercel Edge, Cloudflare Workers, Deno Deploy, or anywhere else without TCP. The main entry's import graph is held under **91 kB brotli** (edge entry under **72 kB**) with `pg` external, enforced by `size-limit` in CI at those exact numbers; run `npm run size` for the current figure.
 
 ```typescript
 import { Pool } from '@neondatabase/serverless';
@@ -284,7 +287,7 @@ HTTP drivers cannot hold a cursor or a LISTEN connection, so `findManyStream` an
 
 ## Database engines
 
-Postgres is the default and primary target. The same typed API also runs on **SQLite** (Node's built-in `node:sqlite`, zero extra installs, Node ≥ 22.5), **MySQL 8** (`mysql2`), **SQL Server 2016+** (`mssql`), and **PowDB** (embedded or networked), each behind a subpath export with its driver as an optional peer:
+Postgres is the default and primary target. The same typed API also runs on **SQLite** (Node's built-in `node:sqlite`, zero extra installs, Node ≥ 22.5), **MySQL 8** (`mysql2`), **SQL Server 2016+** (`mssql`), and **PowDB** (embedded or networked), each behind a subpath export with its driver as an optional peer. All four are **Experimental** in the [stability policy](STABILITY.md): the query API they expose is the shared one, but each engine's capability boundaries and factory options may still change in a minor release.
 
 ```bash
 npm install turbine-orm                        # SQLite needs nothing else
@@ -318,7 +321,7 @@ const schema = defineSchema({
   },
   posts: {
     id: { type: 'serial', primaryKey: true },
-    // "table.column" — this is what makes `with: { posts: true }` work below.
+    // "table.column": this is what makes `with: { posts: true }` work below.
     userId: { type: 'integer', notNull: true, references: 'users.id' },
     title: { type: 'text', notNull: true },
   },
@@ -356,11 +359,11 @@ It is also built to be extended rather than wrapped. All SQL generation routes t
 |---|---|---|---|---|
 | **Engine / runtime** | No engine binary (`pg` only) | Client + TS/WASM query compiler | No engine | No engine |
 | **Runtime deps** | 1 (`pg`) | `@prisma/client` + required driver adapter | 0 | 0 |
-| **Main bundle (brotli)** | under 87 kB import graph (CI-enforced), `pg` external | ~1.6 MB client (TS/WASM compiler) | ~7 KB core | small |
+| **Main bundle (brotli)** | under 91 kB import graph (CI-enforced), `pg` external | ~1.6 MB client (TS/WASM compiler) | ~7 KB core | small |
 | **Studio** | Read-only by default | Full CRUD, cloud-hosted | Full CRUD; [Gateway](https://gateway.drizzle.team/) self-hosted, free | None |
 | **Error PII safety** | Keys only by default | Values in messages | Raw pg errors | Raw pg errors |
 | **Migrations** | SQL-first, SHA-256 checksums | DSL-generated, shadow DB | SQL or Drizzle Kit | None |
-| **Edge runtime** | One import swap, under 69 kB brotli (CI-enforced) | Driver adapter + WASM compiler | Native | Native |
+| **Edge runtime** | One import swap, under 72 kB brotli (CI-enforced) | Driver adapter + WASM compiler | Native | Native |
 | **Pipeline batching** | Parse/Bind/Execute protocol | Sequential in txn | Sequential | Manual |
 | **Typed errors** | `isRetryable` discriminant | Error codes only | None | None |
 | **Nested relations** | 1 query, deep type inference | 1 query per relation by default; single-query `relationJoins` is Preview | 1 query, `relations()` re-declaration | Manual (`jsonArrayFrom`) |
@@ -406,6 +409,7 @@ Stated so you do not find out three weeks in:
 - Node.js ≥ 20 (the SQLite engine needs ≥ 22.5 for `node:sqlite`)
 - PostgreSQL ≥ 14 tested; CI runs the integration suite against PostgreSQL 14, 15, 16, and 17
 - ESM and CommonJS both supported
+- `@types/node` in `devDependencies` when you typecheck with `skipLibCheck: false`: the `turbine-orm/sqlite` engine and the `turbine-orm/cli` declarations reference Node's own types (`node:sqlite`, `NodeJS`)
 
 ## Contributing
 

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

@@ -230,5 +230,11 @@ export declare function connectionStringHasPassword(connectionString: string): b
  * `.env` that holds the real value. The refusal lives here rather than at the
  * call site so no future caller can reintroduce the leak by passing the raw
  * `--url` through.
+ *
+ * `schema` is the RESOLVED Postgres schema (`--schema` or the default), written
+ * as the config's `schema` value. `init --schema app` probes `app` and then
+ * used to write `schema: 'public'` regardless, so the next documented step,
+ * `push`, diffed the starter schema against the wrong namespace and proposed
+ * dropping every column it found there.
  */
-export declare function configTemplate(connectionString?: string): string;
+export declare function configTemplate(connectionString?: string, schema?: string): string;

package/dist/cjs/cli/config.js

@@ -301,9 +301,18 @@ function connectionStringHasPassword(connectionString) {
  * `.env` that holds the real value. The refusal lives here rather than at the
  * call site so no future caller can reintroduce the leak by passing the raw
  * `--url` through.
+ *
+ * `schema` is the RESOLVED Postgres schema (`--schema` or the default), written
+ * as the config's `schema` value. `init --schema app` probes `app` and then
+ * used to write `schema: 'public'` regardless, so the next documented step,
+ * `push`, diffed the starter schema against the wrong namespace and proposed
+ * dropping every column it found there.
  */
-function configTemplate(connectionString) {
+function configTemplate(connectionString, schema = 'public') {
     const inlineUrl = connectionString && !connectionStringHasPassword(connectionString) ? connectionString : undefined;
+    // Same delimiter rule as the URL below: a schema name is an arbitrary
+    // identifier, and a quote in it must not end the TS string early.
+    const schemaLiteral = schema.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
     // Single quotes are the string delimiter in the emitted TS, so a connection
     // string containing one would otherwise produce a config file that does not
     // parse (a password-free URL can still carry a quote in a query parameter).
@@ -324,7 +333,7 @@ ${urlLine}
   out: './generated/turbine',
 
   /** Postgres schema to introspect (default: public) */
-  schema: 'public',
+  schema: '${schemaLiteral}',
 
   /** Tables to exclude from generation */
   // exclude: ['_migrations', '_sessions'],

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

@@ -28,7 +28,7 @@
  * 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' | 'dynamic-destructive';
+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 interface DestructiveStatement {
     /** The offending SQL statement (trimmed, possibly long, display truncated) */
     statement: string;

package/dist/cjs/cli/destructive.js

@@ -49,7 +49,9 @@ exports.DESTRUCTIVE_KIND_LABEL = {
     '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',
+    'rewrite-rule': 'installs a rewrite rule that runs a destructive statement every time a later ordinary statement matches it',
     'dynamic-destructive': 'runs destructive SQL assembled at run time, what it destroys cannot be known without running it',
+    'dynamic-unclassified': 'runs SQL assembled at run time whose statement the scanner cannot read; confirm what it does yourself',
 };
 /** Unquote a "quoted" identifier for display. */
 const ident = (raw) => (raw ?? '?').replace(/^"|"$/g, '');
@@ -154,6 +156,25 @@ const RULES = [
         target: (m) => (m[4] ? `${ident(m[2])}.${ident(m[4])}` : ident(m[2])),
         also: (stmt) => !hasTopLevelWhere(stmt),
     },
+    {
+        // `CREATE RULE r AS ON INSERT TO t DO INSTEAD DELETE FROM u`. The rule
+        // destroys nothing when it is created, which is why it passed: the DELETE
+        // runs later, on every ordinary INSERT into `t`, and the first one emptied
+        // the table. Deferred destruction is still destruction the migration
+        // installs. `DO ALSO` counts too (the action runs in addition), and the
+        // action may be a parenthesized list, whose FIRST statement decides.
+        kind: 'rewrite-rule',
+        regex: new RegExp(String.raw `^CREATE\s+(?:OR\s+REPLACE\s+)?RULE\s+${IDENT}\s+AS\s+ON\s+(?:SELECT|INSERT|UPDATE|DELETE)\s+TO\s+${IDENT}${OUTSIDE_QUOTES}\bDO\s+(?:ALSO\s+|INSTEAD\s+)?\(?\s*(DELETE|UPDATE|TRUNCATE|DROP)\b`, 'i'),
+        target: (m) => `${qualified(m, 4)} (${(m[7] ?? '').toUpperCase()} on every matching statement)`,
+        // An UPDATE action is judged the way a top-level UPDATE is: destructive
+        // without a WHERE, ordinary with one. `CREATE RULE v_upd AS ON UPDATE TO v
+        // DO INSTEAD UPDATE base SET n = 1 WHERE id = 2` is the standard updatable
+        // -view idiom and was being reported, which is a false positive on a shape
+        // 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),
+    },
     // 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.
     {
@@ -226,6 +247,28 @@ function matchRules(candidate) {
     }
     return null;
 }
+/**
+ * The DML inside `COPY (DELETE FROM t RETURNING *) TO ...`.
+ *
+ * The same trick as a data-modifying CTE, through a different wrapper: the
+ * statement reads as a COPY, which nothing here treats as destructive, and the
+ * DELETE inside it runs and empties the table. Verified live on PostgreSQL 17
+ * through node-postgres, `TO STDOUT` included, so it needs no server-side file
+ * permission and no `TO PROGRAM`. `cteSubstatements` does not reach it because
+ * that one only fires on a leading `WITH`.
+ */
+function copySubstatements(stmt) {
+    if (!/^COPY\s*\(/i.test(stmt))
+        return [];
+    const open = stmt.indexOf('(');
+    if (open === -1)
+        return [];
+    const inner = stmt.slice(open + 1, closingParenIndex(stmt, open)).trim();
+    // A `COPY (SELECT ...) TO` is the ordinary export form and destroys nothing.
+    // A leading WITH is handed on so its own CTE bodies are read by the rule
+    // above rather than being judged as one blob here.
+    return /^(?:DELETE|UPDATE|INSERT|MERGE|WITH)\b/i.test(inner) ? [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
@@ -298,7 +341,7 @@ function proceduralCandidates(body) {
         const re = /\b(?:DROP|TRUNCATE|DELETE|ALTER|UPDATE|MERGE)\s/gi;
         let m = re.exec(text);
         while (m !== null) {
-            out.push({ text: text.slice(m.index), before: text.slice(0, m.index) });
+            out.push({ text: text.slice(m.index), before: text.slice(0, m.index), statementCode: text });
             m = re.exec(text);
         }
     }
@@ -326,6 +369,7 @@ function scanDestructiveSql(sql) {
         const candidates = [
             stripLeadingCtes(body),
             ...cteSubstatements(body),
+            ...copySubstatements(body).flatMap((inner) => [inner, ...cteSubstatements(inner)]),
         ].map((text) => ({
             text,
             display,
@@ -343,10 +387,20 @@ function scanDestructiveSql(sql) {
                 candidates.push({
                     text: part.text,
                     display: `${display} [in block: ${part.text.replace(/\s+/g, ' ').slice(0, 60)}]`,
+                    statementCode: part.statementCode,
                 });
                 proceduralParts.push(part);
             }
         }
+        // Sub-statements of a procedural body that some pass has already named.
+        // ONE body holds several statements and each is judged on its own, so a
+        // pass that reports one must not silence the others: `DO $$ BEGIN EXECUTE
+        // 'ALTER TABLE t DROP COLUMN x'; EXECUTE 'D'||'ROP TABLE victim'; END $$`
+        // reported only the DROP COLUMN, and the DROP TABLE then ran under a
+        // confirmation the operator gave for something else. Equally, the
+        // unclassified backstop must not re-report a statement an earlier pass
+        // already named, which is what this set is for.
+        const spokenFor = new Set();
         let matched = false;
         for (const candidate of candidates) {
             const hit = matchRules(candidate.text);
@@ -354,9 +408,15 @@ function scanDestructiveSql(sql) {
                 continue;
             found.push({ statement: candidate.display, kind: hit.kind, target: hit.target });
             matched = true;
-            break;
+            if (candidate.statementCode !== undefined)
+                spokenFor.add(candidate.statementCode);
+            // A statement outside a procedural body has exactly one verdict, as
+            // before. Inside one, keep going: the remaining sub-statements have not
+            // been judged yet.
+            if (!procedural)
+                break;
         }
-        if (matched)
+        if (matched && !procedural)
             continue;
         // Nothing matched a rule. Inside a PROCEDURAL body that is not the end of
         // the question, because the rules all need a parseable object name and
@@ -379,7 +439,10 @@ function scanDestructiveSql(sql) {
         // `RAISE NOTICE 'DROP the mic'` would prompt, and a guard that fires on
         // prose teaches operators to confirm without reading, which costs more than
         // it saves.
+        let dynamicHit = false;
         for (const part of proceduralParts) {
+            if (spokenFor.has(part.statementCode))
+                continue;
             const kind = dynamicDestructiveKind(part);
             if (!kind)
                 continue;
@@ -388,11 +451,210 @@ function scanDestructiveSql(sql) {
                 kind,
                 target: exports.DYNAMIC_TARGET,
             });
-            break;
+            dynamicHit = true;
+            spokenFor.add(part.statementCode);
+        }
+        // Still nothing, in a procedural body. Every pass above needs to SEE a verb,
+        // and an EXECUTE whose text is assembled so that no verb is visible
+        // (`'D' || 'ROP TABLE t'`, `chr(68) || ...`, `reverse(...)`, an escape-
+        // encoded literal, a variable built across statements) walked past all of
+        // them and dropped the table live. The scanner cannot classify such a
+        // statement, and "cannot classify" must not be reported as "clean": that is
+        // the consent gate deciding in the author's favour on no evidence. So it
+        // asks, with a kind whose label says exactly that.
+        for (const block of procedural ? statement.blocks : []) {
+            for (const unreadable of unclassifiableExecutes(block, matched || dynamicHit)) {
+                if (spokenFor.has(unreadable.code))
+                    continue;
+                spokenFor.add(unreadable.code);
+                found.push({
+                    statement: `${display} [in block: ${`EXECUTE ${unreadable.expr}`.replace(/\s+/g, ' ').slice(0, 60)}]`,
+                    kind: 'dynamic-unclassified',
+                    target: exports.DYNAMIC_TARGET,
+                });
+            }
         }
     }
     return found;
 }
+/**
+ * Statement openers that destroy nothing, so an assembled `EXECUTE` whose text
+ * visibly begins with one of them is left alone. `UPDATE` is here because its
+ * destructive form is the ABSENCE of a `WHERE`, which the tail of an assembled
+ * fragment cannot answer; flagging every dynamic `UPDATE ... WHERE` is the
+ * false-positive cost this module refuses to pay.
+ */
+const HARMLESS_OPENER = /^(?:SELECT|INSERT|UPDATE|CREATE|COMMENT|GRANT|REVOKE|ANALYZE|ANALYSE|REFRESH|VACUUM|REINDEX|CLUSTER|SET|RESET|SHOW|NOTIFY|LOCK|CALL|PERFORM|EXPLAIN)\b/i;
+/**
+ * Openers whose rules deliberately stay SILENT on a benign form, so silence
+ * from them is a decision rather than a failure to parse. `ALTER TABLE ... ADD
+ * COLUMN` loses nothing and is not reported on purpose; a `MERGE` without a
+ * `THEN DELETE` likewise; a `WITH` whose CTE bodies are all reads likewise.
+ * Reporting these again here would contradict that silence.
+ */
+const VERB_SILENT_WHEN_BENIGN = /^(?:ALTER|MERGE|WITH)\b/i;
+/**
+ * Openers whose rules ALWAYS report when they can read the statement. Silence
+ * from one of these is not a verdict, it is the rules failing to parse, so the
+ * skip is conditional on an earlier pass having actually reported.
+ *
+ * The shape that made the distinction necessary: two adjacent string literals
+ * are ONE string in PostgreSQL, so `EXECUTE 'DROP TABLE '\n'victims'` reads as
+ * `DROP` to the opener test while every earlier pass declines, the literal
+ * rules because a quote is not an identifier and the assembly test because
+ * continuation is lexical and carries no `||`, `concat` or `format`. The
+ * opener was trusted, the statement was skipped, and the table went.
+ */
+const VERB_ALWAYS_REPORTS = /^(?:DROP|TRUNCATE|DELETE)\b/i;
+/**
+ * `EXECUTE` in a position where plpgsql can begin a statement.
+ *
+ * Matched against a statement's `stripped` view, so the word can never be one
+ * that lived inside a string literal. `GRANT`/`REVOKE EXECUTE ON FUNCTION` are
+ * excluded by construction: their preceding token is a verb, not one of the
+ * introducers here.
+ */
+const EXECUTE_AT_STATEMENT_START = /(?:^|;|\bTHEN\b|\bELSE\b|\bLOOP\b|\bBEGIN\b|\bDECLARE\b)\s*EXECUTE\s/i;
+/**
+ * Functions whose FIRST literal argument is the statement text (or its
+ * template), so the opener can be read through the call.
+ */
+const TEMPLATE_FN = /^(?:format|replace|regexp_replace|concat|concat_ws|array_to_string)\s*\(/i;
+/** The leading string literal of `text`: its raw content and whether it can hide a verb. */
+function leadingLiteral(text) {
+    const m = /^(U&'|[EeBbXx]'|'|\$([A-Za-z_][\w]*)?\$)/.exec(text);
+    if (!m)
+        return null;
+    const open = m[1];
+    if (open.startsWith('$')) {
+        const close = text.indexOf(open, open.length);
+        if (close === -1)
+            return null;
+        return { content: text.slice(open.length, close), rest: text.slice(close + open.length), escaped: false };
+    }
+    // Single-quoted: `''` is an escaped quote inside the literal.
+    let i = open.length;
+    let content = '';
+    while (i < text.length) {
+        const ch = text[i];
+        if (ch === "'") {
+            if (text[i + 1] === "'") {
+                content += "'";
+                i += 2;
+                continue;
+            }
+            break;
+        }
+        content += ch;
+        i++;
+    }
+    if (i >= text.length)
+        return null;
+    // `E'\x44ROP'` and `U&'\0044ROP'` spell a verb the scanner cannot see; an
+    // escape string with no backslash in it hides nothing.
+    const escaped = open !== "'" && content.includes('\\');
+    return { content, rest: text.slice(i + 1), escaped };
+}
+/**
+ * The first word of the statement an `EXECUTE` argument would run, read as far
+ * as the text allows, plus whether the argument is one PLAIN literal (in which
+ * case the literal passes already had their chance and this pass stays out).
+ * `null` opener = the scanner cannot see a verb at all.
+ */
+function executeOpener(expr) {
+    const text = expr.trim();
+    const lit = leadingLiteral(text);
+    if (lit) {
+        const word = /^\s*([A-Za-z_][\w]*)/.exec(lit.content)?.[1] ?? null;
+        // Plain: the literal IS the whole argument (bar an INTO / USING clause),
+        // spelled without escapes.
+        const plain = !lit.escaped && /^\s*(?:;|INTO\b|USING\b|$)/i.test(lit.rest);
+        return { opener: lit.escaped ? null : word, plain };
+    }
+    if (TEMPLATE_FN.test(text)) {
+        // Read the opener from the first literal argument that carries a word: a
+        // `concat_ws(' ', ...)` separator or a `format('%s', ...)` placeholder is
+        // not a verb, and neither is a `concat('DR', 'OP', ...)` fragment.
+        const inner = text.slice(text.indexOf('(') + 1);
+        let cursor = inner;
+        for (let guard = 0; guard < 16; guard++) {
+            const lit2 = leadingLiteral(cursor.trimStart());
+            if (!lit2)
+                break;
+            const word = /^\s*([A-Za-z_][\w]*)/.exec(lit2.content)?.[1];
+            if (word)
+                return { opener: lit2.escaped ? null : word, plain: false };
+            const comma = lit2.rest.indexOf(',');
+            if (comma === -1)
+                break;
+            cursor = lit2.rest.slice(comma + 1);
+        }
+        return { opener: null, plain: false };
+    }
+    // Any other function call, a parenthesised expression, or a bare variable
+    // (`EXECUTE s`, built across earlier statements): nothing readable.
+    return { opener: null, plain: false };
+}
+/**
+ * The EXECUTE argument in `body`, when it is assembled or encoded such that no
+ * statement verb is visible to the passes above. Returns the offending
+ * fragment for display, or `null` when every EXECUTE in the body either is a
+ * plain literal (the literal rules own it) or visibly begins with a verb some
+ * other rule has already judged.
+ */
+function unclassifiableExecutes(body, verbPassesReported) {
+    const out = [];
+    for (const statement of (0, sql_statements_js_1.tokenizeSql)(body)) {
+        // Decide PRESENCE against `stripped`, whose literals are emptied, and read
+        // the ARGUMENT out of `code`, which keeps them. Reading both out of `code`
+        // fired on the word rather than on the statement: `RAISE NOTICE 'EXECUTE
+        // the plan'` and `INSERT INTO log(msg) VALUES ('EXECUTE me later')` both
+        // prompted, and a guard that fires on prose teaches operators to confirm
+        // without reading, which is the cost this module's own doctrine refuses to
+        // pay. `stripped` cannot contain a word that only ever appeared inside a
+        // literal, so it settles the question the offsets cannot.
+        //
+        // The keyword must also sit where a plpgsql STATEMENT can start, not
+        // merely somewhere in the text: `GRANT EXECUTE ON FUNCTION f() TO app` is
+        // an ordinary permission grant and was being reported as unreadable
+        // dynamic SQL, which fails an ordinary migration under `migrate deploy`
+        // where there is no terminal to confirm at. The introducers below are the
+        // positions plpgsql actually allows one at, since `tokenizeSql` splits on
+        // top-level semicolons and a body's `IF ... THEN EXECUTE ...` therefore
+        // arrives as one statement.
+        if (!EXECUTE_AT_STATEMENT_START.test(statement.stripped))
+            continue;
+        const m = /\bEXECUTE\s+([\s\S]+)$/i.exec(statement.code);
+        if (!m)
+            continue;
+        const expr = m[1];
+        const { opener, plain } = executeOpener(expr);
+        if (plain)
+            continue;
+        // `EXECUTE s` where `s` is a bare variable: the statement it runs was
+        // assembled by some EARLIER sub-statement of the same block, so when a pass
+        // has already named one, the operator has been told what this body does and
+        // a second "cannot classify" entry for the same thing is noise that
+        // contradicts the first. When nothing was named, this is the whole finding
+        // and it stands: an assignment the rules could not read leaves
+        // `verbPassesReported` false.
+        if (opener === null && verbPassesReported && /^[A-Za-z_]\w*\s*;?$/.test(expr.trim()))
+            continue;
+        if (opener !== null) {
+            if (HARMLESS_OPENER.test(opener))
+                continue;
+            if (VERB_SILENT_WHEN_BENIGN.test(opener))
+                continue;
+            // The remaining skip is a claim that an earlier pass already reported
+            // this statement, so it holds only when one actually did. See
+            // VERB_ALWAYS_REPORTS for the shape where none does.
+            if (verbPassesReported && VERB_ALWAYS_REPORTS.test(opener))
+                continue;
+        }
+        out.push({ code: statement.code, expr });
+    }
+    return out;
+}
 /** Shown in place of an object name that does not exist until the block runs. */
 exports.DYNAMIC_TARGET = '<name assembled at run time>';
 /**
@@ -457,16 +719,41 @@ const ASSEMBLY_FN = /\b(?:format|concat_ws|concat|quote_ident|quote_literal|quot
 const WRAPPING_ASSEMBLY_FN = /\b(?:format|concat_ws|concat|quote_ident|quote_literal|quote_nullable|array_to_string|regexp_replace|replace)\s*\([^)]*$/i;
 /** Dynamic SQL only runs if something runs it. Scoped to the candidate's own statement. */
 const RUNS_DYNAMIC_SQL = /\bEXECUTE\b/i;
+/**
+ * `ALTER TABLE <assembled name> DROP [COLUMN] ...`: the sub-action that loses
+ * rows, with the same exclusions as the static `drop-column` rule (`DROP
+ * CONSTRAINT` / `DEFAULT` / `NOT NULL` / `IDENTITY` / `EXPRESSION` lose none).
+ * Matches when the keyword `COLUMN`, an `IF EXISTS`, or a literal column name
+ * follows the `DROP`; a `DROP` followed by nothing literal is handled below.
+ * {@link OUTSIDE_QUOTES} keeps `ADD COLUMN "drop me"` out, as it does statically.
+ */
+const DYNAMIC_ALTER_DROP_COLUMN = new RegExp(String.raw `^ALTER\s+TABLE\b${OUTSIDE_QUOTES}\bDROP\s+(?!CONSTRAINT\b|DEFAULT\b|NOT\b|IDENTITY\b|EXPRESSION\b)(?:COLUMN\b|IF\s+EXISTS\b|${IDENT})`, 'i');
+/** `ALTER TABLE <assembled name> ALTER [COLUMN] <col> [SET DATA] TYPE ...`. */
+const DYNAMIC_ALTER_COLUMN_TYPE = new RegExp(String.raw `^ALTER\s+TABLE\b${OUTSIDE_QUOTES}\bALTER\s+(?:COLUMN\s+)?${IDENT}\s+(?:SET\s+DATA\s+)?TYPE\b`, 'i');
+/** The `DROP <thing>` sub-actions of ALTER TABLE that lose no rows. */
+const DYNAMIC_ALTER_DROP_HARMLESS = new RegExp(String.raw `^ALTER\s+TABLE\b${OUTSIDE_QUOTES}\bDROP\s+(?:CONSTRAINT|DEFAULT|NOT\s+NULL|IDENTITY|EXPRESSION)\b`, 'i');
 /**
  * The kind a runtime-assembled procedural fragment should be reported as, or
  * `null` when it is not dynamic (so a rule already had its chance) or its verb
  * is not one that destroys data on its own.
  *
- * `ALTER` and `UPDATE` are deliberately absent even though
- * {@link proceduralCandidates} collects them: their destructive forms are
- * narrow (`ALTER COLUMN ... TYPE`, an `UPDATE` with no `WHERE`) and neither is
- * decidable from a fragment whose tail is a runtime expression, so including
- * them would flag every dynamic `UPDATE ... WHERE` in the file.
+ * `ALTER TABLE` IS decided here, by the sub-action that follows the assembled
+ * table name, because in the shape that matters that sub-action is literal
+ * text: a multi-tenant loop assembles the TABLE (`'ALTER TABLE ' ||
+ * quote_ident(t) || ' DROP COLUMN legacy_phone'`) and writes out what it does
+ * to it. That statement dropped the column from every tenant table while the
+ * scan reported a clean inventory, and its `DROP TABLE` twin was already being
+ * flagged, so an operator who had seen the guard fire once would assume this
+ * was covered. Only the forms that lose rows are reported (`DROP [COLUMN]`,
+ * `ALTER COLUMN ... TYPE`), with the same exclusions as their static rules; an
+ * assembled `ADD COLUMN` stays silent. A `DROP` whose object is itself in the
+ * runtime expression (`' DROP ' || what`) is `dynamic-destructive`, the bare
+ * `DROP` precedent below: alarming is fine, wrong is not.
+ *
+ * `UPDATE` is still deliberately absent even though {@link proceduralCandidates}
+ * collects it: its destructive form is the ABSENCE of a `WHERE`, and absence
+ * is not decidable from a fragment whose tail is a runtime expression, so
+ * including it would flag every dynamic `UPDATE ... WHERE` in the file.
  */
 function dynamicDestructiveKind({ text, before }) {
     const assembled = DYNAMIC_ASSEMBLY.test(text) ||
@@ -474,6 +761,17 @@ function dynamicDestructiveKind({ text, before }) {
         (RUNS_DYNAMIC_SQL.test(before) && WRAPPING_ASSEMBLY_FN.test(before));
     if (!assembled)
         return null;
+    if (/^ALTER\s+TABLE\b/i.test(text)) {
+        if (DYNAMIC_ALTER_DROP_COLUMN.test(text))
+            return 'drop-column';
+        if (DYNAMIC_ALTER_COLUMN_TYPE.test(text))
+            return 'alter-column-type';
+        if (DYNAMIC_ALTER_DROP_HARMLESS.test(text))
+            return null;
+        if (new RegExp(String.raw `^ALTER\s+TABLE\b${OUTSIDE_QUOTES}\bDROP\b`, 'i').test(text))
+            return 'dynamic-destructive';
+        return null;
+    }
     if (/^DROP\s+TABLE\b/i.test(text))
         return 'drop-table';
     if (/^DROP\s+SCHEMA\b/i.test(text))