turbine-orm 0.77.1 → 0.78.0

package/dist/cli/index.js

@@ -29,7 +29,8 @@ import { appendFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFi
 import { tmpdir } from 'node:os';
 import { basename, dirname, extname, join, relative, resolve, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { detectPooler, poolerRefusalMessage } from '../connection-url.js';
+import { detectPooler, parseSearchPathValue, poolerRefusalMessage } from '../connection-url.js';
+import { ValidationError } from '../errors.js';
 import { generate, generatePrismaMap, resolveImportExtension } from '../generate.js';
 import { buildCreateIndexSql, buildCreateIndexStatements, buildDropIndexSql, collectDoctorProbeIndexNames, collectRelationProbeColumns, findMissingRelationIndexes, } from '../index-advisor.js';
 import { auditDoctorIndexes, collectStatsSnapshot, collectTableHeat, findInvalidIndexes, findRedundantIndexes, findUnusedIndexes, formatBytes, isSnapshotUsable, STATS_THRESHOLDS, scoreMissingIndex, } from '../index-stats.js';
@@ -44,7 +45,7 @@ import { configTemplate, connectionStringHasPassword, DEFAULT_INIT_SEED_FILE, fi
 import { DESTRUCTIVE_KIND_LABEL } from './destructive.js';
 import { canResolveTsx, getTsLoaderError, needsTsLoader, registerTsLoader } from './loader.js';
 import { runMcpServer } from './mcp.js';
-import { buildDiffMigrationBody, collectUpDestructive, createMigration, formatChecksumMismatchError, inspectMigrationDeploy, listMigrationFiles, MIGRATION_RECIPES, migrateDeploy, migrateDown, migrateStatus, migrateUp, parseMigrationContent, } from './migrate.js';
+import { assertNoEmbeddedTransactions, assertPinnableSchema, assertSchemaExists, assertUpHasStatements, buildDiffMigrationBody, collectUpDestructive, connectionStringForSchema, createMigration, formatChecksumMismatchError, inspectMigrationDeploy, listIgnoredSqlFiles, listMigrationFiles, MIGRATION_RECIPES, migrateDeploy, migrateDown, migrateStatus, migrateUp, parseMigrationContent, planMigrationRollback, } from './migrate.js';
 import { startObserve } from './observe.js';
 import { formatPrismaReport, summaryLines } from './prisma-report.js';
 import { DEFAULT_EXCLUDED_TABLES, resolvePrismaSchema } from './prisma-resolve.js';
@@ -299,6 +300,8 @@ export function parseArgs(argv = process.argv.slice(2)) {
     // command instead, which is the actual problem.
     const accepted = acceptedFlagTokens(result.command);
     const unknownFlags = [];
+    /** The raw `--step` operand, judged after the loop. Absent means unset. */
+    let stepRaw;
     for (; i < args.length; i++) {
         const arg = args[i];
         const next = args[i + 1];
@@ -337,10 +340,17 @@ export function parseArgs(argv = process.argv.slice(2)) {
                 i++;
                 break;
             case '--step':
-            case '-n':
-                result.step = next ? parseInt(next, 10) : undefined;
+            case '-n': {
+                // The VALUE is captured here and JUDGED after the loop, see
+                // `stepRaw` below. `--step -1` reached `applied.reverse().slice(0, -1)`,
+                // which is "every migration except the oldest" and began tearing down
+                // the history newest-first; `--step 0` and `--step abc` (NaN) were
+                // silent no-ops that look like a successful rollback. A count of things
+                // to do is a positive integer or it is a mistake.
+                stepRaw = next ?? '';
                 i++;
                 break;
+            }
             case '--dry-run':
                 result.dryRun = true;
                 break;
@@ -503,6 +513,21 @@ export function parseArgs(argv = process.argv.slice(2)) {
     // are two lines of one error rather than two runs of the CLI.
     if (unknownFlags.length > 0)
         failUnknownFlags(result.command, unknownFlags);
+    // Flag VALUES are judged last, and only for a command that exists. Both halves
+    // are the fix for one report: `turbine genrate --step 0` used to complain
+    // about `--step` and never mention the misspelled command, because the check
+    // ran mid-loop and threw past `main()`'s dispatch. And it threw a bare
+    // `ValidationError` rather than calling `failArg`, so it printed one unstyled
+    // sentence with no banner and no hint, which reads like an internal crash.
+    // `accepted === undefined` means the command is unknown; main() reports that,
+    // which is the actual problem.
+    if (stepRaw !== undefined && accepted !== undefined) {
+        const parsed = /^\d+$/.test(stepRaw.trim()) ? Number.parseInt(stepRaw, 10) : Number.NaN;
+        if (!Number.isSafeInteger(parsed) || parsed < 1) {
+            failArg(`${cyan('--step, -n')} expects a positive whole number of migrations, got ${bold(stepRaw === '' ? '(nothing)' : `"${stepRaw}"`)}.`, 'It is a COUNT of migrations to apply or roll back, so the smallest useful value is 1.', 'Example: npx turbine migrate down --step 2');
+        }
+        result.step = parsed;
+    }
     return result;
 }
 // ---------------------------------------------------------------------------
@@ -1285,6 +1310,7 @@ async function runInitGenerate(config, url) {
     const spinner = new Spinner('Introspecting database').start();
     try {
         const schema = await introspect({
+            keepColumnNames: config.keepColumnNames,
             connectionString: url,
             schema: config.schema,
             include: config.include.length ? config.include : undefined,
@@ -1549,7 +1575,7 @@ async function cmdInit(args, config) {
         }
         switch (step.id) {
             case 'config': {
-                writeFileSync('turbine.config.ts', configTemplate(args.url ?? undefined), 'utf-8');
+                writeFileSync('turbine.config.ts', configTemplate(args.url ?? undefined, config.schema), 'utf-8');
                 success(state.configExists ? `Overwrote ${cyan('turbine.config.ts')}` : `Created ${cyan('turbine.config.ts')}`);
                 tsFilesWritten.push('turbine.config.ts');
                 // A `--url` with a password is never inlined by configTemplate, so the
@@ -1712,6 +1738,7 @@ async function cmdGenerate(args, config) {
     const spinner = new Spinner('Introspecting database schema').start();
     const skippedInternalTables = [];
     const schema = await introspect({
+        keepColumnNames: config.keepColumnNames,
         connectionString: url,
         schema: config.schema,
         include: config.include.length ? config.include : undefined,
@@ -1912,6 +1939,7 @@ async function cmdMigrateFromPrisma(args, config) {
         label('Database', redactUrl(url));
         const spinner = new Spinner('Introspecting database schema').start();
         schemaMeta = await introspect({
+            keepColumnNames: config.keepColumnNames,
             connectionString: url,
             // The Postgres NAMESPACE is fixed to `public` here (`--schema` names the
             // Prisma file, not the namespace).
@@ -2161,7 +2189,7 @@ async function cmdMigrate(args, config) {
         console.log(`    ${cyan('--step, -n')}         Number of migrations to apply/rollback`);
         console.log(`    ${cyan('--dry-run')}          Show SQL without executing`);
         console.log(`    ${cyan('--allow-destructive')} Run data-destroying statements without prompting`);
-        console.log(`    ${cyan('--allow-drift')}      Bypass checksum validation on ${cyan('up')} / ${cyan('deploy')} ${dim('(advanced)')}`);
+        console.log(`    ${cyan('--allow-drift')}      Re-baseline drifted checksums on ${cyan('up')} / ${cyan('deploy')} / ${cyan('down')} ${dim('(advanced)')}`);
         newline();
         console.log(`  ${bold('Recipes')} ${dim('(--recipe):')}`);
         for (const [key, recipe] of Object.entries(MIGRATION_RECIPES)) {
@@ -2452,6 +2480,7 @@ async function cmdMigrateUp(args, config) {
     label('Database', redactUrl(url));
     label('Migrations', config.migrationsDir);
     newline();
+    warnIgnoredMigrationFiles(config.migrationsDir);
     const allFiles = listMigrationFiles(config.migrationsDir);
     if (allFiles.length === 0) {
         warn('No migration files found.');
@@ -2460,19 +2489,29 @@ async function cmdMigrateUp(args, config) {
         return;
     }
     if (args.dryRun) {
-        const status = await migrateStatus(url, config.migrationsDir);
+        const status = await migrateStatus(url, config.migrationsDir, { schema: config.schema });
         let pending = status.filter((st) => !st.applied).map((st) => st.file);
         if (args.step != null && args.step > 0)
             pending = pending.slice(0, args.step);
+        // The same pre-flight the real run does, by calling the same two functions
+        // rather than re-deriving their rules. They live inside `migrateUp`, which a
+        // dry run never reaches, so `--dry-run` used to green-light a batch the real
+        // command refuses outright: an empty-UP migration previewed as "would apply
+        // 1 migration" and exit 0, and the deploy that followed on merge failed.
+        // A preview that is quieter than the run it previews is not a preview.
+        assertNoEmbeddedTransactions(pending, 'up');
+        assertUpHasStatements(pending);
         printMigrationDryRun(pending, 'up');
         return;
     }
     // Big, loud warning when bypassing drift detection, this is a deliberately
     // dangerous operation and the user should see it on every invocation.
     if (args.allowDrift) {
-        warn('--allow-drift is set, checksum validation is DISABLED for this run.');
-        console.log(`  ${dim('Applied migrations may have been modified or deleted on disk.')}`);
-        console.log(`  ${dim('Proceed only if you are intentionally rewriting migration history.')}`);
+        warn('--allow-drift is set: a drifted migration will be RE-BASELINED, not skipped.');
+        console.log(`  ${dim('Checksum validation still runs, and its result is written back to the history')}`);
+        console.log(`  ${dim("table: each modified file's stored checksum becomes its current content.")}`);
+        console.log(`  ${dim('The SQL that already ran is NOT re-run. Proceed only if you are')}`);
+        console.log(`  ${dim('intentionally rewriting migration history.')}`);
         newline();
     }
     if (args.allowDestructive) {
@@ -2498,6 +2537,7 @@ async function cmdMigrateUp(args, config) {
             allowDrift: args.allowDrift,
             allowDestructive: args.allowDestructive,
             onNoTransaction,
+            schema: config.schema,
         });
     }
     catch (err) {
@@ -2515,19 +2555,26 @@ async function cmdMigrateUp(args, config) {
             allowDrift: args.allowDrift,
             allowDestructive: true,
             onNoTransaction,
+            schema: config.schema,
         });
     }
-    if (result.applied.length === 0 && result.errors.length === 0) {
-        spinner.succeed('All migrations are up to date');
-        newline();
-        return;
-    }
     if (result.applied.length > 0) {
         spinner.succeed(`Applied ${bold(String(result.applied.length))} migration(s)`);
         for (const file of result.applied) {
             console.log(`    ${green(symbols.check)} ${file.filename}`);
         }
     }
+    else if (result.errors.length === 0) {
+        spinner.succeed('All migrations are up to date');
+    }
+    // Reported on EVERY path, including the one where nothing was applied. That is
+    // `--allow-drift`'s most common case by far (you edited an already-applied
+    // file, so nothing is pending), and it used to sit below an early return: the
+    // stored checksum was rewritten and the terminal said everything was up to
+    // date. A write to migration history announced as a no-op is worse than no
+    // report at all, because the reader now believes the file and the database
+    // still disagree.
+    reportRebaselined(result.rebaselined);
     warnOutOfOrder(result.outOfOrder);
     if (result.errors.length > 0) {
         spinner.fail('Migration failed');
@@ -2540,6 +2587,40 @@ async function cmdMigrateUp(args, config) {
     }
     newline();
 }
+/**
+ * Report each applied migration whose stored checksum was re-baselined to the
+ * file's current content, naming both hashes so the change is auditable from
+ * the terminal output alone.
+ */
+function reportRebaselined(rebaselined) {
+    if (rebaselined.length === 0)
+        return;
+    newline();
+    warn(`Re-baselined ${bold(String(rebaselined.length))} migration checksum(s) to the current file content:`);
+    for (const r of rebaselined) {
+        console.log(`    ${yellow(symbols.arrowRight)} ${r.name}.sql  ${dim(`${r.from.slice(0, 12)} -> ${r.to.slice(0, 12)}`)}`);
+    }
+    console.log(`  ${dim('The history table now records what is on disk, so future runs need no --allow-drift.')}`);
+    newline();
+}
+/**
+ * Warn about `.sql` files in the migrations directory that the runner will
+ * never see, because their name is not `YYYYMMDDHHMMSS_<name>.sql`.
+ *
+ * They were skipped in silence by `status`, `up` and `deploy` alike, so a
+ * hand-named migration simply never ran and nothing said so.
+ */
+function warnIgnoredMigrationFiles(migrationsDir) {
+    const ignored = listIgnoredSqlFiles(migrationsDir);
+    if (ignored.length === 0)
+        return;
+    warn(`${bold(String(ignored.length))} .sql file(s) in ${migrationsDir} are NOT migrations and will never run:`);
+    for (const name of ignored)
+        console.log(`    ${yellow(symbols.dot)} ${name}`);
+    console.log(`  ${dim('A migration filename must be')} ${cyan('YYYYMMDDHHMMSS_name.sql')}${dim('.')}`);
+    console.log(`  ${dim('Rename the file(s), or create them with')} ${cyan('npx turbine migrate create <name>')}${dim('.')}`);
+    newline();
+}
 /** Print a one-line warning for each migration applied out of timestamp order. */
 function warnOutOfOrder(outOfOrder) {
     if (outOfOrder.length === 0)
@@ -2577,8 +2658,9 @@ async function cmdMigrateDeploy(args, config) {
     label('Database', redactUrl(url));
     label('Migrations', config.migrationsDir);
     newline();
+    warnIgnoredMigrationFiles(config.migrationsDir);
     const spinner = new Spinner('Checking pending migrations').start();
-    const plan = await inspectMigrationDeploy(url, config.migrationsDir);
+    const plan = await inspectMigrationDeploy(url, config.migrationsDir, { schema: config.schema });
     spinner.stop();
     // Drift handling: honor --allow-drift exactly like `up`. Without it, block;
     // with it, warn loudly and proceed.
@@ -2592,8 +2674,10 @@ async function cmdMigrateDeploy(args, config) {
             errorLine();
             process.exit(1);
         }
-        warn('--allow-drift is set: checksum validation is DISABLED for this deploy.');
-        console.log(`  ${dim('Applied migrations may have been modified or deleted on disk.')}`);
+        warn('--allow-drift is set: a drifted migration will be RE-BASELINED, not skipped.');
+        console.log(`  ${dim('Checksum validation still runs, and its result is written back to the history')}`);
+        console.log(`  ${dim("table: each modified file's stored checksum becomes its current content.")}`);
+        console.log(`  ${dim('The SQL that already ran is NOT re-run.')}`);
         newline();
     }
     if (args.dryRun) {
@@ -2602,10 +2686,21 @@ async function cmdMigrateDeploy(args, config) {
             newline();
             return;
         }
+        // The same pre-flight the real run does, by calling the same two functions
+        // rather than re-deriving their rules. They live inside `migrateUp`, which a
+        // dry run never reaches, so `--dry-run` used to green-light a batch the real
+        // command refuses outright: an empty-UP migration previewed as "would apply
+        // 1 migration" and exit 0, and the deploy that followed on merge failed.
+        // A preview that is quieter than the run it previews is not a preview.
+        assertNoEmbeddedTransactions(plan.pending, 'up');
+        assertUpHasStatements(plan.pending);
         info(`${bold(String(plan.pending.length))} pending migration(s)`);
         for (const file of plan.pending) {
             console.log(`    ${yellow(symbols.dot)} ${file.filename}`);
         }
+        // The real deploy warns about out-of-order applies; a preview that is
+        // quieter than the run it previews is not a preview.
+        warnOutOfOrder(plan.outOfOrder);
         // Surface destructive statements even in a dry run so CI can see them.
         const destructive = collectUpDestructive(plan.pending);
         if (destructive.length > 0) {
@@ -2620,18 +2715,24 @@ async function cmdMigrateDeploy(args, config) {
     if (destructive.length > 0)
         printDestructiveNotice(destructive);
     const runSpinner = new Spinner('Deploying migrations').start();
-    const result = await migrateDeploy(url, config.migrationsDir, { allowDrift: args.allowDrift });
-    if (result.applied.length === 0 && result.errors.length === 0) {
-        runSpinner.succeed('0 applied, all migrations are up to date');
-        newline();
-        return;
-    }
+    const result = await migrateDeploy(url, config.migrationsDir, { allowDrift: args.allowDrift, schema: config.schema });
     if (result.applied.length > 0) {
         runSpinner.succeed(`${bold(String(result.applied.length))} applied`);
         for (const file of result.applied) {
             console.log(`    ${green(symbols.check)} ${file.filename}`);
         }
     }
+    else if (result.errors.length === 0) {
+        runSpinner.succeed('0 applied, all migrations are up to date');
+    }
+    // Reported on EVERY path, including the one where nothing was applied. That is
+    // `--allow-drift`'s most common case by far (you edited an already-applied
+    // file, so nothing is pending), and it used to sit below an early return: the
+    // stored checksum was rewritten and the terminal said everything was up to
+    // date. A write to migration history announced as a no-op is worse than no
+    // report at all, because the reader now believes the file and the database
+    // still disagree.
+    reportRebaselined(result.rebaselined);
     warnOutOfOrder(result.outOfOrder);
     if (result.errors.length > 0) {
         runSpinner.fail('Deploy failed');
@@ -2689,11 +2790,24 @@ async function cmdMigrateDown(args, config) {
     label('Migrations', config.migrationsDir);
     newline();
     if (args.dryRun) {
-        const status = await migrateStatus(url, config.migrationsDir);
-        // Rollback order is newest-applied first, and a migration whose file is
-        // missing has no DOWN section to show.
-        const applied = status.filter((st) => st.applied && !st.missingFile).map((st) => st.file);
-        printMigrationDryRun(applied.reverse().slice(0, args.step ?? 1), 'down');
+        // Computed by the RUNNER'S rule (planMigrationRollback), not re-derived
+        // from `status`. The old derivation sorted by filename and dropped applied
+        // migrations whose file is missing, so with a deleted file it named the
+        // migration AFTER the gap while the real run stopped at the gap.
+        const plan = await planMigrationRollback(url, config.migrationsDir, {
+            step: args.step ?? 1,
+            schema: config.schema,
+            // The real rollback refuses on drift unless this is set, so the preview
+            // has to be told too: without it a deleted migration file previewed as
+            // "would roll back 1 migration" while `migrate down` refused with E006.
+            allowDrift: args.allowDrift,
+        });
+        printMigrationDryRun(plan.toRollback, 'down');
+        if (plan.stoppedAt) {
+            warn(`Rollback would STOP at ${bold(`${plan.stoppedAt.name}.sql`)}: ${plan.stoppedAt.error}`);
+            console.log(`  ${dim('A rollback batch is strictly LIFO with no gaps, so nothing after it would run.')}`);
+            newline();
+        }
         return;
     }
     const spinner = new Spinner('Rolling back migration(s)').start();
@@ -2702,6 +2816,8 @@ async function cmdMigrateDown(args, config) {
         result = await migrateDown(url, config.migrationsDir, {
             step: args.step ?? 1,
             allowDestructive: args.allowDestructive,
+            allowDrift: args.allowDrift,
+            schema: config.schema,
         });
     }
     catch (err) {
@@ -2717,19 +2833,27 @@ async function cmdMigrateDown(args, config) {
         result = await migrateDown(url, config.migrationsDir, {
             step: args.step ?? 1,
             allowDestructive: true,
+            allowDrift: args.allowDrift,
+            schema: config.schema,
         });
     }
-    if (result.rolledBack.length === 0 && result.errors.length === 0) {
-        spinner.succeed('No migrations to roll back');
-        newline();
-        return;
-    }
     if (result.rolledBack.length > 0) {
         spinner.succeed(`Rolled back ${bold(String(result.rolledBack.length))} migration(s)`);
         for (const file of result.rolledBack) {
             console.log(`    ${yellow(symbols.arrowRight)} ${file.filename}`);
         }
     }
+    else if (result.errors.length === 0) {
+        spinner.succeed('No migrations to roll back');
+    }
+    // Reported on EVERY path, including the one where nothing was applied. That is
+    // `--allow-drift`'s most common case by far (you edited an already-applied
+    // file, so nothing is pending), and it used to sit below an early return: the
+    // stored checksum was rewritten and the terminal said everything was up to
+    // date. A write to migration history announced as a no-op is worse than no
+    // report at all, because the reader now believes the file and the database
+    // still disagree.
+    reportRebaselined(result.rebaselined);
     if (result.errors.length > 0) {
         spinner.fail('Rollback failed');
         for (const { file, error: msg } of result.errors) {
@@ -2754,7 +2878,8 @@ async function cmdMigrateStatus(_args, config) {
         newline();
         return;
     }
-    const statuses = await migrateStatus(url, config.migrationsDir);
+    warnIgnoredMigrationFiles(config.migrationsDir);
+    const statuses = await migrateStatus(url, config.migrationsDir, { schema: config.schema });
     const appliedCount = statuses.filter((s) => s.applied).length;
     const pendingCount = statuses.filter((s) => !s.applied).length;
     info(`${bold(String(appliedCount))} applied, ${pendingCount > 0 ? yellow(bold(String(pendingCount))) : bold(String(pendingCount))} pending`);
@@ -2822,10 +2947,61 @@ export function getSeedExecutionPlan(seedFile) {
     }
     throw new Error(`Unsupported seed file extension: ${ext || '(none)'}. Use seed.ts, seed.js, or seed.sql.`);
 }
+/**
+ * The seed's pinned connection string, refusing a configured schema that does
+ * not exist before any seed kind runs.
+ *
+ * `migrate` gained that guard and `seed` did not, because the seed reached
+ * `connectionStringForSchema` directly instead of going through the migration
+ * runner's connect helper. So seeding a project whose schema was missing (a
+ * typo, or a fresh database nobody had created it in) failed with a bare
+ * `relation "..." does not exist`: no error code, no schema name, no mention of
+ * search_path or turbine.config.ts. That is verbatim the failure the guard
+ * exists to prevent.
+ *
+ * Checked ONCE here rather than in each of the three seed kinds, because that
+ * is the only place all three still share: the `.sql` kind opens its own client
+ * below, while the `.ts` and `.js` kinds connect somewhere this process cannot
+ * reach (a `tsx` CHILD PROCESS, and the user's own `defineSeed` callback), both
+ * of them through the `DATABASE_URL` this function returns.
+ *
+ * The probe also reads the connection's own `search_path`, so the pin EXTENDS
+ * it rather than replacing it, exactly as `migrate` does. Without that, seeding
+ * into a pinned schema stops resolving extension types and functions that the
+ * unpinned connection could see.
+ */
+async function seedConnectionString(config) {
+    const schema = config.schema;
+    if (schema === undefined || schema === '')
+        return config.url;
+    // Before the connection: an unpinnable NAME is not a missing schema.
+    assertPinnableSchema(schema);
+    const { default: pg } = await import('pg');
+    const probe = new pg.Client({ connectionString: config.url });
+    await probe.connect();
+    let inherited;
+    try {
+        await assertSchemaExists(probe, schema);
+        const shown = await probe.query('SHOW search_path');
+        inherited = parseSearchPathValue(shown.rows[0]?.search_path ?? '');
+    }
+    finally {
+        await probe.end();
+    }
+    return connectionStringForSchema(config.url, schema, inherited);
+}
 async function runSeedPlan(plan, config) {
     const oldDatabaseUrl = process.env.DATABASE_URL;
-    if (config.url)
-        process.env.DATABASE_URL = config.url;
+    // The seed connects through DATABASE_URL, whichever way it runs: `defineSeed`
+    // reads it in the tsx child and in the in-process `import()`, and the `.sql`
+    // path opens a client on it below. So the configured schema is applied HERE,
+    // once, as the `options=-c search_path` connection parameter (never a `SET`),
+    // and every seed kind inherits it. Without this the seed ran against the
+    // role's default path while `push` and the generated client used
+    // `config.schema`, so the two halves of one project wrote to two namespaces.
+    const seedUrl = config.url ? await seedConnectionString(config) : undefined;
+    if (seedUrl)
+        process.env.DATABASE_URL = seedUrl;
     try {
         if (plan.kind === 'tsx') {
             if (!canResolveTsx()) {
@@ -2844,7 +3020,7 @@ async function runSeedPlan(plan, config) {
                     stdio: 'inherit',
                     env: {
                         ...process.env,
-                        DATABASE_URL: config.url || process.env.DATABASE_URL,
+                        DATABASE_URL: seedUrl || process.env.DATABASE_URL,
                         TURBINE_SEED_SENTINEL: sentinel,
                     },
                 });
@@ -2867,7 +3043,10 @@ async function runSeedPlan(plan, config) {
             await mod.default();
             return;
         }
-        const url = requireUrl(config);
+        // `seedUrl` is already pinned and already schema-checked; `requireUrl` is
+        // only reached when no url was configured at all, in which case there is no
+        // schema to pin either.
+        const url = seedUrl ?? requireUrl(config);
         const { default: pg } = await import('pg');
         const client = new pg.Client({ connectionString: url });
         await client.connect();
@@ -2927,6 +3106,7 @@ async function cmdStatus(_args, config) {
     newline();
     const spinner = new Spinner('Introspecting database').start();
     const schema = await introspect({
+        keepColumnNames: config.keepColumnNames,
         connectionString: url,
         schema: config.schema,
         include: config.include.length ? config.include : undefined,
@@ -3072,6 +3252,7 @@ async function cmdDoctor(args, config) {
     }
     const spinner = jsonMode ? null : new Spinner('Introspecting database').start();
     const schema = await introspect({
+        keepColumnNames: config.keepColumnNames,
         connectionString: url,
         schema: config.schema,
         include: config.include.length ? config.include : undefined,
@@ -4078,6 +4259,7 @@ function showInitHelp() {
     console.log(`    ${cyan('--skip-seed')}        Don't create the seed file or run the seed`);
     console.log(`    ${cyan('--skip-push')}        Don't push the schema to the database`);
     console.log(`    ${cyan('--skip-generate')}    Don't generate the typed client`);
+    console.log(`    ${cyan('--schema, -s')} ${dim('<name>')} Postgres schema to write into config ${dim('(default: public)')}`);
     newline();
 }
 function showGenerateHelp() {
@@ -4185,8 +4367,9 @@ function showMigrateHelp() {
     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)')}`);
+    console.log(`    ${cyan('--allow-drift')}     Re-baseline drifted checksums, REWRITING history ${dim('(up / deploy / down)')}`);
     console.log(`    ${cyan('--allow-destructive')} Run data-destroying migration statements without the interactive confirm`);
+    console.log(`    ${cyan('--schema, -s')} ${dim('<name>')}  Postgres schema the migrations run in ${dim('(default: public)')}`);
     console.log(`    ${cyan('--verbose, -v')}     Show detailed output`);
     newline();
     console.log(`  ${bold('Examples:')}`);
@@ -4213,7 +4396,8 @@ function showSeedHelp() {
     console.log(`  ${dim('TypeScript seeds run with')} ${cyan('npx tsx')} ${dim('and can export')} ${cyan('defineSeed(fn)')}${dim('.')}`);
     newline();
     console.log(`  ${bold('Options:')}`);
-    console.log(`    ${cyan('--url, -u')} ${dim('<url>')}   Postgres connection string`);
+    console.log(`    ${cyan('--url, -u')} ${dim('<url>')}     Postgres connection string`);
+    console.log(`    ${cyan('--schema, -s')} ${dim('<name>')}  Postgres schema the seed writes into ${dim('(default: public)')}`);
     newline();
 }
 function showStatusHelp() {
@@ -4421,7 +4605,7 @@ function showHelp() {
     console.log(`    ${cyan('--recipe')} ${dim('<name>')}       Scaffold a named migration recipe, e.g. backfill ${dim('(create)')}`);
     console.log(`    ${cyan('--step, -n')} ${dim('<N>')}       Number of migrations to apply/rollback`);
     console.log(`    ${cyan('--allow-destructive')}  Run data-destroying statements without prompting ${dim('(up/down/push)')}`);
-    console.log(`    ${cyan('--allow-drift')}        Bypass checksum validation on ${cyan('migrate up')} / ${cyan('deploy')} ${dim('(advanced)')}`);
+    console.log(`    ${cyan('--allow-drift')}        Re-baseline drifted checksums on ${cyan('migrate up')} / ${cyan('deploy')} / ${cyan('down')} ${dim('(advanced)')}`);
     newline();
     console.log(`  ${bold('Init options:')}`);
     console.log(`    ${cyan('--yes, -y')}            Accept every step's default (non-interactive)`);
@@ -4593,7 +4777,20 @@ function showVersion() {
 // Main
 // ---------------------------------------------------------------------------
 async function main() {
-    const args = parseArgs();
+    let args;
+    try {
+        args = parseArgs();
+    }
+    catch (err) {
+        // A last-resort net. Every flag refusal parseArgs makes goes through
+        // `failArg` (banner, red line, hints) and exits there, so nothing is
+        // expected here; anything that does arrive is a bug in the parser rather
+        // than in the caller's command line, and printing it beats swallowing it.
+        errorLine();
+        error(err instanceof Error ? err.message : String(err));
+        errorLine();
+        process.exit(1);
+    }
     // Quick exits that don't need config
     if (args.command === 'help' || args.command === '--help' || args.command === '-h') {
         showHelp();
@@ -4723,7 +4920,20 @@ async function main() {
     }
     catch (err) {
         if (err instanceof Error) {
-            if (err.message.includes('ECONNREFUSED') || err.message.includes('connection')) {
+            // TYPE first, message second. These branches sniff for substrings, and
+            // `ValidationError` beat them by accident: a refused `--schema` value says
+            // "used as a connection parameter", which contains "connection", so a bad
+            // flag value was reported under "Could not connect to database" with three
+            // firewall hints. A typed error already knows what it is.
+            if (err instanceof ValidationError) {
+                errorLine();
+                error(redactUrl(err.message));
+                if (args.verbose && err.stack) {
+                    errorLine();
+                    console.error(dim(redactUrl(err.stack)));
+                }
+            }
+            else if (err.message.includes('ECONNREFUSED') || err.message.includes('connection')) {
                 errorLine();
                 error(`Could not connect to database`);
                 errorLine(`${dim(redactUrl(err.message))}`);

package/dist/cli/mcp.d.ts

@@ -26,9 +26,32 @@ export interface McpTransport {
      */
     pool?: PgCompatPool;
 }
+/**
+ * Why a session ended: an explicit {@link McpServerHandle.dispose} (a signal,
+ * stdin closing), or the server closing it ITSELF because the peer's framing
+ * was lost. `runMcpServer` exits non-zero on the latter so a supervisor
+ * restarts the server rather than assuming a clean end.
+ */
+export type McpCloseReason = 'disposed' | 'framing-lost';
 export interface McpServerHandle {
     dispose(): Promise<void>;
+    /**
+     * Resolves once the session has ended and the pool is closed, by either
+     * path. After the unframed-buffer refusal the server used to detach its
+     * reader and then neither exit nor answer: a live process that would never
+     * speak again, which a supervisor cannot tell from a healthy idle one.
+     */
+    closed: Promise<McpCloseReason>;
 }
+/**
+ * The most bytes the stdio reader will hold WITHOUT seeing a newline.
+ *
+ * 8 MiB, which is far above any real request: the largest thing a client sends
+ * here is a `compile_query` args object, and the tool schemas cap what can
+ * meaningfully be in one. It is a liveness bound, not a policy: see the check
+ * itself for why an over-long line ends the session instead of being truncated.
+ */
+export declare const MAX_STDIO_BUFFER_BYTES: number;
 export declare function startMcpServer(options: McpServerOptions, transport?: McpTransport): McpServerHandle;
 /**
  * Every SHORTEST relation chain from `from` to `to`, in deterministic order.