turbine-orm 0.81.0 → 0.90.0

package/dist/cli/index.js

@@ -25,7 +25,7 @@
  *   npx turbine init --url postgres://...
  *   npx turbine migrate create add_users_table
  */
-import { appendFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync, } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { basename, dirname, extname, join, relative, resolve, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -35,24 +35,28 @@ 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';
-import { introspect } from '../introspect.js';
+import { applyTableFilters, introspect, printableCatalogName } from '../introspect.js';
 import { collectDivergenceCandidateColumns, collectDivergenceOrderColumns, findPlanDivergence, PLAN_DIVERGENCE_THRESHOLDS, } from '../plan-divergence.js';
 import { applyFlipVerdicts, emptyFlipProbeResult, needsFlipProbe, probePlanFlips } from '../plan-flip-probe.js';
 import { fingerprintPrismaSchema } from '../prisma-schema-fingerprint.js';
 import { closestName } from '../query/utils.js';
 import { snakeToCamel } from '../schema.js';
-import { DestructivePushRefusal, schemaDiff, schemaPush } from '../schema-sql.js';
+import { DestructivePushRefusal, driftWarnings, schemaDiff, schemaPush } from '../schema-sql.js';
+import { applyCodeFirstColumnTags, extractCodeFirstColumnTags } from './code-first-tags.js';
 import { configTemplate, connectionStringHasPassword, DEFAULT_INIT_SEED_FILE, findConfigFile, loadConfigResult, looksLikeSchemaFilePath, resolveConfig, resolveSeedFile, unwrapModuleDefault, } from './config.js';
 import { DESTRUCTIVE_KIND_LABEL } from './destructive.js';
+import { errorText } from './error-text.js';
 import { canResolveTsx, getTsLoaderError, needsTsLoader, registerTsLoader } from './loader.js';
 import { runMcpServer } from './mcp.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 { assertNoEmbeddedTransactions, assertPinnableSchema, assertSchemaExists, assertUpHasStatements, buildDiffMigrationBody, collectUpDestructive, connectionStringForSchema, createMigration, formatChecksumMismatchError, formatPendingAutoRefusal, inspectMigrationDeploy, listIgnoredSqlFiles, listMigrationFiles, MIGRATION_RECIPES, migrateDeploy, migrateDown, migrateStatus, migrateUp, parseMigrationContent, pendingMigrationFiles, planMigrationRollback, rollbacksWithoutSql, statusGateProblems, summarizeMigrationStatus, } from './migrate.js';
 import { startObserve } from './observe.js';
 import { formatPrismaReport, summaryLines } from './prisma-report.js';
 import { DEFAULT_EXCLUDED_TABLES, resolvePrismaSchema } from './prisma-resolve.js';
 import { PrismaParseError, parsePrismaSchema, resolvePrismaDatasourceUrl, } from './prisma-schema.js';
 import { startStudio } from './studio.js';
 import { banner, blue, bold, box, cyan, dim, divider, elapsed, error, errorBanner, errorLine, table as formatTable, gray, green, header, info, label, magenta, newline, red, redactUrl, Spinner, success, symbols, warn, yellow, } from './ui.js';
+/** How long a bare `migrate deploy --wait` waits for a concurrent deploy to finish. */
+export const DEFAULT_LOCK_WAIT_SECONDS = 300;
 /**
  * Fail an argument-parse error the way every other CLI failure looks: banner,
  * red error line, then indented hint lines. The flag validators used to call
@@ -107,6 +111,7 @@ const GLOBAL_FLAGS = [
 const COMMAND_FLAGS = {
     init: ['--yes', '--schema-file', '--skip-schema', '--with-schema', '--skip-seed', '--skip-push', '--skip-generate'],
     generate: [
+        '--schema-file',
         '--zod',
         '--include-views',
         '--no-timestamp',
@@ -116,7 +121,7 @@ const COMMAND_FLAGS = {
         '--allow-empty',
     ],
     'migrate-from-prisma': ['--no-db', '--if-db', '--allow-partial', '--no-timestamp'],
-    push: ['--schema-file', '--dry-run', '--allow-destructive'],
+    push: ['--schema-file', '--dry-run', '--exit-code', '--allow-destructive'],
     migrate: [
         '--schema-file',
         '--auto',
@@ -124,8 +129,12 @@ const COMMAND_FLAGS = {
         '--recipe',
         '--step',
         '--dry-run',
+        '--exit-code',
+        '--wait',
         '--allow-drift',
         '--allow-destructive',
+        '--allow-pending',
+        '--allow-pooler',
     ],
     seed: [],
     status: [],
@@ -303,6 +312,8 @@ export function parseArgs(argv = process.argv.slice(2)) {
     const unknownFlags = [];
     /** The raw `--step` operand, judged after the loop. Absent means unset. */
     let stepRaw;
+    /** The raw `--wait` operand, judged after the loop: undefined absent, null bare `--wait`. */
+    let waitRaw;
     for (; i < args.length; i++) {
         const arg = args[i];
         const next = args[i + 1];
@@ -310,8 +321,15 @@ export function parseArgs(argv = process.argv.slice(2)) {
         // (`--step -1`, `--host -x`) is consumed by its own case and never reaches
         // this test. A bare `-`-prefixed token that is not a flag reaches it and is
         // rejected: no command takes a negative-number positional.
-        if (accepted && arg.startsWith('-') && !accepted.has(arg))
+        // `--wait=30` is the one flag whose value attaches with `=`, so it is
+        // matched by its name and handled here rather than by a `case` label.
+        const attachedWait = arg.startsWith('--wait=');
+        if (accepted && arg.startsWith('-') && !accepted.has(attachedWait ? '--wait' : arg))
             unknownFlags.push(arg);
+        if (attachedWait) {
+            waitRaw = arg.slice('--wait='.length);
+            continue;
+        }
         switch (arg) {
             case '--url':
             case '-u':
@@ -355,6 +373,23 @@ export function parseArgs(argv = process.argv.slice(2)) {
             case '--dry-run':
                 result.dryRun = true;
                 break;
+            case '--exit-code':
+                result.exitCode = true;
+                break;
+            case '--allow-pending':
+                result.allowPending = true;
+                break;
+            case '--wait':
+                // `--wait 30` reads the next token only when it is all digits: `deploy`
+                // takes no positional, so a bare number after the flag is its value.
+                if (next !== undefined && /^\d+$/.test(next)) {
+                    waitRaw = next;
+                    i++;
+                }
+                else {
+                    waitRaw = null;
+                }
+                break;
             case '--auto':
                 result.auto = true;
                 break;
@@ -437,8 +472,8 @@ export function parseArgs(argv = process.argv.slice(2)) {
                 break;
             case '--import-ext':
             case '--import-extension':
-                if (next !== 'js' && next !== 'none' && next !== 'auto') {
-                    failArg(`${cyan('--import-ext')} requires one of: js, none, auto ${dim(`(got ${next ?? 'nothing'})`)}`, 'Example: npx turbine generate --import-ext none');
+                if (next !== 'js' && next !== 'ts' && next !== 'none' && next !== 'auto') {
+                    failArg(`${cyan('--import-ext')} requires one of: js, ts, none, auto ${dim(`(got ${next ?? 'nothing'})`)}`, 'Example: npx turbine generate --import-ext ts');
                 }
                 result.importExtension = next;
                 i++;
@@ -529,6 +564,18 @@ export function parseArgs(argv = process.argv.slice(2)) {
         }
         result.step = parsed;
     }
+    if (waitRaw !== undefined && accepted !== undefined) {
+        if (waitRaw === null) {
+            result.wait = DEFAULT_LOCK_WAIT_SECONDS;
+        }
+        else {
+            const parsed = /^\d+$/.test(waitRaw.trim()) ? Number.parseInt(waitRaw, 10) : Number.NaN;
+            if (!Number.isSafeInteger(parsed) || parsed < 1) {
+                failArg(`${cyan('--wait')} expects a positive whole number of seconds, got ${bold(waitRaw === '' ? '(nothing)' : `"${waitRaw}"`)}.`, `Bare ${'--wait'} waits ${DEFAULT_LOCK_WAIT_SECONDS} seconds. To not wait at all, leave the flag off.`, 'Example: npx turbine migrate deploy --wait=120');
+            }
+            result.wait = parsed;
+        }
+    }
     return result;
 }
 // ---------------------------------------------------------------------------
@@ -727,6 +774,11 @@ export function loadDotEnvForCli(deps = {}) {
     if (!fileExists(envPath)) {
         return { fileExists: false, loaded: false, unsupported: false, databaseUrlProvenance: shellOrNone };
     }
+    // An exported-but-empty `DATABASE_URL=` means "not configured", and the loader
+    // never overrides a variable that is already set, so it would otherwise block
+    // the value in the `.env` for good.
+    if (env.DATABASE_URL === '')
+        delete env.DATABASE_URL;
     const loader = deps.loadEnvFile !== undefined
         ? deps.loadEnvFile
         : typeof process.loadEnvFile === 'function'
@@ -744,7 +796,7 @@ export function loadDotEnvForCli(deps = {}) {
             loaded: false,
             unsupported: false,
             databaseUrlProvenance: shellOrNone,
-            loadError: err instanceof Error ? err.message : String(err),
+            loadError: errorText(err),
         };
     }
     // `.env`-sourced only if DATABASE_URL was absent before and present after.
@@ -1143,42 +1195,94 @@ DATABASE_URL=postgres://user:password@localhost:5432/database
  * @internal exported for tests.
  */
 export function scaffoldEnvForUrl(url) {
+    // The plan is read from disk and the writes come after it, so a file can
+    // appear in between. Creation is exclusive (see createFileExclusive); when it
+    // loses, plan again from what is there now. The cap only ends the loop for a
+    // name that cannot be read but cannot be created either, a dangling symlink.
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const plan = applyEnvScaffold(url);
+        if (plan)
+            return plan;
+    }
+    throw new ValidationError('Could not write .env, .env.example and .gitignore: one of those names is taken by something that cannot be read ' +
+        '(a dangling symlink?). Remove it and run the command again.');
+}
+/** One planning pass plus its writes; undefined when a create found its name already taken. */
+function applyEnvScaffold(url) {
     const envPath = '.env';
     const envExamplePath = '.env.example';
     const gitignorePath = '.gitignore';
-    const envExists = existsSync(envPath);
+    const env = readIfPresent(envPath);
+    const gitignore = readIfPresent(gitignorePath);
     const plan = planEnvScaffold({
-        envExists,
-        envHasDatabaseUrl: envExists ? /^\s*(export\s+)?DATABASE_URL\s*=/m.test(readFileSync(envPath, 'utf-8')) : false,
-        envExampleExists: existsSync(envExamplePath),
-        gitignoreExists: existsSync(gitignorePath),
-        gitignoreIgnoresEnv: existsSync(gitignorePath) ? gitignoreIgnoresEnv(readFileSync(gitignorePath, 'utf-8')) : false,
+        envExists: env !== undefined,
+        envHasDatabaseUrl: env !== undefined && /^\s*(export\s+)?DATABASE_URL\s*=/m.test(env),
+        envExampleExists: readIfPresent(envExamplePath) !== undefined,
+        gitignoreExists: gitignore !== undefined,
+        gitignoreIgnoresEnv: gitignore !== undefined && gitignoreIgnoresEnv(gitignore),
     });
     // .gitignore FIRST: the ignore rule has to exist before the file holding the
     // password does, or a `git add -A` in between commits it.
-    if (plan.gitignore === 'created')
-        writeFileSync(gitignorePath, '# Local environment (secrets)\n.env\n', 'utf-8');
-    else if (plan.gitignore === 'appended')
+    if (plan.gitignore === 'created') {
+        if (!createFileExclusive(gitignorePath, '# Local environment (secrets)\n.env\n'))
+            return undefined;
+    }
+    else if (plan.gitignore === 'appended') {
         appendFileSync(gitignorePath, '\n# Local environment (secrets)\n.env\n');
+    }
+    // 0600 on CREATION only. The whole point of this scaffold is moving a live
+    // password out of a committed file, and the default 0644 would leave it
+    // world-readable to every account on a shared box or CI runner. `mode` is
+    // applied by the OS only when the open() actually creates the file, so a
+    // `.env` that exists keeps whatever mode its owner chose.
     if (plan.env === 'created') {
-        // 0600 on CREATION only. The whole point of this scaffold is moving a live
-        // password out of a committed file, and the default 0644 would leave it
-        // world-readable to every account on a shared box or CI runner. `mode` is
-        // applied by the OS only when the open() actually creates the file, so if
-        // one appeared since the existsSync above we write into it without widening
-        // or narrowing whatever mode its owner chose.
-        writeFileSync(envPath, `# Turbine database connection. Never commit this file.\nDATABASE_URL=${url}\n`, {
-            encoding: 'utf-8',
-            mode: 0o600,
-        });
+        const body = `# Turbine database connection. Never commit this file.\nDATABASE_URL=${url}\n`;
+        if (!createFileExclusive(envPath, body, 0o600))
+            return undefined;
     }
     else if (plan.env === 'appended') {
-        appendFileSync(envPath, `\n# Added by turbine init\nDATABASE_URL=${url}\n`);
+        appendFileSync(envPath, `\n# Added by turbine init\nDATABASE_URL=${url}\n`, { mode: 0o600 });
     }
-    if (plan.envExample === 'created')
-        writeFileSync(envExamplePath, ENV_EXAMPLE_TEMPLATE, 'utf-8');
+    if (plan.envExample === 'created' && !createFileExclusive(envExamplePath, ENV_EXAMPLE_TEMPLATE))
+        return undefined;
     return plan;
 }
+/**
+ * A file's text, or undefined when there is no such file. One read in place of
+ * an existence check followed by a read, so there is no window between the two.
+ * A directory under that name counts as present: the write step then fails on
+ * it by name, which is the error that was always raised.
+ */
+function readIfPresent(path) {
+    try {
+        return readFileSync(path, 'utf-8');
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT')
+            return undefined;
+        if (code === 'EISDIR')
+            return '';
+        throw err;
+    }
+}
+/**
+ * Create `path` only if nothing is there; false when the name is taken.
+ * `wx` is O_CREAT | O_EXCL: the kernel refuses (EEXIST) any existing name,
+ * a symlink included, so a file that appeared after the plan was made is never
+ * truncated and a link planted at the name is never written through.
+ */
+function createFileExclusive(path, body, mode) {
+    try {
+        writeFileSync(path, body, { encoding: 'utf-8', flag: 'wx', ...(mode === undefined ? {} : { mode }) });
+        return true;
+    }
+    catch (err) {
+        if (err.code === 'EEXIST')
+            return false;
+        throw err;
+    }
+}
 /** Say exactly what was written where, so nobody has to guess where the password went. */
 function reportEnvScaffold(plan, url) {
     warn(`The connection string passed to ${cyan('--url')} contains a password.`);
@@ -1214,8 +1318,8 @@ function ensureInitScaffoldDirs(config) {
         success(`Created ${cyan(`${config.out}/`)}`);
     }
     const gitignorePath = '.gitignore';
-    if (existsSync(gitignorePath)) {
-        const gitignoreContent = readFileSync(gitignorePath, 'utf-8');
+    const gitignoreContent = readIfPresent(gitignorePath);
+    if (gitignoreContent !== undefined) {
         const additions = [];
         if (!gitignoreContent.includes('generated/turbine'))
             additions.push('generated/turbine/');
@@ -1321,8 +1425,19 @@ async function runInitGenerate(config, url) {
         });
         const tableNames = Object.keys(schema.tables);
         spinner.succeed(`Found ${bold(String(tableNames.length))} tables`);
+        // The schema file init just pushed is where `pii` / `updatedAt` live.
+        const appliedTags = await overlayCodeFirstTags(schema, config);
+        if (appliedTags && describeAppliedTags(appliedTags)) {
+            info(`Applied column tags from ${cyan(config.schemaFile)}: ${describeAppliedTags(appliedTags)}`);
+        }
         const genSpinner = new Spinner('Generating TypeScript client').start();
-        const result = generate({ schema, outDir: config.out, connectionString: url });
+        const result = generate({
+            schema,
+            outDir: config.out,
+            connectionString: url,
+            importExtension: config.importExtension,
+            columnTypes: await generatorColumnTypesFor(appliedTags, config, schema, url),
+        });
         genSpinner.succeed(`Generated ${bold(String(result.files.length))} files to ${cyan(`${config.out}/`)}`);
         // The accessor name the generator emits is snakeToCamel of the table name
         // (generate.ts, generateIndex), so this is the spelling that autocompletes.
@@ -1331,8 +1446,7 @@ async function runInitGenerate(config, url) {
     }
     catch (err) {
         spinner.fail('Could not generate client');
-        if (err instanceof Error)
-            errorLine(dim(redactUrl(err.message)));
+        errorLine(dim(redactUrl(errorText(err))));
         info(`Run generation later with: ${cyan('npx turbine generate')}`);
         return { tableCount: null };
     }
@@ -1346,13 +1460,14 @@ async function runInitSeed(config) {
     }
     const spinner = new Spinner('Running seed file').start();
     try {
-        await runSeedPlan(getSeedExecutionPlan(seedFile), config);
+        const outcome = await runSeedPlan(getSeedExecutionPlan(seedFile), config);
         spinner.succeed('Seed completed');
+        if (!outcome.confirmed)
+            warn(UNCONFIRMED_SEED_NOTICE);
     }
     catch (err) {
         spinner.fail('Seed failed');
-        if (err instanceof Error)
-            console.log(`  ${dim(redactUrl(err.message))}`);
+        console.log(`  ${dim(redactUrl(errorText(err)))}`);
     }
 }
 /** Human label for a step, used in prompts and skip messages. */
@@ -1663,7 +1778,7 @@ async function cmdInit(args, config) {
         console.log(`  ${dim('Nothing to connect to yet?')} ${cyan('npx turbine studio --demo')} ${dim('needs no database.')}`);
     }
     else {
-        const accessor = generated.sampleAccessor ?? 'users';
+        const accessor = shown(generated.sampleAccessor ?? 'users');
         console.log(`  ${dim('1.')} Import the generated client:`);
         console.log(`     ${cyan(generatedClientImport(config))}`);
         newline();
@@ -1712,7 +1827,7 @@ export function refuseSchemaFilePath(config, options = {}) {
     errorLine();
     errorLine(`${dim('Or set it once in')} ${cyan('turbine.config.ts')}${dim(':')}`);
     errorLine(`  ${green('schema:')} ${cyan("'public'")}${dim(",       // or omit, reads the 'public' schema")}`);
-    errorLine(`  ${green('schemaFile:')} ${cyan(`'${config.schema}'`)}${dim(', // your defineSchema() file (used by `turbine push`)')}`);
+    errorLine(`  ${green('schemaFile:')} ${cyan(`'${config.schema}'`)}${dim(', // your defineSchema() file (read by push and generate)')}`);
     if (options.escapeHatch) {
         errorLine();
         errorLine(`${dim('Re-run with')} ${cyan(options.escapeHatch)} ${dim('to use this literal schema name anyway.')}`);
@@ -1721,6 +1836,113 @@ export function refuseSchemaFilePath(config, options = {}) {
     process.exit(1);
 }
 // ---------------------------------------------------------------------------
+// Code-first column tags
+// ---------------------------------------------------------------------------
+/**
+ * Overlay the column tags the defineSchema() file declares (`pii`, `updatedAt`,
+ * `maxLength`) onto an introspected schema, before it is generated.
+ *
+ * Introspection reads the database, and the database has no column for these
+ * flags, so a client generated from introspection alone returns PII by default,
+ * never stamps `updatedAt`, and leaves Studio and the MCP server with nothing to
+ * redact. The schema file is the only place the tags exist.
+ *
+ * Loaded when the file was named (`--schema-file` / config `schemaFile`) or sits
+ * at the default path. A named file that is missing, or any file that cannot be
+ * loaded, fails the command: carrying on would generate the unredacted client
+ * this exists to prevent. Only a missing DEFAULT file is skipped, which is a
+ * database-first project with no schema file at all.
+ *
+ * Returns what was applied, or `null` when there was no schema file to read.
+ *
+ * @internal exported for tests.
+ */
+export async function overlayCodeFirstTags(schema, config) {
+    if (config.schemaFileConfigured !== true && !existsSync(resolve(config.schemaFile)))
+        return null;
+    const def = await loadSchemaFile(config.schemaFile);
+    const filters = {
+        include: config.include.length ? config.include : undefined,
+        exclude: config.exclude.length ? config.exclude : undefined,
+    };
+    return applyCodeFirstColumnTags(schema, extractCodeFirstColumnTags(def), {
+        source: config.schemaFile,
+        // A table the caller filtered out of the client has no client to tag.
+        inScope: (table) => applyTableFilters([table], filters).length > 0,
+    });
+}
+/** "2 pii, 1 updatedAt" for the line that reports an {@link overlayCodeFirstTags} result. */
+function describeAppliedTags(applied) {
+    const parts = [];
+    if (applied.pii > 0)
+        parts.push(`${applied.pii} pii`);
+    if (applied.updatedAt > 0)
+        parts.push(`${applied.updatedAt} updatedAt`);
+    if (applied.maxLength > 0)
+        parts.push(`${applied.maxLength} maxLength`);
+    const tsTypes = Object.keys(applied.columnTypes).length;
+    if (tsTypes > 0)
+        parts.push(`${tsTypes} tsType`);
+    return parts.join(', ');
+}
+/**
+ * The generator's `columnTypes`: the schema file's `tsType` declarations, then
+ * the config file's `columnTypes`, which wins on the same key. A config key
+ * whose table the run's include / exclude filters leave out is dropped, since
+ * that table has no generated type to override; every other key goes to the
+ * generator, which rejects one naming no table or column.
+ *
+ * An `include` list leaves out every table it does not name, so a misspelt
+ * table looks exactly like a real table that was left out. `databaseTables`
+ * (every table the schema holds, before filtering) tells them apart: only a
+ * table the database has is dropped, and a name it does not have goes on to the
+ * generator, which names the closest match. Without it every key outside the
+ * filters is dropped.
+ *
+ * @internal exported for tests.
+ */
+export function generatorColumnTypes(applied, config, schema, databaseTables) {
+    const filters = {
+        include: config.include.length ? config.include : undefined,
+        exclude: config.exclude.length ? config.exclude : undefined,
+    };
+    const merged = { ...applied?.columnTypes };
+    for (const [key, type] of Object.entries(config.columnTypes ?? {})) {
+        const table = key.slice(0, key.lastIndexOf('.'));
+        const leftOut = !Object.hasOwn(schema.tables, table) && applyTableFilters([table], filters).length === 0;
+        if (leftOut && (databaseTables === undefined || databaseTables.has(table)))
+            continue;
+        merged[key] = type;
+    }
+    return Object.keys(merged).length > 0 ? merged : undefined;
+}
+/** The names of every table and view in `schema`, before any include / exclude filter. */
+async function listDatabaseTables(url, schema) {
+    const { default: pg } = await import('pg');
+    const client = new pg.Client({ connectionString: url });
+    guardConnection(client);
+    await client.connect();
+    try {
+        const res = await client.query('SELECT table_name FROM information_schema.tables WHERE table_schema = $1', [schema]);
+        return new Set(res.rows.map((r) => r.table_name));
+    }
+    finally {
+        await client.end();
+    }
+}
+/**
+ * {@link generatorColumnTypes} for a run against a database. The catalog is read
+ * only when an `include` list is set and a config key names a table outside the
+ * generated set, which is the one case where a typo and a table left out look
+ * alike.
+ */
+async function generatorColumnTypesFor(applied, config, schema, url, namespace = config.schema) {
+    const keys = Object.keys(config.columnTypes ?? {});
+    const outsideInclude = config.include.length > 0 && keys.some((key) => !Object.hasOwn(schema.tables, key.slice(0, key.lastIndexOf('.'))));
+    const databaseTables = outsideInclude && url ? await listDatabaseTables(url, namespace) : undefined;
+    return generatorColumnTypes(applied, config, schema, databaseTables);
+}
+// ---------------------------------------------------------------------------
 // Command: generate (pull)
 // ---------------------------------------------------------------------------
 async function cmdGenerate(args, config) {
@@ -1759,6 +1981,10 @@ async function cmdGenerate(args, config) {
     for (const t of skippedInternalTables) {
         console.log(`    ${dim(`${symbols.teeEnd} skipped internal table ${t} (add it to include to keep it)`)}`);
     }
+    const appliedTags = await overlayCodeFirstTags(schema, config);
+    if (appliedTags && describeAppliedTags(appliedTags)) {
+        console.log(`    ${dim(`${symbols.teeEnd} applied column tags from ${config.schemaFile}: ${describeAppliedTags(appliedTags)}`)}`);
+    }
     // Guard: zero tables means the generated client would be empty. That is almost
     // always a misconfiguration (wrong `schema`, an include/exclude that filtered
     // everything, or a database with no tables yet) rather than intent. Fail loudly
@@ -1783,12 +2009,12 @@ async function cmdGenerate(args, config) {
         for (const tbl of Object.values(schema.tables)) {
             const relCount = Object.keys(tbl.relations).length;
             const pk = tbl.primaryKey.join(', ') || '(none)';
-            console.log(`  ${symbols.tee} ${bold(tbl.name)} ${dim(`${tbl.columns.length} cols, PK: ${pk}`)}${relCount > 0 ? dim(`, ${relCount} rels`) : ''}`);
+            console.log(`  ${symbols.tee} ${bold(shown(tbl.name))} ${dim(`${tbl.columns.length} cols, PK: ${shown(pk)}`)}${relCount > 0 ? dim(`, ${relCount} rels`) : ''}`);
         }
         newline();
     }
     if (Object.keys(schema.enums).length > 0) {
-        info(`Enums: ${Object.keys(schema.enums).join(', ')}`);
+        info(`Enums: ${Object.keys(schema.enums).map(shown).join(', ')}`);
     }
     // Generate
     const genSpinner = new Spinner('Generating TypeScript client').start();
@@ -1800,6 +2026,7 @@ async function cmdGenerate(args, config) {
         noTimestamp: args.noTimestamp,
         importExtension: config.importExtension,
         keepColumnNames: config.keepColumnNames,
+        columnTypes: await generatorColumnTypesFor(appliedTags, config, schema, url),
     });
     genSpinner.succeed(`Generated ${bold(String(result.files.length))} files in ${elapsed(startTime)}`);
     // List files
@@ -1816,7 +2043,12 @@ async function cmdGenerate(args, config) {
     console.log(`  ${dim('const db = turbine({ connectionString: process.env.DATABASE_URL });')}`);
     // Name a table the client just emitted rather than a hardcoded `users`.
     const sampleAccessor = snakeToCamel(tableNames[0] ?? 'users');
-    console.log(`  ${dim(`const row = await db.${sampleAccessor}.findFirst();`)}`);
+    console.log(`  ${dim(`const row = await db.${shown(sampleAccessor)}.findFirst();`)}`);
+    if (config.importExtension === 'ts') {
+        newline();
+        console.log(`  ${dim('Run it with Node type stripping:')} ${cyan('node --env-file=.env app.ts')} ${dim('(Node 22.18+ or 23.6+; earlier 22.x needs --experimental-strip-types)')}`);
+        console.log(`  ${dim('A type checker needs')} ${cyan('allowImportingTsExtensions')} ${dim('(or')} ${cyan('rewriteRelativeImportExtensions')}${dim(') in tsconfig.json.')}`);
+    }
     newline();
 }
 /**
@@ -1854,8 +2086,15 @@ export function resolveMigrateFromPrismaUrl(configUrl, ast, env) {
  * concatenation, so each file is introduced by a comment naming it.
  */
 export function readPrismaSchemaSource(path) {
-    if (!statSync(path).isDirectory())
+    // Read first, ask what it is only if that fails: a stat followed by a read
+    // can disagree with itself when the path is replaced in between.
+    try {
         return readFileSync(path, 'utf-8');
+    }
+    catch (err) {
+        if (err.code !== 'EISDIR')
+            throw err;
+    }
     const files = readdirSync(path)
         .filter((f) => f.endsWith('.prisma'))
         .sort();
@@ -1890,7 +2129,7 @@ async function cmdMigrateFromPrisma(args, config) {
     catch (err) {
         newline();
         error(`Could not read ${cyan(prismaPath)}`);
-        errorLine(`${red(err instanceof Error ? err.message : String(err))}`);
+        errorLine(`${red(errorText(err))}`);
         errorLine();
         process.exit(1);
     }
@@ -2013,6 +2252,8 @@ async function cmdMigrateFromPrisma(args, config) {
             noTimestamp: args.noTimestamp,
             importExtension: config.importExtension,
             keepColumnNames: config.keepColumnNames,
+            // No schema file is read here, so only the config file's overrides apply.
+            columnTypes: await generatorColumnTypesFor(null, config, schemaMeta, url, 'public'),
         });
         for (const file of gen.files) {
             console.log(`  ${dim(symbols.teeEnd)} ${cyan(join(outDir, file))} ${dim('(client)')}`);
@@ -2045,9 +2286,26 @@ async function cmdMigrateFromPrisma(args, config) {
 // ---------------------------------------------------------------------------
 // Command: push
 // ---------------------------------------------------------------------------
+/**
+ * Print what a diff did NOT compare, under an "in sync" style message.
+ *
+ * "Already in sync" only means the compared surface matches. The rest is listed
+ * so the sentence is not read as a guarantee about the whole database.
+ */
+function printNotCompared(items) {
+    if (!items || items.length === 0)
+        return;
+    console.log(`  ${dim('Not compared, so this says nothing about:')}`);
+    for (const item of items)
+        console.log(`    ${dim(symbols.dot)} ${dim(item)}`);
+    newline();
+}
 async function cmdPush(args, config) {
     banner();
     refuseSchemaFilePath(config);
+    if (args.exitCode && !args.dryRun) {
+        failArg(`${cyan('--exit-code')} needs ${cyan('--dry-run')} on push.`, 'It reports whether the database differs from the schema file (exit 2) without changing it.', 'Example: npx turbine push --dry-run --exit-code');
+    }
     const url = requireUrl(config);
     label('Database', redactUrl(url));
     label('Schema file', config.schemaFile);
@@ -2059,8 +2317,32 @@ async function cmdPush(args, config) {
     const diffSpinner = new Spinner('Computing schema diff').start();
     const diff = await schemaDiff(schemaDef, url, { schema: config.schema });
     if (diff.statements.length === 0 && diff.drop.length === 0) {
-        diffSpinner.succeed('Database is already in sync');
+        // "In sync" is a claim about everything the diff looked at, so it is made
+        // only when the diff also has nothing to say. A difference it cannot apply
+        // (an undeclared index, a reordered enum) is reported as exactly that.
+        const advisories = diff.warnings ?? [];
+        if (advisories.length === 0) {
+            diffSpinner.succeed('Database is already in sync');
+        }
+        else {
+            diffSpinner.succeed('Nothing to apply, but the database is not fully in sync');
+        }
         newline();
+        for (const w of advisories)
+            warn(w);
+        if (advisories.length > 0)
+            newline();
+        printNotCompared(diff.notCompared);
+        // A warning is a difference the diff found and cannot apply (a unique index
+        // that is not unique, a removed enum label), so a gate fails on it. What the
+        // diff only discloses as "not compared" is not a difference it found, and a
+        // CHECK expression that merely reads differently is a warning it cannot
+        // confirm (driftWarnings leaves it out).
+        if (args.exitCode && driftWarnings(diff).length > 0) {
+            warn(`The database differs from the schema file ${dim('(--exit-code: exiting 2)')}.`);
+            newline();
+            process.exit(2);
+        }
         return;
     }
     diffSpinner.succeed('Found changes');
@@ -2117,6 +2399,11 @@ async function cmdPush(args, config) {
     if (args.dryRun) {
         info('Dry run, no changes applied.');
         newline();
+        if (args.exitCode) {
+            warn(`The database differs from the schema file ${dim('(--exit-code: exiting 2)')}.`);
+            newline();
+            process.exit(2);
+        }
         return;
     }
     if (args.allowDestructive) {
@@ -2190,8 +2477,12 @@ async function cmdMigrate(args, config) {
         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('--exit-code')}        Exit 2 when ${cyan('status')} finds pending, modified, missing or misnamed migrations`);
+        console.log(`    ${cyan('--wait')}${dim('[=<seconds>]')}   Make ${cyan('deploy')} wait for a concurrent deploy's lock`);
+        console.log(`    ${cyan('--allow-pending')}    Let ${cyan('--auto')} / ${cyan('--from-diff')} run with migrations pending`);
         console.log(`    ${cyan('--allow-destructive')} Run data-destroying statements without prompting`);
         console.log(`    ${cyan('--allow-drift')}      Re-baseline drifted checksums on ${cyan('up')} / ${cyan('deploy')} / ${cyan('down')} ${dim('(advanced)')}`);
+        console.log(`    ${cyan('--allow-pooler')}     Run ${cyan('up')} / ${cyan('deploy')} / ${cyan('down')} against a transaction pooler anyway ${dim('(refused by default: the migration lock is session-level and a pooler can release it on another backend)')}`);
         newline();
         console.log(`  ${bold('Recipes')} ${dim('(--recipe):')}`);
         for (const [key, recipe] of Object.entries(MIGRATION_RECIPES)) {
@@ -2209,6 +2500,23 @@ async function cmdMigrate(args, config) {
         newline();
         return;
     }
+    // Flags that change what a subcommand does are refused where they do nothing,
+    // rather than accepted and ignored: a CI gate that silently never gates is
+    // worse than one that will not start.
+    if (args.exitCode && sub !== 'status' && sub !== 'list') {
+        failArg(`${cyan('--exit-code')} only applies to ${cyan('migrate status')} (and ${cyan('push --dry-run')}).`, 'Example: npx turbine migrate status --exit-code');
+    }
+    if (args.wait !== undefined && sub !== 'deploy') {
+        failArg(`${cyan('--wait')} only applies to ${cyan('migrate deploy')}.`, 'Example: npx turbine migrate deploy --wait=120');
+    }
+    // The commands that take the migration lock, before the banner and before any
+    // connection. A dry run takes no lock, so it may use any endpoint.
+    if ((sub === 'up' || sub === 'deploy' || sub === 'down') && args.dryRun !== true && config.url) {
+        refusePoolerConnection(config.url, args, {
+            command: `turbine migrate ${sub}`,
+            explanation: MIGRATE_POOLER_EXPLANATION,
+        });
+    }
     switch (sub) {
         case 'create':
             await cmdMigrateCreate(args, config);
@@ -2232,6 +2540,58 @@ async function cmdMigrate(args, config) {
             process.exit(1);
     }
 }
+/**
+ * Stop `migrate create --auto` / `--from-diff` while migrations are pending.
+ *
+ * Both diff the schema file against the live database, and a pending migration
+ * is a change the file already describes and the database does not have yet. The
+ * new migration would repeat it and fail on the first database that runs the
+ * pending one first. See {@link formatPendingAutoRefusal}.
+ */
+async function refuseWhenMigrationsPending(args, config, url, flag) {
+    if (listMigrationFiles(config.migrationsDir).length === 0)
+        return;
+    const pending = pendingMigrationFiles(await migrateStatus(url, config.migrationsDir, { schema: config.schema }));
+    if (pending.length === 0)
+        return;
+    if (args.allowPending) {
+        warn(`--allow-pending is set: ${bold(String(pending.length))} pending migration(s) are NOT reflected in the diff.`);
+        newline();
+        return;
+    }
+    const [first, ...rest] = formatPendingAutoRefusal(pending, flag).split('\n');
+    error(first);
+    for (const line of rest)
+        errorLine(line);
+    errorLine();
+    process.exit(1);
+}
+/**
+ * Explain an empty `--auto` / `--from-diff` diff without claiming more than it
+ * knows: "in sync" only when nothing, extra tables and advisories included, was
+ * left over.
+ */
+function reportNothingToMigrate(diff, spinner) {
+    const advisories = diff.warnings ?? [];
+    if (diff.drop.length === 0 && advisories.length === 0) {
+        spinner.succeed('Database is already in sync: nothing to migrate');
+        newline();
+        printNotCompared(diff.notCompared);
+        return;
+    }
+    spinner.succeed('Nothing to migrate: no statement to write, but the database is not fully in sync');
+    newline();
+    if (diff.drop.length > 0) {
+        warn(`${bold(String(diff.drop.length))} table(s) exist in the database but not in the schema file ` +
+            `(${diff.drop.join(', ')}). A migration never drops a table on its own: write that one by hand.`);
+        newline();
+    }
+    for (const w of advisories)
+        warn(w);
+    if (advisories.length > 0)
+        newline();
+    printNotCompared(diff.notCompared);
+}
 async function cmdMigrateCreate(args, config) {
     banner();
     // `--auto` / `--from-diff` diff the schema FILE against the namespace, so both
@@ -2261,18 +2621,21 @@ async function cmdMigrateCreate(args, config) {
         errorLine();
         process.exit(1);
     }
+    if (args.allowPending && !args.auto && !args.fromDiff) {
+        failArg(`${cyan('--allow-pending')} only applies to ${cyan('--auto')} and ${cyan('--from-diff')}.`, 'It lets a diff-generated migration proceed while earlier migrations are still pending.');
+    }
     if (args.auto) {
         // Auto-generate migration from schema diff
         const url = requireUrl(config);
         label('Database', redactUrl(url));
         label('Schema file', config.schemaFile);
         newline();
+        await refuseWhenMigrationsPending(args, config, url, '--auto');
         const schemaDef = await loadSchemaFile(config.schemaFile);
         const diffSpinner = new Spinner('Computing schema diff').start();
         const diff = await schemaDiff(schemaDef, url, { schema: config.schema });
         if (diff.statements.length === 0) {
-            diffSpinner.succeed('Database is already in sync: nothing to migrate');
-            newline();
+            reportNothingToMigrate(diff, diffSpinner);
             return;
         }
         diffSpinner.succeed(`Found ${bold(String(diff.statements.length))} change(s)`);
@@ -2324,7 +2687,9 @@ async function cmdMigrateCreate(args, config) {
                 console.log(`    ${red(symbols.warning)} ${dim('DOWN')} [${h.kind}] ${h.target}`);
             }
             newline();
-            console.log(`  ${dim('`migrate up` refuses destructive statements by default: confirm interactively or pass')} ${cyan('--allow-destructive')}${dim('.')}`);
+            console.log(body.destructiveUp.length > 0
+                ? `  ${dim('`migrate up` refuses destructive statements by default: confirm interactively or pass')} ${cyan('--allow-destructive')}${dim('.')}`
+                : `  ${dim('Only the DOWN section is destructive: `migrate up` runs this file without a prompt, `migrate down` asks first.')}`);
             newline();
         }
         if (diff.warnings && diff.warnings.length > 0) {
@@ -2344,12 +2709,12 @@ async function cmdMigrateCreate(args, config) {
         label('Database', redactUrl(url));
         label('Schema file', config.schemaFile);
         newline();
+        await refuseWhenMigrationsPending(args, config, url, '--from-diff');
         const schemaDef = await loadSchemaFile(config.schemaFile);
         const diffSpinner = new Spinner('Computing schema diff').start();
         const diff = await schemaDiff(schemaDef, url, { schema: config.schema });
         if (diff.statements.length === 0) {
-            diffSpinner.succeed('Database is already in sync: nothing to migrate');
-            newline();
+            reportNothingToMigrate(diff, diffSpinner);
             return;
         }
         diffSpinner.succeed(`Found ${bold(String(diff.statements.length))} change(s)`);
@@ -2396,7 +2761,9 @@ async function cmdMigrateCreate(args, config) {
                 console.log(`    ${red(symbols.warning)} ${dim('DOWN')} [${h.kind}] ${h.target}`);
             }
             newline();
-            console.log(`  ${dim('`migrate up` refuses destructive statements by default: confirm interactively or pass')} ${cyan('--allow-destructive')}${dim('.')}`);
+            console.log(body.destructiveUp.length > 0
+                ? `  ${dim('`migrate up` refuses destructive statements by default: confirm interactively or pass')} ${cyan('--allow-destructive')}${dim('.')}`
+                : `  ${dim('Only the DOWN section is destructive: `migrate up` runs this file without a prompt, `migrate down` asks first.')}`);
             newline();
         }
         if (diff.warnings && diff.warnings.length > 0) {
@@ -2717,7 +3084,18 @@ 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, schema: config.schema });
+    const result = await migrateDeploy(url, config.migrationsDir, {
+        allowDrift: args.allowDrift,
+        schema: config.schema,
+        lockWaitMs: args.wait !== undefined ? args.wait * 1000 : undefined,
+        onLockWait: () => {
+            runSpinner.stop();
+            warn(`Another migration holds the lock: waiting up to ${bold(String(args.wait))}s for it to finish.`);
+            console.log(`  ${dim('Whatever it applies is then no longer pending, so this run will skip it.')}`);
+            newline();
+            runSpinner.start();
+        },
+    });
     if (result.applied.length > 0) {
         runSpinner.succeed(`${bold(String(result.applied.length))} applied`);
         for (const file of result.applied) {
@@ -2844,6 +3222,15 @@ async function cmdMigrateDown(args, config) {
         for (const file of result.rolledBack) {
             console.log(`    ${yellow(symbols.arrowRight)} ${file.filename}`);
         }
+        const noSql = rollbacksWithoutSql(result.rolledBack);
+        if (noSql.length > 0) {
+            newline();
+            warn(`${bold(String(noSql.length))} rolled-back migration(s) have a DOWN section that runs no SQL:`);
+            for (const file of noSql)
+                console.log(`    ${yellow(symbols.dot)} ${file.filename}`);
+            console.log(`  ${dim('Their tracking rows are removed, but nothing they changed was undone (a dropped column')}`);
+            console.log(`  ${dim('cannot be restored automatically). Restore that data from a backup.')}`);
+        }
     }
     else if (result.errors.length === 0) {
         spinner.succeed('No migrations to roll back');
@@ -2867,20 +3254,24 @@ async function cmdMigrateDown(args, config) {
     }
     newline();
 }
-async function cmdMigrateStatus(_args, config) {
+async function cmdMigrateStatus(args, config) {
     banner();
     const url = requireUrl(config);
     label('Database', redactUrl(url));
     label('Migrations', config.migrationsDir);
     newline();
     const allFiles = listMigrationFiles(config.migrationsDir);
-    if (allFiles.length === 0) {
+    // A gate still has to ask the database when there are no files: applied
+    // migrations whose files are gone are exactly the drift it exists to catch.
+    if (allFiles.length === 0 && !args.exitCode) {
         warn('No migration files found.');
         console.log(`  ${dim('Create one with:')} ${cyan('npx turbine migrate create <name>')}`);
         newline();
         return;
     }
     warnIgnoredMigrationFiles(config.migrationsDir);
+    if (allFiles.length === 0)
+        warn('No migration files found.');
     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;
@@ -2935,6 +3326,14 @@ async function cmdMigrateStatus(_args, config) {
         console.log(`  ${dim('Run')} ${cyan('npx turbine migrate up')} ${dim('to apply pending migrations.')}`);
         newline();
     }
+    if (args.exitCode) {
+        const problems = statusGateProblems(summarizeMigrationStatus(statuses), listIgnoredSqlFiles(config.migrationsDir).map(printableCatalogName));
+        if (problems.length > 0) {
+            warn(`Migration history is not clean: ${problems.join(', ')} ${dim('(--exit-code: exiting 2)')}.`);
+            newline();
+            process.exit(2);
+        }
+    }
 }
 export function getSeedExecutionPlan(seedFile) {
     const ext = extname(seedFile).toLowerCase();
@@ -2993,6 +3392,9 @@ async function seedConnectionString(config) {
     }
     return connectionStringForSchema(config.url, schema, inherited);
 }
+/** The notice for a {@link SeedRunOutcome} that could not be confirmed. */
+const UNCONFIRMED_SEED_NOTICE = 'The seed file ran to completion, but it does not call defineSeed(), so Turbine cannot tell whether it wrote anything. ' +
+    'Wrap the work in defineSeed(async (db) => { ... }) to have it confirmed.';
 async function runSeedPlan(plan, config) {
     const oldDatabaseUrl = process.env.DATABASE_URL;
     // The seed connects through DATABASE_URL, whichever way it runs: `defineSeed`
@@ -3012,9 +3414,11 @@ async function runSeedPlan(plan, config) {
             }
             // The seed runs in a child process, so we cannot observe its callback
             // directly. Hand it a sentinel path: `defineSeed`'s runner writes the file
-            // only after a callback executes to completion. If the child exits cleanly
-            // but the sentinel never appears, the seed module loaded without running
-            // anything: a silent no-op we must report as a failure, not success.
+            // only after a callback executes to completion. A non-zero exit is a
+            // failure. A clean exit with no sentinel is a script that did its work at
+            // the top level (a typed-client seed), which succeeds and says so, unless
+            // the file names `defineSeed`: then its callback was expected to run and
+            // did not, which is a no-op to report as a failure.
             const sentinelDir = mkdtempSync(join(tmpdir(), 'turbine-seed-'));
             const sentinel = join(sentinelDir, 'ran');
             const { execFileSync } = await import('node:child_process');
@@ -3027,15 +3431,18 @@ async function runSeedPlan(plan, config) {
                         TURBINE_SEED_SENTINEL: sentinel,
                     },
                 });
-                if (!existsSync(sentinel)) {
+                if (existsSync(sentinel))
+                    return { confirmed: true };
+                const seedFile = plan.args[plan.args.length - 1] ?? '';
+                if (/\bdefineSeed\b/.test(readFileSync(seedFile, 'utf-8'))) {
                     throw new Error('The seed file completed without running a seed callback. ' +
                         'Make sure it calls defineSeed(async (db) => { ... }) at the top level.');
                 }
+                return { confirmed: false };
             }
             finally {
                 rmSync(sentinelDir, { recursive: true, force: true });
             }
-            return;
         }
         if (plan.kind === 'js') {
             const mod = await import(pathToFileURL(plan.file).href);
@@ -3044,7 +3451,7 @@ async function runSeedPlan(plan, config) {
                     'Export your seed with `export default defineSeed(async (db) => { ... })`.');
             }
             await mod.default();
-            return;
+            return { confirmed: true };
         }
         // `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
@@ -3060,6 +3467,7 @@ async function runSeedPlan(plan, config) {
         finally {
             await client.end();
         }
+        return { confirmed: true };
     }
     finally {
         if (oldDatabaseUrl === undefined) {
@@ -3085,14 +3493,14 @@ async function cmdSeed(_args, config) {
     }
     const spinner = new Spinner('Running seed file').start();
     try {
-        await runSeedPlan(getSeedExecutionPlan(seedFile), config);
+        const outcome = await runSeedPlan(getSeedExecutionPlan(seedFile), config);
         spinner.succeed('Seed completed');
+        if (!outcome.confirmed)
+            warn(UNCONFIRMED_SEED_NOTICE);
     }
     catch (err) {
         spinner.fail('Seed failed');
-        if (err instanceof Error) {
-            console.log(`  ${dim(redactUrl(err.message))}`);
-        }
+        console.log(`  ${dim(redactUrl(errorText(err)))}`);
         newline();
         process.exit(1);
     }
@@ -3123,7 +3531,7 @@ async function cmdStatus(_args, config) {
     for (const tbl of Object.values(schema.tables)) {
         const relCount = Object.keys(tbl.relations).length;
         const _pk = tbl.primaryKey.join(', ') || dim('(none)');
-        console.log(`  ${bold(cyan(tbl.name))}`);
+        console.log(`  ${bold(cyan(shown(tbl.name)))}`);
         for (let i = 0; i < tbl.columns.length; i++) {
             const col = tbl.columns[i];
             const isLast = i === tbl.columns.length - 1 && relCount === 0;
@@ -3131,7 +3539,7 @@ async function cmdStatus(_args, config) {
             const nullable = col.nullable ? dim('?') : '';
             const def = col.hasDefault ? dim(' (default)') : '';
             const pkLabel = tbl.primaryKey.includes(col.name) ? ` ${magenta('PK')}` : '';
-            console.log(`    ${dim(prefix)} ${col.field}${nullable}: ${green(col.tsType)}${pkLabel}${def}  ${gray(`${symbols.arrow} ${col.pgType}`)}`);
+            console.log(`    ${dim(prefix)} ${shown(col.field)}${nullable}: ${green(shown(col.tsType))}${pkLabel}${def}  ${gray(`${symbols.arrow} ${shown(col.pgType)}`)}`);
         }
         const rels = Object.entries(tbl.relations);
         if (rels.length > 0) {
@@ -3141,7 +3549,7 @@ async function cmdStatus(_args, config) {
                 const prefix = isLast ? symbols.teeEnd : symbols.tee;
                 const relColor = rel.type === 'hasMany' ? blue : yellow;
                 const fkDisplay = Array.isArray(rel.foreignKey) ? rel.foreignKey.join(', ') : rel.foreignKey;
-                console.log(`    ${dim(prefix)} ${relColor(relName)} ${dim(symbols.arrow)} ${rel.to} ${dim(`(${rel.type}, FK: ${fkDisplay})`)}`);
+                console.log(`    ${dim(prefix)} ${relColor(shown(relName))} ${dim(symbols.arrow)} ${shown(rel.to)} ${dim(`(${rel.type}, FK: ${shown(fkDisplay)})`)}`);
             }
         }
         newline();
@@ -3149,7 +3557,7 @@ async function cmdStatus(_args, config) {
     if (Object.keys(schema.enums).length > 0) {
         console.log(`  ${bold('Enums:')}`);
         for (const [enumName, labels] of Object.entries(schema.enums)) {
-            console.log(`    ${cyan(enumName)}: ${labels.map((l) => green(`'${l}'`)).join(dim(' | '))}`);
+            console.log(`    ${cyan(shown(enumName))}: ${labels.map((l) => green(`'${shown(l)}'`)).join(dim(' | '))}`);
         }
         newline();
     }
@@ -3207,6 +3615,23 @@ const CONCURRENTLY_RECIPE_COMMENT = [
     '--      makes "migrate up" look hung. For bounded waits, SET lock_timeout /',
     '--      statement_timeout in a psql session.',
 ].join('\n');
+/**
+ * Why `migrate up`, `deploy` and `down` refuse a pooled endpoint. The reason is
+ * the migration lock, not the doctor's session-state argument.
+ */
+export const MIGRATE_POOLER_EXPLANATION = [
+    'turbine migrate serializes runs with a session-level advisory lock (pg_try_advisory_lock).',
+    'That lock belongs to one server backend and only means something while the same backend',
+    'serves every statement of the run. A transaction pooler (PgBouncer, a Neon "-pooler"',
+    "endpoint, Supabase's pooler) hands each transaction to whichever backend is free, so:",
+    '',
+    '  1. The lock is not tied to this run. It can be taken on one backend and released on',
+    '     another, which leaves it held on a shared backend (later runs are told another',
+    '     migration is in progress) and lets two runs apply the same file.',
+    '  2. Session state a migration file sets (SET lock_timeout, SET search_path) is left on',
+    '     a shared backend for other clients, and state an earlier client left there applies',
+    '     to this run.',
+];
 /**
  * Refuse a `doctor` run whose connection string points at a transaction pooler.
  *
@@ -3228,13 +3653,13 @@ const CONCURRENTLY_RECIPE_COMMENT = [
  * Exported for the unit test only (like {@link isLoopbackHost}): a gate whose
  * failure path is `process.exit` is untestable through the command itself.
  */
-export function refusePoolerConnection(url, args) {
+export function refusePoolerConnection(url, args, refusal = { command: 'turbine doctor' }) {
     if (args.allowPooler === true)
         return;
     const detection = detectPooler(url);
     if (!detection.pooled)
         return;
-    const lines = poolerRefusalMessage(detection, { command: 'turbine doctor', allowFlag: '--allow-pooler' });
+    const lines = poolerRefusalMessage(detection, { ...refusal, allowFlag: '--allow-pooler' });
     console.error('');
     console.error(`  ${red(symbols.cross)} ${lines[0]}`);
     for (const line of lines.slice(1))
@@ -3302,7 +3727,7 @@ async function cmdDoctor(args, config) {
             tables: {},
             indexes: [],
             nullFrac: {},
-            notices: [`statistics collection failed: ${err instanceof Error ? err.message : String(err)}`],
+            notices: [`statistics collection failed: ${errorText(err)}`],
         };
     }
     // Table-heat boost: read _turbine_metrics (app DB or --metrics-url) and use
@@ -3527,6 +3952,12 @@ function renderUnusedCaveats(minScans, snapshot) {
     }
     newline();
 }
+/**
+ * Catalog names go to the terminal through this. A database lets its creator
+ * pick any characters for a table or index name, and a raw ESC or bidi control
+ * in one rewrites the line it is printed on.
+ */
+const shown = printableCatalogName;
 /** doctor --unused: never-scanned indexes with DROP suggestions (report-only). */
 function renderUnusedIndexes(unused, minScans, snapshot) {
     if (unused.length === 0)
@@ -3535,12 +3966,12 @@ function renderUnusedIndexes(unused, minScans, snapshot) {
     warn(`Found ${bold(String(unused.length))} never-scanned index(es) (${formatBytes(total)} reclaimable).`);
     renderUnusedCaveats(minScans, snapshot);
     for (const u of unused) {
-        console.log(`  ${yellow(symbols.warning)} ${bold(cyan(u.table))} ${dim(`(${u.columns.join(', ') || '?'})`)}  ${gray(`${u.indexName} · ${u.idxScan} scans · ${formatBytes(u.sizeBytes)}`)}`);
+        console.log(`  ${yellow(symbols.warning)} ${bold(cyan(shown(u.table)))} ${dim(`(${shown(u.columns.join(', ') || '?')})`)}  ${gray(`${shown(u.indexName)} · ${u.idxScan} scans · ${formatBytes(u.sizeBytes)}`)}`);
         // A functional / partial / non-btree index is not a plain `(col)` rebuild:
         // say what it actually is before anyone runs the DROP.
         if (u.caveat)
             console.log(`    ${dim(symbols.tee)} ${yellow(u.caveat)}`);
-        console.log(`    ${dim(symbols.teeEnd)} ${green(u.dropSql)}`);
+        console.log(`    ${dim(symbols.teeEnd)} ${green(shown(u.dropSql))}`);
         newline();
     }
 }
@@ -3553,9 +3984,9 @@ function renderRedundantIndexes(redundant) {
     console.log(`  ${dim('Each is a leading prefix of a wider index that already serves the same lookups. Report-only, never auto-dropped.')}`);
     newline();
     for (const r of redundant) {
-        console.log(`  ${yellow(symbols.warning)} ${bold(cyan(r.table))} ${dim(`(${r.columns.join(', ')})`)}  ${gray(`${r.indexName} · ${formatBytes(r.sizeBytes)}`)}`);
-        console.log(`    ${dim(symbols.tee)} covered by ${blue(r.coveredBy)} ${dim(`(${r.coveredByColumns.join(', ')})`)}`);
-        console.log(`    ${dim(symbols.teeEnd)} ${green(r.dropSql)}`);
+        console.log(`  ${yellow(symbols.warning)} ${bold(cyan(shown(r.table)))} ${dim(`(${shown(r.columns.join(', '))})`)}  ${gray(`${shown(r.indexName)} · ${formatBytes(r.sizeBytes)}`)}`);
+        console.log(`    ${dim(symbols.tee)} covered by ${blue(shown(r.coveredBy))} ${dim(`(${shown(r.coveredByColumns.join(', '))})`)}`);
+        console.log(`    ${dim(symbols.teeEnd)} ${green(shown(r.dropSql))}`);
         newline();
     }
 }
@@ -3570,7 +4001,7 @@ function renderDoctorAudit(audit, minScans, snapshot) {
     renderUnusedCaveats(minScans, snapshot);
     for (const a of audit) {
         const tag = a.ambiguous ? red(' [ambiguous: truncated name collides with another column set]') : '';
-        console.log(`  ${yellow(symbols.warning)} ${bold(cyan(a.table))} ${dim(`(${a.columns.join(', ') || '?'})`)}  ${gray(`${a.indexName} · ${a.idxScan} scans · ${formatBytes(a.sizeBytes)}`)}${tag}`);
+        console.log(`  ${yellow(symbols.warning)} ${bold(cyan(shown(a.table)))} ${dim(`(${shown(a.columns.join(', ') || '?')})`)}  ${gray(`${shown(a.indexName)} · ${a.idxScan} scans · ${formatBytes(a.sizeBytes)}`)}${tag}`);
         if (a.ambiguous) {
             console.log(`    ${dim(symbols.tee)} ${dim('the 63-byte name maps to more than one probe column set; confirm before dropping')}`);
         }
@@ -3579,7 +4010,7 @@ function renderDoctorAudit(audit, minScans, snapshot) {
             console.log(`      ${dim('reappear as a missing-index finding in this same report.')}`);
         }
         else if (a.dropSql) {
-            console.log(`    ${dim(symbols.teeEnd)} ${green(a.dropSql)}`);
+            console.log(`    ${dim(symbols.teeEnd)} ${green(shown(a.dropSql))}`);
         }
         newline();
     }
@@ -3633,12 +4064,12 @@ function divergenceAmplificationLines(d) {
     const amp = divInt(d.worstCaseAmplification ?? 0);
     const corr = d.orderColumnCorrelation;
     const corrLabel = corr === null || corr === undefined
-        ? `no pg_stats correlation available for "${d.orderColumn}"`
-        : `correlation ${corr.toFixed(5)} on "${d.orderColumn}"`;
+        ? `no pg_stats correlation available for "${shown(d.orderColumn)}"`
+        : `correlation ${corr.toFixed(5)} on "${shown(d.orderColumn)}"`;
     if (d.heapNearlyOrdered === true) {
         return [
             `The size of that flip turns on the heap's physical order, and THIS heap is in near-exact`,
-            `"${d.orderColumn}" order (${corrLabel}), so consecutive index entries hit the`,
+            `"${shown(d.orderColumn)}" order (${corrLabel}), so consecutive index entries hit the`,
             `same pinned page: measured ~1x, not the ~${amp}x an unordered heap reads. Most likely this`,
             `one is not costing you anything today. It is also one sampled statistic away from the`,
             `much worse reading, so measure rather than assume in either direction.`,
@@ -3647,7 +4078,7 @@ function divergenceAmplificationLines(d) {
     return [
         `That costs ~${amp}x the buffers of the seq scan, because each index entry is its own heap`,
         `fetch (${corrLabel}). The one shape that reads ~1x instead is a heap`,
-        `in near-exact "${d.orderColumn}" order; two pages of local disorder already reads ~41x.`,
+        `in near-exact "${shown(d.orderColumn)}" order; two pages of local disorder already reads ~41x.`,
     ];
 }
 function renderDivergenceEvidence(d) {
@@ -3655,7 +4086,7 @@ function renderDivergenceEvidence(d) {
     console.log(`    ${dim(symbols.tee)} ${yellow('cached-plan risk:')} this unindexed filter column can also flip a cached plan.`);
     console.log(`      ${dim(`${divInt(d.rows)} rows in ${divInt(d.pages)} pages, rarest value ~${divInt(d.rarestBucket)} rows, below the assumed LIMIT ${d.assumedLimit}.`)}`);
     console.log(`      ${dim(`Without the index the good plan is a seq scan (${divInt(d.pages)} pages); a promoted generic`)}`);
-    console.log(`      ${dim(`plan cannot see the value is rare, keeps the ordered "${d.orderColumn}" walk, and reads`)}`);
+    console.log(`      ${dim(`plan cannot see the value is rare, keeps the ordered "${shown(d.orderColumn)}" walk, and reads`)}`);
     console.log(`      ${dim(`up to ~${tuples} tuples before it fills the LIMIT.`)}`);
     console.log(`      ${dim('Postgres promotes this shape exactly when the workload keeps asking for the rare')}`);
     console.log(`      ${dim('value: that is the case where the custom plan is expensive enough for the generic')}`);
@@ -3664,7 +4095,7 @@ function renderDivergenceEvidence(d) {
         console.log(`      ${dim(line)}`);
     console.log(`      ${dim('Adding the index above is the fix. Confirm first if you want to:')}`);
     for (const line of d.diagnosticSql.split('\n')) {
-        console.log(`        ${green(line)}`);
+        console.log(`        ${green(shown(line))}`);
     }
     console.log(`      ${dim('After adding this index, re-run doctor. This column is expected to reappear as a')}`);
     console.log(`      ${dim('sparse-value finding in the cached-plan section. That later finding is exposure, not')}`);
@@ -3718,9 +4149,9 @@ function renderFinding(f, opts) {
     const rows = f.score.metrics.rows;
     const rowsLabel = rows !== null ? `~${rows.toLocaleString()} rows` : 'row count unknown';
     const sizeLabel = f.score.metrics.sizeBytes !== null ? `, ${formatBytes(f.score.metrics.sizeBytes)}` : '';
-    console.log(`  ${yellow(symbols.warning)} ${bold(cyan(m.table))} ${dim(`(${m.columns.join(', ')})`)}  ${gray(`${rowsLabel}${sizeLabel}`)}`);
+    console.log(`  ${yellow(symbols.warning)} ${bold(cyan(shown(m.table)))} ${dim(`(${shown(m.columns.join(', '))})`)}  ${gray(`${rowsLabel}${sizeLabel}`)}`);
     for (const p of m.probes) {
-        console.log(`    ${dim(symbols.tee)} probed by ${p.from}.${blue(p.relation)} ${dim(`(${p.type})`)}`);
+        console.log(`    ${dim(symbols.tee)} probed by ${shown(p.from)}.${blue(shown(p.relation))} ${dim(`(${p.type})`)}`);
     }
     if (opts.withReasons) {
         for (const reason of f.score.reasons) {
@@ -3728,7 +4159,7 @@ function renderFinding(f, opts) {
         }
     }
     const last = opts.divergence ? symbols.tee : symbols.teeEnd;
-    console.log(`    ${dim(last)} ${green(doctorCreateSql(f, { concurrently: opts.concurrently }))}`);
+    console.log(`    ${dim(last)} ${green(shown(doctorCreateSql(f, { concurrently: opts.concurrently })))}`);
     if (opts.divergence)
         renderDivergenceEvidence(opts.divergence);
     newline();
@@ -3741,8 +4172,8 @@ function renderInvalidIndexes(invalid) {
     console.log(`  ${dim('IF NOT EXISTS skips an invalid index on rerun, so it never rebuilds. Drop it, then rerun:')}`);
     newline();
     for (const idx of invalid) {
-        console.log(`  ${red(symbols.warning)} ${bold(cyan(idx.table))} ${dim(`(${idx.columns.join(', ') || '?'})`)}  ${gray(idx.indexName)}`);
-        console.log(`    ${dim(symbols.teeEnd)} ${green(idx.dropSql)}`);
+        console.log(`  ${red(symbols.warning)} ${bold(cyan(shown(idx.table)))} ${dim(`(${shown(idx.columns.join(', ') || '?')})`)}  ${gray(shown(idx.indexName))}`);
+        console.log(`    ${dim(symbols.teeEnd)} ${green(shown(idx.dropSql))}`);
         newline();
     }
 }
@@ -3835,10 +4266,10 @@ function renderPlanDivergence(divergence, attached) {
             // on (an index that exists but cannot serve the equality: partial,
             // expression, or non-btree). The remedy is still an index, not a
             // plan-cache setting, so this entry never suggests forceCustomPlan.
-            console.log(`  ${yellow(symbols.warning)} ${bold(cyan(`${f.table}.${f.column}`))}  ${gray('UNINDEXED-FILTER FLIP')}`);
+            console.log(`  ${yellow(symbols.warning)} ${bold(cyan(`${shown(f.table)}.${shown(f.column)}`))}  ${gray('UNINDEXED-FILTER FLIP')}`);
             console.log(`    ${dim(symbols.tee)} ${divInt(f.rows)} rows in ${divInt(f.pages)} pages, rarest value ~${bold(divInt(f.rarestBucket))} rows, below the assumed LIMIT ${f.assumedLimit}`);
-            console.log(`    ${dim(symbols.tee)} no index serves ${f.column} = $1, so the good plan is a seq scan (${divInt(f.pages)} pages);`);
-            console.log(`      ${dim(`a promoted generic plan keeps the ordered "${f.orderColumn}" walk and reads up to ~${divInt(f.tuplesWalked ?? f.rows)} tuples`)}`);
+            console.log(`    ${dim(symbols.tee)} no index serves ${shown(f.column)} = $1, so the good plan is a seq scan (${divInt(f.pages)} pages);`);
+            console.log(`      ${dim(`a promoted generic plan keeps the ordered "${shown(f.orderColumn)}" walk and reads up to ~${divInt(f.tuplesWalked ?? f.rows)} tuples`)}`);
             console.log(`      ${dim('before it fills the LIMIT.')}`);
             for (const line of divergenceAmplificationLines(f))
                 console.log(`      ${dim(line)}`);
@@ -3853,13 +4284,13 @@ function renderPlanDivergence(divergence, attached) {
             newline();
             continue;
         }
-        console.log(`  ${yellow(symbols.warning)} ${bold(cyan(`${f.table}.${f.column}`))}  ${gray('SPARSE-VALUE FLIP')}`);
+        console.log(`  ${yellow(symbols.warning)} ${bold(cyan(`${shown(f.table)}.${shown(f.column)}`))}  ${gray('SPARSE-VALUE FLIP')}`);
         console.log(`    ${dim(symbols.tee)} generic estimate ${bold(divInt(f.genericEstimate))} rows ${dim(`(${divInt(f.rows)} rows / ${divInt(f.distinctValues)} distinct values)`)}`);
         console.log(`    ${dim(symbols.tee)} rarest value bucket ${bold(divInt(f.rarestBucket))} rows ${dim('(pg_stats most_common_freqs / residual bucket)')}`);
         console.log(`    ${dim(symbols.tee)} crossover ${bold(divInt(f.crossoverRows ?? 0))} rows ${dim(`(sqrt(limit ${f.assumedLimit} x ${divInt(f.pages)} pages); ${divInt(f.crossoverRowsWide ?? 0)} at limit ${f.thresholds.wideLimit})`)}`);
         console.log(`    ${dim(symbols.tee)} ${dim(`values below the crossover: ${divInt(f.valuesBelowCrossover ?? 0)} of ${divInt(f.distinctValues)}, filter-column correlation ${f.correlation.toFixed(2)}, ${analyzedLabel(f)}`)}`);
         console.log(`    ${dim(symbols.tee)} for such a value the generic plan walks ~${bold(divInt(f.walkPages ?? 0))} of ${divInt(f.pages)} pages ${dim(`(${Math.round((f.walkFraction ?? 0) * 100)}% of the table)`)}`);
-        console.log(`      ${dim(`for reads shaped WHERE ${f.column} = $1 ORDER BY ${f.orderColumn} LIMIT $n,`)}`);
+        console.log(`      ${dim(`for reads shaped WHERE ${shown(f.column)} = $1 ORDER BY ${shown(f.orderColumn)} LIMIT $n,`)}`);
         console.log(`      ${dim("where the custom plan reads only that value's own rows.")}`);
         console.log(`    ${dim(symbols.tee)} ${dim('No amplification figure is printed, deliberately. This models how many rows a')}`);
         console.log(`      ${dim('value has, not WHERE they sit in the heap, and the second half can move the')}`);
@@ -3921,7 +4352,7 @@ function renderPlanDivergence(divergence, attached) {
             console.log(`       ${dim('in one direction trades this finding for its mirror image. That applies equally to')}`);
             console.log(`       ${dim("Turbine's client-level `planCacheMode` and to a SET or ALTER ROLE applied outside")}`);
             console.log(`       ${dim('Turbine.')}`);
-            console.log(`    5. A composite index on (${first.column}, ${first.orderColumn}) makes the GOOD plan better. It`);
+            console.log(`    5. A composite index on (${shown(first.column)}, ${shown(first.orderColumn)}) makes the GOOD plan better. It`);
             console.log(`       ${dim('does NOT stop the generic plan from choosing the other one, and it can widen the gap.')}`);
             console.log(`       ${dim('Add it for the custom-plan win, not as a fix for this finding.')}`);
         }
@@ -3946,7 +4377,7 @@ function renderPlanDivergence(divergence, attached) {
     if (notices.length > 0) {
         console.log(`  ${dim('Not scored for cached-plan divergence (statistics missing):')}`);
         for (const n of notices) {
-            console.log(`    ${dim(`- ${n.table}.${n.column}: ${n.reason}`)}`);
+            console.log(`    ${dim(`- ${shown(n.table)}.${shown(n.column)}: ${n.reason}`)}`);
         }
         newline();
     }
@@ -4044,7 +4475,7 @@ async function cmdStudio(args, config) {
         spinner.succeed(demo ? 'Demo Studio is running' : 'Studio is running');
     }
     catch (err) {
-        spinner.fail(`Failed to start Studio: ${err instanceof Error ? err.message : String(err)}`);
+        spinner.fail(`Failed to start Studio: ${errorText(err)}`);
         process.exit(1);
     }
     if (demo) {
@@ -4177,7 +4608,7 @@ async function cmdObserve(args) {
         spinner.succeed('Observe dashboard is running');
     }
     catch (err) {
-        spinner.fail(`Failed to start Observe: ${err instanceof Error ? err.message : String(err)}`);
+        spinner.fail(`Failed to start Observe: ${errorText(err)}`);
         process.exit(1);
     }
     newline();
@@ -4285,10 +4716,12 @@ function showGenerateHelp() {
     console.log(`    ${cyan('--schema, -s')} ${dim('<name>')}   Postgres schema ${dim('(default: public)')}`);
     console.log(`    ${cyan('--include')} ${dim('<tables>')}    Comma-separated tables to include`);
     console.log(`    ${cyan('--exclude')} ${dim('<tables>')}    Comma-separated tables to exclude`);
+    console.log(`    ${cyan('--schema-file')} ${dim('<path>')}  Your ${cyan('defineSchema()')} file, whose ${cyan('pii')} / ${cyan('updatedAt')} tags are applied ${dim('(default: ./turbine/schema.ts)')}`);
     console.log(`    ${cyan('--zod')}                 Also emit ${cyan('zod.ts')} validation schemas ${dim('(needs the zod dep)')}`);
     console.log(`    ${cyan('--include-views')}       Include views + materialized views as read-only entities`);
     console.log(`    ${cyan('--no-timestamp')}        Omit the ${dim('Generated at:')} header line ${dim('(reproducible, diff-stable output)')}`);
-    console.log(`    ${cyan('--import-ext')} ${dim('<mode>')}    Sibling-import extension: ${cyan('js')} / ${cyan('none')} / ${cyan('auto')} ${dim('(default: auto)')}`);
+    console.log(`    ${cyan('--import-ext')} ${dim('<mode>')}    Sibling-import extension: ${cyan('js')} / ${cyan('ts')} / ${cyan('none')} / ${cyan('auto')} ${dim('(default: auto)')}`);
+    console.log(`                           ${dim('ts emits ./types.ts so')} ${cyan('node app.ts')} ${dim('can run the client with native type stripping')}`);
     console.log(`    ${cyan('--keep-column-names')}   Keep raw DB column names as field names ${dim('(snake_case, not camelCase)')}`);
     console.log(`    ${cyan('--legacy-to-many-uniques')} Emit ${cyan('hasMany')} for unique-FK children ${dim('(pre-0.41 shape; default flips to hasOne)')}`);
     console.log(`    ${cyan('--allow-empty')}         Generate even when introspection matches 0 tables`);
@@ -4345,6 +4778,7 @@ function showPushHelp() {
     console.log(`    ${cyan('--url, -u')} ${dim('<url>')}   Postgres connection string`);
     console.log(`    ${cyan('--schema-file')} ${dim('<path>')} Your ${cyan('defineSchema()')} file ${dim('(default: ./turbine/schema.ts)')}`);
     console.log(`    ${cyan('--dry-run')}          Show SQL without executing`);
+    console.log(`    ${cyan('--exit-code')}        With ${cyan('--dry-run')}: exit 2 when the database differs from the schema file, 0 when in sync ${dim('(CI)')}`);
     console.log(`    ${cyan('--allow-destructive')} Skip the interactive confirmation for data-destroying statements ${dim('(CI)')}`);
     console.log(`    ${cyan('--verbose, -v')}      Show detailed output`);
     newline();
@@ -4371,7 +4805,11 @@ 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('--exit-code')}       Exit 2 when migrations are pending, modified, missing or misnamed ${dim('(status only, CI)')}`);
+    console.log(`    ${cyan('--wait')}${dim('[=<seconds>]')}  Wait for a concurrent deploy to release the lock, default ${DEFAULT_LOCK_WAIT_SECONDS}s ${dim('(deploy only)')}`);
+    console.log(`    ${cyan('--allow-pending')}   Let ${cyan('--auto')} / ${cyan('--from-diff')} run while earlier migrations are still pending ${dim('(create only)')}`);
     console.log(`    ${cyan('--allow-drift')}     Re-baseline drifted checksums, REWRITING history ${dim('(up / deploy / down)')}`);
+    console.log(`    ${cyan('--allow-pooler')}    Run ${cyan('up')} / ${cyan('deploy')} / ${cyan('down')} through a transaction pooler ${dim('(refused: the migration lock is session-level)')}`);
     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`);
@@ -4383,8 +4821,10 @@ function showMigrateHelp() {
     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 deploy --wait=120`);
     console.log(`    ${dim('$')} npx turbine migrate down --step 2`);
     console.log(`    ${dim('$')} npx turbine migrate status`);
+    console.log(`    ${dim('$')} npx turbine migrate status --exit-code`);
     newline();
 }
 function showSeedHelp() {
@@ -4608,8 +5048,12 @@ function showHelp() {
     console.log(`    ${cyan('--from-diff')}          Generate from schema diff, destructive statements flagged ${dim('(create)')}`);
     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('--exit-code')}          Exit 2 on drift ${dim('(push --dry-run, migrate status)')}`);
+    console.log(`    ${cyan('--wait')}${dim('[=<seconds>]')}     Wait for a concurrent deploy's lock instead of failing ${dim('(deploy)')}`);
+    console.log(`    ${cyan('--allow-pending')}      Diff even while migrations are pending ${dim('(create --auto / --from-diff)')}`);
     console.log(`    ${cyan('--allow-destructive')}  Run data-destroying statements without prompting ${dim('(up/down/push)')}`);
     console.log(`    ${cyan('--allow-drift')}        Re-baseline drifted checksums on ${cyan('migrate up')} / ${cyan('deploy')} / ${cyan('down')} ${dim('(advanced)')}`);
+    console.log(`    ${cyan('--allow-pooler')}       Let ${cyan('migrate up')} / ${cyan('deploy')} / ${cyan('down')} and ${cyan('doctor')} use a transaction pooler ${dim('(refused by default)')}`);
     newline();
     console.log(`  ${bold('Init options:')}`);
     console.log(`    ${cyan('--yes, -y')}            Accept every step's default (non-interactive)`);
@@ -4726,9 +5170,19 @@ function cmdSkill(args) {
     }
     const skillsDir = args.dir ?? join('.claude', 'skills');
     const target = resolve(process.cwd(), skillsDir, 'turbine-orm', 'SKILL.md');
-    const existed = existsSync(target);
     mkdirSync(dirname(target), { recursive: true });
-    writeFileSync(target, body);
+    // Exclusive create first: only the wording depends on whether the file was
+    // there, and asking separately would let the answer go stale before the write.
+    let existed = false;
+    try {
+        writeFileSync(target, body, { flag: 'wx' });
+    }
+    catch (err) {
+        if (err.code !== 'EEXIST')
+            throw err;
+        existed = true;
+        writeFileSync(target, body);
+    }
     newline();
     success(`${existed ? 'Updated' : 'Installed'} the Turbine query skill`);
     console.log(`  ${dim(relative(process.cwd(), target))}`);
@@ -4791,7 +5245,7 @@ async function main() {
         // 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));
+        error(errorText(err));
         errorLine();
         process.exit(1);
     }
@@ -4924,6 +5378,9 @@ async function main() {
     }
     catch (err) {
         if (err instanceof Error) {
+            // `errorText`, not `message`: a refused `localhost` is an
+            // AggregateError with an empty message (see cli/error-text.ts).
+            const message = errorText(err);
             // 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
@@ -4931,35 +5388,35 @@ async function main() {
             // firewall hints. A typed error already knows what it is.
             if (err instanceof ValidationError) {
                 errorLine();
-                error(redactUrl(err.message));
+                error(redactUrl(message));
                 if (args.verbose && err.stack) {
                     errorLine();
                     console.error(dim(redactUrl(err.stack)));
                 }
             }
-            else if (err.message.includes('ECONNREFUSED') || err.message.includes('connection')) {
+            else if (message.includes('ECONNREFUSED') || message.includes('connection')) {
                 errorLine();
                 error(`Could not connect to database`);
-                errorLine(`${dim(redactUrl(err.message))}`);
+                errorLine(`${dim(redactUrl(message))}`);
                 errorLine();
                 errorLine(`${dim('Check that:')}`);
                 errorLine(`  ${dim('1.')} Your database is running`);
                 errorLine(`  ${dim('2.')} The connection string is correct`);
                 errorLine(`  ${dim('3.')} Network/firewall allows the connection`);
             }
-            else if (err.message.includes('authentication')) {
+            else if (message.includes('authentication')) {
                 errorLine();
                 error(`Authentication failed`);
-                errorLine(`${dim(redactUrl(err.message))}`);
+                errorLine(`${dim(redactUrl(message))}`);
             }
-            else if (err.message.includes('does not exist')) {
+            else if (message.includes('does not exist')) {
                 errorLine();
                 error(`Database or schema not found`);
-                errorLine(`${dim(redactUrl(err.message))}`);
+                errorLine(`${dim(redactUrl(message))}`);
             }
             else {
                 errorLine();
-                error(redactUrl(err.message));
+                error(redactUrl(message));
                 if (args.verbose && err.stack) {
                     errorLine();
                     console.error(dim(redactUrl(err.stack)));