turbine-orm 0.48.0 → 0.49.0

package/README.md

@@ -14,39 +14,44 @@ Every TS ORM now resolves nested relations in a single `json_agg` query — Pris
 
 1. **Read-only-by-default Studio your DBA will approve.** `npx turbine studio` spins up a loopback-bound web UI with 192-bit auth tokens, `BEGIN READ ONLY` transactions, and (since v0.19) no raw-SQL surface at all: queries are composed in the ORM's own validated builder. In the default mode the write endpoints do not exist and every transaction is read-only at the database level; edits require an explicit `--write` opt-in per launch, and every edit is addressed by its full primary key (never a predicate).
 2. **PII-safe error messages.** Turbine errors show WHERE keys, not values. A `UniqueConstraintError` says which column violated the constraint — never the actual user data. Safe to log, safe to surface to monitoring, no scrubbing needed.
-3. **One runtime dependency (`pg`).** No engine binary, no WASM, no adapter packages to keep in lockstep. The main entry's **import graph** is ~53 kB brotli (edge ~40 kB) with `pg` external (that is the client footprint your bundler sees, not the dual ESM+CJS install size on disk, ~3 MB). Prisma 7 dropped its Rust query engine, but its client still ships a TypeScript/WASM query compiler: a ~1.6 MB bundle, down from the ~14 MB Rust-era client.
+3. **One runtime dependency (`pg`).** No engine binary, no WASM, no adapter packages to keep in lockstep. The main entry's **import graph** is ~59 kB brotli (edge ~44 kB) with `pg` external (that is the client footprint your bundler sees, not the dual ESM+CJS install size on disk, ~3 MB). Prisma 7 dropped its Rust query engine, but its client still ships a TypeScript/WASM query compiler: a ~1.6 MB bundle, down from the ~14 MB Rust-era client.
 4. **SQL-first migrations with drift detection.** Write real SQL. SHA-256 checksums catch modified migration files. `pg_try_advisory_lock()` prevents concurrent runs. Each migration in its own transaction. No shadow database, no magic DSL.
 5. **Edge-native — one import swap.** `turbineHttp(pool, SCHEMA)` — same API on Neon, Vercel Postgres, Cloudflare Hyperdrive, Supabase. No WASM bundle, no adapter package, no separate serverless build.
 6. **Pipeline batching via wire protocol.** Real Parse/Bind/Execute pipeline — not queries wrapped in a transaction. N independent queries in one round-trip.
 
 See [How It Works](#how-it-works) for the `json_agg` query strategy itself, but the query strategy isn't why you'd pick Turbine. The safety bundle above is: a Studio that is read-only unless you explicitly opt in to writes, PII columns that stay out of results until asked for, errors that never leak data, one dependency, and checksummed migrations.
 
-**New in 0.28.0:** [global filters](https://turbineorm.dev/global-filters) for soft-delete and multi-tenancy · [read replicas](https://turbineorm.dev/read-replicas) with a `$primary()` escape hatch · a read-only [MCP server](https://turbineorm.dev/mcp) for AI agents · [seed-as-code](https://turbineorm.dev/seeding) and a non-interactive `migrate deploy` for CI · [Zod generation](https://turbineorm.dev/zod) · read-only [views & generated columns](https://turbineorm.dev/views) · `NULLS FIRST/LAST` ordering, relation `_count`, and ordering by a relation · schema referential actions, enums, array, `vector`, and check constraints.
+**Beyond the safety bundle, what ships today:** [global filters](https://turbineorm.dev/global-filters) for soft-delete and multi-tenancy · [read replicas](https://turbineorm.dev/read-replicas) with a `$primary()` escape hatch · a read-only [MCP server](https://turbineorm.dev/mcp) for AI agents · [seed-as-code](https://turbineorm.dev/seeding) and a non-interactive `migrate deploy` for CI · [Zod generation](https://turbineorm.dev/zod) · read-only [views & generated columns](https://turbineorm.dev/views) · [optional SQLite / MySQL / SQL Server / PowDB engines](https://turbineorm.dev/engines) behind subpath exports · a [Prisma migration toolkit](https://turbineorm.dev/migrate-from-prisma) (schema mapper plus a runtime compat adapter) · a cost-aware index advisor in [`turbine doctor`](https://turbineorm.dev/cli#turbine-doctor).
 
-## Benchmarks
-
-Tested against **Prisma 7.6** (adapter-pg, relationJoins preview on) and **Drizzle 0.45** (relational queries) on a **local PostgreSQL 17.9** database over a Unix socket. 200 iterations, 20 warmup, Node v24. Same schema, same data (1K users, 10K posts, 50K comments), same connection pool config. _Measured 2026-07-14 on turbine-orm 0.32.0 (Apple Silicon MacBook Pro, macOS). A local socket has no network round-trip, so these numbers are sub-millisecond and are **not** comparable to the earlier pooled-Neon table: they isolate per-query overhead instead of hiding it behind ~35 ms of network latency. See [`benchmarks/RESULTS.md`](./benchmarks/RESULTS.md) to reproduce._
+Per-release detail lives in the [CHANGELOG](./CHANGELOG.md) and at [turbineorm.dev/changelog](https://turbineorm.dev/changelog).
 
-| Scenario | Turbine | Prisma 7 | Drizzle 0.45 |
-|---|---|---|---|
-| findMany, 100 users (flat) | **0.22 ms** | 0.53 ms | 0.34 ms |
-| findMany, 50 users + posts (L2) | 2.41 ms | 4.63 ms | **1.82 ms** |
-| findMany, 10 users → posts → comments (L3) | 1.13 ms | 3.69 ms | **1.01 ms** |
-| findUnique, single user by PK | **0.06 ms** | 0.11 ms | 0.09 ms |
-| findUnique, user + posts + comments (L3) | **0.18 ms** | 0.43 ms | 0.30 ms |
-| count, all users | **0.06 ms** | 0.08 ms | 0.07 ms |
-| stream, iterate 50K rows (batch 1000) | 58.6 ms | 69.7 ms | **48.9 ms** |
-| atomic increment, `view_count + 1` | 0.13 ms | 0.23 ms | **0.11 ms** |
-| pipeline, 5-query batch | **0.20 ms** | 0.61 ms | 0.58 ms |
-| hot findUnique, 500x same shape | **0.05 ms** | 0.09 ms | 0.10 ms |
+## Benchmarks
 
-**Over a local socket the network floor disappears, so per-query overhead becomes the whole signal.** The picture that emerges (stable across two full runs):
+Tested against **Prisma 7.9.0** (`@prisma/adapter-pg`) and **Drizzle 0.45.2** (relational queries) on a **local PostgreSQL 17.9** database over a Unix socket. 200 iterations, 20 warmup, Node v24.18.0. Same schema, same data (1K users, 10K posts, 50K comments), same connection pool config. _Measured 2026-07-21 on turbine-orm 0.39.0 (Apple Silicon MacBook Pro, macOS); the harness has not been re-run since, so these are not 0.48.0 numbers. A local socket has no network round-trip, so these numbers are sub-millisecond and are **not** comparable to the earlier pooled-Neon table: they isolate per-query overhead instead of hiding it behind ~35 ms of network latency. See [`benchmarks/RESULTS.md`](./benchmarks/RESULTS.md) to reproduce._
 
-- **Turbine leads flat reads, findUnique, count, pipeline, and the hot path.** SQL template caching and prepared statements keep its per-call overhead lowest on simple and repeated-shape queries, and its real Postgres pipeline protocol (one TCP flush for 5 queries) runs the dashboard batch ~3x faster than Prisma's or Drizzle's sequential transaction.
-- **Drizzle leads nested reads (L2), streaming, and atomic increment.** Its relational query builder emits tighter SQL for the posts/comments joins, and its keyset pagination drains 50K rows fastest. Turbine's `json_agg` nesting is close behind and still 1.9x to 3.3x ahead of Prisma on the same L2/L3 shapes. L3 is a genuine Turbine/Drizzle near-tie that flips between runs.
-- **Prisma trails on every scenario here.** Its engine-less client's per-query work is no longer masked by network latency; on a pooled remote database (the regime we measured previously) these same deltas compress back into the noise floor.
+Prisma's nested scenarios run on its **`join`** load strategy: `benchmarks/prisma/schema.prisma` enables the `relationJoins` preview feature, which (per Prisma's docs) makes `join` the client-wide default, and the harness never overrides `relationLoadStrategy` on a query. Without that flag Prisma would fall back to its per-relation `query` strategy and lose the nested scenarios by a wider margin.
 
-Net: on a local socket Turbine wins 6 of 10 scenarios, loses L2 / streaming / atomic increment to Drizzle, and trades the L3 lead run-to-run. It is competitive-to-ahead across the board rather than a clean sweep, and the honest takeaway is unchanged: performance is close enough that the real reasons to choose Turbine are elsewhere. **One dependency and no WASM** (vs Prisma 7's ~1.6 MB TypeScript/WASM query compiler), the **only read-only-by-default Studio** in the TS ORM ecosystem, **PII-safe error messages** that never leak user data, and **SQL-first migrations** with SHA-256 drift detection. Deep type inference through `with` clauses works end-to-end: write `db.users.findMany({ with: { posts: { with: { comments: true } } } })` and `users[0].posts[0].comments[0].body` autocompletes, with no manual assertion and no helper annotation.
+| Scenario | Turbine | Prisma 7.9 | Drizzle 0.45 |
+|---|---|---|---|
+| findMany, 100 users (flat) | **0.29 ms** | 0.37 ms | 0.39 ms |
+| findMany, 50 users + posts (L2) | 2.86 ms | 4.64 ms | **2.39 ms** |
+| findMany, 10 users → posts → comments (L3) *(near-tie)* | 1.55 ms | 4.04 ms | **1.32 ms** |
+| findUnique, single user by PK | **0.06 ms** | 0.12 ms | 0.10 ms |
+| findUnique, user + posts + comments (L3) | **0.18 ms** | 0.45 ms | 0.31 ms |
+| count, all users *(near-tie)* | **0.05 ms** | 0.08 ms | 0.06 ms |
+| stream, iterate 50K rows (batch 1000) *(near-tie)* | **60.7 ms** | 68.8 ms | 65.8 ms |
+| atomic increment, `view_count + 1` *(near-tie)* | **0.14 ms** | 0.19 ms | 0.19 ms |
+| pipeline, 5-query batch | **0.20 ms** | 0.45 ms | 0.41 ms |
+| hot findUnique, 500x same shape | **0.03 ms** | 0.06 ms | 0.08 ms |
+
+**Over a local socket the network floor disappears, so per-query overhead becomes the whole signal.** The picture that emerges across two full runs:
+
+- **Turbine leads flat reads, both findUnique shapes, pipeline, and the hot path.** SQL template caching and prepared statements keep its per-call overhead lowest on simple and repeated-shape queries, and its real Postgres pipeline protocol (one TCP flush for 5 queries) runs the dashboard batch ~2x faster than Prisma's or Drizzle's sequential transaction.
+- **Drizzle leads nested reads (L2).** Its relational query builder emits tighter SQL for the posts/comments joins. Turbine's `json_agg` nesting is close behind and still 1.6x to 2.6x ahead of Prisma on the same L2/L3 shapes on this run.
+- **Four scenarios are near-ties.** L3 nested, count, streaming, and atomic increment each flipped winner between the two runs. Treat them as within noise on this host rather than a lead for either side.
+- **Prisma trails Turbine on every scenario here.** It edges out Drizzle on the flat read and ties it on the atomic increment, but is behind Turbine on all ten. Its engine-less client's per-query work is no longer masked by network latency; on a pooled remote database (the regime we measured previously) these same deltas compress back into the noise floor. Prisma 7.9 is a real improvement on 7.6 (flat reads ~30% faster, the pipeline batch ~26%).
+
+Net: on a local socket Turbine takes five scenarios outright, loses L2 to Drizzle, and trades four more run-to-run. It is competitive-to-ahead across the board rather than a clean sweep, and the honest takeaway is unchanged: performance is close enough that the real reasons to choose Turbine are elsewhere. **One dependency and no WASM** (vs Prisma 7's ~1.6 MB TypeScript/WASM query compiler), the **only read-only-by-default Studio** in the TS ORM ecosystem, **PII-safe error messages** that never leak user data, and **SQL-first migrations** with SHA-256 drift detection. Deep type inference through `with` clauses works end-to-end: write `db.users.findMany({ with: { posts: { with: { comments: true } } } })` and `users[0].posts[0].comments[0].body` autocompletes, with no manual assertion and no helper annotation.
 
 > Full analysis with p50/p95/p99 and methodology notes: [`benchmarks/RESULTS.md`](./benchmarks/RESULTS.md).
 > Reproduce: `cd benchmarks && npm install && npx prisma generate && DATABASE_URL=... npx tsx bench.ts`
@@ -404,21 +409,30 @@ db.$use(async (params, next) => {
 
 > **Warning:** `params.args` is a read-only snapshot — mutating it does not change the executed SQL. The query is fully built and parameterized before middleware runs.
 
-Because middleware can't rewrite queries, cross-cutting filters like **soft deletes** belong in the query itself — either explicitly or via a small scoped helper:
+Middleware can't rewrite queries, so cross-cutting predicates like **soft deletes** and **multi-tenancy** belong to [global filters](https://turbineorm.dev/global-filters) instead. A global filter is a `WhereClause` that Turbine `AND`-merges into the compiled `WHERE` of every query on a table: reads, the relation subqueries that target it, and the predicate of `update` / `delete` / `upsert`. `create` and `createMany` are never filtered, since a new row has nothing to scope.
 
 ```typescript
-import type { WhereClause } from 'turbine-orm';
-
-// Explicit filter
-const users = await db.users.findMany({ where: { deletedAt: null } });
+const db = turbine({
+  connectionString: process.env.DATABASE_URL,
+  globalFilters: {
+    // Soft delete (static)
+    posts: { deletedAt: null },
+    users: { deletedAt: null },
+    // Multi-tenancy: a function is evaluated every time a query is built,
+    // so a closure over per-request state gives you request-scoped isolation
+    orders: () => ({ tenantId: currentTenant() }),
+  },
+});
 
-// Scoped helper that always applies the filter
-const activeUsers = (where: WhereClause<User> = {}) =>
-  db.users.findMany({ where: { ...where, deletedAt: null } });
+await db.posts.findMany();
+// SELECT ... FROM "posts" WHERE "deleted_at" IS NULL
 
-const rows = await activeUsers({ orgId: 1 });
+await db.users.findMany({ where: { role: 'admin' } });
+// SELECT ... FROM "users" WHERE "role" = $1 AND "deleted_at" IS NULL
 ```
 
+Values are always parameterized. Opt a single query out with `skipGlobalFilters: true` (or a table-name array). Note that a global filter does **not** satisfy the empty-`where` guard: an `update` or `delete` with no `where` of its own still throws unless you pass `allowFullTableScan: true`.
+
 ### Error handling
 
 Turbine throws typed errors you can catch programmatically:
@@ -709,7 +723,7 @@ npx turbine studio --port 5173 --host 127.0.0.1 --no-open
 - **Saved queries.** Named builder queries persisted to `.turbine/studio-queries.json` — share them across runs without committing them.
 - **Cmd+K command palette.** Jump to any table, tab, or saved query in one keystroke.
 - **Full-text search across rows.** The Data tab supports substring search across every text column of the current table.
-- **PII redaction.** Columns tagged `pii: true` in the schema render as a redaction placeholder in every tab. `--show-pii` reveals them, with a loud startup warning.
+- **PII redaction.** Columns tagged `pii: true` in the schema render as a redaction placeholder in every tab. `--show-pii` reveals them, with a loud startup warning. Tags are a code-first declaration (introspection never infers one), so Studio reads them from the generated metadata in your `out` directory; if it finds none it says so at startup rather than implying a protection it cannot apply.
 - **Opt-in write mode.** `--write` enables insert/update/delete from the Data tab (single rows, multi-select delete, and paste-to-insert batches), gated per row by the full primary key, compiled by the same validated builders, and flagged with a persistent WRITE MODE banner. Read-only stays the default on every launch.
 
 **Security posture (read-only by default)**
@@ -881,12 +895,17 @@ const db = await turbineMssql('mssql://sa:Passw0rd!@localhost:1433/app', SCHEMA)
 ```ts
 // PowDB — async; embedded (in-process) or networked. Schema is code-defined.
 import { turbinePowDB } from 'turbine-orm/powdb';
+import { schemaDefToMetadata } from 'turbine-orm';
 import { schema } from './schema.js'; // defineSchema({...})
 
-// Embedded, in-process — syncMode 'normal' makes writes beat SQLite:
-const db = await turbinePowDB({ embedded: './data', syncMode: 'normal' }, schema);
+// PowDB has no introspection-driven `turbine generate`, so derive the runtime
+// SchemaMetadata from the code-first definition.
+const SCHEMA = schemaDefToMetadata(schema);
+
+// Embedded, in-process. syncMode 'normal' moves fsync off the commit path:
+const db = await turbinePowDB({ embedded: './data', syncMode: 'normal' }, SCHEMA);
 // …or networked against a running powdb-server:
-// const db = await turbinePowDB('powdb://127.0.0.1:7070', schema);
+// const db = await turbinePowDB('powdb://127.0.0.1:7070', SCHEMA);
 ```
 
 Migrating from Prisma? `turbine migrate-from-prisma` emits a typed `PRISMA_MAP`, and the
@@ -976,11 +995,11 @@ Turbine maps Postgres types to TypeScript:
 |---|---|---|---|---|
 | **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)** | ~53 kB | ~1.6 MB client (TS/WASM compiler) | ~7 KB core | small |
+| **Main bundle (brotli)** | ~59 kB | ~1.6 MB client (TS/WASM compiler) | ~7 KB core | small |
 | **Studio** | Read-only, 192-bit auth | Full CRUD, cloud-hosted | Free; hosted Gateway paid | 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, ~40 kB brotli | Driver adapter + WASM compiler | Native | Native |
+| **Edge runtime** | One import swap, ~44 kB brotli | 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, shallow inference | 1 query, `relations()` re-declaration | Manual (`jsonArrayFrom`) |
@@ -997,8 +1016,8 @@ All three ORMs now do single-query nested loads — that's table stakes. Turbine
 
 Turbine is focused and opinionated. Here's what it doesn't do:
 
-- **Postgres-first.** PostgreSQL is the default and primary target — going deep on one database is what enables the safety bundle and the edge-runtime story. SQLite, MySQL 8, and SQL Server engines are available as additive subpath exports (see [Database engines](#database-engines)), but several flagship features (pgvector, LISTEN/NOTIFY, RLS `sessionContext`) are Postgres-only and throw `UnsupportedFeatureError` elsewhere.
-- **Full-text search** is available via a `search` filter — `where: { title: { search: 'hello & world', config: 'english' } }` compiles to a parameterized `to_tsvector(...) @@ to_tsquery(...)`. For advanced ranking (`ts_rank`, weighted vectors) use `db.raw`.
+- **Postgres-first.** PostgreSQL is the default and primary target — going deep on one database is what enables the safety bundle and the edge-runtime story. SQLite, MySQL 8, and SQL Server engines are available as additive subpath exports (see [Database engines](#database-engines)), but several flagship features (pgvector, LISTEN/NOTIFY, RLS `sessionContext`, full-text `search`, array-column filters, `groupBy({ distinctOn })`) are Postgres-only and throw `UnsupportedFeatureError` elsewhere.
+- **Full-text search** is available via a `search` filter — `where: { title: { search: 'hello & world', config: 'english' } }` compiles to a parameterized `to_tsvector(...) @@ to_tsquery(...)`. PostgreSQL only: the other engines throw `UnsupportedFeatureError` (`TURBINE_E017`) rather than degrade to a `LIKE`. For advanced ranking (`ts_rank`, weighted vectors) use `db.raw`.
 - **Large nested result sets.** Nested results are materialized server-side in PostgreSQL memory. For relations with 10K+ rows, always use `limit` in your `with` clause — or stream the parents with `findManyStream` and resolve children per-row.
 
 ## Examples

package/dist/cjs/cli/destructive.js

@@ -11,10 +11,16 @@
  * Deliberately conservative in BOTH directions:
  *   - comments and string literals are stripped first, so `-- DROP TABLE foo`
  *     or `INSERT ... VALUES ('DROP TABLE x')` never false-positive;
- *   - anything that removes rows, columns, tables, or schemas — or rewrites a
- *     column's type (a potentially lossy cast) — is flagged. `DROP INDEX`,
+ *   - anything that removes rows, columns, tables, or schemas, or rewrites a
+ *     column's type (a potentially lossy cast), is flagged. `DROP INDEX`,
  *     `DROP CONSTRAINT`, and `DROP TRIGGER` are NOT flagged (recreatable
  *     structures; no row data lost).
+ *
+ * Row removal hides in more than a leading `DELETE`, so the scan also covers:
+ * 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, and an `UPDATE` whose only WHERE sits inside
+ * a subquery (which restricts nothing).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DESTRUCTIVE_KIND_LABEL = void 0;
@@ -23,14 +29,25 @@ exports.scanDestructiveSql = scanDestructiveSql;
 exports.DESTRUCTIVE_KIND_LABEL = {
     'drop-table': 'drops a table and ALL its rows',
     'drop-schema': 'drops an entire schema',
+    'drop-database': 'drops an entire database and everything in it',
+    'drop-owned': 'drops every object owned by a role, and their rows',
+    'drop-matview': 'drops a materialized view and its stored rows',
     'drop-column': 'drops a column and its data in every row',
     truncate: 'deletes every row',
     delete: 'deletes rows',
     'update-without-where': 'rewrites every row (no WHERE clause)',
     'alter-column-type': 'rewrites a column type (cast may truncate or fail)',
+    'merge-delete': 'deletes matched rows (MERGE ... THEN DELETE)',
 };
+/**
+ * A dollar-quote tag. Postgres allows digits after the first character
+ * (`$do1$`), so a tag regex that stops at letters reads the body as code and
+ * misses everything inside it. Same shape as the splitter in `migrate.ts`.
+ */
+const DOLLAR_TAG = /^\$([A-Za-z_][A-Za-z_0-9]*)?\$/;
 /** Strip -- line comments, C-style block comments, and quoted literals. */
 function stripCommentsAndStrings(sql) {
+    const blocks = [];
     let out = '';
     let i = 0;
     while (i < sql.length) {
@@ -45,10 +62,17 @@ function stripCommentsAndStrings(sql) {
             out += ' ';
         }
         else if (sql[i] === "'") {
-            // single-quoted literal ('' escapes a quote)
+            // Single-quoted literal. `''` always escapes a quote; inside an E-string
+            // (`E'...'`) a backslash escapes the next character too, so `E'a\'b'` is
+            // ONE literal. Without the E-string case the scan ends the literal at the
+            // backslash-quote and treats the rest of the file as code, which
+            // (worse) then hides every following statement from the guard.
+            const escapes = isEscapeStringPrefix(sql, i);
             let j = i + 1;
             while (j < sql.length) {
-                if (sql[j] === "'" && sql[j + 1] === "'")
+                if (escapes && sql[j] === '\\')
+                    j += 2;
+                else if (sql[j] === "'" && sql[j + 1] === "'")
                     j += 2;
                 else if (sql[j] === "'")
                     break;
@@ -58,10 +82,28 @@ function stripCommentsAndStrings(sql) {
             i = j + 1;
             out += "''";
         }
-        else if (sql[i] === '$' && /^\$[a-zA-Z_]*\$/.test(sql.slice(i))) {
+        else if (sql[i] === '"') {
+            // Quoted identifier. Kept VERBATIM (rules match on identifiers), but it
+            // has to be consumed as one token: an apostrophe inside a quoted name
+            // (`"customer's_orders"`) would otherwise open a string literal and hide
+            // every statement after it from the scan.
+            let j = i + 1;
+            while (j < sql.length) {
+                if (sql[j] === '"' && sql[j + 1] === '"')
+                    j += 2;
+                else if (sql[j] === '"')
+                    break;
+                else
+                    j++;
+            }
+            out += sql.slice(i, Math.min(j + 1, sql.length));
+            i = j + 1;
+        }
+        else if (sql[i] === '$' && DOLLAR_TAG.test(sql.slice(i))) {
             // dollar-quoted literal ($$...$$ / $tag$...$tag$)
-            const tag = sql.slice(i).match(/^\$[a-zA-Z_]*\$/)?.[0] ?? '$$';
+            const tag = sql.slice(i).match(DOLLAR_TAG)?.[0] ?? '$$';
             const end = sql.indexOf(tag, i + tag.length);
+            blocks.push({ at: out.length, body: sql.slice(i + tag.length, end === -1 ? sql.length : end) });
             i = end === -1 ? sql.length : end + tag.length;
             out += "''";
         }
@@ -70,7 +112,23 @@ function stripCommentsAndStrings(sql) {
             i++;
         }
     }
-    return out;
+    return { text: out, blocks };
+}
+/**
+ * True when the quote at `quoteAt` opens an E-string (`E'...'`), where a
+ * backslash escapes the next character. The preceding `E` must not itself be
+ * part of an identifier, so `some_table'` never turns the following literal
+ * into an E-string. Ordinary literals are left alone on purpose: with the
+ * modern `standard_conforming_strings = on` default, `'a\'` IS a complete
+ * string. Mirrors the same-named helper in `migrate.ts`; kept local so this
+ * module stays a pure leaf with no CLI imports of its own.
+ */
+function isEscapeStringPrefix(sql, quoteAt) {
+    const prev = sql[quoteAt - 1];
+    if (prev !== 'E' && prev !== 'e')
+        return false;
+    const before = sql[quoteAt - 2];
+    return before === undefined || !/[A-Za-z0-9_$"]/.test(before);
 }
 /** Unquote a "quoted" identifier for display. */
 const ident = (raw) => (raw ?? '?').replace(/^"|"$/g, '');
@@ -87,15 +145,34 @@ const RULES = [
         regex: new RegExp(String.raw `^DROP\s+SCHEMA\s+(IF\s+EXISTS\s+)?${IDENT}`, 'i'),
         target: (m) => ident(m[2]),
     },
+    {
+        kind: 'drop-matview',
+        regex: new RegExp(String.raw `^DROP\s+MATERIALIZED\s+VIEW\s+(IF\s+EXISTS\s+)?${IDENT}`, 'i'),
+        target: (m) => (m[4] ? `${ident(m[2])}.${ident(m[4])}` : ident(m[2])),
+    },
+    {
+        kind: 'drop-database',
+        regex: new RegExp(String.raw `^DROP\s+DATABASE\s+(IF\s+EXISTS\s+)?${IDENT}`, 'i'),
+        target: (m) => ident(m[2]),
+    },
+    {
+        // `DROP OWNED BY role` removes every object that role owns, rows included.
+        kind: 'drop-owned',
+        regex: new RegExp(String.raw `^DROP\s+OWNED\s+BY\s+${IDENT}`, 'i'),
+        target: (m) => ident(m[1]),
+    },
     {
         kind: 'truncate',
         regex: new RegExp(String.raw `^TRUNCATE\s+(TABLE\s+)?(ONLY\s+)?${IDENT}`, 'i'),
         target: (m) => (m[5] ? `${ident(m[3])}.${ident(m[5])}` : ident(m[3])),
     },
     {
+        // `COLUMN` is OPTIONAL in Postgres: `ALTER TABLE t DROP email` drops the
+        // column and its data exactly like the spelled-out form. The lookahead
+        // excludes the other `DROP <thing>` sub-actions, none of which lose rows.
         kind: 'drop-column',
-        regex: new RegExp(String.raw `^ALTER\s+TABLE\s+(IF\s+EXISTS\s+)?(ONLY\s+)?${IDENT}[\s\S]*?\bDROP\s+COLUMN\s+(IF\s+EXISTS\s+)?${IDENT}`, 'i'),
-        target: (m) => `${ident(m[3])}.${ident(m[7])}`,
+        regex: new RegExp(String.raw `^ALTER\s+TABLE\s+(IF\s+EXISTS\s+)?(ONLY\s+)?${IDENT}[\s\S]*?\bDROP\s+(?!CONSTRAINT\b|DEFAULT\b|NOT\b|IDENTITY\b|EXPRESSION\b)(COLUMN\s+)?(IF\s+EXISTS\s+)?${IDENT}`, 'i'),
+        target: (m) => `${ident(m[3])}.${ident(m[8])}`,
     },
     {
         kind: 'alter-column-type',
@@ -105,15 +182,130 @@ const RULES = [
     {
         kind: 'delete',
         regex: new RegExp(String.raw `^DELETE\s+FROM\s+(ONLY\s+)?${IDENT}`, 'i'),
-        target: (m) => ident(m[2]),
+        target: (m) => (m[4] ? `${ident(m[2])}.${ident(m[4])}` : ident(m[2])),
+    },
+    {
+        // 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[\s\S]*?\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.
         kind: 'update-without-where',
         regex: new RegExp(String.raw `^UPDATE\s+(ONLY\s+)?${IDENT}\b`, 'i'),
-        target: (m) => ident(m[2]),
-        also: (stmt) => !/\bWHERE\b/i.test(stmt),
+        target: (m) => (m[4] ? `${ident(m[2])}.${ident(m[4])}` : ident(m[2])),
+        also: (stmt) => !hasTopLevelWhere(stmt),
     },
 ];
+/** True when the statement has a `WHERE` outside every parenthesized group. */
+function hasTopLevelWhere(stmt) {
+    const re = /[()]|\bWHERE\b/gi;
+    let depth = 0;
+    let m = re.exec(stmt);
+    while (m !== null) {
+        if (m[0] === '(')
+            depth++;
+        else if (m[0] === ')')
+            depth = Math.max(0, depth - 1);
+        else if (depth === 0)
+            return true;
+        m = re.exec(stmt);
+    }
+    return false;
+}
+/**
+ * A leading CTE list is a prefix, not a statement: `WITH c AS (SELECT 1) DELETE
+ * FROM users` is a plain DELETE that the anchored rules would otherwise skip.
+ * Strip balanced `WITH name AS ( ... )` groups (and their comma-separated
+ * siblings) so the real statement head is what gets matched. The CTE bodies
+ * themselves are handled separately by {@link cteSubstatements}.
+ */
+function stripLeadingCtes(stmt) {
+    if (!/^WITH\b/i.test(stmt))
+        return stmt;
+    let rest = stmt.replace(/^WITH\s+(RECURSIVE\s+)?/i, '');
+    for (;;) {
+        const open = rest.indexOf('(');
+        if (open === -1)
+            return stmt;
+        const close = closingParenIndex(rest, open);
+        rest = rest.slice(close + 1).trimStart();
+        if (rest.startsWith(',')) {
+            rest = rest.slice(1).trimStart();
+            continue;
+        }
+        return rest;
+    }
+}
+/** First matching rule for one candidate fragment, or null. */
+function matchRules(candidate) {
+    for (const rule of RULES) {
+        const m = candidate.match(rule.regex);
+        if (!m)
+            continue;
+        if (rule.also && !rule.also(candidate))
+            continue;
+        return { kind: rule.kind, target: rule.target(m) };
+    }
+    return null;
+}
+/**
+ * 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
+ * at the paren that closes its CTE, so the outer query's WHERE cannot mask a
+ * `WITH u AS (UPDATE t SET ...) SELECT ... WHERE ...`.
+ */
+function cteSubstatements(stmt) {
+    if (!/^WITH\b/i.test(stmt))
+        return [];
+    const out = [];
+    const re = /\(\s*(?=(?:DELETE|UPDATE|INSERT|TRUNCATE|DROP|ALTER|MERGE)\b)/gi;
+    let m = re.exec(stmt);
+    while (m !== null) {
+        const start = m.index + m[0].length;
+        out.push(stmt.slice(start, closingParenIndex(stmt, m.index)));
+        m = re.exec(stmt);
+    }
+    return out;
+}
+/** Index of the `)` closing the `(` at `openAt`, or the end of the string. */
+function closingParenIndex(stmt, openAt) {
+    let depth = 0;
+    for (let i = openAt; i < stmt.length; i++) {
+        if (stmt[i] === '(')
+            depth++;
+        else if (stmt[i] === ')') {
+            depth--;
+            if (depth === 0)
+                return i;
+        }
+    }
+    return stmt.length;
+}
+/** Statements whose dollar-quoted body is executable SQL rather than data. */
+const PROCEDURAL_STATEMENT = /^(DO\b|CREATE\s+(OR\s+REPLACE\s+)?(FUNCTION|PROCEDURE)\b)/i;
+/**
+ * Candidate fragments inside a procedural body (a `DO $$ ... $$` block or a
+ * function source). The body's own string literals are NOT stripped here: the
+ * whole point is dynamic SQL, whose payload lives in a literal
+ * (`EXECUTE 'DROP TABLE users'`). Rules are anchored, so every keyword-leading
+ * position in the body is offered as its own candidate. This deliberately
+ * over-reports (a body that merely mentions "drop table" in a message string is
+ * flagged) in keeping with the module's false-positives-only asymmetry.
+ */
+function proceduralCandidates(body) {
+    const withoutComments = body.replace(/\/\*[\s\S]*?\*\//g, ' ').replace(/--[^\n]*/g, ' ');
+    const out = [];
+    const re = /\b(?:DROP|TRUNCATE|DELETE|ALTER|UPDATE|MERGE)\s/gi;
+    let m = re.exec(withoutComments);
+    while (m !== null) {
+        out.push(withoutComments.slice(m.index));
+        m = re.exec(withoutComments);
+    }
+    return out;
+}
 /**
  * Scan SQL (one file's worth; may contain many `;`-separated statements) and
  * return every statement that can destroy data.
@@ -121,17 +313,40 @@ const RULES = [
 function scanDestructiveSql(sql) {
     const found = [];
     const cleaned = stripCommentsAndStrings(sql);
-    for (const rawStmt of cleaned.split(';')) {
+    let offset = 0;
+    for (const rawStmt of cleaned.text.split(';')) {
+        const start = offset;
+        const end = offset + rawStmt.length;
+        offset = end + 1; // the ';' consumed by split
         const stmt = rawStmt.trim();
         if (!stmt)
             continue;
-        for (const rule of RULES) {
-            const m = stmt.match(rule.regex);
-            if (!m)
+        // Top level, then data-modifying CTEs, then any procedural body this
+        // statement blanked. First match per statement wins, as before.
+        const display = stmt.replace(/\s+/g, ' ');
+        const candidates = [
+            stripLeadingCtes(stmt),
+            ...cteSubstatements(stmt),
+        ].map((text) => ({
+            text,
+            display,
+        }));
+        // Only a DO block / routine body is procedural SQL. A dollar-quoted literal
+        // used as DATA (`INSERT ... VALUES ($$DELETE FROM x$$)`) stays a literal.
+        const procedural = PROCEDURAL_STATEMENT.test(stmt);
+        for (const block of procedural ? cleaned.blocks : []) {
+            if (block.at < start || block.at >= end)
                 continue;
-            if (rule.also && !rule.also(stmt))
+            for (const text of proceduralCandidates(block.body)) {
+                // The body was blanked in `display`, so name the fragment that matched.
+                candidates.push({ text, display: `${display} [in block: ${text.replace(/\s+/g, ' ').slice(0, 60)}]` });
+            }
+        }
+        for (const candidate of candidates) {
+            const hit = matchRules(candidate.text);
+            if (!hit)
                 continue;
-            found.push({ statement: stmt.replace(/\s+/g, ' '), kind: rule.kind, target: rule.target(m) });
+            found.push({ statement: candidate.display, kind: hit.kind, target: hit.target });
             break;
         }
     }

package/dist/cjs/cli/index.js

@@ -2168,9 +2168,14 @@ async function cmdDoctor(args, config) {
     const unusedRan = args.unused === true;
     const auditRan = args.audit === true;
     const minScans = args.minScans;
-    const unused = unusedRan ? (0, index_stats_js_1.findUnusedIndexes)(snapshot, { minScans }) : [];
+    // Never suggest dropping an index that still serves a relation probe: the
+    // missing-index half of this very report demands it.
+    const relationProbes = (0, index_advisor_js_1.collectRelationProbeColumns)(schema);
+    const unused = unusedRan ? (0, index_stats_js_1.findUnusedIndexes)(snapshot, { minScans, relationProbes }) : [];
     const redundant = unusedRan ? (0, index_stats_js_1.findRedundantIndexes)(snapshot) : [];
-    const audit = auditRan ? (0, index_stats_js_1.auditDoctorIndexes)(snapshot, (0, index_advisor_js_1.collectDoctorProbeIndexNames)(schema), { minScans }) : [];
+    const audit = auditRan
+        ? (0, index_stats_js_1.auditDoctorIndexes)(snapshot, (0, index_advisor_js_1.collectDoctorProbeIndexNames)(schema), { minScans, relationProbes })
+        : [];
     const subtract = { unusedRan, auditRan, minScans, unused, redundant, audit };
     if (jsonMode) {
         spinner?.stop();
@@ -2240,15 +2245,19 @@ function buildDoctorJson(ctx) {
         })),
         invalidIndexes: ctx.invalid,
     };
-    // Additive: the drop-suggestion arrays appear only when --unused / --audit ran.
-    if (ctx.subtract.unusedRan) {
-        out.unused = ctx.subtract.unused;
-        out.redundant = ctx.subtract.redundant;
-        out.invalid = ctx.invalid;
-    }
-    if (ctx.subtract.auditRan) {
-        out.audit = ctx.subtract.audit;
-    }
+    // The keys below are ALWAYS present under `schemaVersion: 1`: a declared
+    // schema version that changes shape by flag forces every consumer to write
+    // `json.unused ?? []`. Which subtraction scans actually ran is reported as
+    // data (`ran`), not as the presence or absence of a key.
+    out.subtraction = {
+        unusedRan: ctx.subtract.unusedRan,
+        auditRan: ctx.subtract.auditRan,
+        minScans: ctx.subtract.minScans ?? null,
+    };
+    out.unused = ctx.subtract.unusedRan ? ctx.subtract.unused : [];
+    out.redundant = ctx.subtract.unusedRan ? ctx.subtract.redundant : [];
+    out.audit = ctx.subtract.auditRan ? ctx.subtract.audit : [];
+    out.invalid = ctx.invalid;
     return out;
 }
 async function renderDoctorHuman(ctx) {
@@ -2312,6 +2321,15 @@ function renderUnusedCaveats(minScans, snapshot) {
     console.log(`  ${(0, ui_js_1.dim)(`Caveats: counters zero on a stats reset or crash; a read replica's index scans NEVER feed`)}`);
     console.log(`  ${(0, ui_js_1.dim)(`the primary's counters, so an index only a replica uses looks dead here. Threshold: idx_scan < ${threshold}.`)}`);
     console.log(`  ${(0, ui_js_1.dim)('Primary-key, unique, exclusion, and replica-identity indexes are excluded. Nothing here is auto-dropped.')}`);
+    console.log(`  ${(0, ui_js_1.dim)('Indexes that still serve a relation Turbine probes are withheld: this report demands those.')}`);
+    // The cost section refuses to SCORE on stats this young; prescribing drops off
+    // the same counters in the next section would be the report contradicting
+    // itself. Say so where the advice is, not only where the scoring is.
+    if (snapshot.statsAgeDays !== null && snapshot.statsAgeDays < index_stats_js_1.STATS_THRESHOLDS.minStatsAgeDays) {
+        console.log(`  ${(0, ui_js_1.yellow)(`Statistics are only ${ageLabel} old, below the ${index_stats_js_1.STATS_THRESHOLDS.minStatsAgeDays}d floor this report uses to score cost.`)}`);
+        console.log(`  ${(0, ui_js_1.yellow)('Treat everything below as a list to investigate, not advice to act on: an index your')}`);
+        console.log(`  ${(0, ui_js_1.yellow)('workload simply has not reached yet looks identical to a dead one.')}`);
+    }
     (0, ui_js_1.newline)();
 }
 /** doctor --unused: never-scanned indexes with DROP suggestions (report-only). */
@@ -2323,6 +2341,10 @@ function renderUnusedIndexes(unused, minScans, snapshot) {
     renderUnusedCaveats(minScans, snapshot);
     for (const u of unused) {
         console.log(`  ${(0, ui_js_1.yellow)(ui_js_1.symbols.warning)} ${(0, ui_js_1.bold)((0, ui_js_1.cyan)(u.table))} ${(0, ui_js_1.dim)(`(${u.columns.join(', ') || '?'})`)}  ${(0, ui_js_1.gray)(`${u.indexName} · ${u.idxScan} scans · ${(0, index_stats_js_1.formatBytes)(u.sizeBytes)}`)}`);
+        // A functional / partial / non-btree index is not a plain `(col)` rebuild:
+        // say what it actually is before anyone runs the DROP.
+        if (u.caveat)
+            console.log(`    ${(0, ui_js_1.dim)(ui_js_1.symbols.tee)} ${(0, ui_js_1.yellow)(u.caveat)}`);
         console.log(`    ${(0, ui_js_1.dim)(ui_js_1.symbols.teeEnd)} ${(0, ui_js_1.green)(u.dropSql)}`);
         (0, ui_js_1.newline)();
     }
@@ -2357,7 +2379,13 @@ function renderDoctorAudit(audit, minScans, snapshot) {
         if (a.ambiguous) {
             console.log(`    ${(0, ui_js_1.dim)(ui_js_1.symbols.tee)} ${(0, ui_js_1.dim)('the 63-byte name maps to more than one probe column set; confirm before dropping')}`);
         }
-        console.log(`    ${(0, ui_js_1.dim)(ui_js_1.symbols.teeEnd)} ${(0, ui_js_1.green)(a.dropSql)}`);
+        if (a.stillProbed) {
+            console.log(`    ${(0, ui_js_1.dim)(ui_js_1.symbols.teeEnd)} ${(0, ui_js_1.dim)('kept: a relation in your schema still probes these columns, so dropping it would')}`);
+            console.log(`      ${(0, ui_js_1.dim)('reappear as a missing-index finding in this same report.')}`);
+        }
+        else if (a.dropSql) {
+            console.log(`    ${(0, ui_js_1.dim)(ui_js_1.symbols.teeEnd)} ${(0, ui_js_1.green)(a.dropSql)}`);
+        }
         (0, ui_js_1.newline)();
     }
     console.log(`  ${(0, ui_js_1.dim)('Consider dropping the ones you confirm are unused. Nothing here is auto-dropped.')}`);
@@ -2515,6 +2543,7 @@ async function cmdStudio(args, config) {
             write: args.write === true,
             showPii: args.showPii === true,
             demo,
+            metadataDir: config.out,
         });
         spinner.succeed(demo ? 'Demo Studio is running' : 'Studio is running');
     }
@@ -2549,6 +2578,20 @@ async function cmdStudio(args, config) {
             (0, ui_js_1.newline)();
             console.log((0, ui_js_1.warn)('--show-pii is ON. PII-tagged column values are shown UNREDACTED in Studio.'));
         }
+        // PII tags are a code-first declaration; introspection never infers them.
+        // Say plainly whether any reached this session, so nobody assumes a
+        // redaction guarantee that has nothing to act on.
+        if (!args.showPii) {
+            (0, ui_js_1.newline)();
+            if (studio.piiTags && studio.piiTags.applied > 0) {
+                console.log(`  ${(0, ui_js_1.dim)('PII redaction:')} ${studio.piiTags.applied} tagged column(s) from ${(0, ui_js_1.dim)(studio.piiTags.path)}`);
+            }
+            else {
+                console.log((0, ui_js_1.warn)('No PII-tagged columns found, so nothing will be redacted. Tags are declared in code ' +
+                    `(defineSchema \`pii: true\`) and read from generated metadata in ${config.out}; ` +
+                    'introspection alone never infers them. Run `turbine generate` after tagging.'));
+            }
+        }
         (0, ui_js_1.newline)();
         console.log((0, ui_js_1.box)([
             `${(0, ui_js_1.bold)('Turbine Studio')}  ${(0, ui_js_1.dim)(args.write ? 'local UI (WRITE MODE)' : 'local read-only UI')}`,
@@ -2589,6 +2632,7 @@ async function cmdMcp(_args, config) {
         url,
         schema: config.schema,
         migrationsDir: config.migrationsDir,
+        metadataDir: config.out,
         include: config.include.length ? config.include : undefined,
         exclude: config.exclude.length ? config.exclude : undefined,
     });