turbine-orm 0.7.1 → 0.9.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 built around features no other ORM bundles together: a **read-only, DBA-approvable Studio web UI** (the only one in the TS ORM ecosystem — `BEGIN READ ONLY` + statement-stacking guard + loopback-only + 24-byte auth token), **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:
 
-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).
+- **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.
 
+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 the **read-only Studio** web UI that ships in the CLI — the only one in the TS ORM ecosystem that physically cannot mutate your database. Deep type inference through `with` clauses is runtime-correct today (the relations are nested for you in a single round-trip) and lands at the type level in v1.0 — see the tracking issue for progress.
+
+> 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
@@ -223,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
 })) {
@@ -295,7 +296,7 @@ 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
 
@@ -380,6 +381,7 @@ Commands:
   migrate status               Show applied/pending migrations
   seed                         Run seed file
   status                       Show database schema summary
+  studio                       Launch local read-only Studio web UI
 
 Options:
   --url, -u <url>       Postgres connection string
@@ -435,6 +437,32 @@ npx turbine migrate down
 npx turbine migrate status
 ```
 
+## 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, no way around the transaction guard.
+
+```bash
+DATABASE_URL=postgres://user:pass@localhost:5432/mydb npx turbine studio
+# With flags
+npx turbine studio --port 5173 --host 127.0.0.1 --no-open
+```
+
+**Features**
+
+- **Data / Schema / SQL / Builder tabs.** Browse rows, inspect tables and relations, run ad-hoc `SELECT`s, or compose queries visually with a live TypeScript preview.
+- **Saved queries.** Named SQL snippets persisted to `.turbine/studio-queries.json` — share them across runs without committing them.
+- **Cmd+K command palette.** Jump to any table, tab, or saved query in one keystroke.
+- **Full-text search across rows.** The Data tab supports substring search across every text column of the current table.
+- **Visual query composer.** The Builder tab lets you click together `where` / `orderBy` / `with` / `limit` clauses and renders the matching `db.table.findMany(...)` TypeScript in real time — copy it into your codebase.
+
+**Security posture (read-only by design)**
+
+- **Loopback by default** (`127.0.0.1`) with a loud warning if you bind to a non-loopback address.
+- **Per-process auth token** — 24 random bytes of hex, stored in a `SameSite=Strict` `HttpOnly` cookie.
+- **Every query runs inside `BEGIN READ ONLY` + `SET LOCAL statement_timeout = '30s'`.** Writes are physically impossible at the transaction level.
+- **SELECT/WITH-only SQL parser** strips comments and rejects non-trailing semicolons, blocking statement-stacking attacks.
+- **Security headers on every response** — `X-Content-Type-Options`, `X-Frame-Options: DENY`, `Referrer-Policy: no-referrer`.
+
 ## Serverless / Edge
 
 Turbine's core is driver-agnostic: pass any pg-compatible pool to `TurbineConfig.pool` (or use the `turbineHttp()` factory) and Turbine runs on **Vercel Edge**, **Cloudflare Workers**, **Deno Deploy**, **Netlify Edge**, or any other environment where a direct TCP connection is unavailable. No new dependencies — install whichever driver you already use.
@@ -532,22 +560,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 runtime nests relations for you via `json_agg` — one round-trip, no N+1, no client-side stitching. Deep `with` type inference at the TypeScript level (so `users[0].posts[0].comments[0].author.name` autocompletes without a manual assertion) is the last piece landing in v1.0; today, the generated `*With*` helper interfaces let you annotate the return type when you need the nested shape to narrow.
 
-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 plus the read-only Studio. One runtime dependency (`pg`), no DSL compiler, no driver adapter shim for edge, and the only TS ORM Studio your DBA will approve.
 
 ## Type Mapping
 
@@ -569,26 +584,33 @@ 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.
+- **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.
-- **No admin UI.** Turbine Studio is planned but not yet available.
+- **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.
 
 ## 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`

package/dist/cjs/cli/index.js

@@ -13,7 +13,7 @@
  *   turbine migrate status        — Show migration status
  *   turbine seed                  — Run seed file
  *   turbine status                — Show schema summary
- *   turbine studio                — Launch web UI (coming soon)
+ *   turbine studio                — Launch local read-only web UI
  *
  * Usage:
  *   DATABASE_URL=postgres://... npx turbine generate
@@ -63,6 +63,7 @@ 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 studio_js_1 = require("./studio.js");
 const ui_js_1 = require("./ui.js");
 function parseArgs() {
     const args = process.argv.slice(2);
@@ -129,6 +130,17 @@ function parseArgs() {
             case '-h':
                 result.help = true;
                 break;
+            case '--port':
+                result.port = next ? Number.parseInt(next, 10) : undefined;
+                i++;
+                break;
+            case '--host':
+                result.host = next;
+                i++;
+                break;
+            case '--no-open':
+                result.noOpen = true;
+                break;
             default:
                 if (!arg.startsWith('-')) {
                     result.positional.push(arg);
@@ -925,19 +937,71 @@ async function cmdStatus(_args, config) {
     }
 }
 // ---------------------------------------------------------------------------
-// Command: studio (scaffold)
+// Command: studio — local read-only web UI
 // ---------------------------------------------------------------------------
-async function cmdStudio(_args, _config) {
+async function cmdStudio(args, config) {
     (0, ui_js_1.banner)();
+    const url = requireUrl(config);
+    const port = args.port ?? 4983;
+    const host = args.host ?? '127.0.0.1';
+    const openBrowser = !args.noOpen;
+    if (!Number.isFinite(port) || port <= 0 || port > 65535) {
+        console.log((0, ui_js_1.red)(`✗ invalid port: ${args.port}`));
+        process.exit(1);
+    }
+    // Refuse to bind anything other than loopback unless explicitly overridden.
+    // This is deliberate: Studio has no real authentication beyond a random
+    // session token, so exposing it on a LAN interface is foot-gun territory.
+    if (host !== '127.0.0.1' && host !== 'localhost' && host !== '::1') {
+        console.log((0, ui_js_1.warn)(`Studio is binding to ${(0, ui_js_1.yellow)(host)} — this is NOT loopback. ` +
+            `Anyone on your network who can reach this port + guess the session token can read your database.`));
+    }
+    const spinner = new ui_js_1.Spinner('Introspecting database').start();
+    let studio;
+    try {
+        studio = await (0, studio_js_1.startStudio)({
+            url,
+            schema: config.schema,
+            port,
+            host,
+            openBrowser,
+            include: config.include.length ? config.include : undefined,
+            exclude: config.exclude.length ? config.exclude : undefined,
+        });
+        spinner.succeed(`Studio is running`);
+    }
+    catch (err) {
+        spinner.fail(`Failed to start Studio: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    (0, ui_js_1.newline)();
     console.log((0, ui_js_1.box)([
-        `${(0, ui_js_1.bold)('Turbine Studio')} ${(0, ui_js_1.dim)('— coming soon')}`,
+        `${(0, ui_js_1.bold)('Turbine Studio')}  ${(0, ui_js_1.dim)('— local read-only UI')}`,
         '',
-        'A local web UI for browsing your database,',
-        'exploring relations, and managing data.',
+        `  ${(0, ui_js_1.cyan)('URL:')}    ${(0, ui_js_1.bold)(studio.url)}`,
+        `  ${(0, ui_js_1.cyan)('Schema:')} ${config.schema}`,
+        `  ${(0, ui_js_1.cyan)('DB:')}     ${(0, ui_js_1.redactUrl)(url)}`,
         '',
-        `Follow ${(0, ui_js_1.cyan)('@turbineorm')} for updates.`,
-    ].join('\n'), { title: (0, ui_js_1.bold)((0, ui_js_1.cyan)('Studio')), padding: 2 }));
+        (0, ui_js_1.dim)('Open the URL above in your browser. It includes a one-time session'),
+        (0, ui_js_1.dim)('token that gets set as an HttpOnly cookie on first load.'),
+        (0, ui_js_1.dim)('Press Ctrl+C to stop.'),
+    ].join('\n'), { title: (0, ui_js_1.bold)((0, ui_js_1.cyan)('Studio')), padding: 1 }));
     (0, ui_js_1.newline)();
+    // Wait forever until SIGINT/SIGTERM, then dispose cleanly.
+    await new Promise((resolve) => {
+        const shutdown = async () => {
+            console.log((0, ui_js_1.dim)('\n  shutting down…'));
+            try {
+                await studio.dispose();
+            }
+            catch {
+                /* ignore */
+            }
+            resolve();
+        };
+        process.once('SIGINT', shutdown);
+        process.once('SIGTERM', shutdown);
+    });
 }
 // ---------------------------------------------------------------------------
 // Subcommand help
@@ -1086,7 +1150,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)('studio')}             Launch web UI (coming soon)`);
+    console.log(`    ${(0, ui_js_1.cyan)('studio')}             Launch local read-only web UI`);
     (0, ui_js_1.newline)();
     console.log(`  ${(0, ui_js_1.bold)('Options:')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--url, -u')} ${(0, ui_js_1.dim)('<url>')}      Postgres connection string`);
@@ -1098,6 +1162,11 @@ function showHelp() {
     console.log(`    ${(0, ui_js_1.cyan)('--verbose, -v')}        Show detailed output`);
     console.log(`    ${(0, ui_js_1.cyan)('--force, -f')}          Overwrite existing files`);
     (0, ui_js_1.newline)();
+    console.log(`  ${(0, ui_js_1.bold)('Studio options:')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--port')} ${(0, ui_js_1.dim)('<n>')}           HTTP port ${(0, ui_js_1.dim)('(default: 4983)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--host')} ${(0, ui_js_1.dim)('<addr>')}        Bind address ${(0, ui_js_1.dim)('(default: 127.0.0.1)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--no-open')}            Don't auto-open the browser`);
+    (0, ui_js_1.newline)();
     console.log(`  ${(0, ui_js_1.bold)('Config file:')}`);
     console.log(`    ${(0, ui_js_1.dim)('Create')} ${(0, ui_js_1.cyan)('turbine.config.ts')} ${(0, ui_js_1.dim)('with')} ${(0, ui_js_1.cyan)('npx turbine init')}`);
     console.log(`    ${(0, ui_js_1.dim)('CLI flags override config file values.')}`);
@@ -1114,7 +1183,30 @@ function showHelp() {
 // Version
 // ---------------------------------------------------------------------------
 function showVersion() {
-    console.log(`turbine-orm v0.5.0`);
+    // Walk up from the running script to find the turbine-orm package.json.
+    // Using process.argv[1] instead of import.meta.url so the same code compiles
+    // cleanly for both the ESM and CJS builds.
+    try {
+        let dir = (0, node_path_1.dirname)(process.argv[1] ?? '');
+        for (let i = 0; i < 6; i++) {
+            const candidate = (0, node_path_1.resolve)(dir, 'package.json');
+            if ((0, node_fs_1.existsSync)(candidate)) {
+                const pkg = JSON.parse((0, node_fs_1.readFileSync)(candidate, 'utf8'));
+                if (pkg.name === 'turbine-orm') {
+                    console.log(`turbine-orm v${pkg.version ?? '?'}`);
+                    return;
+                }
+            }
+            const parent = (0, node_path_1.dirname)(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+        console.log(`turbine-orm`);
+    }
+    catch {
+        console.log(`turbine-orm`);
+    }
 }
 // ---------------------------------------------------------------------------
 // Main

package/dist/cjs/cli/migrate.js

@@ -24,6 +24,7 @@ exports.listMigrationFiles = listMigrationFiles;
 exports.parseMigrationContent = parseMigrationContent;
 exports.parseMigrationSQL = parseMigrationSQL;
 exports.createMigration = createMigration;
+exports.deriveLockId = deriveLockId;
 exports.migrateUp = migrateUp;
 exports.migrateDown = migrateDown;
 exports.migrateStatus = migrateStatus;
@@ -218,16 +219,44 @@ ${autoContent.down}
 // ---------------------------------------------------------------------------
 // Advisory lock for concurrent migration safety
 // ---------------------------------------------------------------------------
-/** Fixed lock ID for Turbine migrations — prevents concurrent migrate runs */
-const MIGRATION_LOCK_ID = 8_347_291; // arbitrary but stable
-async function acquireLock(client) {
-    const result = await client.query(`SELECT pg_try_advisory_lock($1)`, [
-        MIGRATION_LOCK_ID,
-    ]);
-    return result.rows[0]?.pg_try_advisory_lock ?? false;
+/**
+ * Derive a Postgres advisory lock ID (positive int4) from the database name.
+ *
+ * Uses FNV-1a 32-bit hash — a well-known, stable, non-cryptographic hash with
+ * excellent distribution over short strings (database names are typically <64
+ * chars). Chosen over alternatives because it's:
+ *   - deterministic (same input → same output, across processes/machines)
+ *   - tiny (two lines, no allocations, no imports)
+ *   - well-distributed (low collision rate for typical DB-name distributions)
+ *
+ * The top bit is cleared so the result fits in a positive int4, which is the
+ * range `pg_advisory_lock` expects for the single-argument form. Two databases
+ * in the same Postgres cluster can now run `turbine migrate` concurrently
+ * without contending on a single hardcoded lock ID.
+ */
+function deriveLockId(databaseName) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < databaseName.length; i++) {
+        hash ^= databaseName.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return hash >>> 1; // positive int4 (top bit cleared)
+}
+/**
+ * Fetch the current database name from the connected client. Used to derive
+ * the advisory lock ID so concurrent migrations in sibling databases do not
+ * contend on one another.
+ */
+async function getCurrentDatabaseName(client) {
+    const result = await client.query(`SELECT current_database()`);
+    return result.rows[0]?.current_database ?? '';
+}
+async function acquireLock(client, lockId) {
+    const result = await client.query(`SELECT pg_try_advisory_lock($1) AS locked`, [lockId]);
+    return result.rows[0]?.locked ?? false;
 }
-async function releaseLock(client) {
-    await client.query(`SELECT pg_advisory_unlock($1)`, [MIGRATION_LOCK_ID]);
+async function releaseLock(client, lockId) {
+    await client.query(`SELECT pg_advisory_unlock($1)`, [lockId]);
 }
 /**
  * Validate that applied migration files have not been modified or deleted since they were run.
@@ -290,8 +319,12 @@ async function migrateUp(connectionString, migrationsDir, options) {
     // Treat `force` as an alias for `allowDrift` for backwards compatibility.
     const allowDrift = options?.allowDrift === true || options?.force === true;
     try {
+        // Derive an advisory lock ID per-database so concurrent migrations in
+        // sibling databases on the same Postgres cluster do not contend.
+        const dbName = await getCurrentDatabaseName(client);
+        const lockId = deriveLockId(dbName);
         // Acquire advisory lock to prevent concurrent migrations
-        const gotLock = await acquireLock(client);
+        const gotLock = await acquireLock(client, lockId);
         if (!gotLock) {
             throw new errors_js_1.MigrationError('[turbine] Could not acquire migration lock — another migration is already running');
         }
@@ -363,7 +396,7 @@ async function migrateUp(connectionString, migrationsDir, options) {
             return { applied: results, errors };
         }
         finally {
-            await releaseLock(client);
+            await releaseLock(client, lockId);
         }
     }
     finally {
@@ -382,7 +415,11 @@ async function migrateDown(connectionString, migrationsDir, options) {
     const client = new pg_1.default.Client({ connectionString });
     await client.connect();
     try {
-        const gotLock = await acquireLock(client);
+        // Derive a per-database advisory lock ID so concurrent migrations in
+        // sibling databases on the same cluster do not contend.
+        const dbName = await getCurrentDatabaseName(client);
+        const lockId = deriveLockId(dbName);
+        const gotLock = await acquireLock(client, lockId);
         if (!gotLock) {
             throw new errors_js_1.MigrationError('[turbine] Could not acquire migration lock — another migration is already running');
         }
@@ -429,7 +466,7 @@ async function migrateDown(connectionString, migrationsDir, options) {
             return { rolledBack: results, errors };
         }
         finally {
-            await releaseLock(client);
+            await releaseLock(client, lockId);
         }
     }
     finally {