turbine-orm 0.25.0 → 0.27.0

package/dist/cjs/query/utils.js

@@ -12,6 +12,7 @@ exports.escapeLike = escapeLike;
 exports.fnv1a64Hex = fnv1a64Hex;
 exports.sqlToPreparedName = sqlToPreparedName;
 exports.buildCorrelation = buildCorrelation;
+exports.parseDbDate = parseDbDate;
 // ---------------------------------------------------------------------------
 // Identifier quoting — prevents SQL injection via table/column names
 // ---------------------------------------------------------------------------
@@ -139,3 +140,38 @@ function buildCorrelation(leftRef, leftColumns, rightRef, rightColumns) {
         .map((col, i) => `${leftRef}.${quoteIdent(col)} = ${rightRef}.${quoteIdent(rightCols[i])}`)
         .join(' AND ');
 }
+/**
+ * Matches an explicit timezone suffix on a date-time string: a trailing `Z`
+ * or a `±HH`, `±HHMM`, `±HH:MM` offset.
+ */
+const TZ_SUFFIX_RE = /(?:Z|[+-]\d{2}(?::?\d{2})?)$/;
+/**
+ * Parse a database date-time string deterministically.
+ *
+ * Postgres `timestamp` (without time zone) values arrive with no offset —
+ * both from the driver and from `json_agg`/`json_build_object` subquery JSON
+ * (`2026-07-07T17:15:41.896`). JavaScript's `new Date()` interprets such
+ * strings in the SERVER'S LOCAL TIME ZONE, so the same row parses to a
+ * different instant depending on where the code runs. The universal ORM
+ * convention (Prisma, Rails, Django) is to treat offset-less timestamps as
+ * UTC — that is also the only interpretation that round-trips: Postgres
+ * stores exactly the wall-clock fields you sent.
+ *
+ * Strings that carry an explicit offset (`timestamptz` output) are parsed
+ * as-is.
+ */
+function parseDbDate(value) {
+    // Date-only values (`2026-07-07`, from `date` columns in json_agg output)
+    // have no time to zone-pin — and their `-07` tail must not be read as an
+    // offset. JS parses bare ISO dates as UTC midnight already.
+    if (!value.includes(':'))
+        return new Date(value);
+    if (TZ_SUFFIX_RE.test(value)) {
+        // JS Date can't parse colon-less (`-0430`) or bare-hour (`+02`) offsets —
+        // normalize both to `±HH:MM`. Postgres emits the bare-hour form for
+        // whole-hour zones in some text outputs.
+        return new Date(value.replace(/([+-]\d{2})(\d{2})$/, '$1:$2').replace(/([+-]\d{2})$/, '$1:00'));
+    }
+    // normalize `YYYY-MM-DD HH:MM:SS` (driver form) to ISO before pinning UTC
+    return new Date(`${value.replace(' ', 'T')}Z`);
+}

package/dist/cli/destructive.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Destructive-migration detection.
+ *
+ * `migrate up`/`down` execute user-authored SQL files verbatim, which is the
+ * one place data loss can hide: a `DROP TABLE` or a `DELETE FROM` in a
+ * migration runs with no ceremony. This module scans migration SQL for
+ * statements that can destroy data so the CLI can force an explicit,
+ * interactive confirmation (and the programmatic API can refuse by default).
+ *
+ * Deliberately conservative in BOTH directions:
+ *   - comments and string literals are stripped first, so `-- DROP TABLE foo`
+ *     or `INSERT ... VALUES ('DROP TABLE x')` never false-positive;
+ *   - anything that removes rows, columns, tables, or schemas — or rewrites a
+ *     column's type (a potentially lossy cast) — is flagged. `DROP INDEX`,
+ *     `DROP CONSTRAINT`, and `DROP TRIGGER` are NOT flagged (recreatable
+ *     structures; no row data lost).
+ */
+export type DestructiveKind = 'drop-table' | 'drop-schema' | 'drop-column' | 'truncate' | 'delete' | 'update-without-where' | 'alter-column-type';
+export interface DestructiveStatement {
+    /** The offending SQL statement (trimmed, possibly long — display truncated) */
+    statement: string;
+    kind: DestructiveKind;
+    /** Best-effort extracted object name (table, schema, or table.column) */
+    target: string;
+}
+/** Human explanation per kind, used in CLI output. */
+export declare const DESTRUCTIVE_KIND_LABEL: Record<DestructiveKind, string>;
+/**
+ * Scan SQL (one file's worth; may contain many `;`-separated statements) and
+ * return every statement that can destroy data.
+ */
+export declare function scanDestructiveSql(sql: string): DestructiveStatement[];

package/dist/cli/destructive.js

@@ -0,0 +1,119 @@
+/**
+ * Destructive-migration detection.
+ *
+ * `migrate up`/`down` execute user-authored SQL files verbatim, which is the
+ * one place data loss can hide: a `DROP TABLE` or a `DELETE FROM` in a
+ * migration runs with no ceremony. This module scans migration SQL for
+ * statements that can destroy data so the CLI can force an explicit,
+ * interactive confirmation (and the programmatic API can refuse by default).
+ *
+ * Deliberately conservative in BOTH directions:
+ *   - comments and string literals are stripped first, so `-- DROP TABLE foo`
+ *     or `INSERT ... VALUES ('DROP TABLE x')` never false-positive;
+ *   - anything that removes rows, columns, tables, or schemas — or rewrites a
+ *     column's type (a potentially lossy cast) — is flagged. `DROP INDEX`,
+ *     `DROP CONSTRAINT`, and `DROP TRIGGER` are NOT flagged (recreatable
+ *     structures; no row data lost).
+ */
+/** Human explanation per kind, used in CLI output. */
+export const DESTRUCTIVE_KIND_LABEL = {
+    'drop-table': 'drops a table and ALL its rows',
+    'drop-schema': 'drops an entire schema',
+    'drop-column': 'drops a column and its data in every row',
+    truncate: 'deletes every row',
+    delete: 'deletes rows',
+    'update-without-where': 'rewrites every row (no WHERE clause)',
+    'alter-column-type': 'rewrites a column type (cast may truncate or fail)',
+};
+/** Strip -- line comments, C-style block comments, and quoted literals. */
+function stripCommentsAndStrings(sql) {
+    let out = '';
+    let i = 0;
+    while (i < sql.length) {
+        const two = sql.slice(i, i + 2);
+        if (two === '--') {
+            const nl = sql.indexOf('\n', i);
+            i = nl === -1 ? sql.length : nl; // keep the newline
+        }
+        else if (two === '/*') {
+            const end = sql.indexOf('*/', i + 2);
+            i = end === -1 ? sql.length : end + 2;
+            out += ' ';
+        }
+        else if (sql[i] === "'") {
+            // single-quoted literal ('' escapes a quote)
+            let j = i + 1;
+            while (j < sql.length) {
+                if (sql[j] === "'" && sql[j + 1] === "'")
+                    j += 2;
+                else if (sql[j] === "'")
+                    break;
+                else
+                    j++;
+            }
+            i = j + 1;
+            out += "''";
+        }
+        else if (sql[i] === '$' && /^\$[a-zA-Z_]*\$/.test(sql.slice(i))) {
+            // dollar-quoted literal ($$...$$ / $tag$...$tag$)
+            const tag = sql.slice(i).match(/^\$[a-zA-Z_]*\$/)?.[0] ?? '$$';
+            const end = sql.indexOf(tag, i + tag.length);
+            i = end === -1 ? sql.length : end + tag.length;
+            out += "''";
+        }
+        else {
+            out += sql[i];
+            i++;
+        }
+    }
+    return out;
+}
+/** Unquote a "quoted" identifier for display. */
+const ident = (raw) => (raw ?? '?').replace(/^"|"$/g, '');
+const IDENT = String.raw `("[^"]+"|[a-zA-Z_][\w$]*)(\.("[^"]+"|[a-zA-Z_][\w$]*))?`;
+/**
+ * Scan SQL (one file's worth; may contain many `;`-separated statements) and
+ * return every statement that can destroy data.
+ */
+export function scanDestructiveSql(sql) {
+    const found = [];
+    const cleaned = stripCommentsAndStrings(sql);
+    for (const rawStmt of cleaned.split(';')) {
+        const stmt = rawStmt.trim();
+        if (!stmt)
+            continue;
+        const display = stmt.replace(/\s+/g, ' ');
+        let m;
+        if ((m = stmt.match(new RegExp(String.raw `^DROP\s+TABLE\s+(IF\s+EXISTS\s+)?${IDENT}`, 'i')))) {
+            found.push({
+                statement: display,
+                kind: 'drop-table',
+                target: ident(m[4] ? `${ident(m[2])}.${ident(m[4])}` : m[2]),
+            });
+        }
+        else if ((m = stmt.match(new RegExp(String.raw `^DROP\s+SCHEMA\s+(IF\s+EXISTS\s+)?${IDENT}`, 'i')))) {
+            found.push({ statement: display, kind: 'drop-schema', target: ident(m[2]) });
+        }
+        else if ((m = stmt.match(new RegExp(String.raw `^TRUNCATE\s+(TABLE\s+)?(ONLY\s+)?${IDENT}`, 'i')))) {
+            found.push({
+                statement: display,
+                kind: 'truncate',
+                target: ident(m[5] ? `${ident(m[3])}.${ident(m[5])}` : m[3]),
+            });
+        }
+        else if ((m = stmt.match(new RegExp(String.raw `^ALTER\s+TABLE\s+(IF\s+EXISTS\s+)?(ONLY\s+)?${IDENT}[\s\S]*?\bDROP\s+COLUMN\s+(IF\s+EXISTS\s+)?${IDENT}`, 'i')))) {
+            found.push({ statement: display, kind: 'drop-column', target: `${ident(m[3])}.${ident(m[7])}` });
+        }
+        else if ((m = stmt.match(new RegExp(String.raw `^ALTER\s+TABLE\s+(IF\s+EXISTS\s+)?(ONLY\s+)?${IDENT}[\s\S]*?\bALTER\s+(COLUMN\s+)?${IDENT}\s+(SET\s+DATA\s+)?TYPE\b`, 'i')))) {
+            found.push({ statement: display, kind: 'alter-column-type', target: `${ident(m[3])}.${ident(m[7])}` });
+        }
+        else if ((m = stmt.match(new RegExp(String.raw `^DELETE\s+FROM\s+(ONLY\s+)?${IDENT}`, 'i')))) {
+            found.push({ statement: display, kind: 'delete', target: ident(m[2]) });
+        }
+        else if ((m = stmt.match(new RegExp(String.raw `^UPDATE\s+(ONLY\s+)?${IDENT}\b`, 'i'))) &&
+            !/\bWHERE\b/i.test(stmt)) {
+            found.push({ statement: display, kind: 'update-without-where', target: ident(m[2]) });
+        }
+    }
+    return found;
+}

package/dist/cli/index.d.ts

@@ -12,6 +12,7 @@
  *   turbine migrate status        — Show migration status
  *   turbine seed                  — Run seed file
  *   turbine status                — Show schema summary
+ *   turbine doctor                — Check relations for missing FK indexes (--fix emits migration)
  *   turbine studio                — Launch local read-only web UI
  *   turbine observe               — Launch metrics dashboard (requires TURBINE_OBSERVE_URL)
  *

package/dist/cli/index.js

@@ -12,6 +12,7 @@
  *   turbine migrate status        — Show migration status
  *   turbine seed                  — Run seed file
  *   turbine status                — Show schema summary
+ *   turbine doctor                — Check relations for missing FK indexes (--fix emits migration)
  *   turbine studio                — Launch local read-only web UI
  *   turbine observe               — Launch metrics dashboard (requires TURBINE_OBSERVE_URL)
  *
@@ -24,6 +25,7 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync, writ
 import { dirname, relative, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { generate } from '../generate.js';
+import { findMissingRelationIndexes } from '../index-advisor.js';
 import { introspect } from '../introspect.js';
 import { schemaDiff, schemaPush } from '../schema-sql.js';
 import { configTemplate, findConfigFile, loadConfig, looksLikeSchemaFilePath, resolveConfig } from './config.js';
@@ -88,6 +90,12 @@ function parseArgs() {
             case '--allow-empty':
                 result.allowEmpty = true;
                 break;
+            case '--fix':
+                result.fix = true;
+                break;
+            case '--allow-destructive':
+                result.allowDestructive = true;
+                break;
             case '--force':
             case '-f':
                 result.force = true;
@@ -744,11 +752,35 @@ async function cmdMigrateUp(args, config) {
         console.log(`  ${dim('Proceed only if you are intentionally rewriting migration history.')}`);
         newline();
     }
+    if (args.allowDestructive) {
+        warn('--allow-destructive is set — data-destroying statements in migrations WILL run.');
+        newline();
+    }
     const spinner = new Spinner('Applying migrations').start();
-    const result = await migrateUp(url, config.migrationsDir, {
-        step: args.step,
-        allowDrift: args.allowDrift,
-    });
+    let result;
+    try {
+        result = await migrateUp(url, config.migrationsDir, {
+            step: args.step,
+            allowDrift: args.allowDrift,
+            allowDestructive: args.allowDestructive,
+        });
+    }
+    catch (err) {
+        if (!isDestructiveRefusal(err))
+            throw err;
+        spinner.stop();
+        if (!(await confirmDestructive(err.message))) {
+            error('Aborted — no migrations were applied and no data was touched.');
+            newline();
+            process.exit(1);
+        }
+        spinner.start();
+        result = await migrateUp(url, config.migrationsDir, {
+            step: args.step,
+            allowDrift: args.allowDrift,
+            allowDestructive: true,
+        });
+    }
     if (result.applied.length === 0 && result.errors.length === 0) {
         spinner.succeed('All migrations are up to date');
         newline();
@@ -771,6 +803,44 @@ async function cmdMigrateUp(args, config) {
     }
     newline();
 }
+/** True when the error is migrate up/down's destructive-statement refusal. */
+function isDestructiveRefusal(err) {
+    return err instanceof Error && err.message.includes('DESTRUCTIVE');
+}
+/**
+ * Triple confirmation for destructive migrations:
+ *   1. show the full itemized report (statement kinds + targets),
+ *   2. require typing the literal phrase `destroy my data`,
+ *   3. require a final explicit `yes`.
+ * Non-interactive shells (CI, pipes) can never pass this — they must use the
+ * explicit `--allow-destructive` flag instead. Anything but exact answers aborts.
+ */
+async function confirmDestructive(report) {
+    newline();
+    error('DESTRUCTIVE MIGRATION DETECTED');
+    newline();
+    for (const line of report.split('\n'))
+        console.log(`  ${line.includes('[turbine]') ? line.replace('[turbine] ', '') : line}`);
+    newline();
+    if (!process.stdin.isTTY) {
+        console.log(`  ${dim('Non-interactive shell: rerun with')} ${cyan('--allow-destructive')} ${dim('to proceed.')}`);
+        newline();
+        return false;
+    }
+    const { createInterface } = await import('node:readline/promises');
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        console.log(`  ${yellow('This will permanently destroy data. There is no undo.')}`);
+        const phrase = await rl.question(`  Type ${bold('destroy my data')} to continue, anything else to abort: `);
+        if (phrase.trim() !== 'destroy my data')
+            return false;
+        const finalAnswer = await rl.question(`  Final confirmation — apply the destructive statements above? Type ${bold('yes')}: `);
+        return finalAnswer.trim() === 'yes';
+    }
+    finally {
+        rl.close();
+    }
+}
 async function cmdMigrateDown(args, config) {
     banner();
     const url = requireUrl(config);
@@ -778,9 +848,28 @@ async function cmdMigrateDown(args, config) {
     label('Migrations', config.migrationsDir);
     newline();
     const spinner = new Spinner('Rolling back migration(s)').start();
-    const result = await migrateDown(url, config.migrationsDir, {
-        step: args.step ?? 1,
-    });
+    let result;
+    try {
+        result = await migrateDown(url, config.migrationsDir, {
+            step: args.step ?? 1,
+            allowDestructive: args.allowDestructive,
+        });
+    }
+    catch (err) {
+        if (!isDestructiveRefusal(err))
+            throw err;
+        spinner.stop();
+        if (!(await confirmDestructive(err.message))) {
+            error('Aborted — nothing was rolled back and no data was touched.');
+            newline();
+            process.exit(1);
+        }
+        spinner.start();
+        result = await migrateDown(url, config.migrationsDir, {
+            step: args.step ?? 1,
+            allowDestructive: true,
+        });
+    }
     if (result.rolledBack.length === 0 && result.errors.length === 0) {
         spinner.succeed('No migrations to roll back');
         newline();
@@ -974,6 +1063,80 @@ async function cmdStatus(_args, config) {
     }
 }
 // ---------------------------------------------------------------------------
+// Command: doctor — relation/index health check
+// ---------------------------------------------------------------------------
+async function cmdDoctor(args, config) {
+    banner();
+    const url = requireUrl(config);
+    label('Database', redactUrl(url));
+    label('Schema', config.schema);
+    newline();
+    const spinner = new Spinner('Introspecting database').start();
+    const schema = await introspect({
+        connectionString: url,
+        schema: config.schema,
+        include: config.include.length ? config.include : undefined,
+        exclude: config.exclude.length ? config.exclude : undefined,
+    });
+    const missing = findMissingRelationIndexes(schema);
+    if (missing.length === 0) {
+        spinner.succeed('Every relation probe is backed by an index');
+        newline();
+        return;
+    }
+    spinner.succeed(`Scanned ${bold(String(Object.keys(schema.tables).length))} tables`);
+    warn(`Found ${bold(String(missing.length))} unindexed relation probe(s)`);
+    newline();
+    // Row counts put the findings in severity order: a missing index on a 300-row
+    // table is noise; on a 300K-row table it is the whole page load.
+    const rowCounts = new Map();
+    {
+        const { Pool } = (await import('pg')).default;
+        const pool = new Pool({ connectionString: url, max: 1 });
+        try {
+            const tables = [...new Set(missing.map((m) => m.table))];
+            const res = await pool.query(`SELECT c.relname, c.reltuples::bigint::text AS reltuples
+           FROM pg_class c
+           JOIN pg_namespace n ON n.oid = c.relnamespace
+          WHERE n.nspname = $1 AND c.relname = ANY($2)`, [config.schema, tables]);
+            for (const row of res.rows)
+                rowCounts.set(row.relname, Math.max(0, Number(row.reltuples)));
+        }
+        finally {
+            await pool.end();
+        }
+    }
+    missing.sort((a, b) => (rowCounts.get(b.table) ?? 0) - (rowCounts.get(a.table) ?? 0));
+    console.log(`  ${dim('Turbine loads relations as correlated subqueries — the child table is probed')}`);
+    console.log(`  ${dim('once per parent row, so an unindexed FK costs a full table scan PER PARENT.')}`);
+    newline();
+    for (const m of missing) {
+        const rows = rowCounts.get(m.table);
+        const rowsLabel = rows !== undefined ? `~${rows.toLocaleString()} rows` : 'row count unknown';
+        console.log(`  ${yellow(symbols.warning)} ${bold(cyan(m.table))} ${dim(`(${m.columns.join(', ')})`)}  ${gray(rowsLabel)}`);
+        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.teeEnd)} ${green(m.createSql)}`);
+        newline();
+    }
+    if (args.fix) {
+        const up = missing.map((m) => m.createSql).join('\n');
+        const down = missing.map((m) => m.dropSql).join('\n');
+        const file = createMigration(config.migrationsDir, 'add_relation_fk_indexes', { up, down });
+        success(`Created migration: ${bold(file.filename)}`);
+        newline();
+        console.log(`  ${dim('Review it, then apply with:')} ${cyan('npx turbine migrate up')}`);
+        console.log(`  ${dim('Large, hot tables: consider running the statements manually with')} ${cyan('CREATE INDEX CONCURRENTLY')}`);
+        console.log(`  ${dim('(cannot run inside a transaction, so it is not emitted in the migration).')}`);
+        newline();
+    }
+    else {
+        console.log(`  ${dim('Generate a fix migration with:')} ${cyan('npx turbine doctor --fix')}`);
+        newline();
+    }
+}
+// ---------------------------------------------------------------------------
 // Command: studio — local read-only web UI
 // ---------------------------------------------------------------------------
 async function cmdStudio(args, config) {
@@ -1194,6 +1357,7 @@ function showMigrateHelp() {
     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-destructive')} Run data-destroying migration statements without the interactive confirm`);
     console.log(`    ${cyan('--verbose, -v')}     Show detailed output`);
     newline();
     console.log(`  ${bold('Examples:')}`);
@@ -1252,6 +1416,7 @@ function showHelp() {
     console.log(`      ${dim('status')}           Show applied/pending migrations`);
     console.log(`    ${cyan('seed')}               Run seed file`);
     console.log(`    ${cyan('status')} ${dim('| info')}      Show schema summary`);
+    console.log(`    ${cyan('doctor')}             Check relations for missing FK indexes ${dim('(--fix emits migration)')}`);
     console.log(`    ${cyan('studio')}             Launch local read-only web UI`);
     console.log(`    ${cyan('observe')}            Launch metrics dashboard ${dim('(requires TURBINE_OBSERVE_URL)')}`);
     newline();
@@ -1404,6 +1569,9 @@ async function main() {
             case 'info':
                 await cmdStatus(args, config);
                 break;
+            case 'doctor':
+                await cmdDoctor(args, config);
+                break;
             case 'studio':
                 await cmdStudio(args, config);
                 break;

package/dist/cli/migrate.d.ts

@@ -115,6 +115,8 @@ export declare function migrateUp(connectionString: string, migrationsDir: strin
     step?: number;
     allowDrift?: boolean;
     force?: boolean /** @deprecated use allowDrift */;
+    /** Run migrations even when they contain data-destroying statements. Default false. */
+    allowDestructive?: boolean;
     adapter?: DatabaseAdapter;
     dialect?: Dialect;
 }): Promise<{
@@ -134,6 +136,7 @@ export declare function migrateUp(connectionString: string, migrationsDir: strin
  */
 export declare function migrateDown(connectionString: string, migrationsDir: string, options?: {
     step?: number;
+    allowDestructive?: boolean;
     adapter?: DatabaseAdapter;
     dialect?: Dialect;
 }): Promise<{

package/dist/cli/migrate.js

@@ -18,6 +18,7 @@ import pg from 'pg';
 import { postgresql } from '../adapters/index.js';
 import { postgresDialect } from '../dialect.js';
 import { MigrationError } from '../errors.js';
+import { DESTRUCTIVE_KIND_LABEL, scanDestructiveSql } from './destructive.js';
 // ---------------------------------------------------------------------------
 // Tracking table management
 // ---------------------------------------------------------------------------
@@ -351,6 +352,35 @@ export async function migrateUp(connectionString, migrationsDir, options) {
             if (options?.step != null && options.step > 0) {
                 pending = pending.slice(0, options.step);
             }
+            // Data-loss gate: refuse to run pending migrations containing destructive
+            // statements unless the caller has EXPLICITLY opted in. The CLI layers an
+            // interactive typed confirmation on top of this; programmatic callers must
+            // pass `allowDestructive: true`. Safe-by-default is the whole point — a
+            // DROP TABLE should never run just because a file exists.
+            if (!options?.allowDestructive) {
+                const offenders = [];
+                for (const file of pending) {
+                    const { up } = parseMigrationSQL(file.path);
+                    if (!up)
+                        continue;
+                    const hits = scanDestructiveSql(up);
+                    if (hits.length > 0)
+                        offenders.push({ file: file.filename, hits });
+                }
+                if (offenders.length > 0) {
+                    const lines = ['[turbine] Refusing to apply migrations containing DESTRUCTIVE statements:', ''];
+                    for (const o of offenders) {
+                        lines.push(`  ${o.file}`);
+                        for (const h of o.hits) {
+                            lines.push(`    - [${h.kind}] ${h.target} — ${DESTRUCTIVE_KIND_LABEL[h.kind]}`);
+                        }
+                    }
+                    lines.push('');
+                    lines.push('Review the statements above. To proceed: run `npx turbine migrate up` interactively');
+                    lines.push('and confirm, pass --allow-destructive, or set allowDestructive: true programmatically.');
+                    throw new MigrationError(lines.join('\n'));
+                }
+            }
             const results = [];
             const errors = [];
             for (const file of pending) {
@@ -418,6 +448,36 @@ export async function migrateDown(connectionString, migrationsDir, options) {
             const fileMap = new Map(allFiles.map((f) => [f.name, f]));
             // Reverse order — rollback most recent first
             const toRollback = applied.reverse().slice(0, options?.step ?? 1);
+            // Same data-loss gate as migrateUp — DOWN sections routinely contain
+            // DROP TABLE (the legitimate reverse of a CREATE), which still destroys
+            // every row written since the migration ran. Explicit opt-in required.
+            if (!options?.allowDestructive) {
+                const offenders = [];
+                for (const migration of toRollback) {
+                    const file = fileMap.get(migration.name);
+                    if (!file)
+                        continue;
+                    const { down } = parseMigrationSQL(file.path);
+                    if (!down)
+                        continue;
+                    const hits = scanDestructiveSql(down);
+                    if (hits.length > 0)
+                        offenders.push({ file: file.filename, hits });
+                }
+                if (offenders.length > 0) {
+                    const lines = ['[turbine] Refusing to roll back migrations whose DOWN sections are DESTRUCTIVE:', ''];
+                    for (const o of offenders) {
+                        lines.push(`  ${o.file}`);
+                        for (const h of o.hits) {
+                            lines.push(`    - [${h.kind}] ${h.target} — ${DESTRUCTIVE_KIND_LABEL[h.kind]}`);
+                        }
+                    }
+                    lines.push('');
+                    lines.push('To proceed: run `npx turbine migrate down` interactively and confirm, pass');
+                    lines.push('--allow-destructive, or set allowDestructive: true programmatically.');
+                    throw new MigrationError(lines.join('\n'));
+                }
+            }
             const results = [];
             const errors = [];
             for (const migration of toRollback) {

package/dist/cli/ui.d.ts

@@ -30,7 +30,7 @@ export declare const symbols: {
     readonly bullet: "*" | "•";
     readonly arrow: "→" | "->";
     readonly arrowRight: ">" | "▸";
-    readonly info: "ℹ" | "i";
+    readonly info: "i" | "ℹ";
     readonly warning: "⚠" | "!";
     readonly dot: "." | "∙";
     readonly line: "─" | "-";

package/dist/client.d.ts

@@ -26,7 +26,7 @@ import { type Dialect } from './dialect.js';
 import { type ErrorMessageMode } from './errors.js';
 import { type ObserveConfig, type ObserveHandle } from './observe.js';
 import { type PipelineOptions, type PipelineResults } from './pipeline.js';
-import { type DeferredQuery, type QueryEventListener, QueryInterface, type QueryInterfaceOptions } from './query/index.js';
+import { type DeferredQuery, type QueryEventListener, QueryInterface, type QueryInterfaceOptions, type RelationLoadStrategy } from './query/index.js';
 import { type NotificationHandler, type Subscription } from './realtime.js';
 import type { SchemaMetadata } from './schema.js';
 import { TypedSqlQuery } from './typed-sql.js';
@@ -140,6 +140,44 @@ export interface TurbineConfig {
     defaultLimit?: number;
     /** Log a warning when findMany() is called without a limit (default: false) */
     warnOnUnlimited?: boolean;
+    /**
+     * Interpret Postgres `timestamp` (without time zone) values as UTC — both
+     * at the driver level (OID 1114 type parser, registered only when Turbine
+     * owns the pool) and when coercing nested-relation JSON dates. This is the
+     * Prisma/Rails/Django convention and makes results independent of the
+     * server's local time zone. Default: `true`. Set `false` for the legacy
+     * local-time interpretation.
+     */
+    utcTimestamps?: boolean;
+    /**
+     * Default strategy for resolving `with`-clause relations, applied to every
+     * `findMany`/`findUnique`/`findFirst` unless overridden per query.
+     *
+     *   - `'join'` (default) — one SQL statement using correlated
+     *     `json_agg(json_build_object(...))` subqueries.
+     *   - `'batched'` — run the base query, then one flat follow-up query per
+     *     relation (`WHERE fk = ANY($1)`), stitching children client-side. Wins
+     *     when child FK columns are unindexed or result sets are large.
+     *
+     * Precedence: per-query `relationLoadStrategy` arg > this config > `'join'`.
+     */
+    relationLoadStrategy?: RelationLoadStrategy;
+    /**
+     * How nested-relation subqueries encode each row's JSON.
+     *
+     *   - `'object'` (default) — `json_agg(json_build_object('key', v, …))`. Every
+     *     key name is repeated in every nested object of every row.
+     *   - `'positional'` — `json_agg(json_build_array(v, …))`. Turbine knows the
+     *     column order at build time, so it emits a key-less array and maps
+     *     positions back to keys client-side. Same information, a fraction of the
+     *     bytes on wide/deeply-nested `with` trees. Parsed output is byte-identical
+     *     to `'object'`.
+     *
+     * Postgres-only in v1: setting `'positional'` on a non-Postgres engine throws
+     * `UnsupportedFeatureError` (E017) when a `with` clause is present. Default:
+     * `'object'` (today's behavior, byte-unchanged).
+     */
+    jsonEncoding?: 'object' | 'positional';
     /**
      * Controls how `NotFoundError` (and other where-aware errors) format their
      * messages.
@@ -263,6 +301,7 @@ export declare class TurbineClient {
     /** The schema metadata this client was built from */
     readonly schema: SchemaMetadata;
     private static int8ParserRegistered;
+    private static utcTimestampParserRegistered;
     private readonly logging;
     /** Active SQL dialect — owns transaction keywords, set_config, raw-SQL placeholders, capability flags. */
     private readonly dialect;

package/dist/client.js

@@ -197,6 +197,7 @@ export class TurbineClient {
     /** The schema metadata this client was built from */
     schema;
     static int8ParserRegistered = false;
+    static utcTimestampParserRegistered = false;
     logging;
     /** Active SQL dialect — owns transaction keywords, set_config, raw-SQL placeholders, capability flags. */
     dialect;
@@ -244,6 +245,16 @@ export class TurbineClient {
             });
             TurbineClient.int8ParserRegistered = true;
         }
+        // Parse `timestamp` (OID 1114) as UTC instead of server-local time. The
+        // pg driver's default hands back a Date built in the process's local zone,
+        // so the same row yields a different instant per deployment region. The
+        // ORM convention (Prisma, Rails, Django) — and the only interpretation
+        // that round-trips what Postgres stores — is UTC. Same ownership rule as
+        // the int8 parser: never mutate parser state on external pools.
+        if (!config.pool && config.utcTimestamps !== false && !TurbineClient.utcTimestampParserRegistered) {
+            pg.types.setTypeParser(1114, (val) => new Date(`${val.replace(' ', 'T')}Z`));
+            TurbineClient.utcTimestampParserRegistered = true;
+        }
         this.logging = config.logging ?? false;
         this.dialect = config.dialect ?? postgresDialect;
         this.schema = schema;
@@ -253,6 +264,9 @@ export class TurbineClient {
         this.queryOptions = {
             defaultLimit: config.defaultLimit,
             warnOnUnlimited: config.warnOnUnlimited,
+            utcTimestamps: config.utcTimestamps,
+            relationLoadStrategy: config.relationLoadStrategy,
+            jsonEncoding: config.jsonEncoding,
             preparedStatements: envDisablePrepared ? false : (config.preparedStatements ?? !config.pool),
             sqlCache: config.sqlCache ?? true,
             dialect: config.dialect,