turbine-orm 0.25.0 → 0.27.0

package/README.md

@@ -344,6 +344,30 @@ const db = turbine({
 });
 ```
 
+### Relation loading and wire encoding
+
+A few client options tune how `with` relations are loaded and encoded. All are optional and default to today's behavior.
+
+```typescript
+const db = turbine({
+  connectionString: process.env.DATABASE_URL,
+  // How with-clause relations resolve: 'join' (default, one correlated-subquery
+  // statement) or 'batched' (base query + one flat follow-up per relation).
+  // Override per query on findMany/findFirst/findUnique. See Relations.
+  relationLoadStrategy: 'join',
+  // 'positional' (Postgres-only) drops repeated JSON keys from relation
+  // subqueries — ~39% fewer wire bytes on wide relations, byte-identical output.
+  // Default 'object'.
+  jsonEncoding: 'object',
+  // Parse `timestamp` (without time zone) as UTC — the Prisma/Rails/Django
+  // convention — so results don't shift with the server's local zone.
+  // Default true; set false for the legacy local-time interpretation.
+  utcTimestamps: true,
+});
+```
+
+Run `npx turbine doctor` to catch relations whose child-side FK lacks a covering index — the correlated-subquery strategy probes the child once per parent row, so a missing FK index costs a full scan per parent.
+
 ### Middleware
 
 Middleware wraps every query. It runs **after SQL generation**, so it can observe what's about to execute (`params.model`, `params.action`, `params.args`), measure timing, and transform the result returned by `next()` — but it cannot change the query itself.
@@ -579,6 +603,7 @@ Commands:
   migrate status               Show applied/pending migrations
   seed                         Run seed file
   status                       Show database schema summary
+  doctor                       Check relations for missing FK indexes (--fix emits migration)
   studio                       Launch local read-only Studio web UI
   observe                      Launch local metrics dashboard (requires TURBINE_OBSERVE_URL)
 
@@ -636,6 +661,12 @@ npx turbine migrate down
 npx turbine migrate status
 ```
 
+**Destructive migrations require explicit confirmation.** If a pending migration (or a DOWN
+section being rolled back) contains data-destroying SQL — `DROP TABLE`, `DROP COLUMN`,
+`TRUNCATE`, `DELETE FROM`, `UPDATE` without `WHERE`, `ALTER COLUMN … TYPE` — Turbine refuses
+to run it and prints an itemized report. Interactively you must type `destroy my data` and
+then `yes`; in CI you must pass `--allow-destructive`. A refused batch applies nothing.
+
 ## Studio
 
 The only Postgres ORM with a Studio your DBA will approve. `turbine studio` launches a local, read-only web UI for exploring your database — no mutations, no writes, and since v0.19 **no raw-SQL surface at all**: every query is composed visually in the ORM and compiled by the same validated query builder your application uses.
@@ -890,7 +921,7 @@ Turbine maps Postgres types to TypeScript:
 | `int8` / `bigint` | `number` | Values > `Number.MAX_SAFE_INTEGER` (2^53 - 1) are returned as `string` at runtime to avoid precision loss. This affects < 0.01% of use cases (auto-increment IDs, counts, etc. are all safe). |
 | `numeric`, `money` | `string` | Arbitrary precision — kept as string to avoid JS float issues |
 | `text`, `varchar`, `uuid`, `citext` | `string` | |
-| `timestamptz`, `timestamp`, `date` | `Date` | |
+| `timestamptz`, `timestamp`, `date` | `Date` | `timestamp` (without time zone) is parsed as UTC by default (Prisma/Rails/Django convention), so the same row yields the same instant in every region. Opt out with `utcTimestamps: false`. |
 | `boolean` | `boolean` | |
 | `json`, `jsonb` | `unknown` | |
 | `bytea` | `Buffer` | |

package/dist/cjs/cli/destructive.js

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * 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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DESTRUCTIVE_KIND_LABEL = void 0;
+exports.scanDestructiveSql = scanDestructiveSql;
+/** Human explanation per kind, used in CLI output. */
+exports.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.
+ */
+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/cjs/cli/index.js

@@ -13,6 +13,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)
  *
@@ -59,6 +60,7 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const node_url_1 = require("node:url");
 const generate_js_1 = require("../generate.js");
+const index_advisor_js_1 = require("../index-advisor.js");
 const introspect_js_1 = require("../introspect.js");
 const schema_sql_js_1 = require("../schema-sql.js");
 const config_js_1 = require("./config.js");
@@ -123,6 +125,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;
@@ -779,11 +787,35 @@ async function cmdMigrateUp(args, config) {
         console.log(`  ${(0, ui_js_1.dim)('Proceed only if you are intentionally rewriting migration history.')}`);
         (0, ui_js_1.newline)();
     }
+    if (args.allowDestructive) {
+        (0, ui_js_1.warn)('--allow-destructive is set — data-destroying statements in migrations WILL run.');
+        (0, ui_js_1.newline)();
+    }
     const spinner = new ui_js_1.Spinner('Applying migrations').start();
-    const result = await (0, migrate_js_1.migrateUp)(url, config.migrationsDir, {
-        step: args.step,
-        allowDrift: args.allowDrift,
-    });
+    let result;
+    try {
+        result = await (0, migrate_js_1.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))) {
+            (0, ui_js_1.error)('Aborted — no migrations were applied and no data was touched.');
+            (0, ui_js_1.newline)();
+            process.exit(1);
+        }
+        spinner.start();
+        result = await (0, migrate_js_1.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');
         (0, ui_js_1.newline)();
@@ -806,6 +838,44 @@ async function cmdMigrateUp(args, config) {
     }
     (0, ui_js_1.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) {
+    (0, ui_js_1.newline)();
+    (0, ui_js_1.error)('DESTRUCTIVE MIGRATION DETECTED');
+    (0, ui_js_1.newline)();
+    for (const line of report.split('\n'))
+        console.log(`  ${line.includes('[turbine]') ? line.replace('[turbine] ', '') : line}`);
+    (0, ui_js_1.newline)();
+    if (!process.stdin.isTTY) {
+        console.log(`  ${(0, ui_js_1.dim)('Non-interactive shell: rerun with')} ${(0, ui_js_1.cyan)('--allow-destructive')} ${(0, ui_js_1.dim)('to proceed.')}`);
+        (0, ui_js_1.newline)();
+        return false;
+    }
+    const { createInterface } = await Promise.resolve().then(() => __importStar(require('node:readline/promises')));
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        console.log(`  ${(0, ui_js_1.yellow)('This will permanently destroy data. There is no undo.')}`);
+        const phrase = await rl.question(`  Type ${(0, ui_js_1.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 ${(0, ui_js_1.bold)('yes')}: `);
+        return finalAnswer.trim() === 'yes';
+    }
+    finally {
+        rl.close();
+    }
+}
 async function cmdMigrateDown(args, config) {
     (0, ui_js_1.banner)();
     const url = requireUrl(config);
@@ -813,9 +883,28 @@ async function cmdMigrateDown(args, config) {
     (0, ui_js_1.label)('Migrations', config.migrationsDir);
     (0, ui_js_1.newline)();
     const spinner = new ui_js_1.Spinner('Rolling back migration(s)').start();
-    const result = await (0, migrate_js_1.migrateDown)(url, config.migrationsDir, {
-        step: args.step ?? 1,
-    });
+    let result;
+    try {
+        result = await (0, migrate_js_1.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))) {
+            (0, ui_js_1.error)('Aborted — nothing was rolled back and no data was touched.');
+            (0, ui_js_1.newline)();
+            process.exit(1);
+        }
+        spinner.start();
+        result = await (0, migrate_js_1.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');
         (0, ui_js_1.newline)();
@@ -1009,6 +1098,80 @@ async function cmdStatus(_args, config) {
     }
 }
 // ---------------------------------------------------------------------------
+// Command: doctor — relation/index health check
+// ---------------------------------------------------------------------------
+async function cmdDoctor(args, config) {
+    (0, ui_js_1.banner)();
+    const url = requireUrl(config);
+    (0, ui_js_1.label)('Database', (0, ui_js_1.redactUrl)(url));
+    (0, ui_js_1.label)('Schema', config.schema);
+    (0, ui_js_1.newline)();
+    const spinner = new ui_js_1.Spinner('Introspecting database').start();
+    const schema = await (0, introspect_js_1.introspect)({
+        connectionString: url,
+        schema: config.schema,
+        include: config.include.length ? config.include : undefined,
+        exclude: config.exclude.length ? config.exclude : undefined,
+    });
+    const missing = (0, index_advisor_js_1.findMissingRelationIndexes)(schema);
+    if (missing.length === 0) {
+        spinner.succeed('Every relation probe is backed by an index');
+        (0, ui_js_1.newline)();
+        return;
+    }
+    spinner.succeed(`Scanned ${(0, ui_js_1.bold)(String(Object.keys(schema.tables).length))} tables`);
+    (0, ui_js_1.warn)(`Found ${(0, ui_js_1.bold)(String(missing.length))} unindexed relation probe(s)`);
+    (0, ui_js_1.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 Promise.resolve().then(() => __importStar(require('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(`  ${(0, ui_js_1.dim)('Turbine loads relations as correlated subqueries — the child table is probed')}`);
+    console.log(`  ${(0, ui_js_1.dim)('once per parent row, so an unindexed FK costs a full table scan PER PARENT.')}`);
+    (0, ui_js_1.newline)();
+    for (const m of missing) {
+        const rows = rowCounts.get(m.table);
+        const rowsLabel = rows !== undefined ? `~${rows.toLocaleString()} rows` : 'row count unknown';
+        console.log(`  ${(0, ui_js_1.yellow)(ui_js_1.symbols.warning)} ${(0, ui_js_1.bold)((0, ui_js_1.cyan)(m.table))} ${(0, ui_js_1.dim)(`(${m.columns.join(', ')})`)}  ${(0, ui_js_1.gray)(rowsLabel)}`);
+        for (const p of m.probes) {
+            console.log(`    ${(0, ui_js_1.dim)(ui_js_1.symbols.tee)} probed by ${p.from}.${(0, ui_js_1.blue)(p.relation)} ${(0, ui_js_1.dim)(`(${p.type})`)}`);
+        }
+        console.log(`    ${(0, ui_js_1.dim)(ui_js_1.symbols.teeEnd)} ${(0, ui_js_1.green)(m.createSql)}`);
+        (0, ui_js_1.newline)();
+    }
+    if (args.fix) {
+        const up = missing.map((m) => m.createSql).join('\n');
+        const down = missing.map((m) => m.dropSql).join('\n');
+        const file = (0, migrate_js_1.createMigration)(config.migrationsDir, 'add_relation_fk_indexes', { up, down });
+        (0, ui_js_1.success)(`Created migration: ${(0, ui_js_1.bold)(file.filename)}`);
+        (0, ui_js_1.newline)();
+        console.log(`  ${(0, ui_js_1.dim)('Review it, then apply with:')} ${(0, ui_js_1.cyan)('npx turbine migrate up')}`);
+        console.log(`  ${(0, ui_js_1.dim)('Large, hot tables: consider running the statements manually with')} ${(0, ui_js_1.cyan)('CREATE INDEX CONCURRENTLY')}`);
+        console.log(`  ${(0, ui_js_1.dim)('(cannot run inside a transaction, so it is not emitted in the migration).')}`);
+        (0, ui_js_1.newline)();
+    }
+    else {
+        console.log(`  ${(0, ui_js_1.dim)('Generate a fix migration with:')} ${(0, ui_js_1.cyan)('npx turbine doctor --fix')}`);
+        (0, ui_js_1.newline)();
+    }
+}
+// ---------------------------------------------------------------------------
 // Command: studio — local read-only web UI
 // ---------------------------------------------------------------------------
 async function cmdStudio(args, config) {
@@ -1229,6 +1392,7 @@ function showMigrateHelp() {
     console.log(`    ${(0, ui_js_1.cyan)('--step, -n')} ${(0, ui_js_1.dim)('<N>')}    Number of migrations to apply/rollback`);
     console.log(`    ${(0, ui_js_1.cyan)('--dry-run')}         Show SQL without executing`);
     console.log(`    ${(0, ui_js_1.cyan)('--allow-drift')}     Bypass checksum validation ${(0, ui_js_1.dim)('(migrate up only — advanced)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--allow-destructive')} Run data-destroying migration statements without the interactive confirm`);
     console.log(`    ${(0, ui_js_1.cyan)('--verbose, -v')}     Show detailed output`);
     (0, ui_js_1.newline)();
     console.log(`  ${(0, ui_js_1.bold)('Examples:')}`);
@@ -1287,6 +1451,7 @@ function showHelp() {
     console.log(`      ${(0, ui_js_1.dim)('status')}           Show applied/pending migrations`);
     console.log(`    ${(0, ui_js_1.cyan)('seed')}               Run seed file`);
     console.log(`    ${(0, ui_js_1.cyan)('status')} ${(0, ui_js_1.dim)('| info')}      Show schema summary`);
+    console.log(`    ${(0, ui_js_1.cyan)('doctor')}             Check relations for missing FK indexes ${(0, ui_js_1.dim)('(--fix emits migration)')}`);
     console.log(`    ${(0, ui_js_1.cyan)('studio')}             Launch local read-only web UI`);
     console.log(`    ${(0, ui_js_1.cyan)('observe')}            Launch metrics dashboard ${(0, ui_js_1.dim)('(requires TURBINE_OBSERVE_URL)')}`);
     (0, ui_js_1.newline)();
@@ -1439,6 +1604,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/cjs/cli/migrate.js

@@ -35,6 +35,7 @@ const pg_1 = __importDefault(require("pg"));
 const index_js_1 = require("../adapters/index.js");
 const dialect_js_1 = require("../dialect.js");
 const errors_js_1 = require("../errors.js");
+const destructive_js_1 = require("./destructive.js");
 // ---------------------------------------------------------------------------
 // Tracking table management
 // ---------------------------------------------------------------------------
@@ -368,6 +369,35 @@ 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 = (0, destructive_js_1.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_js_1.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 errors_js_1.MigrationError(lines.join('\n'));
+                }
+            }
             const results = [];
             const errors = [];
             for (const file of pending) {
@@ -435,6 +465,36 @@ 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 = (0, destructive_js_1.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_js_1.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 errors_js_1.MigrationError(lines.join('\n'));
+                }
+            }
             const results = [];
             const errors = [];
             for (const migration of toRollback) {

package/dist/cjs/client.js

@@ -205,6 +205,7 @@ 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;
@@ -252,6 +253,16 @@ 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_1.default.types.setTypeParser(1114, (val) => new Date(`${val.replace(' ', 'T')}Z`));
+            TurbineClient.utcTimestampParserRegistered = true;
+        }
         this.logging = config.logging ?? false;
         this.dialect = config.dialect ?? dialect_js_1.postgresDialect;
         this.schema = schema;
@@ -261,6 +272,9 @@ 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,

package/dist/cjs/dialect.js

@@ -68,8 +68,32 @@ exports.postgresDialect = {
     },
     buildJsonObject(pairs) {
         const args = pairs.map(([key, expr]) => `'${this.escapeStringLiteral(key)}', ${expr}`);
+        // Postgres caps function calls at 100 arguments (= 50 key/value pairs).
+        // Wide tables (or wide select+relation trees) exceed that, so chunk into
+        // multiple jsonb_build_object calls merged with `||`, cast back to json.
+        if (pairs.length > 50) {
+            const chunks = [];
+            for (let i = 0; i < args.length; i += 50) {
+                chunks.push(`jsonb_build_object(${args.slice(i, i + 50).join(', ')})`);
+            }
+            return `(${chunks.join(' || ')})::json`;
+        }
         return `json_build_object(${args.join(', ')})`;
     },
+    buildJsonArray(exprs) {
+        // Mirror buildJsonObject's chunking at the SAME 50-element threshold: for
+        // wide rows, concatenate 50-element jsonb_build_array calls with `||` (which
+        // concatenates jsonb arrays) and cast back to json. `jsonb ||` preserves
+        // element order, so positions map back to keys unchanged after decode.
+        if (exprs.length > 50) {
+            const chunks = [];
+            for (let i = 0; i < exprs.length; i += 50) {
+                chunks.push(`jsonb_build_array(${exprs.slice(i, i + 50).join(', ')})`);
+            }
+            return `(${chunks.join(' || ')})::json`;
+        }
+        return `json_build_array(${exprs.join(', ')})`;
+    },
     buildJsonArrayAgg(jsonObjectExpr, orderBy) {
         const suffix = orderBy ? ` ${orderBy}` : '';
         return `COALESCE(json_agg(${jsonObjectExpr}${suffix}), ${this.emptyJsonArrayLiteral})`;

package/dist/cjs/mssql.js

@@ -807,7 +807,9 @@ function buildForJsonSubquery(dialect, ctx) {
         return buildForJsonManyToMany(dialect, ctx, { colSelect, buildNested, buildPaging, hasLimit });
     }
     const isToOne = relDef.type === 'belongsTo' || relDef.type === 'hasOne';
-    const correlation = isToOne
+    // Correlation direction is about WHERE THE FK LIVES, not cardinality:
+    // belongsTo has it on the source; hasMany AND hasOne have it on the target.
+    const correlation = relDef.type === 'belongsTo'
         ? dialect.buildCorrelation(alias, relDef.referenceKey, qParent, relDef.foreignKey)
         : dialect.buildCorrelation(alias, relDef.foreignKey, qParent, relDef.referenceKey);
     // ----- to-one (belongsTo / hasOne): single object, no paging --------------