turbine-orm 0.60.0 → 0.61.0

package/README.md

@@ -22,11 +22,11 @@ The reason to reach for Turbine is that every layer between you and a production
 4. **Data-destroying statements need consent.** `migrate up`, `migrate down` and `push` scan for `DROP TABLE`, `DROP COLUMN`, `TRUNCATE`, unqualified `DELETE` / `UPDATE`, and `ALTER COLUMN … TYPE`, print an itemized report, and refuse to run. Interactively you type `destroy my data` and then `yes`; in CI you pass `--allow-destructive`. A refused batch applies nothing.
 5. **The review a DBA would have given you, offline.** `npx turbine doctor` derives every column set the ORM's relation subqueries probe and reports the ones with no covering index, with a cost tier per finding. `--fix` writes the migration. No cloud service, no telemetry, no account: it reads your introspected schema.
 
-**On "only".** Each of these is checkable, so here is the checkable version, current as of July 2026: no other TypeScript ORM ships a studio that is read-only by default or that redacts PII (Prisma Studio is proprietary and its read-only request has been open since February 2021; Drizzle Studio is not open source and self-hosting runs through the paid Drizzle Gateway; TypeORM, MikroORM, Kysely and Sequelize have no studio). No TypeScript ORM CLI offers missing-index advice: not the Prisma CLI, drizzle-kit, kysely-ctl, or the MikroORM / TypeORM / Sequelize CLIs, and Prisma Optimize was retired in March 2026 in favour of cloud-only Query Insights. Prior art exists outside TypeScript, notably Ruby's `active_record_doctor`, so the honest claim is "no TypeScript ORM", not "no ORM". Turbine is the only TypeScript ORM that ships all five of the above together.
+**On "only".** Each of these is checkable, so here is the checkable version, current as of July 2026: no other TypeScript ORM ships a studio that is read-only by default or that redacts PII (Prisma Studio is open source, `@prisma/studio-core` is Apache-2.0, but it has no read-only mode and that request has been open since February 2021; Drizzle Studio is not open source and self-hosting runs through the paid Drizzle Gateway; TypeORM, MikroORM, Kysely and Sequelize have no studio). No TypeScript ORM CLI offers missing-index advice: not the Prisma CLI, drizzle-kit, kysely-ctl, or the MikroORM / TypeORM / Sequelize CLIs, and Prisma Optimize was retired in March 2026 in favour of cloud-only Query Insights. Prior art exists outside TypeScript, notably Ruby's `active_record_doctor`, so the honest claim is "no TypeScript ORM", not "no ORM". Turbine is the only TypeScript ORM that ships all five of the above together.
 
 Two more things worth knowing, which are about cost rather than safety:
 
-- **One runtime dependency (`pg`).** No engine binary, no WASM, no adapter packages in lockstep. The main entry's **import graph** is ~65 kB brotli (edge ~50 kB) with `pg` external (measured 2026-07-25 on 0.50.0: 65.16 kB and 50.18 kB, budgeted in `.size-limit.js`). That is the client footprint your bundler sees, not the size of the dual ESM+CJS build on disk, which is larger. Prisma 7 dropped its Rust query engine but its client still ships a TypeScript/WASM query compiler, a ~1.6 MB bundle, down from the ~14 MB Rust-era client.
+- **One runtime dependency (`pg`).** No engine binary, no WASM, no adapter packages in lockstep. The main entry's **import graph** is held under **77 kB brotli** (edge under 61 kB) with `pg` external. That is the ceiling `size-limit` enforces in CI from `.size-limit.js`, not a figure typed into this file: a measurement quoted in prose goes stale silently, and this one did, drifting ~12% low over ten releases before a review caught it. Run `npm run size` for the current number. That is the client footprint your bundler sees, not the size of the dual ESM+CJS build on disk, which is larger. Prisma 7 dropped its Rust query engine but its client still ships a TypeScript/WASM query compiler, a ~1.6 MB bundle, down from the ~14 MB Rust-era client.
 - **Real pipelining, not a batch transaction.** `db.pipeline(...)` uses the Postgres extended-query protocol (Parse/Bind/Execute/Sync) to put N independent queries in one TCP flush. node-postgres does not expose pipelining in its pure-JS core ([brianc/node-postgres#2646](https://github.com/brianc/node-postgres/issues/2646) was still open as of July 2026), and Drizzle's `db.batch()` is an implicit transaction on specific drivers rather than independent-query pipelining.
 
 **Beyond the safety bundle, what ships today:** [global filters](https://turbineorm.dev/global-filters) for soft-delete and multi-tenancy · [read replicas](https://turbineorm.dev/read-replicas) with a `$primary()` escape hatch · a read-only [MCP server](https://turbineorm.dev/mcp) for AI agents · [seed-as-code](https://turbineorm.dev/seeding) and a non-interactive `migrate deploy` for CI · [Zod generation](https://turbineorm.dev/zod) · read-only [views & generated columns](https://turbineorm.dev/views) · [optional SQLite / MySQL / SQL Server / PowDB engines](https://turbineorm.dev/engines) behind subpath exports · a [Prisma migration toolkit](https://turbineorm.dev/migrate-from-prisma) (schema mapper plus a runtime compat adapter) · a cost-aware index advisor in [`turbine doctor`](https://turbineorm.dev/cli#turbine-doctor).
@@ -1131,14 +1131,14 @@ Turbine maps Postgres types to TypeScript:
 |---|---|---|---|---|
 | **Engine / runtime** | No engine binary (`pg` only) | Client + TS/WASM query compiler | No engine | No engine |
 | **Runtime deps** | 1 (`pg`) | `@prisma/client` + required driver adapter | 0 | 0 |
-| **Main bundle (brotli)** | ~65 kB import graph, `pg` external | ~1.6 MB client (TS/WASM compiler) | ~7 KB core | small |
+| **Main bundle (brotli)** | under 77 kB import graph (CI-enforced), `pg` external | ~1.6 MB client (TS/WASM compiler) | ~7 KB core | small |
 | **Studio** | Read-only, 192-bit auth | Full CRUD, cloud-hosted | Free; hosted Gateway paid | None |
 | **Error PII safety** | Keys only by default | Values in messages | Raw pg errors | Raw pg errors |
 | **Migrations** | SQL-first, SHA-256 checksums | DSL-generated, shadow DB | SQL or Drizzle Kit | None |
-| **Edge runtime** | One import swap, ~50 kB brotli | Driver adapter + WASM compiler | Native | Native |
+| **Edge runtime** | One import swap, under 61 kB brotli (CI-enforced) | Driver adapter + WASM compiler | Native | Native |
 | **Pipeline batching** | Parse/Bind/Execute protocol | Sequential in txn | Sequential | Manual |
 | **Typed errors** | `isRetryable` discriminant | Error codes only | None | None |
-| **Nested relations** | 1 query, deep type inference | 1 query, shallow inference | 1 query, `relations()` re-declaration | Manual (`jsonArrayFrom`) |
+| **Nested relations** | 1 query, deep type inference | 1 query per relation by default; single-query `relationJoins` is still Preview and whole-query only | 1 query, `relations()` re-declaration | Manual (`jsonArrayFrom`) |
 | **Many-to-many** | Auto-detected from junctions | Implicit/explicit | Explicit `relations()` | Manual joins |
 | **Vector search** | Built-in `distance` / KNN | Preview / raw | Extension API | Manual |
 | **LISTEN/NOTIFY** | `$listen` / `$notify` | None | None | None |
@@ -1148,7 +1148,7 @@ Reading the table: no engine binary and no WASM, just one runtime dependency (`p
 
 *Competitor columns are re-verified against competitor releases on a fixed schedule. Last checked July 2026, against Prisma 7 and Drizzle 0.45. Features marked Preview or beta may change, and bundle sizes move release to release.*
 
-**A note on Kysely.** Kysely's [`jsonArrayFrom` / `jsonObjectFrom`](https://kysely.dev/docs/recipes/relations) relations recipe builds nested results with the same correlated-subquery-plus-JSON approach Turbine uses, good evidence the pattern is the right one. The gap is in what the driver can no longer see once rows are aggregated into JSON: nested fields lose their column types, so a `Date` inside a `jsonArrayFrom` result is typed `Date` but arrives as a **string** at runtime ([kysely-org/kysely#482](https://github.com/kysely-org/kysely/issues/482)), and the nesting isn't type-checked at depth. Turbine's `WithResult` inference types the whole tree, and `parseNestedRow` re-applies date coercion (and snake→camel mapping) to every nested row, so `users[0].posts[0].createdAt` is an actual `Date`, at any depth, with no plugin to wire up.
+**A note on Kysely.** Kysely's [`jsonArrayFrom` / `jsonObjectFrom`](https://kysely.dev/docs/recipes/relations) relations recipe builds nested results with the same correlated-subquery-plus-JSON approach Turbine uses, good evidence the pattern is the right one. The gap is in what the driver can no longer see once rows are aggregated into JSON: a `Date` nested inside a `jsonArrayFrom` result arrives as a **string** at runtime, because the aggregation erased the column type the driver would otherwise have parsed on. Kysely types that honestly and leaves the conversion to you. Turbine's `parseNestedRow` re-applies date coercion and snake→camel mapping to every nested row, so `users[0].posts[0].createdAt` is an actual `Date` at any depth with nothing to wire up. Stated from documented behaviour rather than from an issue-tracker link: a linked issue's state changes without notice, and a claim resting on one goes stale silently.
 
 ## Limitations
 

package/dist/cjs/cli/index.js

@@ -1777,6 +1777,41 @@ async function cmdMigrateCreate(args, config) {
     console.log(`  ${(0, ui_js_1.cyan)('npx turbine migrate up')}`);
     (0, ui_js_1.newline)();
 }
+/**
+ * Print the SQL a `migrate up` / `migrate down` WOULD run, and execute nothing.
+ *
+ * `--dry-run` was parsed and then read by `push` and `deploy` only, so on
+ * `migrate up` it was silently inert: the flag was accepted, no warning was
+ * printed, and the migrations were applied. A flag whose whole purpose is
+ * "show me what this would do to the database" that instead does it, against
+ * whatever `--url` was passed, is the most dangerous shape a CLI bug can take.
+ *
+ * Reads through the same `parseMigrationContent` the executor uses, so what is
+ * printed is what would run, rather than a second rendering that can drift.
+ */
+function printMigrationDryRun(files, section) {
+    const verb = section === 'up' ? 'apply' : 'roll back';
+    if (files.length === 0) {
+        (0, ui_js_1.info)(`Dry run: nothing to ${verb}.`);
+        (0, ui_js_1.newline)();
+        return;
+    }
+    (0, ui_js_1.info)(`Dry run: would ${verb} ${(0, ui_js_1.bold)(String(files.length))} migration(s). Nothing was executed.`);
+    (0, ui_js_1.newline)();
+    for (const file of files) {
+        const parsed = (0, migrate_js_1.parseMigrationContent)((0, node_fs_1.readFileSync)(file.path, 'utf-8'));
+        const sql = section === 'up' ? parsed.up : parsed.down;
+        console.log(`  ${(0, ui_js_1.cyan)(file.filename)}${parsed.noTransaction ? (0, ui_js_1.dim)('  (no transaction)') : ''}`);
+        if (sql.trim().length === 0) {
+            console.log(`    ${(0, ui_js_1.dim)(`(empty ${section.toUpperCase()} section)`)}`);
+        }
+        else {
+            for (const line of sql.split('\n'))
+                console.log(`    ${(0, ui_js_1.dim)(line)}`);
+        }
+        (0, ui_js_1.newline)();
+    }
+}
 async function cmdMigrateUp(args, config) {
     (0, ui_js_1.banner)();
     const url = requireUrl(config);
@@ -1790,6 +1825,14 @@ async function cmdMigrateUp(args, config) {
         (0, ui_js_1.newline)();
         return;
     }
+    if (args.dryRun) {
+        const status = await (0, migrate_js_1.migrateStatus)(url, config.migrationsDir);
+        let pending = status.filter((st) => !st.applied).map((st) => st.file);
+        if (args.step != null && args.step > 0)
+            pending = pending.slice(0, args.step);
+        printMigrationDryRun(pending, 'up');
+        return;
+    }
     // Big, loud warning when bypassing drift detection, this is a deliberately
     // dangerous operation and the user should see it on every invocation.
     if (args.allowDrift) {
@@ -2011,6 +2054,14 @@ async function cmdMigrateDown(args, config) {
     (0, ui_js_1.label)('Database', (0, ui_js_1.redactUrl)(url));
     (0, ui_js_1.label)('Migrations', config.migrationsDir);
     (0, ui_js_1.newline)();
+    if (args.dryRun) {
+        const status = await (0, migrate_js_1.migrateStatus)(url, config.migrationsDir);
+        // Rollback order is newest-applied first, and a migration whose file is
+        // missing has no DOWN section to show.
+        const applied = status.filter((st) => st.applied && !st.missingFile).map((st) => st.file);
+        printMigrationDryRun(applied.reverse().slice(0, args.step ?? 1), 'down');
+        return;
+    }
     const spinner = new ui_js_1.Spinner('Rolling back migration(s)').start();
     let result;
     try {

package/dist/cjs/client.js

@@ -193,13 +193,65 @@ function warnUnknownConfigKeys(config) {
         // must never be the reason a client fails to construct.
     }
 }
-/** Maps isolation level names to SQL */
-const ISOLATION_LEVELS = {
+/**
+ * Maps isolation level names to SQL. Null-prototype and read through
+ * {@link resolveIsolationLevel}, never indexed directly: an inherited key
+ * (`constructor`, `toString`) would otherwise resolve to a function and be
+ * interpolated verbatim into `BEGIN ISOLATION LEVEL …`.
+ */
+const ISOLATION_LEVELS = Object.assign(Object.create(null), {
     ReadUncommitted: 'READ UNCOMMITTED',
     ReadCommitted: 'READ COMMITTED',
     RepeatableRead: 'REPEATABLE READ',
     Serializable: 'SERIALIZABLE',
-};
+});
+/**
+ * Resolve a requested isolation level, REFUSING anything not in the map.
+ *
+ * A miss used to yield `undefined`, which `beginStatement` renders as a plain
+ * `BEGIN`. So `isolationLevel: 'serializable'` (wrong case) asked for
+ * SERIALIZABLE and silently got READ COMMITTED, which is the worst available
+ * outcome for this option: the caller believes it has a guarantee it does not
+ * have, and the workload that depended on it produces wrong data with no error.
+ *
+ * The TypeScript union on `TransactionOptions.isolationLevel` does not prevent
+ * this. It is not enforced for a JavaScript consumer of a published package, for
+ * a value read from config or an environment variable, or across any `as`.
+ * Throwing costs a caller who was already broken one clear error.
+ */
+/**
+ * Run a transaction-control statement (BEGIN / COMMIT / ROLLBACK) with the same
+ * error translation every other query boundary gets.
+ *
+ * These four statements were the only ones issued raw, and COMMIT is the one
+ * that matters: Postgres reports DEFERRABLE constraint violations and a good
+ * share of SERIALIZABLE conflicts at COMMIT rather than at the statement that
+ * caused them. Unwrapped, those surfaced as a raw `DatabaseError` carrying a
+ * SQLSTATE in `.code`, which is the SAME property Turbine puts `TURBINE_E0NN`
+ * in, so `err.code === 'TURBINE_E008'` silently missed them and a `switch` on
+ * `.code` received a value from a foreign namespace. Worse for the retry case:
+ * `SerializationFailureError.isRetryable` exists so callers can build retry
+ * loops, and a loop keyed on it would never fire for the commit-time conflicts
+ * that are the main reason to run SERIALIZABLE at all.
+ */
+async function runTxControl(client, sql) {
+    try {
+        await client.query(sql);
+    }
+    catch (err) {
+        throw (0, errors_js_1.wrapPgError)(err);
+    }
+}
+function resolveIsolationLevel(level) {
+    if (level === undefined)
+        return undefined;
+    const sql = (0, utils_js_1.ownLookup)(ISOLATION_LEVELS, level);
+    if (sql === undefined) {
+        throw new errors_js_1.ValidationError(`[turbine] $transaction: unknown isolationLevel ${JSON.stringify(level)}. ` +
+            `Expected one of: ${Object.keys(ISOLATION_LEVELS).join(', ')} (case-sensitive).`);
+    }
+    return sql;
+}
 /**
  * Strict GUC (session variable) name: an optionally namespaced identifier such
  * as `app.current_tenant` or `search_path`. Even though the name is passed as a
@@ -1270,7 +1322,7 @@ class TurbineClient {
          */
         let began = false;
         try {
-            await client.query(this.dialect.beginStatement());
+            await runTxControl(client, this.dialect.beginStatement());
             began = true;
             // Engine seam: single-writer engines scope their transaction re-entrancy
             // marker to the callback's async subtree (see
@@ -1278,7 +1330,7 @@ class TurbineClient {
             const wrap = client.wrapTransactionCallback;
             // `.call` erases the generic, so the callback's Promise<T> is re-asserted.
             const result = wrap ? (await wrap.call(client, () => fn(client))) : await fn(client);
-            await client.query(this.dialect.commitStatement());
+            await runTxControl(client, this.dialect.commitStatement());
             return result;
         }
         catch (err) {
@@ -1303,6 +1355,9 @@ class TurbineClient {
             return this.transactionBatch(fnOrQueries);
         }
         const fn = fnOrQueries;
+        // Resolve the isolation level BEFORE taking a pool slot: a bad argument is
+        // the caller's bug and should not cost a connection to discover.
+        const isolationSql = resolveIsolationLevel(options?.isolationLevel);
         const client = await this.pool.connect();
         const timeout = options?.timeout;
         /**
@@ -1335,8 +1390,7 @@ class TurbineClient {
         try {
             // BEGIN with optional isolation level, the dialect owns the keyword and
             // BEGIN+isolation composition (Postgres appends ` ISOLATION LEVEL …`).
-            const isolationSql = options?.isolationLevel ? ISOLATION_LEVELS[options.isolationLevel] : undefined;
-            await client.query(this.dialect.beginStatement(isolationSql));
+            await runTxControl(client, this.dialect.beginStatement(isolationSql));
             began = true;
             // Apply transaction-local session context (RLS / multi-tenant GUCs).
             // Order matters: BEGIN -> isolation level (above) -> set_config loop ->
@@ -1408,7 +1462,7 @@ class TurbineClient {
             else {
                 result = await runCallback();
             }
-            await client.query(this.dialect.commitStatement());
+            await runTxControl(client, this.dialect.commitStatement());
             if (this.logging) {
                 console.log('[turbine] Transaction committed');
             }

package/dist/cjs/pipeline-submittable.js

@@ -364,14 +364,37 @@ async function runPipelined(client, queries, options = {}) {
                     connection.sync();
                 }
             }
-            if (connection.stream.uncork) {
-                connection.stream.uncork();
-            }
         }
         catch (err) {
+            // The send path threw PART WAY THROUGH an extended-query sequence, so the
+            // backend has Parse/Bind bytes for the preceding queries and will never
+            // receive their Sync. `valueMapper: prepareValue` runs synchronously
+            // inside `bind`, so any param with a throwing `toPostgres`/`toJSON`, or a
+            // circular reference, lands here.
+            //
+            // Returning that connection to the pool is what made this severe: the pool
+            // reports it idle and healthy, the NEXT borrower checks it out, and its
+            // first query hangs forever waiting on a ReadyForQuery for a sequence that
+            // was never completed. The failure surfaces in an unrelated query with
+            // nothing pointing back here. Destroy the connection instead: one dead
+            // socket is recoverable, a wedged pool slot is not.
+            //
+            // Destroying the socket is the same move the timeout path above already
+            // makes, and node-postgres drops a client whose stream errored rather than
+            // returning it to the pool.
+            if (connection.stream.destroy) {
+                connection.stream.destroy(err instanceof Error ? err : new Error(String(err)));
+            }
             cleanup();
             reject(err);
         }
+        finally {
+            // Always uncork, including on the throw path: leaving the stream corked
+            // strands the buffered bytes and the socket with them.
+            if (connection.stream.uncork) {
+                connection.stream.uncork();
+            }
+        }
     });
 }
 // ---------------------------------------------------------------------------

package/dist/cjs/prisma-schema-fingerprint.d.ts

@@ -35,7 +35,13 @@
  *  - a leading UTF-8 BOM, which some editors add and remove without being asked;
  *  - CRLF and lone CR line endings, so a Windows checkout of an unchanged file
  *    is not reported as drift (`core.autocrlf` rewrites on checkout);
- *  - trailing whitespace at the very end of the file, for the same reason.
+ *  - whitespace at the very END of the file, for the same reason.
+ *
+ * Note the last one is end-of-FILE only, not per line. Trailing whitespace on an
+ * individual line is hashed, and changing it is reported as drift. That is the
+ * intended reading: nothing in a checkout rewrites it, so it got there because
+ * someone edited the line, and the cost of an unnecessary regeneration is lower
+ * than the cost of a missed one.
  *
  * Nothing else is normalized. Comments and blank lines are hashed as-is: a
  * "harmless" edit is still an edit, and reporting one costs a regeneration

package/dist/cjs/prisma-schema-fingerprint.js

@@ -36,7 +36,13 @@
  *  - a leading UTF-8 BOM, which some editors add and remove without being asked;
  *  - CRLF and lone CR line endings, so a Windows checkout of an unchanged file
  *    is not reported as drift (`core.autocrlf` rewrites on checkout);
- *  - trailing whitespace at the very end of the file, for the same reason.
+ *  - whitespace at the very END of the file, for the same reason.
+ *
+ * Note the last one is end-of-FILE only, not per line. Trailing whitespace on an
+ * individual line is hashed, and changing it is reported as drift. That is the
+ * intended reading: nothing in a checkout rewrites it, so it got there because
+ * someone edited the line, and the cost of an unnecessary regeneration is lower
+ * than the cost of a missed one.
  *
  * Nothing else is normalized. Comments and blank lines are hashed as-is: a
  * "harmless" edit is still an edit, and reporting one costs a regeneration

package/dist/cjs/query/builder.js

@@ -1879,6 +1879,30 @@ class QueryInterface {
         // Prisma compound-unique selector expansion (before global-filter merge and
         // fingerprinting, so the cache only ever sees the canonical expanded where).
         args = maybeExpandCompoundUnique(this.tableMeta, args);
+        // A findUnique whose `where` carries NO predicate must not run.
+        //
+        // `{ id: undefined }` is what `{ id: req.params.id }` becomes on a request
+        // that omitted the parameter, or on a typo'd one. Undefined keys are dropped
+        // downstream, so that used to emit `SELECT … FROM t LIMIT 1`: no predicate,
+        // and the caller gets an ARBITRARY row where it asked for a specific one and
+        // would have handled `null`. On an authorization check keyed by id that is a
+        // silent cross-record read, and `findUniqueOrThrow` made it worse by
+        // promising to throw when nothing matched and then returning a stranger's
+        // row instead.
+        //
+        // Checked against the USER's where, before the global-filter merge, and
+        // deliberately so: a tenant filter is not a unique selector, and letting it
+        // satisfy this would still hand back an arbitrary row from inside the tenant.
+        //
+        // `findFirst` is intentionally NOT guarded. "The first row matching an
+        // optional filter" is its whole contract and Prisma's `findFirst` behaves
+        // the same way; ask for one row by identity with `findUnique`.
+        if (whereMod.userPredicateIsEmpty(this.ctx, (args.where ?? {}))) {
+            throw new errors_js_1.ValidationError(`[turbine] findUnique on "${this.table}" refused: the \`where\` clause has no predicate, ` +
+                'so this would return an arbitrary row rather than a specific one. ' +
+                'A key whose value is `undefined` does not count, check that the value you are looking up is defined. ' +
+                'If you meant "any row matching an optional filter", use `findFirst`.');
+        }
         // Stable relation order (opt-in): fill PK-asc orderBy into unordered to-many
         // relations before fingerprinting (see buildFindMany).
         if (args.with && this.resolveStableOrder(args.stableRelationOrder)) {

package/dist/cli/index.js

@@ -41,7 +41,7 @@ import { configTemplate, DEFAULT_INIT_SEED_FILE, findConfigFile, loadConfigResul
 import { DESTRUCTIVE_KIND_LABEL } from './destructive.js';
 import { canResolveTsx, getTsLoaderError, needsTsLoader, registerTsLoader } from './loader.js';
 import { runMcpServer } from './mcp.js';
-import { buildDiffMigrationBody, collectUpDestructive, createMigration, formatChecksumMismatchError, inspectMigrationDeploy, listMigrationFiles, MIGRATION_RECIPES, migrateDeploy, migrateDown, migrateStatus, migrateUp, } from './migrate.js';
+import { buildDiffMigrationBody, collectUpDestructive, createMigration, formatChecksumMismatchError, inspectMigrationDeploy, listMigrationFiles, MIGRATION_RECIPES, migrateDeploy, migrateDown, migrateStatus, migrateUp, parseMigrationContent, } from './migrate.js';
 import { startObserve } from './observe.js';
 import { formatPrismaReport, summaryLines } from './prisma-report.js';
 import { DEFAULT_EXCLUDED_TABLES, resolvePrismaSchema } from './prisma-resolve.js';
@@ -1727,6 +1727,41 @@ async function cmdMigrateCreate(args, config) {
     console.log(`  ${cyan('npx turbine migrate up')}`);
     newline();
 }
+/**
+ * Print the SQL a `migrate up` / `migrate down` WOULD run, and execute nothing.
+ *
+ * `--dry-run` was parsed and then read by `push` and `deploy` only, so on
+ * `migrate up` it was silently inert: the flag was accepted, no warning was
+ * printed, and the migrations were applied. A flag whose whole purpose is
+ * "show me what this would do to the database" that instead does it, against
+ * whatever `--url` was passed, is the most dangerous shape a CLI bug can take.
+ *
+ * Reads through the same `parseMigrationContent` the executor uses, so what is
+ * printed is what would run, rather than a second rendering that can drift.
+ */
+function printMigrationDryRun(files, section) {
+    const verb = section === 'up' ? 'apply' : 'roll back';
+    if (files.length === 0) {
+        info(`Dry run: nothing to ${verb}.`);
+        newline();
+        return;
+    }
+    info(`Dry run: would ${verb} ${bold(String(files.length))} migration(s). Nothing was executed.`);
+    newline();
+    for (const file of files) {
+        const parsed = parseMigrationContent(readFileSync(file.path, 'utf-8'));
+        const sql = section === 'up' ? parsed.up : parsed.down;
+        console.log(`  ${cyan(file.filename)}${parsed.noTransaction ? dim('  (no transaction)') : ''}`);
+        if (sql.trim().length === 0) {
+            console.log(`    ${dim(`(empty ${section.toUpperCase()} section)`)}`);
+        }
+        else {
+            for (const line of sql.split('\n'))
+                console.log(`    ${dim(line)}`);
+        }
+        newline();
+    }
+}
 async function cmdMigrateUp(args, config) {
     banner();
     const url = requireUrl(config);
@@ -1740,6 +1775,14 @@ async function cmdMigrateUp(args, config) {
         newline();
         return;
     }
+    if (args.dryRun) {
+        const status = await migrateStatus(url, config.migrationsDir);
+        let pending = status.filter((st) => !st.applied).map((st) => st.file);
+        if (args.step != null && args.step > 0)
+            pending = pending.slice(0, args.step);
+        printMigrationDryRun(pending, 'up');
+        return;
+    }
     // Big, loud warning when bypassing drift detection, this is a deliberately
     // dangerous operation and the user should see it on every invocation.
     if (args.allowDrift) {
@@ -1961,6 +2004,14 @@ async function cmdMigrateDown(args, config) {
     label('Database', redactUrl(url));
     label('Migrations', config.migrationsDir);
     newline();
+    if (args.dryRun) {
+        const status = await migrateStatus(url, config.migrationsDir);
+        // Rollback order is newest-applied first, and a migration whose file is
+        // missing has no DOWN section to show.
+        const applied = status.filter((st) => st.applied && !st.missingFile).map((st) => st.file);
+        printMigrationDryRun(applied.reverse().slice(0, args.step ?? 1), 'down');
+        return;
+    }
     const spinner = new Spinner('Rolling back migration(s)').start();
     let result;
     try {

package/dist/client.js

@@ -27,7 +27,7 @@ import { setErrorMessageMode, TimeoutError, UnsupportedFeatureError, ValidationE
 import { ObserveEngine } from './observe.js';
 import { executePipeline, pipelineSupported } from './pipeline.js';
 import { QueryInterface, } from './query/index.js';
-import { markTurbineParser, quoteIdent, registerUtcTemporalParsers, suggestKey, warnParserOverwrite, } from './query/utils.js';
+import { markTurbineParser, ownLookup, quoteIdent, registerUtcTemporalParsers, suggestKey, warnParserOverwrite, } from './query/utils.js';
 import { shouldWarnOnce, WARN_NS } from './query/warn-registry.js';
 import { createSubscription, validateChannel, } from './realtime.js';
 import { buildTypedSql, TypedSqlQuery } from './typed-sql.js';
@@ -186,13 +186,65 @@ function warnUnknownConfigKeys(config) {
         // must never be the reason a client fails to construct.
     }
 }
-/** Maps isolation level names to SQL */
-const ISOLATION_LEVELS = {
+/**
+ * Maps isolation level names to SQL. Null-prototype and read through
+ * {@link resolveIsolationLevel}, never indexed directly: an inherited key
+ * (`constructor`, `toString`) would otherwise resolve to a function and be
+ * interpolated verbatim into `BEGIN ISOLATION LEVEL …`.
+ */
+const ISOLATION_LEVELS = Object.assign(Object.create(null), {
     ReadUncommitted: 'READ UNCOMMITTED',
     ReadCommitted: 'READ COMMITTED',
     RepeatableRead: 'REPEATABLE READ',
     Serializable: 'SERIALIZABLE',
-};
+});
+/**
+ * Resolve a requested isolation level, REFUSING anything not in the map.
+ *
+ * A miss used to yield `undefined`, which `beginStatement` renders as a plain
+ * `BEGIN`. So `isolationLevel: 'serializable'` (wrong case) asked for
+ * SERIALIZABLE and silently got READ COMMITTED, which is the worst available
+ * outcome for this option: the caller believes it has a guarantee it does not
+ * have, and the workload that depended on it produces wrong data with no error.
+ *
+ * The TypeScript union on `TransactionOptions.isolationLevel` does not prevent
+ * this. It is not enforced for a JavaScript consumer of a published package, for
+ * a value read from config or an environment variable, or across any `as`.
+ * Throwing costs a caller who was already broken one clear error.
+ */
+/**
+ * Run a transaction-control statement (BEGIN / COMMIT / ROLLBACK) with the same
+ * error translation every other query boundary gets.
+ *
+ * These four statements were the only ones issued raw, and COMMIT is the one
+ * that matters: Postgres reports DEFERRABLE constraint violations and a good
+ * share of SERIALIZABLE conflicts at COMMIT rather than at the statement that
+ * caused them. Unwrapped, those surfaced as a raw `DatabaseError` carrying a
+ * SQLSTATE in `.code`, which is the SAME property Turbine puts `TURBINE_E0NN`
+ * in, so `err.code === 'TURBINE_E008'` silently missed them and a `switch` on
+ * `.code` received a value from a foreign namespace. Worse for the retry case:
+ * `SerializationFailureError.isRetryable` exists so callers can build retry
+ * loops, and a loop keyed on it would never fire for the commit-time conflicts
+ * that are the main reason to run SERIALIZABLE at all.
+ */
+async function runTxControl(client, sql) {
+    try {
+        await client.query(sql);
+    }
+    catch (err) {
+        throw wrapPgError(err);
+    }
+}
+function resolveIsolationLevel(level) {
+    if (level === undefined)
+        return undefined;
+    const sql = ownLookup(ISOLATION_LEVELS, level);
+    if (sql === undefined) {
+        throw new ValidationError(`[turbine] $transaction: unknown isolationLevel ${JSON.stringify(level)}. ` +
+            `Expected one of: ${Object.keys(ISOLATION_LEVELS).join(', ')} (case-sensitive).`);
+    }
+    return sql;
+}
 /**
  * Strict GUC (session variable) name: an optionally namespaced identifier such
  * as `app.current_tenant` or `search_path`. Even though the name is passed as a
@@ -1262,7 +1314,7 @@ export class TurbineClient {
          */
         let began = false;
         try {
-            await client.query(this.dialect.beginStatement());
+            await runTxControl(client, this.dialect.beginStatement());
             began = true;
             // Engine seam: single-writer engines scope their transaction re-entrancy
             // marker to the callback's async subtree (see
@@ -1270,7 +1322,7 @@ export class TurbineClient {
             const wrap = client.wrapTransactionCallback;
             // `.call` erases the generic, so the callback's Promise<T> is re-asserted.
             const result = wrap ? (await wrap.call(client, () => fn(client))) : await fn(client);
-            await client.query(this.dialect.commitStatement());
+            await runTxControl(client, this.dialect.commitStatement());
             return result;
         }
         catch (err) {
@@ -1295,6 +1347,9 @@ export class TurbineClient {
             return this.transactionBatch(fnOrQueries);
         }
         const fn = fnOrQueries;
+        // Resolve the isolation level BEFORE taking a pool slot: a bad argument is
+        // the caller's bug and should not cost a connection to discover.
+        const isolationSql = resolveIsolationLevel(options?.isolationLevel);
         const client = await this.pool.connect();
         const timeout = options?.timeout;
         /**
@@ -1327,8 +1382,7 @@ export class TurbineClient {
         try {
             // BEGIN with optional isolation level, the dialect owns the keyword and
             // BEGIN+isolation composition (Postgres appends ` ISOLATION LEVEL …`).
-            const isolationSql = options?.isolationLevel ? ISOLATION_LEVELS[options.isolationLevel] : undefined;
-            await client.query(this.dialect.beginStatement(isolationSql));
+            await runTxControl(client, this.dialect.beginStatement(isolationSql));
             began = true;
             // Apply transaction-local session context (RLS / multi-tenant GUCs).
             // Order matters: BEGIN -> isolation level (above) -> set_config loop ->
@@ -1400,7 +1454,7 @@ export class TurbineClient {
             else {
                 result = await runCallback();
             }
-            await client.query(this.dialect.commitStatement());
+            await runTxControl(client, this.dialect.commitStatement());
             if (this.logging) {
                 console.log('[turbine] Transaction committed');
             }

package/dist/pipeline-submittable.js

@@ -357,14 +357,37 @@ export async function runPipelined(client, queries, options = {}) {
                     connection.sync();
                 }
             }
-            if (connection.stream.uncork) {
-                connection.stream.uncork();
-            }
         }
         catch (err) {
+            // The send path threw PART WAY THROUGH an extended-query sequence, so the
+            // backend has Parse/Bind bytes for the preceding queries and will never
+            // receive their Sync. `valueMapper: prepareValue` runs synchronously
+            // inside `bind`, so any param with a throwing `toPostgres`/`toJSON`, or a
+            // circular reference, lands here.
+            //
+            // Returning that connection to the pool is what made this severe: the pool
+            // reports it idle and healthy, the NEXT borrower checks it out, and its
+            // first query hangs forever waiting on a ReadyForQuery for a sequence that
+            // was never completed. The failure surfaces in an unrelated query with
+            // nothing pointing back here. Destroy the connection instead: one dead
+            // socket is recoverable, a wedged pool slot is not.
+            //
+            // Destroying the socket is the same move the timeout path above already
+            // makes, and node-postgres drops a client whose stream errored rather than
+            // returning it to the pool.
+            if (connection.stream.destroy) {
+                connection.stream.destroy(err instanceof Error ? err : new Error(String(err)));
+            }
             cleanup();
             reject(err);
         }
+        finally {
+            // Always uncork, including on the throw path: leaving the stream corked
+            // strands the buffered bytes and the socket with them.
+            if (connection.stream.uncork) {
+                connection.stream.uncork();
+            }
+        }
     });
 }
 // ---------------------------------------------------------------------------

package/dist/prisma-schema-fingerprint.d.ts

@@ -35,7 +35,13 @@
  *  - a leading UTF-8 BOM, which some editors add and remove without being asked;
  *  - CRLF and lone CR line endings, so a Windows checkout of an unchanged file
  *    is not reported as drift (`core.autocrlf` rewrites on checkout);
- *  - trailing whitespace at the very end of the file, for the same reason.
+ *  - whitespace at the very END of the file, for the same reason.
+ *
+ * Note the last one is end-of-FILE only, not per line. Trailing whitespace on an
+ * individual line is hashed, and changing it is reported as drift. That is the
+ * intended reading: nothing in a checkout rewrites it, so it got there because
+ * someone edited the line, and the cost of an unnecessary regeneration is lower
+ * than the cost of a missed one.
  *
  * Nothing else is normalized. Comments and blank lines are hashed as-is: a
  * "harmless" edit is still an edit, and reporting one costs a regeneration

package/dist/prisma-schema-fingerprint.js

@@ -35,7 +35,13 @@
  *  - a leading UTF-8 BOM, which some editors add and remove without being asked;
  *  - CRLF and lone CR line endings, so a Windows checkout of an unchanged file
  *    is not reported as drift (`core.autocrlf` rewrites on checkout);
- *  - trailing whitespace at the very end of the file, for the same reason.
+ *  - whitespace at the very END of the file, for the same reason.
+ *
+ * Note the last one is end-of-FILE only, not per line. Trailing whitespace on an
+ * individual line is hashed, and changing it is reported as drift. That is the
+ * intended reading: nothing in a checkout rewrites it, so it got there because
+ * someone edited the line, and the cost of an unnecessary regeneration is lower
+ * than the cost of a missed one.
  *
  * Nothing else is normalized. Comments and blank lines are hashed as-is: a
  * "harmless" edit is still an edit, and reporting one costs a regeneration

package/dist/query/builder.js

@@ -1843,6 +1843,30 @@ export class QueryInterface {
         // Prisma compound-unique selector expansion (before global-filter merge and
         // fingerprinting, so the cache only ever sees the canonical expanded where).
         args = maybeExpandCompoundUnique(this.tableMeta, args);
+        // A findUnique whose `where` carries NO predicate must not run.
+        //
+        // `{ id: undefined }` is what `{ id: req.params.id }` becomes on a request
+        // that omitted the parameter, or on a typo'd one. Undefined keys are dropped
+        // downstream, so that used to emit `SELECT … FROM t LIMIT 1`: no predicate,
+        // and the caller gets an ARBITRARY row where it asked for a specific one and
+        // would have handled `null`. On an authorization check keyed by id that is a
+        // silent cross-record read, and `findUniqueOrThrow` made it worse by
+        // promising to throw when nothing matched and then returning a stranger's
+        // row instead.
+        //
+        // Checked against the USER's where, before the global-filter merge, and
+        // deliberately so: a tenant filter is not a unique selector, and letting it
+        // satisfy this would still hand back an arbitrary row from inside the tenant.
+        //
+        // `findFirst` is intentionally NOT guarded. "The first row matching an
+        // optional filter" is its whole contract and Prisma's `findFirst` behaves
+        // the same way; ask for one row by identity with `findUnique`.
+        if (whereMod.userPredicateIsEmpty(this.ctx, (args.where ?? {}))) {
+            throw new ValidationError(`[turbine] findUnique on "${this.table}" refused: the \`where\` clause has no predicate, ` +
+                'so this would return an arbitrary row rather than a specific one. ' +
+                'A key whose value is `undefined` does not count, check that the value you are looking up is defined. ' +
+                'If you meant "any row matching an optional filter", use `findFirst`.');
+        }
         // Stable relation order (opt-in): fill PK-asc orderBy into unordered to-many
         // relations before fingerprinting (see buildFindMany).
         if (args.with && this.resolveStableOrder(args.stableRelationOrder)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.60.0",
+  "version": "0.61.0",
   "description": "Postgres-native TypeScript ORM, runs on Neon, Vercel Postgres, Cloudflare, Supabase. Streaming cursors, typed errors, single-query nested relations. One dependency, no WASM engine",
   "type": "module",
   "//exports": "Each subpath declares its types PER CONDITION. A single shared top-level \"types\" resolves to the ESM declarations for `require` too, which is TS1479 (\"is an ES module ... cannot be require()d\") for any CJS consumer on moduleResolution node16/nodenext. The require condition points at dist/cjs, which ships its own {\"type\":\"commonjs\"} package.json, so those declarations are CJS declarations. Gated in CI by publint + @arethetypeswrong/cli + a real .cts consumer typecheck (see the package-types job in ci.yml).",