turbine-orm 0.7.0 → 0.8.0

package/README.md

@@ -8,34 +8,35 @@ npm install turbine-orm
 
 ## Why Turbine?
 
-Turbine is a PostgreSQL-native TypeScript ORM with features no other ORM offers together: **cursor-based streaming** through nested relations, **typed error classes** with PostgreSQL constraint mapping, **pipeline batching** (N queries, 1 round-trip), **middleware**, and a driver-agnostic core that plugs into any pg-compatible pool so it runs on Vercel Edge, Cloudflare Workers, Deno Deploy, and similar environments. It resolves nested relations in a single SQL query using `json_agg` — an approach now shared by Prisma 7+ and Drizzle v2, but Turbine does it with 1 runtime dependency (`pg`) and ~110KB on npm.
+Turbine is a PostgreSQL-native TypeScript ORM with features no other ORM offers together: **deep typed `with` inference** (`users[0].posts[0].comments[0].author` autocompletes after one `findMany`), **cursor-based streaming** through nested relations, **typed error classes** with PostgreSQL constraint mapping, **pipeline batching** (N queries, 1 round-trip), **middleware**, and a driver-agnostic core that plugs into any pg-compatible pool so it runs on Vercel Edge, Cloudflare Workers, Deno Deploy, and similar environments. 1 runtime dependency (`pg`), ~110KB on npm.
 
-**One query for nested relations.** When you write `db.users.findMany({ with: { posts: { with: { comments: true } } } })`, Turbine generates a single SQL statement using correlated subqueries with `json_agg`. Modern ORMs like Prisma 7+ and Drizzle v2 use similar single-query approaches (LATERAL JOINs). Turbine's advantage is architectural simplicity: 1 dependency, no code generation DSL, and PostgreSQL-native depth.
+**One round-trip for nested relations.** `db.users.findMany({ with: { posts: { with: { comments: true } } } })` resolves the entire object graph in a single database round-trip, regardless of nesting depth. Prisma 7+ and Drizzle v2 also do single-query nested loads — Turbine's advantage is architectural simplicity: 1 dependency, no code generation DSL, no query plan compiler.
 
 ## Benchmarks
 
-Tested against **Prisma 7.6** (adapter-pg, relationJoins) and **Drizzle 0.45** (relational queries) on the same PostgreSQL database. 200 iterations, 20 warmup, Node v22.
+Tested against **Prisma 7.6** (adapter-pg, relationJoins preview on) and **Drizzle 0.45** (relational queries) on a **Neon** PostgreSQL database (pooled endpoint, US-East, PostgreSQL 17.8). 100 iterations, 20 warmup, Node v22. Same schema, same data (1K users, 10K posts, 50K comments), same connection pool config.
 
 | Scenario | Turbine | Prisma 7 | Drizzle v2 |
 |---|---|---|---|
-| **findMany — 100 rows (flat)** | **0.39 ms** | 0.58 ms | 0.44 ms |
-| **findMany — L2 nested (users + posts)** | **1.29 ms** | 1.84 ms | 1.30 ms |
-| **findMany — L3 nested (users → posts → comments)** | **0.50 ms** | 0.91 ms | 0.69 ms |
-| **findUnique by PK** | **0.08 ms** | 0.13 ms | 0.14 ms |
-| **findUnique — L3 nested** | **0.18 ms** | 0.32 ms | 0.34 ms |
-| **count** | **0.06 ms** | 0.10 ms | 0.08 ms |
+| findMany — 100 users (flat) | **51.97 ms** | 52.90 ms | 53.51 ms |
+| findMany — 50 users + posts (L2) | **55.84 ms** | 56.10 ms | 88.80 ms |
+| findMany — 10 users → posts → comments (L3) | 52.77 ms | 59.35 ms | **52.38 ms** |
+| findUnique — single user by PK | **47.66 ms** | 52.15 ms | 47.78 ms |
+| findUnique — user + posts + comments (L3) | **51.71 ms** | 54.42 ms | 52.47 ms |
+| count — all users | **44.57 ms** | 47.54 ms | 46.75 ms |
+| stream — iterate 50K rows (batch 1000) | 3,207 ms | **3,099 ms** | 4,620 ms |
+| atomic increment — `view_count + 1` | 49.76 ms | 49.09 ms | **46.25 ms** |
+| pipeline — 5-query batch | 318 ms | 327 ms | **316 ms** |
 
-| Scenario | Turbine | Prisma 7 | Drizzle v2 |
-|---|---|---|---|
-| findMany — flat | **1.00x** | 1.51x | 1.15x |
-| findMany — L2 nested | **1.00x** | 1.43x | 1.01x |
-| findMany — L3 nested | **1.00x** | 1.81x | 1.38x |
-| findUnique by PK | **1.00x** | 1.67x | 1.69x |
-| findUnique — L3 nested | **1.00x** | 1.81x | 1.93x |
-| count | **1.00x** | 1.70x | 1.38x |
+**Against a real pooled database, most single-query scenarios are within noise** — network round-trip to Neon is ~33–40 ms, which swamps per-query CPU overhead. But a few results stand out:
+
+- **L2 nested reads.** Turbine and Prisma are neck-and-neck (~56 ms), while Drizzle is **1.59× slower** (89 ms) on the 50-user + posts scenario. Turbine's `json_agg` approach and SQL template caching pay off here.
+- **Streaming 50K rows.** Turbine's optimized streaming (speculative first fetch + batch size 1000) matches Prisma at ~3.1–3.2 s. Drizzle's keyset pagination is 1.49× slower at 4.6 s. Turbine's cursor still gives you correctness on any `orderBy` and clean early-`break` semantics.
+- **Pipeline batching** puts 5 independent queries through a single round-trip using the Postgres extended-query pipeline protocol — all three ORMs are tied here since each runs 5 queries sequentially in a transaction.
 
-Turbine is fastest in every scenario. The advantage is largest on deep nesting (1.8x vs Prisma, up to 1.9x vs Drizzle) and single-record lookups (1.7x). All three ORMs now use single-query approaches for nested relations — Turbine's advantage comes from lower per-query overhead (minimal JS object allocation, no query plan compilation layer, direct pg driver access).
+Beyond the numbers, Turbine's real strengths are: **one runtime dependency** (`pg`, ~110 KB), a **single import swap** for edge runtimes (`turbine-orm/serverless`), **typed Postgres errors** with a `readonly isRetryable` const for retry loops, and **inferred `with` result types** — `users[0].posts[0].comments[0].author.name` autocompletes from a single `findMany` with no manual assertion.
 
+> Full analysis with p50/p95/p99 and methodology notes: [`benchmarks/RESULTS.md`](./benchmarks/RESULTS.md).
 > Reproduce: `cd benchmarks && npm install && npx prisma generate && DATABASE_URL=... npx tsx bench.ts`
 
 ## Quick Start
@@ -147,6 +148,30 @@ const deleted = await db.users.delete({
 });
 ```
 
+### Atomic update operators
+
+For race-free counter updates, pass an operator object instead of a literal. Turbine generates `col = col + $n` style SQL so concurrent updates are safe.
+
+```typescript
+// Atomic increment — no read-modify-write race
+await db.posts.update({
+  where: { id: 1 },
+  data: { viewCount: { increment: 1 } },
+});
+
+// Other supported operators on numeric columns
+await db.posts.update({
+  where: { id: 1 },
+  data: {
+    viewCount:  { increment: 5 },
+    likesCount: { decrement: 1 },
+    score:      { multiply: 2 },
+    rank:       { divide: 2 },
+    title:      { set: 'New title' }, // explicit set, equivalent to a literal
+  },
+});
+```
+
 ### Transactions
 
 ```typescript
@@ -199,7 +224,7 @@ const users = await db.users.findMany({
 // Stream rows using PostgreSQL cursors — constant memory, no matter how many rows
 for await (const user of db.users.findManyStream({
   where: { orgId: 1 },
-  batchSize: 500,       // internal FETCH batch size (default: 100)
+  batchSize: 500,       // internal FETCH batch size (default: 1000)
   orderBy: { id: 'asc' },
   with: { posts: true }, // nested relations work too
 })) {
@@ -271,7 +296,74 @@ try {
 }
 ```
 
-Error codes: `TURBINE_E001` (NotFound), `TURBINE_E002` (Timeout), `TURBINE_E003` (Validation), `TURBINE_E004` (Connection), `TURBINE_E005` (Relation), `TURBINE_E006` (Migration), `TURBINE_E007` (CircularRelation).
+Error codes: `TURBINE_E001` (NotFound), `TURBINE_E002` (Timeout), `TURBINE_E003` (Validation), `TURBINE_E004` (Connection), `TURBINE_E005` (Relation), `TURBINE_E006` (Migration), `TURBINE_E007` (CircularRelation), `TURBINE_E008` (UniqueConstraint), `TURBINE_E009` (ForeignKey), `TURBINE_E010` (NotNullViolation), `TURBINE_E011` (CheckConstraint), `TURBINE_E012` (Deadlock), `TURBINE_E013` (SerializationFailure), `TURBINE_E014` (Pipeline).
+
+## WHERE Operator Reference
+
+Every operator supported by the `where` clause. Operators compose freely with `AND`, `OR`, `NOT`, and the relation filters `some` / `every` / `none`.
+
+### Equality
+
+| Operator | Description | Example |
+|---|---|---|
+| literal | Implicit equality | `where: { email: 'a@b.com' }` |
+| `equals` | Explicit equality | `where: { email: { equals: 'a@b.com' } }` |
+| `not` | Inequality (or `not: null` for `IS NOT NULL`) | `where: { role: { not: 'admin' } }` |
+
+### Sets
+
+| Operator | Description | Example |
+|---|---|---|
+| `in` | Match any value in the array | `where: { id: { in: [1, 2, 3] } }` |
+| `notIn` | Match none of the values in the array | `where: { role: { notIn: ['banned', 'spam'] } }` |
+
+### Comparison
+
+| Operator | Description | Example |
+|---|---|---|
+| `gt` | Greater than | `where: { score: { gt: 100 } }` |
+| `gte` | Greater than or equal | `where: { score: { gte: 100 } }` |
+| `lt` | Less than | `where: { score: { lt: 100 } }` |
+| `lte` | Less than or equal | `where: { score: { lte: 100 } }` |
+
+### String
+
+| Operator | Description | Example |
+|---|---|---|
+| `contains` | Substring match (`LIKE %v%`) | `where: { title: { contains: 'sql' } }` |
+| `startsWith` | Prefix match (`LIKE v%`) | `where: { email: { startsWith: 'admin@' } }` |
+| `endsWith` | Suffix match (`LIKE %v`) | `where: { email: { endsWith: '@acme.com' } }` |
+| `mode: 'insensitive'` | Switch any string operator to `ILIKE` | `where: { title: { contains: 'SQL', mode: 'insensitive' } }` |
+
+LIKE wildcards in user input are escaped automatically — `%`, `_`, and `\` are treated as literals.
+
+### Relation filters
+
+Filter parent rows by predicates against their related child rows. Available on `hasMany` and `hasOne` relations.
+
+| Operator | Description | Example |
+|---|---|---|
+| `some` | At least one related row matches | `where: { posts: { some: { published: true } } }` |
+| `every` | Every related row matches | `where: { posts: { every: { published: true } } }` |
+| `none` | No related row matches | `where: { posts: { none: { published: false } } }` |
+
+### Array columns
+
+Operators for Postgres array columns (`text[]`, `int[]`, etc.).
+
+| Operator | Description | Example |
+|---|---|---|
+| `has` | Array contains the given element | `where: { tags: { has: 'sql' } }` |
+| `hasEvery` | Array contains every element in the list | `where: { tags: { hasEvery: ['sql', 'postgres'] } }` |
+| `hasSome` | Array contains at least one element from the list | `where: { tags: { hasSome: ['sql', 'mysql'] } }` |
+
+### Combinators
+
+| Operator | Description | Example |
+|---|---|---|
+| `AND` | All sub-clauses must match | `where: { AND: [{ orgId: 1 }, { role: 'admin' }] }` |
+| `OR` | Any sub-clause matches | `where: { OR: [{ role: 'admin' }, { role: 'owner' }] }` |
+| `NOT` | Negate a sub-clause | `where: { NOT: { role: 'banned' } }` |
 
 ## CLI
 
@@ -441,22 +533,9 @@ Priority order: CLI flags > environment variables (`DATABASE_URL`) > config file
 
 ## How It Works
 
-Turbine generates a single SQL query using Postgres `json_agg` + subqueries to fetch nested relations:
-
-```sql
--- db.users.findMany({ where: { orgId: 1 }, with: { posts: { with: { comments: true } } } })
-SELECT u.*,
-  (SELECT COALESCE(json_agg(sub), '[]'::json) FROM (
-    SELECT p.*,
-      (SELECT COALESCE(json_agg(sub2), '[]'::json) FROM (
-        SELECT c.* FROM comments c WHERE c.post_id = p.id
-      ) sub2) AS comments
-    FROM posts p WHERE p.user_id = u.id
-  ) sub) AS posts
-FROM users u WHERE u.org_id = 1
-```
+Turbine resolves the entire object graph in a single database round-trip, regardless of nesting depth. The `with` clause is fully type-inferred end-to-end — `users[0].posts[0].comments[0].author.name` autocompletes from a single `findMany` call, with no manual type assertions.
 
-This resolves the entire 3-level object graph in one database round-trip. Prisma 7+ and Drizzle v2 also use single-query approaches (LATERAL JOINs), but Turbine's correlated subquery strategy has lower per-query overhead — see [Benchmarks](#benchmarks).
+Prisma 7+ and Drizzle v2 also do single-query nested loads. Turbine's advantage isn't query latency (see [Benchmarks](#benchmarks) — all three are within noise over a real pooled database); it's architectural simplicity. One runtime dependency (`pg`), no DSL compiler, no driver adapter shim for edge, and deep `with` type inference without verbose helper types.
 
 ## Type Mapping
 
@@ -478,28 +557,43 @@ Turbine maps Postgres types to TypeScript:
 
 | | **Turbine** | **Prisma** | **Drizzle** | **Kysely** |
 |---|---|---|---|---|
-| **Nested relations** | 1 query (`json_agg`) | 1 query (LATERAL JOIN + json_agg, since v5.8) | 1 query (LATERAL JOINs) | Manual (`jsonArrayFrom`) |
+| **Nested relations** | 1 query, deep type inference | 1 query (since v5.8), shallow inference | 1 query, requires `relations()` re-declaration | Manual (`jsonArrayFrom`) |
 | **API style** | `findMany`, `with` | `findMany`, `include` | SQL-like + relational | SQL builder |
 | **Schema** | TypeScript | Custom DSL (`.prisma`) | TypeScript | Manual interfaces |
 | **Runtime deps** | 1 (`pg`) | `@prisma/client` + adapter | 0 | 0 |
 | **Multi-DB** | PostgreSQL only | PG, MySQL, SQLite, MSSQL | PG, MySQL, SQLite | PG, MySQL, SQLite |
 | **Code generation** | `turbine generate` | `prisma generate` | Not needed | Not needed |
 
-All three ORMs now use single-query approaches for nested relations. Turbine uses correlated subqueries with `json_agg`, Prisma 7 uses LATERAL JOIN + `json_agg`, and Drizzle uses LATERAL JOINs. Turbine is 1.4–1.9x faster due to lower per-query overhead — minimal JS object allocation, no query plan compilation layer, and direct pg driver access. See [Benchmarks](#benchmarks) for full results.
+All three ORMs now do single-query nested loads. Over a real pooled database (Neon, US-East) most single-query scenarios land within noise — but Turbine's SQL template caching and prepared statements give it a consistent edge, particularly on L2 nested reads (1.59× faster than Drizzle) and streaming (at parity with Prisma, 1.49× faster than Drizzle). Turbine's differentiators are both architectural and performance: one runtime dependency, one import swap for edge, typed errors with `isRetryable`, deep `with` type inference, and real Postgres pipeline protocol support. See [Benchmarks](#benchmarks) and [`benchmarks/RESULTS.md`](./benchmarks/RESULTS.md) for the full breakdown.
 
 ## Limitations
 
 Turbine is focused and opinionated. Here's what it doesn't do:
 
-- **PostgreSQL only.** No MySQL, SQLite, or MSSQL. This is by design — the `json_agg` approach is PostgreSQL-specific, and going deep on one database enables the performance advantage.
-- **No incremental updates.** Prisma's `{ count: { increment: 1 } }` syntax is not yet supported. Use raw SQL for atomic increments.
+- **PostgreSQL only.** No MySQL, SQLite, or MSSQL. By design — going deep on one database enables the performance advantage and the edge-runtime story.
 - **No full-text search operators.** TSVECTOR/TSQUERY are not exposed in the query builder. Use `db.raw` for full-text queries.
-- **Large nested result sets.** `json_agg` builds the entire JSON array in PostgreSQL memory. For relations with 10K+ rows, always use `limit` in your `with` clause to cap the aggregation size.
+- **Large nested result sets.** Nested results are materialized server-side in PostgreSQL memory. For relations with 10K+ rows, always use `limit` in your `with` clause — or stream the parents with `findManyStream` and resolve children per-row.
 - **No admin UI.** Turbine Studio is planned but not yet available.
 
 ## Examples
 
+**Feature demos**
+
+- **[Thread Machine](./examples/thread-machine/)** — HN clone rendered from a single `findMany`. 4-level object graph (stories → comments → replies → author), every property autocompletes through the chain
+- **[Streaming CSV](./examples/streaming-csv/)** — Export 100K orders + line items to CSV with constant memory. PostgreSQL cursors, live heap meter, nested `with` inside `findManyStream`
+- **[Clickstorm](./examples/clickstorm/)** — Side-by-side atomic-increment vs read-modify-write load test. 10K concurrent clicks. The atomic path wins every time
+
+**Runtime targets**
+
 - **[Next.js](./examples/nextjs/)** — Server-rendered app with nested relations, streaming, and live code demos
+- **[Neon Edge](./examples/neon-edge/)** — Vercel Edge route handler talking to Neon over HTTP via `@neondatabase/serverless`
+- **[Vercel Postgres](./examples/vercel-postgres/)** — Next.js app router route handler on `@vercel/postgres`
+- **[Cloudflare Worker](./examples/cloudflare-worker/)** — Worker `fetch` handler with `pg` over Cloudflare Hyperdrive
+- **[Supabase](./examples/supabase/)** — Standalone script over the standard `pg` driver against Supabase
+
+## Guides
+
+- **[Migrating from Prisma](./docs/migrate-from-prisma.md)** — API mapping table, side-by-side `findMany`, and notes on the differences
 
 ## Requirements
 

package/dist/cjs/cli/index.js

@@ -61,6 +61,7 @@ const generate_js_1 = require("../generate.js");
 const introspect_js_1 = require("../introspect.js");
 const schema_sql_js_1 = require("../schema-sql.js");
 const config_js_1 = require("./config.js");
+const loader_js_1 = require("./loader.js");
 const migrate_js_1 = require("./migrate.js");
 const ui_js_1 = require("./ui.js");
 function parseArgs() {
@@ -113,6 +114,9 @@ function parseArgs() {
             case '--auto':
                 result.auto = true;
                 break;
+            case '--allow-drift':
+                result.allowDrift = true;
+                break;
             case '--force':
             case '-f':
                 result.force = true;
@@ -135,6 +139,36 @@ function parseArgs() {
     return result;
 }
 // ---------------------------------------------------------------------------
+// TypeScript loader — user-facing error helper
+// ---------------------------------------------------------------------------
+/**
+ * Print a friendly error explaining how to install tsx, then exit.
+ * Called when we know we need to load a `.ts` file but the loader isn't available.
+ */
+function failMissingTsLoader(filePath, reason) {
+    (0, ui_js_1.newline)();
+    (0, ui_js_1.error)(`Cannot load TypeScript file: ${filePath}`);
+    (0, ui_js_1.newline)();
+    if (reason === 'unsupported') {
+        console.log(`  ${(0, ui_js_1.dim)('Your Node.js version does not support')} ${(0, ui_js_1.cyan)('module.register()')}.`);
+        console.log(`  ${(0, ui_js_1.dim)('Upgrade to Node.js')} ${(0, ui_js_1.cyan)('20.6+')} ${(0, ui_js_1.dim)('or use a')} ${(0, ui_js_1.cyan)('.js')} ${(0, ui_js_1.dim)('/')} ${(0, ui_js_1.cyan)('.mjs')} ${(0, ui_js_1.dim)('config file.')}`);
+    }
+    else {
+        console.log(`  ${(0, ui_js_1.dim)('Loading .ts config / schema files requires')} ${(0, ui_js_1.cyan)('tsx')} ${(0, ui_js_1.dim)('to be installed.')}`);
+        (0, ui_js_1.newline)();
+        console.log(`  ${(0, ui_js_1.dim)('Install it as a dev dependency:')}`);
+        console.log(`    ${(0, ui_js_1.cyan)('npm install --save-dev tsx')}`);
+        console.log(`    ${(0, ui_js_1.dim)('or')}`);
+        console.log(`    ${(0, ui_js_1.cyan)('pnpm add -D tsx')}`);
+        console.log(`    ${(0, ui_js_1.dim)('or')}`);
+        console.log(`    ${(0, ui_js_1.cyan)('yarn add -D tsx')}`);
+        (0, ui_js_1.newline)();
+        console.log(`  ${(0, ui_js_1.dim)('Alternatively, rename your file to')} ${(0, ui_js_1.cyan)('.js')} ${(0, ui_js_1.dim)('or')} ${(0, ui_js_1.cyan)('.mjs')}.`);
+    }
+    (0, ui_js_1.newline)();
+    process.exit(1);
+}
+// ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 function requireUrl(config) {
@@ -157,6 +191,15 @@ async function loadSchemaFile(schemaFile) {
         console.log(`  ${(0, ui_js_1.dim)('Create one with:')} ${(0, ui_js_1.cyan)('turbine init')}`);
         process.exit(1);
     }
+    // If this is a TypeScript file, ensure the tsx ESM loader is registered
+    // before we attempt the dynamic import. Without this, Node throws
+    // ERR_UNKNOWN_FILE_EXTENSION for `.ts`.
+    if ((0, loader_js_1.needsTsLoader)(absPath)) {
+        const status = await (0, loader_js_1.registerTsLoader)();
+        if (status === 'missing' || status === 'unsupported') {
+            failMissingTsLoader(schemaFile, status);
+        }
+    }
     try {
         const fileUrl = (0, node_url_1.pathToFileURL)(absPath).href;
         const mod = await Promise.resolve(`${fileUrl}`).then(s => __importStar(require(s)));
@@ -171,6 +214,11 @@ async function loadSchemaFile(schemaFile) {
         (0, ui_js_1.error)(`Failed to load schema file: ${schemaFile}`);
         if (err instanceof Error) {
             console.log(`  ${(0, ui_js_1.dim)(err.message)}`);
+            // If the error is the classic ERR_UNKNOWN_FILE_EXTENSION, give a hint.
+            if (err.message.includes('ERR_UNKNOWN_FILE_EXTENSION') || err.message.includes('Unknown file extension')) {
+                (0, ui_js_1.newline)();
+                console.log(`  ${(0, ui_js_1.dim)('Hint: install')} ${(0, ui_js_1.cyan)('tsx')} ${(0, ui_js_1.dim)('to load .ts files:')} ${(0, ui_js_1.cyan)('npm install --save-dev tsx')}`);
+            }
         }
         process.exit(1);
     }
@@ -521,9 +569,10 @@ async function cmdMigrate(args, config) {
         console.log(`    ${(0, ui_js_1.cyan)('status')}                Show migration status`);
         (0, ui_js_1.newline)();
         console.log(`  ${(0, ui_js_1.bold)('Options:')}`);
-        console.log(`    ${(0, ui_js_1.cyan)('--auto')}         Auto-generate UP/DOWN SQL from schema diff`);
-        console.log(`    ${(0, ui_js_1.cyan)('--step, -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)('--auto')}           Auto-generate UP/DOWN SQL from schema diff`);
+        console.log(`    ${(0, ui_js_1.cyan)('--step, -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 on ${(0, ui_js_1.cyan)('migrate up')} ${(0, ui_js_1.dim)('(advanced)')}`);
         (0, ui_js_1.newline)();
         console.log(`  ${(0, ui_js_1.bold)('Examples:')}`);
         console.log(`    ${(0, ui_js_1.dim)('npx turbine migrate create add_users_table')}`);
@@ -639,9 +688,18 @@ async function cmdMigrateUp(args, config) {
         (0, ui_js_1.newline)();
         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) {
+        (0, ui_js_1.warn)('--allow-drift is set — checksum validation is DISABLED for this run.');
+        console.log(`  ${(0, ui_js_1.dim)('Applied migrations may have been modified or deleted on disk.')}`);
+        console.log(`  ${(0, ui_js_1.dim)('Proceed only if you are intentionally rewriting migration history.')}`);
+        (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,
     });
     if (result.applied.length === 0 && result.errors.length === 0) {
         spinner.succeed('All migrations are up to date');
@@ -970,6 +1028,7 @@ function showMigrateHelp() {
     console.log(`    ${(0, ui_js_1.cyan)('--url, -u')} ${(0, ui_js_1.dim)('<url>')}   Postgres connection string`);
     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)('--verbose, -v')}      Show detailed output`);
     (0, ui_js_1.newline)();
     console.log(`  ${(0, ui_js_1.bold)('Examples:')}`);
@@ -1078,6 +1137,16 @@ async function main() {
         showVersion();
         return;
     }
+    // If the user has a TypeScript config file, register the tsx ESM loader
+    // before we attempt to import it. Otherwise Node throws
+    // ERR_UNKNOWN_FILE_EXTENSION for `.ts`.
+    const configPath = (0, config_js_1.findConfigFile)();
+    if ((0, loader_js_1.needsTsLoader)(configPath)) {
+        const status = await (0, loader_js_1.registerTsLoader)();
+        if (status === 'missing' || status === 'unsupported') {
+            failMissingTsLoader(configPath ?? 'turbine.config.ts', status);
+        }
+    }
     // Load config file
     let fileConfig = {};
     try {

package/dist/cjs/cli/loader.js

@@ -0,0 +1,129 @@
+"use strict";
+/**
+ * turbine-orm CLI — TypeScript loader registration
+ *
+ * The CLI loads user-supplied config and schema files via dynamic `import()`.
+ * Plain Node has no built-in `.ts` loader, so importing `turbine.config.ts`
+ * blows up with `ERR_UNKNOWN_FILE_EXTENSION` unless we register a TypeScript
+ * loader first.
+ *
+ * Strategy:
+ *   1. If the file we're about to import ends in `.ts` / `.mts` / `.cts`,
+ *      probe whether `tsx/esm` is resolvable from the user's CWD.
+ *   2. If yes, call `module.register('tsx/esm', ...)` ONCE per process.
+ *   3. If no, surface an actionable error telling the user to install `tsx`.
+ *
+ * `tsx` is intentionally NOT a runtime dependency — many projects already
+ * have it, and adding a heavy dev tool to a 1-dependency ORM would be silly.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.needsTsLoader = needsTsLoader;
+exports.canResolveTsx = canResolveTsx;
+exports.registerTsLoader = registerTsLoader;
+exports._resetTsLoaderStateForTests = _resetTsLoaderStateForTests;
+const node_module_1 = require("node:module");
+const node_url_1 = require("node:url");
+/**
+ * Detect whether a config / schema file path needs the tsx ESM loader.
+ * Returns true for `.ts`, `.mts`, and `.cts` files; false for `.js`, `.mjs`,
+ * `.cjs`, `.json`, missing paths, or anything else.
+ */
+function needsTsLoader(filePath) {
+    if (!filePath)
+        return false;
+    return /\.(ts|mts|cts)$/i.test(filePath);
+}
+/**
+ * Probe whether `tsx/esm` is resolvable from the user's current working
+ * directory. Returns true if `tsx` is installed in the user's project.
+ *
+ * Accepts an injected `resolver` so unit tests don't need a real filesystem.
+ */
+function canResolveTsx(resolver) {
+    try {
+        if (resolver) {
+            resolver('tsx/esm');
+            return true;
+        }
+        // Probe relative to the user's CWD, not Turbine's install location.
+        // This way we honour whatever `tsx` version the user has pinned.
+        const userRequire = (0, node_module_1.createRequire)(`${process.cwd()}/`);
+        userRequire.resolve('tsx/esm');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+let tsLoaderState = null;
+/**
+ * Register the tsx ESM loader so subsequent dynamic imports of `.ts` files
+ * work. Safe to call multiple times — internal flag prevents double registration.
+ *
+ * Returns:
+ *   - 'registered'  loader was successfully registered this call
+ *   - 'already'     a loader was previously registered (idempotent)
+ *   - 'unsupported' Node lacks `module.register()` (Node < 20.6)
+ *   - 'missing'     `tsx` is not installed in the user's project
+ */
+async function registerTsLoader() {
+    if (tsLoaderState === 'registered' || tsLoaderState === 'already') {
+        return 'already';
+    }
+    if (!canResolveTsx()) {
+        tsLoaderState = 'missing';
+        return 'missing';
+    }
+    try {
+        const mod = await Promise.resolve().then(() => __importStar(require('node:module')));
+        const register = mod.register;
+        if (typeof register !== 'function') {
+            tsLoaderState = 'unsupported';
+            return 'unsupported';
+        }
+        register('tsx/esm', (0, node_url_1.pathToFileURL)(`${process.cwd()}/`));
+        tsLoaderState = 'registered';
+        return 'registered';
+    }
+    catch {
+        tsLoaderState = 'missing';
+        return 'missing';
+    }
+}
+/** Reset the loader state — used by unit tests only. */
+function _resetTsLoaderStateForTests() {
+    tsLoaderState = null;
+}

package/dist/cjs/cli/migrate.js

@@ -276,12 +276,19 @@ async function validateChecksums(client, migrationsDir) {
  * Features:
  * - Idempotent: running twice is safe (already-applied migrations are skipped)
  * - Advisory lock: prevents concurrent migration runs
- * - Checksum validation: detects modified migration files
+ * - Checksum validation: detects modified migration files (BLOCKING — use
+ *   `allowDrift: true` to bypass when intentionally rewriting history)
  * - Each migration runs in its own transaction
+ *
+ * Throws `MigrationError` if any applied migration has been modified or deleted
+ * on disk, listing the offending files. Pass `{ allowDrift: true }` to bypass
+ * this check (the CLI exposes this as `--allow-drift`).
  */
 async function migrateUp(connectionString, migrationsDir, options) {
     const client = new pg_1.default.Client({ connectionString });
     await client.connect();
+    // Treat `force` as an alias for `allowDrift` for backwards compatibility.
+    const allowDrift = options?.allowDrift === true || options?.force === true;
     try {
         // Acquire advisory lock to prevent concurrent migrations
         const gotLock = await acquireLock(client);
@@ -290,18 +297,35 @@ async function migrateUp(connectionString, migrationsDir, options) {
         }
         try {
             await ensureTrackingTable(client);
-            // Validate checksums of already-applied migrations (skip with --force)
-            if (!options?.force) {
+            // Validate checksums of already-applied migrations.
+            // Drift = an APPLIED migration's on-disk file has changed (or been deleted)
+            // since it was run. Either situation means the database state and the
+            // migration history no longer agree, so we BLOCK the run by default.
+            // Users can pass `allowDrift: true` (CLI: `--allow-drift`) to force past
+            // the block when they are intentionally rewriting history.
+            if (!allowDrift) {
                 const mismatches = await validateChecksums(client, migrationsDir);
                 if (mismatches.length > 0) {
                     const modified = mismatches.filter((m) => m.type === 'modified');
                     const missing = mismatches.filter((m) => m.type === 'missing');
-                    const parts = [];
-                    if (modified.length > 0)
-                        parts.push(`modified: ${modified.map((m) => m.name).join(', ')}`);
-                    if (missing.length > 0)
-                        parts.push(`deleted: ${missing.map((m) => m.name).join(', ')}`);
-                    throw new errors_js_1.MigrationError(`[turbine] Migration integrity check failed — ${parts.join('; ')}. Applied migrations should be immutable. Use --force to skip this check.`);
+                    const lines = [
+                        '[turbine] Migration drift detected — refusing to apply pending migrations.',
+                        '',
+                        'Applied migrations should be immutable. The following files no longer match their applied state:',
+                        '',
+                    ];
+                    for (const m of modified) {
+                        lines.push(`  - ${m.name}.sql  (modified on disk)`);
+                    }
+                    for (const m of missing) {
+                        lines.push(`  - ${m.name}.sql  (deleted from disk)`);
+                    }
+                    lines.push('');
+                    lines.push('Fix one of these:');
+                    lines.push('  1. Restore the file(s) to their original content, OR');
+                    lines.push('  2. Roll back the affected migrations with `npx turbine migrate down`, OR');
+                    lines.push('  3. Pass `--allow-drift` to bypass this check (advanced — make sure you know what you are doing).');
+                    throw new errors_js_1.MigrationError(lines.join('\n'));
                 }
             }
             const applied = await getAppliedMigrations(client);