turbine-orm 0.35.0 → 0.36.0

package/README.md

@@ -1,6 +1,6 @@
 # turbine-orm
 
-The Postgres ORM your DBA will sign off on. A read-only Studio that can't touch prod, errors that never leak PII, one dependency, and checksummed migrations.
+The Postgres ORM your DBA will sign off on. A read-only-by-default Studio, PII-tagged columns that stay out of results until asked for, errors that never leak data, one dependency, and checksummed migrations.
 
 ```
 npm install turbine-orm
@@ -12,14 +12,14 @@ npm install turbine-orm
 
 Every TS ORM now resolves nested relations in a single `json_agg` query — Prisma 7 and Drizzle both ship it, and so does Turbine. That part is table stakes. The reason to reach for Turbine is the **safety bundle**: the boxes a DBA ticks before a query layer goes anywhere near production. It's the only TypeScript ORM that ships all six of these together:
 
-1. **Read-only 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. The only TS ORM Studio that physically cannot mutate your database.
+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; single-row edits require an explicit `--write` opt-in per launch.
 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 ~42 kB brotli (edge ~33 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 ~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.
 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 can't mutate prod, errors that never leak PII, one dependency, and checksummed migrations.
+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.
 
@@ -46,7 +46,7 @@ Tested against **Prisma 7.6** (adapter-pg, relationJoins preview on) and **Drizz
 - **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.
 
-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 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.
+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.
 
 > 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`
@@ -440,7 +440,7 @@ try {
 }
 ```
 
-Error codes: `TURBINE_E001` (NotFound), `TURBINE_E002` (Timeout), `TURBINE_E003` (Validation), `TURBINE_E004` (Connection), `TURBINE_E005` (Relation), `TURBINE_E006` (Migration), `TURBINE_E007` (CircularRelation), `TURBINE_E008` (UniqueConstraint), `TURBINE_E009` (ForeignKey), `TURBINE_E010` (NotNullViolation), `TURBINE_E011` (CheckConstraint), `TURBINE_E012` (Deadlock), `TURBINE_E013` (SerializationFailure), `TURBINE_E014` (Pipeline), `TURBINE_E015` (OptimisticLock), `TURBINE_E016` (ExclusionConstraint), `TURBINE_E017` (UnsupportedFeature — a Postgres-only feature invoked on another engine).
+Error codes: `TURBINE_E001` (NotFound), `TURBINE_E002` (Timeout), `TURBINE_E003` (Validation), `TURBINE_E004` (Connection), `TURBINE_E005` (Relation), `TURBINE_E006` (Migration), `TURBINE_E007` (CircularRelation), `TURBINE_E008` (UniqueConstraint), `TURBINE_E009` (ForeignKey), `TURBINE_E010` (NotNullViolation), `TURBINE_E011` (CheckConstraint), `TURBINE_E012` (Deadlock), `TURBINE_E013` (SerializationFailure), `TURBINE_E014` (Pipeline), `TURBINE_E015` (OptimisticLock), `TURBINE_E016` (ExclusionConstraint), `TURBINE_E017` (UnsupportedFeature: a Postgres-only feature invoked on another engine), `TURBINE_E018` (ReadOnly: a write refused on a read-only database, reason `'snapshot'` | `'rbac'`).
 
 Full reference with `wrapPgError()` translation, retry patterns for `DeadlockError` / `SerializationFailureError`, and safe vs verbose message modes: **[turbineorm.dev/errors](https://turbineorm.dev/errors)**.
 
@@ -614,7 +614,7 @@ Commands:
   seed                         Run seed file
   status                       Show database schema summary
   doctor                       Check relations for missing FK indexes (--fix emits migration)
-  studio                       Launch local read-only Studio web UI
+  studio                       Launch local Studio web UI (read-only; --write opts in to single-row writes)
   mcp                          Start read-only MCP server over JSON-RPC stdio
   observe                      Launch local metrics dashboard (requires TURBINE_OBSERVE_URL)
 
@@ -680,7 +680,7 @@ then `yes`; in CI you must pass `--allow-destructive`. A refused batch applies n
 
 ## Studio
 
-The only Postgres ORM with a Studio your DBA will approve. `turbine studio` launches a local, read-only web UI for exploring your database — no mutations, no writes, and since v0.19 **no raw-SQL surface at all**: every query is composed visually in the ORM and compiled by the same validated query builder your application uses.
+The only Postgres ORM with a Studio your DBA will approve. `turbine studio` launches a local web UI for exploring your database. It is **read-only by default** (no mutations, no writes, every transaction `BEGIN READ ONLY`) and since v0.19 has **no raw-SQL surface at all**: every query is composed visually in the ORM and compiled by the same validated query builder your application uses. Since v0.36, `--write` opts a launch in to single-row insert/update/delete through that same validated builder; without the flag the write endpoints do not exist.
 
 ```bash
 DATABASE_URL=postgres://user:pass@localhost:5432/mydb npx turbine studio
@@ -695,14 +695,16 @@ 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.
+- **Opt-in write mode.** `--write` enables single-row insert/update/delete from the Data tab, 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 design)**
+**Security posture (read-only by default)**
 
-- **No SQL input surface.** There is nothing to inject into — builder requests are validated identifier-by-identifier against the introspected schema, and every value is bound as a `$N` parameter.
+- **No SQL input surface.** There is nothing to inject into: builder requests are validated identifier-by-identifier against the introspected schema, and every value is bound as a `$N` parameter.
 - **Loopback by default** (`127.0.0.1`). Non-loopback `--host` is **refused** unless you pass `--allow-remote` (loud warning when you opt in).
-- **Per-process auth token** — 24 random bytes of hex, stored in a `SameSite=Strict` `HttpOnly` cookie.
-- **Every query runs inside `BEGIN READ ONLY`** with a 30s transaction-local statement timeout (parameterized `set_config`). Writes are physically impossible at the transaction level.
-- **Security headers on every response** — CSP, `X-Content-Type-Options`, `X-Frame-Options: DENY`, `Referrer-Policy: no-referrer` — plus per-session rate limiting and cross-origin refusal.
+- **Per-process auth token**: 24 random bytes of hex, stored in a `SameSite=Strict` `HttpOnly` cookie.
+- **Every read query runs inside `BEGIN READ ONLY`** with a 30s transaction-local statement timeout (parameterized `set_config`). Without `--write`, the write endpoints do not exist (they 404) and writes are impossible at the transaction level; with it, each write runs in its own transaction with the same timeout and schema pinning, requires the row's full primary key, and rejects absent or mismatched `Origin` headers.
+- **Security headers on every response**: nonce-based CSP, `X-Content-Type-Options`, `X-Frame-Options: DENY`, `Referrer-Policy: no-referrer`, plus per-session rate limiting and cross-origin refusal.
 
 ## Observability
 
@@ -944,11 +946,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)** | ~42 kB | ~1.6 MB client (TS/WASM compiler) | ~7 KB core | small |
+| **Main bundle (brotli)** | ~53 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, ~33 kB brotli | Driver adapter + WASM compiler | Native | Native |
+| **Edge runtime** | One import swap, ~40 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`) |
@@ -957,7 +959,7 @@ Turbine maps Postgres types to TypeScript:
 | **LISTEN/NOTIFY** | `$listen` / `$notify` | None | None | None |
 | **Multi-DB** | Postgres-first (+ SQLite/MySQL/MSSQL engines) | PG, MySQL, SQLite, MSSQL | PG, MySQL, SQLite | PG, MySQL, SQLite |
 
-All three ORMs now do single-query nested loads — that's table stakes. Turbine's real differentiators: no engine binary or WASM — just one dependency (`pg`), vs Prisma 7's ~1.6 MB TypeScript/WASM query compiler and required driver adapter; the only read-only Studio in the ecosystem; error messages that never leak PII; and SQL-first migrations with SHA-256 drift detection. See [Benchmarks](#benchmarks) for performance numbers — most scenarios are within noise over a real pooled database.
+All three ORMs now do single-query nested loads — that's table stakes. Turbine's real differentiators: no engine binary or WASM — just one dependency (`pg`), vs Prisma 7's ~1.6 MB TypeScript/WASM query compiler and required driver adapter; the only read-only-by-default Studio in the ecosystem; error messages that never leak PII; and SQL-first migrations with SHA-256 drift detection. See [Benchmarks](#benchmarks) for performance numbers — most scenarios are within noise over a real pooled database.
 
 **A note on Kysely.** Kysely's [`jsonArrayFrom` / `jsonObjectFrom`](https://kysely.dev/docs/recipes/relations) relations recipe builds nested results with the same correlated-subquery-plus-JSON approach Turbine uses — good evidence the pattern is the right one. The gap is in what the driver can no longer see once rows are aggregated into JSON: nested fields lose their column types, so a `Date` inside a `jsonArrayFrom` result is typed `Date` but arrives as a **string** at runtime ([kysely-org/kysely#482](https://github.com/kysely-org/kysely/issues/482)), and the nesting isn't type-checked at depth. Turbine's `WithResult` inference types the whole tree, and `parseNestedRow` re-applies date coercion (and snake→camel mapping) to every nested row — so `users[0].posts[0].createdAt` is an actual `Date`, at any depth, with no plugin to wire up.
 

package/dist/cjs/cli/index.js

@@ -6,8 +6,8 @@
  * Commands:
  *   turbine init                  — Initialize a Turbine project
  *   turbine generate | pull       — Introspect database and generate TypeScript types
- *   turbine push                  — Apply schema-builder definitions to database
- *   turbine migrate create <name> — Create a new SQL migration file
+ *   turbine push                  - Apply schema-builder definitions to database (destructive ops gated)
+ *   turbine migrate create <name> - Create a new SQL migration file (--auto | --recipe <name>)
  *   turbine migrate up            — Apply pending migrations
  *   turbine migrate deploy        — Apply pending migrations without prompts
  *   turbine migrate down          — Rollback last migration
@@ -150,6 +150,14 @@ function parseArgs(argv = process.argv.slice(2)) {
             case '--allow-destructive':
                 result.allowDestructive = true;
                 break;
+            case '--recipe':
+                if (next === undefined || next.startsWith('-')) {
+                    console.error('--recipe requires a name (e.g. --recipe backfill)');
+                    process.exit(1);
+                }
+                result.recipe = next;
+                i++;
+                break;
             case '--force':
             case '-f':
                 result.force = true;
@@ -176,6 +184,12 @@ function parseArgs(argv = process.argv.slice(2)) {
             case '--allow-remote':
                 result.allowRemote = true;
                 break;
+            case '--write':
+                result.write = true;
+                break;
+            case '--show-pii':
+                result.showPii = true;
+                break;
             default:
                 if (!arg.startsWith('-')) {
                     result.positional.push(arg);
@@ -773,14 +787,45 @@ async function cmdPush(args, config) {
         }
         (0, ui_js_1.newline)();
     }
+    // Surface any non-fatal diff warnings (e.g. undeclared DB indexes, enum
+    // removals) the diff refuses to apply automatically.
+    if (diff.warnings && diff.warnings.length > 0) {
+        for (const w of diff.warnings)
+            (0, ui_js_1.warn)(w);
+        (0, ui_js_1.newline)();
+    }
     if (args.dryRun) {
         (0, ui_js_1.info)('Dry run — no changes applied.');
         (0, ui_js_1.newline)();
         return;
     }
-    // Execute
+    if (args.allowDestructive) {
+        (0, ui_js_1.warn)('--allow-destructive is set: data-destroying schema changes WILL run.');
+        (0, ui_js_1.newline)();
+    }
+    // Execute (gated): schemaPush throws on destructive statements unless allowed.
+    // Pass the diff computed above as `precomputedDiff` so schemaPush applies the
+    // EXACT statements just displayed and confirmed, with no re-diff between confirm
+    // and apply (the TOCTOU window where a concurrent schema change could alter
+    // the applied set). Both the initial attempt and the post-confirmation retry
+    // reuse `diff`, so the confirmed plan and the applied plan are identical.
     const pushSpinner = new ui_js_1.Spinner('Applying changes').start();
-    const result = await (0, schema_sql_js_1.schemaPush)(schemaDef, url);
+    let result;
+    try {
+        result = await (0, schema_sql_js_1.schemaPush)(schemaDef, url, { allowDestructive: args.allowDestructive, precomputedDiff: diff });
+    }
+    catch (err) {
+        if (!(err instanceof schema_sql_js_1.DestructivePushRefusal))
+            throw err;
+        pushSpinner.stop();
+        if (!(await confirmDestructive(err.message))) {
+            (0, ui_js_1.error)('Aborted: no changes were applied and no data was touched.');
+            (0, ui_js_1.newline)();
+            process.exit(1);
+        }
+        pushSpinner.start();
+        result = await (0, schema_sql_js_1.schemaPush)(schemaDef, url, { allowDestructive: true, precomputedDiff: diff });
+    }
     pushSpinner.succeed(`Applied ${(0, ui_js_1.bold)(String(result.statementsExecuted))} statement(s)`);
     if (result.tablesCreated.length > 0) {
         (0, ui_js_1.success)(`Created: ${result.tablesCreated.join(', ')}`);
@@ -802,22 +847,30 @@ async function cmdMigrate(args, config) {
         console.log(`  ${(0, ui_js_1.bold)('turbine migrate')} ${(0, ui_js_1.dim)('— SQL-first migration system')}`);
         (0, ui_js_1.newline)();
         console.log(`  ${(0, ui_js_1.bold)('Commands:')}`);
-        console.log(`    ${(0, ui_js_1.cyan)('create <name>')}         Create a new migration file`);
-        console.log(`    ${(0, ui_js_1.cyan)('create <name> --auto')}  Auto-generate from schema diff`);
-        console.log(`    ${(0, ui_js_1.cyan)('up')}                    Apply pending migrations`);
-        console.log(`    ${(0, ui_js_1.cyan)('deploy')}                Apply pending migrations without prompts`);
-        console.log(`    ${(0, ui_js_1.cyan)('down')}                  Rollback last migration`);
-        console.log(`    ${(0, ui_js_1.cyan)('status')}                Show migration status`);
+        console.log(`    ${(0, ui_js_1.cyan)('create <name>')}            Create a new migration file`);
+        console.log(`    ${(0, ui_js_1.cyan)('create <name> --auto')}     Auto-generate from schema diff`);
+        console.log(`    ${(0, ui_js_1.cyan)('create <name> --recipe')}   Scaffold a named recipe (e.g. backfill)`);
+        console.log(`    ${(0, ui_js_1.cyan)('up')}                       Apply pending migrations`);
+        console.log(`    ${(0, ui_js_1.cyan)('deploy')}                   Apply pending migrations without prompts`);
+        console.log(`    ${(0, ui_js_1.cyan)('down')}                     Rollback last migration`);
+        console.log(`    ${(0, ui_js_1.cyan)('status')}                   Show migration status`);
         (0, ui_js_1.newline)();
         console.log(`  ${(0, ui_js_1.bold)('Options:')}`);
-        console.log(`    ${(0, ui_js_1.cyan)('--auto')}           Auto-generate UP/DOWN SQL from schema diff`);
-        console.log(`    ${(0, ui_js_1.cyan)('--step, -n')}       Number of migrations to apply/rollback`);
-        console.log(`    ${(0, ui_js_1.cyan)('--dry-run')}        Show SQL without executing`);
-        console.log(`    ${(0, ui_js_1.cyan)('--allow-drift')}    Bypass checksum validation on ${(0, ui_js_1.cyan)('migrate up')} ${(0, ui_js_1.dim)('(advanced)')}`);
+        console.log(`    ${(0, ui_js_1.cyan)('--auto')}             Auto-generate UP/DOWN SQL from schema diff`);
+        console.log(`    ${(0, ui_js_1.cyan)('--recipe <name>')}    Scaffold a sanctioned migration pattern`);
+        console.log(`    ${(0, ui_js_1.cyan)('--step, -n')}         Number of migrations to apply/rollback`);
+        console.log(`    ${(0, ui_js_1.cyan)('--dry-run')}          Show SQL without executing`);
+        console.log(`    ${(0, ui_js_1.cyan)('--allow-drift')}      Bypass checksum validation on ${(0, ui_js_1.cyan)('migrate up')} ${(0, ui_js_1.dim)('(advanced)')}`);
+        (0, ui_js_1.newline)();
+        console.log(`  ${(0, ui_js_1.bold)('Recipes')} ${(0, ui_js_1.dim)('(--recipe):')}`);
+        for (const [key, recipe] of Object.entries(migrate_js_1.MIGRATION_RECIPES)) {
+            console.log(`    ${(0, ui_js_1.cyan)(key)}  ${(0, ui_js_1.dim)(recipe.description)}`);
+        }
         (0, ui_js_1.newline)();
         console.log(`  ${(0, ui_js_1.bold)('Examples:')}`);
         console.log(`    ${(0, ui_js_1.dim)('npx turbine migrate create add_users_table')}`);
         console.log(`    ${(0, ui_js_1.dim)('npx turbine migrate create add_email_index --auto')}`);
+        console.log(`    ${(0, ui_js_1.dim)('npx turbine migrate create backfill_full_name --recipe backfill')}`);
         console.log(`    ${(0, ui_js_1.dim)('npx turbine migrate up')}`);
         console.log(`    ${(0, ui_js_1.dim)('npx turbine migrate deploy --dry-run')}`);
         console.log(`    ${(0, ui_js_1.dim)('npx turbine migrate down --step 2')}`);
@@ -910,6 +963,28 @@ async function cmdMigrateCreate(args, config) {
         (0, ui_js_1.newline)();
         return;
     }
+    if (args.recipe) {
+        if (!migrate_js_1.MIGRATION_RECIPES[args.recipe]) {
+            (0, ui_js_1.error)(`Unknown migration recipe: ${args.recipe}`);
+            (0, ui_js_1.newline)();
+            console.log(`  ${(0, ui_js_1.dim)('Available recipes:')}`);
+            for (const [key, recipe] of Object.entries(migrate_js_1.MIGRATION_RECIPES)) {
+                console.log(`    ${(0, ui_js_1.cyan)(key)}  ${(0, ui_js_1.dim)(recipe.description)}`);
+            }
+            (0, ui_js_1.newline)();
+            process.exit(1);
+        }
+        const file = (0, migrate_js_1.createMigration)(config.migrationsDir, name, undefined, { recipe: args.recipe });
+        const relPath = (0, node_path_1.relative)(process.cwd(), file.path);
+        (0, ui_js_1.success)(`Created ${args.recipe} migration: ${(0, ui_js_1.bold)(file.filename)}`);
+        (0, ui_js_1.newline)();
+        console.log(`  ${(0, ui_js_1.dim)('File:')} ${(0, ui_js_1.cyan)(relPath)}`);
+        (0, ui_js_1.newline)();
+        console.log(`  ${(0, ui_js_1.dim)('Fill in the commented placeholders, then run:')}`);
+        console.log(`  ${(0, ui_js_1.cyan)('npx turbine migrate up')}`);
+        (0, ui_js_1.newline)();
+        return;
+    }
     const file = (0, migrate_js_1.createMigration)(config.migrationsDir, name);
     const relPath = (0, node_path_1.relative)(process.cwd(), file.path);
     (0, ui_js_1.success)(`Created migration: ${(0, ui_js_1.bold)(file.filename)}`);
@@ -1462,6 +1537,8 @@ async function cmdStudio(args, config) {
             openBrowser,
             include: config.include.length ? config.include : undefined,
             exclude: config.exclude.length ? config.exclude : undefined,
+            write: args.write === true,
+            showPii: args.showPii === true,
         });
         spinner.succeed(`Studio is running`);
     }
@@ -1469,13 +1546,24 @@ async function cmdStudio(args, config) {
         spinner.fail(`Failed to start Studio: ${err instanceof Error ? err.message : String(err)}`);
         process.exit(1);
     }
+    // Loud startup warnings for the opt-in modes that widen Studio's surface.
+    if (args.write) {
+        (0, ui_js_1.newline)();
+        console.log((0, ui_js_1.warn)('WRITE MODE is ON. Studio can update, insert, and delete single rows in ' +
+            `${(0, ui_js_1.redactUrl)(url)}. Every change is committed directly to your database.`));
+    }
+    if (args.showPii) {
+        (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.'));
+    }
     (0, ui_js_1.newline)();
     console.log((0, ui_js_1.box)([
-        `${(0, ui_js_1.bold)('Turbine Studio')}  ${(0, ui_js_1.dim)('— local read-only UI')}`,
+        `${(0, ui_js_1.bold)('Turbine Studio')}  ${(0, ui_js_1.dim)(args.write ? 'local UI (WRITE MODE)' : 'local read-only UI')}`,
         '',
         `  ${(0, ui_js_1.cyan)('URL:')}    ${(0, ui_js_1.bold)(studio.url)}`,
         `  ${(0, ui_js_1.cyan)('Schema:')} ${config.schema}`,
         `  ${(0, ui_js_1.cyan)('DB:')}     ${(0, ui_js_1.redactUrl)(url)}`,
+        `  ${(0, ui_js_1.cyan)('Mode:')}   ${args.write ? (0, ui_js_1.red)('read-write (single-row)') : 'read-only'}`,
         '',
         (0, ui_js_1.dim)('Open the URL above in your browser. It includes a one-time session'),
         (0, ui_js_1.dim)('token that gets set as an HttpOnly cookie on first load.'),
@@ -1655,6 +1743,7 @@ function showPushHelp() {
     console.log(`  ${(0, ui_js_1.bold)('Options:')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--url, -u')} ${(0, ui_js_1.dim)('<url>')}   Postgres connection string`);
     console.log(`    ${(0, ui_js_1.cyan)('--dry-run')}          Show SQL without executing`);
+    console.log(`    ${(0, ui_js_1.cyan)('--allow-destructive')} Skip the interactive confirmation for data-destroying statements ${(0, ui_js_1.dim)('(CI)')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--verbose, -v')}      Show detailed output`);
     (0, ui_js_1.newline)();
 }
@@ -1675,6 +1764,7 @@ function showMigrateHelp() {
     console.log(`  ${(0, ui_js_1.bold)('Options:')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--url, -u')} ${(0, ui_js_1.dim)('<url>')}   Postgres connection string`);
     console.log(`    ${(0, ui_js_1.cyan)('--auto')}            Auto-generate UP/DOWN SQL from schema diff ${(0, ui_js_1.dim)('(create only)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--recipe')} ${(0, ui_js_1.dim)('<name>')}   Scaffold a sanctioned migration pattern ${(0, ui_js_1.dim)('(create only, e.g. backfill)')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--step, -n')} ${(0, ui_js_1.dim)('<N>')}    Number of migrations to apply/rollback`);
     console.log(`    ${(0, ui_js_1.cyan)('--dry-run')}         Show SQL without executing`);
     console.log(`    ${(0, ui_js_1.cyan)('--allow-drift')}     Bypass checksum validation ${(0, ui_js_1.dim)('(migrate up only — advanced)')}`);
@@ -1684,6 +1774,7 @@ function showMigrateHelp() {
     console.log(`  ${(0, ui_js_1.bold)('Examples:')}`);
     console.log(`    ${(0, ui_js_1.dim)('$')} npx turbine migrate create add_users_table`);
     console.log(`    ${(0, ui_js_1.dim)('$')} npx turbine migrate create add_email_index --auto`);
+    console.log(`    ${(0, ui_js_1.dim)('$')} npx turbine migrate create backfill_full_name --recipe backfill`);
     console.log(`    ${(0, ui_js_1.dim)('$')} npx turbine migrate up`);
     console.log(`    ${(0, ui_js_1.dim)('$')} npx turbine migrate deploy --dry-run`);
     console.log(`    ${(0, ui_js_1.dim)('$')} npx turbine migrate down --step 2`);
@@ -1759,7 +1850,7 @@ function showHelp() {
     console.log(`    ${(0, ui_js_1.cyan)('seed')}               Run seed file`);
     console.log(`    ${(0, ui_js_1.cyan)('status')} ${(0, ui_js_1.dim)('| info')}      Show schema summary`);
     console.log(`    ${(0, ui_js_1.cyan)('doctor')}             Check relations for missing FK indexes ${(0, ui_js_1.dim)('(--fix emits migration)')}`);
-    console.log(`    ${(0, ui_js_1.cyan)('studio')}             Launch local read-only web UI`);
+    console.log(`    ${(0, ui_js_1.cyan)('studio')}             Launch local read-only web UI ${(0, ui_js_1.dim)('(--write opts in to single-row writes)')}`);
     console.log(`    ${(0, ui_js_1.cyan)('mcp')}                Start read-only MCP server over stdio`);
     console.log(`    ${(0, ui_js_1.cyan)('observe')}            Launch metrics dashboard ${(0, ui_js_1.dim)('(requires TURBINE_OBSERVE_URL)')}`);
     (0, ui_js_1.newline)();
@@ -1783,6 +1874,8 @@ function showHelp() {
     console.log(`    ${(0, ui_js_1.cyan)('--host')} ${(0, ui_js_1.dim)('<addr>')}        Bind address ${(0, ui_js_1.dim)('(default: 127.0.0.1)')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--no-open')}            Don't auto-open the browser`);
     console.log(`    ${(0, ui_js_1.cyan)('--allow-remote')}       Allow non-loopback --host ${(0, ui_js_1.dim)('(refused without this flag)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--write')}              Studio: enable single-row update/insert/delete ${(0, ui_js_1.dim)('(read-only by default)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--show-pii')}           Studio: show PII-tagged values unredacted ${(0, ui_js_1.dim)('(redacted by default)')}`);
     (0, ui_js_1.newline)();
     console.log(`  ${(0, ui_js_1.bold)('Config file:')}`);
     console.log(`    ${(0, ui_js_1.dim)('Create')} ${(0, ui_js_1.cyan)('turbine.config.ts')} ${(0, ui_js_1.dim)('with')} ${(0, ui_js_1.cyan)('npx turbine init')}`);

package/dist/cjs/cli/migrate.js

@@ -16,6 +16,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIGRATION_RECIPES = void 0;
 exports.parseMigrationFilename = parseMigrationFilename;
 exports.sanitizeName = sanitizeName;
 exports.formatTimestamp = formatTimestamp;
@@ -169,14 +170,70 @@ function checksum(content) {
 function isLegacyChecksum(hash) {
     return hash.length < 64;
 }
+/** The sanctioned two-phase (add nullable, batched backfill, swap) recipe. */
+function buildBackfillRecipe() {
+    const up = `-- Two-phase backfill scaffold. Every statement below is COMMENTED OUT: fill in
+-- your table, the new column, the old column, and the transform, then uncomment
+-- the phases you need and review before running \`npx turbine migrate up\`.
+--
+-- Phase 1: add the new column as NULLABLE. This is a fast, non-blocking change
+-- (no table rewrite, no long lock), so it is safe to ship ahead of the backfill.
+-- ALTER TABLE "my_table" ADD COLUMN "new_col" text;
+--
+-- Phase 2: backfill in bounded batches. Repeat this UPDATE until it reports
+-- 0 rows affected. \`turbine migrate\` runs each file exactly once, so for large
+-- tables drive the loop from psql or your app rather than inlining it here.
+-- Tune the LIMIT (batch size) to your row width and lock tolerance.
+-- UPDATE "my_table"
+--    SET "new_col" = transform("old_col")
+--  WHERE "new_col" IS NULL
+--    AND "id" IN (
+--      SELECT "id" FROM "my_table" WHERE "new_col" IS NULL LIMIT 5000
+--    );
+--
+-- Phase 3: once every row is populated, enforce NOT NULL.
+-- Note: SET NOT NULL takes an exclusive lock and scans the table. On huge
+-- tables, first ADD CONSTRAINT ... CHECK ("new_col" IS NOT NULL) NOT VALID,
+-- then VALIDATE CONSTRAINT (PG 12+ uses the validated check to skip the scan).
+-- ALTER TABLE "my_table" ALTER COLUMN "new_col" SET NOT NULL;
+--
+-- Phase 4 (optional atomic swap): retire the old column and rename the new one
+-- into its place, in one transaction so readers never see a missing column.
+-- BEGIN;
+--   ALTER TABLE "my_table" RENAME COLUMN "old_col" TO "old_col_retired";
+--   ALTER TABLE "my_table" RENAME COLUMN "new_col" TO "old_col";
+-- COMMIT;`;
+    const down = `-- Reverse the Phase 4 atomic swap (only if you ran it).
+-- BEGIN;
+--   ALTER TABLE "my_table" RENAME COLUMN "old_col" TO "new_col";
+--   ALTER TABLE "my_table" RENAME COLUMN "old_col_retired" TO "old_col";
+-- COMMIT;
+--
+-- If you stopped after phases 1 to 3, drop the added column instead:
+-- ALTER TABLE "my_table" DROP COLUMN "new_col";`;
+    return { up, down };
+}
+/**
+ * Registry of migration recipes, keyed by `--recipe <name>`. New recipes slot
+ * in here without touching {@link createMigration} or the CLI handler.
+ */
+exports.MIGRATION_RECIPES = {
+    backfill: {
+        description: 'Two-phase column backfill (add nullable, batched UPDATE, SET NOT NULL, rename swap)',
+        build: buildBackfillRecipe,
+    },
+};
 // ---------------------------------------------------------------------------
 // Commands
 // ---------------------------------------------------------------------------
 /**
  * Create a new migration file.
- * If `autoContent` is provided, the UP/DOWN sections are pre-populated with the given SQL.
+ *
+ * - `autoContent`: pre-populate UP/DOWN from a schema diff.
+ * - `options.recipe`: scaffold a named recipe (see {@link MIGRATION_RECIPES}).
+ *   Mutually exclusive with `autoContent`; an unknown recipe throws.
  */
-function createMigration(migrationsDir, name, autoContent) {
+function createMigration(migrationsDir, name, autoContent, options) {
     (0, node_fs_1.mkdirSync)(migrationsDir, { recursive: true });
     const now = new Date();
     const ts = formatTimestamp(now);
@@ -184,7 +241,25 @@ function createMigration(migrationsDir, name, autoContent) {
     const filename = `${ts}_${safeName}.sql`;
     const filePath = (0, node_path_1.join)(migrationsDir, filename);
     let template;
-    if (autoContent) {
+    if (options?.recipe) {
+        const recipe = exports.MIGRATION_RECIPES[options.recipe];
+        if (!recipe) {
+            const known = Object.keys(exports.MIGRATION_RECIPES).join(', ') || '(none)';
+            throw new errors_js_1.MigrationError(`[turbine] Unknown migration recipe "${options.recipe}". Available recipes: ${known}`);
+        }
+        const body = recipe.build(name);
+        template = `-- Migration: ${name} (${options.recipe} recipe scaffold)
+-- Created: ${now.toISOString()}
+-- Fill in the placeholders and review before running: npx turbine migrate up
+
+-- UP
+${body.up}
+
+-- DOWN
+${body.down}
+`;
+    }
+    else if (autoContent) {
         template = `-- Migration: ${name} (auto-generated from schema diff)
 -- Created: ${now.toISOString()}
 -- Review this file before running: npx turbine migrate up