turbine-orm 0.35.0 → 0.36.0

package/dist/cli/index.js

@@ -5,8 +5,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
@@ -29,11 +29,11 @@ import { pathToFileURL } from 'node:url';
 import { generate } from '../generate.js';
 import { findMissingRelationIndexes } from '../index-advisor.js';
 import { introspect } from '../introspect.js';
-import { schemaDiff, schemaPush } from '../schema-sql.js';
+import { DestructivePushRefusal, schemaDiff, schemaPush } from '../schema-sql.js';
 import { configTemplate, findConfigFile, loadConfigResult, looksLikeSchemaFilePath, resolveConfig, resolveSeedFile, unwrapModuleDefault, } from './config.js';
 import { canResolveTsx, getTsLoaderError, needsTsLoader, registerTsLoader } from './loader.js';
 import { runMcpServer } from './mcp.js';
-import { createMigration, inspectMigrationDeploy, listMigrationFiles, migrateDeploy, migrateDown, migrateStatus, migrateUp, } from './migrate.js';
+import { createMigration, inspectMigrationDeploy, listMigrationFiles, MIGRATION_RECIPES, migrateDeploy, migrateDown, migrateStatus, migrateUp, } from './migrate.js';
 import { startObserve } from './observe.js';
 import { startStudio } from './studio.js';
 import { banner, blue, bold, box, cyan, dim, divider, elapsed, error, table as formatTable, gray, green, header, info, label, magenta, newline, red, redactUrl, Spinner, success, symbols, warn, yellow, } from './ui.js';
@@ -108,6 +108,14 @@ export 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;
@@ -134,6 +142,12 @@ export 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);
@@ -731,14 +745,45 @@ async function cmdPush(args, config) {
         }
         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)
+            warn(w);
+        newline();
+    }
     if (args.dryRun) {
         info('Dry run — no changes applied.');
         newline();
         return;
     }
-    // Execute
+    if (args.allowDestructive) {
+        warn('--allow-destructive is set: data-destroying schema changes WILL run.');
+        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 Spinner('Applying changes').start();
-    const result = await schemaPush(schemaDef, url);
+    let result;
+    try {
+        result = await schemaPush(schemaDef, url, { allowDestructive: args.allowDestructive, precomputedDiff: diff });
+    }
+    catch (err) {
+        if (!(err instanceof DestructivePushRefusal))
+            throw err;
+        pushSpinner.stop();
+        if (!(await confirmDestructive(err.message))) {
+            error('Aborted: no changes were applied and no data was touched.');
+            newline();
+            process.exit(1);
+        }
+        pushSpinner.start();
+        result = await schemaPush(schemaDef, url, { allowDestructive: true, precomputedDiff: diff });
+    }
     pushSpinner.succeed(`Applied ${bold(String(result.statementsExecuted))} statement(s)`);
     if (result.tablesCreated.length > 0) {
         success(`Created: ${result.tablesCreated.join(', ')}`);
@@ -760,22 +805,30 @@ async function cmdMigrate(args, config) {
         console.log(`  ${bold('turbine migrate')} ${dim('— SQL-first migration system')}`);
         newline();
         console.log(`  ${bold('Commands:')}`);
-        console.log(`    ${cyan('create <name>')}         Create a new migration file`);
-        console.log(`    ${cyan('create <name> --auto')}  Auto-generate from schema diff`);
-        console.log(`    ${cyan('up')}                    Apply pending migrations`);
-        console.log(`    ${cyan('deploy')}                Apply pending migrations without prompts`);
-        console.log(`    ${cyan('down')}                  Rollback last migration`);
-        console.log(`    ${cyan('status')}                Show migration status`);
+        console.log(`    ${cyan('create <name>')}            Create a new migration file`);
+        console.log(`    ${cyan('create <name> --auto')}     Auto-generate from schema diff`);
+        console.log(`    ${cyan('create <name> --recipe')}   Scaffold a named recipe (e.g. backfill)`);
+        console.log(`    ${cyan('up')}                       Apply pending migrations`);
+        console.log(`    ${cyan('deploy')}                   Apply pending migrations without prompts`);
+        console.log(`    ${cyan('down')}                     Rollback last migration`);
+        console.log(`    ${cyan('status')}                   Show migration status`);
         newline();
         console.log(`  ${bold('Options:')}`);
-        console.log(`    ${cyan('--auto')}           Auto-generate UP/DOWN SQL from schema diff`);
-        console.log(`    ${cyan('--step, -n')}       Number of migrations to apply/rollback`);
-        console.log(`    ${cyan('--dry-run')}        Show SQL without executing`);
-        console.log(`    ${cyan('--allow-drift')}    Bypass checksum validation on ${cyan('migrate up')} ${dim('(advanced)')}`);
+        console.log(`    ${cyan('--auto')}             Auto-generate UP/DOWN SQL from schema diff`);
+        console.log(`    ${cyan('--recipe <name>')}    Scaffold a sanctioned migration pattern`);
+        console.log(`    ${cyan('--step, -n')}         Number of migrations to apply/rollback`);
+        console.log(`    ${cyan('--dry-run')}          Show SQL without executing`);
+        console.log(`    ${cyan('--allow-drift')}      Bypass checksum validation on ${cyan('migrate up')} ${dim('(advanced)')}`);
+        newline();
+        console.log(`  ${bold('Recipes')} ${dim('(--recipe):')}`);
+        for (const [key, recipe] of Object.entries(MIGRATION_RECIPES)) {
+            console.log(`    ${cyan(key)}  ${dim(recipe.description)}`);
+        }
         newline();
         console.log(`  ${bold('Examples:')}`);
         console.log(`    ${dim('npx turbine migrate create add_users_table')}`);
         console.log(`    ${dim('npx turbine migrate create add_email_index --auto')}`);
+        console.log(`    ${dim('npx turbine migrate create backfill_full_name --recipe backfill')}`);
         console.log(`    ${dim('npx turbine migrate up')}`);
         console.log(`    ${dim('npx turbine migrate deploy --dry-run')}`);
         console.log(`    ${dim('npx turbine migrate down --step 2')}`);
@@ -868,6 +921,28 @@ async function cmdMigrateCreate(args, config) {
         newline();
         return;
     }
+    if (args.recipe) {
+        if (!MIGRATION_RECIPES[args.recipe]) {
+            error(`Unknown migration recipe: ${args.recipe}`);
+            newline();
+            console.log(`  ${dim('Available recipes:')}`);
+            for (const [key, recipe] of Object.entries(MIGRATION_RECIPES)) {
+                console.log(`    ${cyan(key)}  ${dim(recipe.description)}`);
+            }
+            newline();
+            process.exit(1);
+        }
+        const file = createMigration(config.migrationsDir, name, undefined, { recipe: args.recipe });
+        const relPath = relative(process.cwd(), file.path);
+        success(`Created ${args.recipe} migration: ${bold(file.filename)}`);
+        newline();
+        console.log(`  ${dim('File:')} ${cyan(relPath)}`);
+        newline();
+        console.log(`  ${dim('Fill in the commented placeholders, then run:')}`);
+        console.log(`  ${cyan('npx turbine migrate up')}`);
+        newline();
+        return;
+    }
     const file = createMigration(config.migrationsDir, name);
     const relPath = relative(process.cwd(), file.path);
     success(`Created migration: ${bold(file.filename)}`);
@@ -1420,6 +1495,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`);
     }
@@ -1427,13 +1504,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) {
+        newline();
+        console.log(warn('WRITE MODE is ON. Studio can update, insert, and delete single rows in ' +
+            `${redactUrl(url)}. Every change is committed directly to your database.`));
+    }
+    if (args.showPii) {
+        newline();
+        console.log(warn('--show-pii is ON. PII-tagged column values are shown UNREDACTED in Studio.'));
+    }
     newline();
     console.log(box([
-        `${bold('Turbine Studio')}  ${dim('— local read-only UI')}`,
+        `${bold('Turbine Studio')}  ${dim(args.write ? 'local UI (WRITE MODE)' : 'local read-only UI')}`,
         '',
         `  ${cyan('URL:')}    ${bold(studio.url)}`,
         `  ${cyan('Schema:')} ${config.schema}`,
         `  ${cyan('DB:')}     ${redactUrl(url)}`,
+        `  ${cyan('Mode:')}   ${args.write ? red('read-write (single-row)') : 'read-only'}`,
         '',
         dim('Open the URL above in your browser. It includes a one-time session'),
         dim('token that gets set as an HttpOnly cookie on first load.'),
@@ -1613,6 +1701,7 @@ function showPushHelp() {
     console.log(`  ${bold('Options:')}`);
     console.log(`    ${cyan('--url, -u')} ${dim('<url>')}   Postgres connection string`);
     console.log(`    ${cyan('--dry-run')}          Show SQL without executing`);
+    console.log(`    ${cyan('--allow-destructive')} Skip the interactive confirmation for data-destroying statements ${dim('(CI)')}`);
     console.log(`    ${cyan('--verbose, -v')}      Show detailed output`);
     newline();
 }
@@ -1633,6 +1722,7 @@ function showMigrateHelp() {
     console.log(`  ${bold('Options:')}`);
     console.log(`    ${cyan('--url, -u')} ${dim('<url>')}   Postgres connection string`);
     console.log(`    ${cyan('--auto')}            Auto-generate UP/DOWN SQL from schema diff ${dim('(create only)')}`);
+    console.log(`    ${cyan('--recipe')} ${dim('<name>')}   Scaffold a sanctioned migration pattern ${dim('(create only, e.g. backfill)')}`);
     console.log(`    ${cyan('--step, -n')} ${dim('<N>')}    Number of migrations to apply/rollback`);
     console.log(`    ${cyan('--dry-run')}         Show SQL without executing`);
     console.log(`    ${cyan('--allow-drift')}     Bypass checksum validation ${dim('(migrate up only — advanced)')}`);
@@ -1642,6 +1732,7 @@ function showMigrateHelp() {
     console.log(`  ${bold('Examples:')}`);
     console.log(`    ${dim('$')} npx turbine migrate create add_users_table`);
     console.log(`    ${dim('$')} npx turbine migrate create add_email_index --auto`);
+    console.log(`    ${dim('$')} npx turbine migrate create backfill_full_name --recipe backfill`);
     console.log(`    ${dim('$')} npx turbine migrate up`);
     console.log(`    ${dim('$')} npx turbine migrate deploy --dry-run`);
     console.log(`    ${dim('$')} npx turbine migrate down --step 2`);
@@ -1717,7 +1808,7 @@ function showHelp() {
     console.log(`    ${cyan('seed')}               Run seed file`);
     console.log(`    ${cyan('status')} ${dim('| info')}      Show schema summary`);
     console.log(`    ${cyan('doctor')}             Check relations for missing FK indexes ${dim('(--fix emits migration)')}`);
-    console.log(`    ${cyan('studio')}             Launch local read-only web UI`);
+    console.log(`    ${cyan('studio')}             Launch local read-only web UI ${dim('(--write opts in to single-row writes)')}`);
     console.log(`    ${cyan('mcp')}                Start read-only MCP server over stdio`);
     console.log(`    ${cyan('observe')}            Launch metrics dashboard ${dim('(requires TURBINE_OBSERVE_URL)')}`);
     newline();
@@ -1741,6 +1832,8 @@ function showHelp() {
     console.log(`    ${cyan('--host')} ${dim('<addr>')}        Bind address ${dim('(default: 127.0.0.1)')}`);
     console.log(`    ${cyan('--no-open')}            Don't auto-open the browser`);
     console.log(`    ${cyan('--allow-remote')}       Allow non-loopback --host ${dim('(refused without this flag)')}`);
+    console.log(`    ${cyan('--write')}              Studio: enable single-row update/insert/delete ${dim('(read-only by default)')}`);
+    console.log(`    ${cyan('--show-pii')}           Studio: show PII-tagged values unredacted ${dim('(redacted by default)')}`);
     newline();
     console.log(`  ${bold('Config file:')}`);
     console.log(`    ${dim('Create')} ${cyan('turbine.config.ts')} ${dim('with')} ${cyan('npx turbine init')}`);

package/dist/cli/migrate.d.ts

@@ -73,13 +73,36 @@ export declare function parseMigrationSQL(filePath: string): {
     up: string;
     down: string;
 };
+/**
+ * A named migration scaffold. `build()` returns the commented-SQL UP/DOWN body
+ * for the recipe; `createMigration({ recipe })` wraps it in the file header.
+ */
+export interface MigrationRecipe {
+    /** One-line description shown in CLI help. */
+    description: string;
+    /** Build the UP/DOWN body (commented scaffold with placeholders). */
+    build(name: string): {
+        up: string;
+        down: string;
+    };
+}
+/**
+ * Registry of migration recipes, keyed by `--recipe <name>`. New recipes slot
+ * in here without touching {@link createMigration} or the CLI handler.
+ */
+export declare const MIGRATION_RECIPES: Record<string, MigrationRecipe>;
 /**
  * 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.
  */
 export declare function createMigration(migrationsDir: string, name: string, autoContent?: {
     up: string;
     down: string;
+}, options?: {
+    recipe?: string;
 }): MigrationFile;
 /**
  * Derive a Postgres advisory lock ID (positive int4) from the database name.

package/dist/cli/migrate.js

@@ -149,14 +149,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.
+ */
+export const 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.
  */
-export function createMigration(migrationsDir, name, autoContent) {
+export function createMigration(migrationsDir, name, autoContent, options) {
     mkdirSync(migrationsDir, { recursive: true });
     const now = new Date();
     const ts = formatTimestamp(now);
@@ -164,7 +220,25 @@ export function createMigration(migrationsDir, name, autoContent) {
     const filename = `${ts}_${safeName}.sql`;
     const filePath = join(migrationsDir, filename);
     let template;
-    if (autoContent) {
+    if (options?.recipe) {
+        const recipe = MIGRATION_RECIPES[options.recipe];
+        if (!recipe) {
+            const known = Object.keys(MIGRATION_RECIPES).join(', ') || '(none)';
+            throw new 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