turbine-orm 0.9.2 → 0.11.0

package/README.md

@@ -1,21 +1,25 @@
 # turbine-orm
 
-Postgres ORM built for the edge. One runtime dependency. Built-in read-only Studio. Code-first and DB-first schema workflows in the same CLI. Runs on **Neon, Vercel Postgres, Cloudflare Hyperdrive, Supabase**, and any pg-compatible driver.
+110 KB. One runtime dependency. The Postgres ORM that ships light and locks tight.
 
 ```
 npm install turbine-orm
 ```
 
+**Full docs: [turbineorm.dev](https://turbineorm.dev)** — [Quick Start](https://turbineorm.dev/quickstart) · [API Reference](https://turbineorm.dev/queries) · [Relations](https://turbineorm.dev/relations) · [Transactions & Pipelines](https://turbineorm.dev/transactions) · [Serverless & Edge](https://turbineorm.dev/serverless) · [Typed Errors](https://turbineorm.dev/errors) · [Benchmarks](https://turbineorm.dev/benchmarks)
+
 ## Why Turbine?
 
-The elevator pitch: **a Prisma-like DX without Prisma's engine, a Drizzle-class runtime footprint, and the only built-in read-only Studio in the TS ORM ecosystem.** Four things bundled together that no other ORM bundles:
+Prisma ships a 1.6 MB WASM engine. Drizzle ships zero runtime but no Studio, no typed errors, no migration checksums. Turbine ships **one dependency (`pg`), ~110 KB**, and bundles six things no other TS ORM has together:
 
-1. **One runtime dependency (`pg`).** No engine binary, no WASM adapter, no code-generation DSL. ~110 KB on npm. 5 KB on the edge entry.
-2. **First-class edge support.** `turbineHttp(pool, schema)` — one import swap — and the full API runs on Neon, Vercel Postgres, Cloudflare Hyperdrive, Supabase. No extra adapter package, no WASM bundle.
-3. **Built-in read-only Studio.** `npx turbine studio` spins up a loopback-bound, token-authed web UI with `BEGIN READ ONLY` + statement-stacking guard. DBA-approvable. No separate install.
-4. **Code-first and DB-first in the same CLI.** `defineSchema()` in TypeScript *or* `npx turbine pull` against a live database — same generated client, same migrations runner. Prisma forces the DSL; Drizzle is code-only.
+1. **One runtime dependency (`pg`).** No engine binary, no WASM adapter, no adapter packages to keep in lockstep. ~110 KB on npm. 5 KB on the edge entry. Prisma's WASM engine alone is 1.6 MB.
+2. **Built-in read-only Studio.** `npx turbine studio` spins up a loopback-bound web UI with 192-bit auth tokens, `BEGIN READ ONLY` transactions, and a statement-stacking guard. The only TS ORM Studio that physically cannot mutate your database. DBA-approvable.
+3. **PII-safe error messages.** Turbine errors show WHERE keys, not values. A `UniqueConstraintError` says which column violated the constraint — never the actual user data. Safe to log, safe to surface to monitoring, no scrubbing needed.
+4. **SQL-first migrations with drift detection.** Write real SQL. SHA-256 checksums catch modified migration files. `pg_try_advisory_lock()` prevents concurrent runs. Each migration in its own transaction. No shadow database, no magic DSL.
+5. **Edge-native — one import swap.** `turbineHttp(pool, schema)` — same API on Neon, Vercel Postgres, Cloudflare Hyperdrive, Supabase. No WASM bundle, no adapter package, no separate serverless build.
+6. **Pipeline batching via wire protocol.** Real Parse/Bind/Execute pipeline — not queries wrapped in a transaction. N independent queries in one round-trip.
 
-Plus the architectural bits you'd expect: pipeline batching (N queries in one round-trip via the pg extended-query protocol), `json_agg`-based nested relation loading (same technique Drizzle and Prisma 7 use — no N+1), deep `with` type inference, streaming cursors, typed error hierarchy with `isRetryable` discriminants, middleware.
+Every ORM claims single-query nested loads now (Prisma 7 and Drizzle v2 both use json_agg). Turbine does too — see [How It Works](#how-it-works). The differentiator isn't the query strategy; it's the 110 KB footprint, the read-only Studio, and the error messages that never leak user data.
 
 ## Benchmarks
 
@@ -39,7 +43,7 @@ Tested against **Prisma 7.6** (adapter-pg, relationJoins preview on) and **Drizz
 - **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. And deep type inference through `with` clauses works end-to-end: write `db.users.findMany({ with: { posts: { with: { comments: true } } } })` and `users[0].posts[0].comments[0].body` autocompletes — no manual assertion, no `*With*` helper interfaces.
+Performance is at parity with Prisma and Drizzle — the real reasons to choose Turbine are elsewhere: **110 KB install** (vs Prisma's 1.6 MB WASM), the **only read-only Studio** in the TS ORM ecosystem, **PII-safe error messages** that never leak user data, and **SQL-first migrations** with SHA-256 drift detection. Deep type inference through `with` clauses works end-to-end: write `db.users.findMany({ with: { posts: { with: { comments: true } } } })` and `users[0].posts[0].comments[0].body` autocompletes — no manual assertion, no helper annotation.
 
 > 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`
@@ -303,6 +307,8 @@ try {
 
 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).
 
+Full reference with `wrapPgError()` translation, retry patterns for `DeadlockError` / `SerializationFailureError`, and safe vs verbose message modes: **[turbineorm.dev/errors](https://turbineorm.dev/errors)**.
+
 ## WHERE Operator Reference
 
 Every operator supported by the `where` clause. Operators compose freely with `AND`, `OR`, `NOT`, and the relation filters `some` / `every` / `none`.
@@ -565,9 +571,9 @@ Priority order: CLI flags > environment variables (`DATABASE_URL`) > config file
 
 ## How It Works
 
-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. And the `with` clause is fully type-inferred: the generator emits branded `*Relations` interfaces with `RelationDescriptor` phantom fields, and a recursive `WithResult<T, R, W>` conditional type walks an arbitrarily-deep `with` literal to produce the exact nested return shape. Write `db.users.findMany({ with: { posts: { with: { comments: { with: { author: true } } } } } })` and `users[0].posts[0].comments[0].author.name` autocompletes — no manual assertion, no `*With*` helper annotation.
+Turbine resolves nested relations the same way Prisma 7 and Drizzle v2 do: correlated subqueries with `json_agg` + `json_build_object`, evaluated by PostgreSQL in a single round-trip. No N+1, no client-side stitching, no separate queries per relation. The `with` clause is fully type-inferred end-to-end — write `db.users.findMany({ with: { posts: { with: { comments: { with: { author: true } } } } } })` and `users[0].posts[0].comments[0].author.name` autocompletes with zero manual annotation.
 
-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.
+The query strategy is table stakes now. What isn't table stakes: the 110 KB footprint that makes it possible, the read-only Studio your DBA will approve, the error messages that never leak PII, and the SQL-first migrations with SHA-256 drift detection. See [Why Turbine?](#why-turbine) for the full breakdown.
 
 ## Type Mapping
 
@@ -589,14 +595,18 @@ Turbine maps Postgres types to TypeScript:
 
 | | **Turbine** | **Prisma** | **Drizzle** | **Kysely** |
 |---|---|---|---|---|
-| **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 |
+| **Install size** | ~110 KB (`pg` only) | ~1.6 MB (WASM engine) | ~0 KB (no runtime) | ~0 KB (no runtime) |
 | **Runtime deps** | 1 (`pg`) | `@prisma/client` + adapter | 0 | 0 |
+| **Studio** | Read-only, 192-bit auth | Full CRUD, cloud-hosted | Paid tier | 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, 5 KB | 1.6 MB WASM adapter | 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`) |
 | **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 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.
+All three ORMs now do single-query nested loads — that's table stakes. Turbine's real differentiators: the smallest install of any full-featured ORM (110 KB vs Prisma's 1.6 MB), the only read-only Studio in the ecosystem, error messages that never leak PII, and SQL-first migrations with SHA-256 drift detection. See [Benchmarks](#benchmarks) for performance numbers — most scenarios are within noise over a real pooled database.
 
 ## Limitations
 
@@ -624,7 +634,15 @@ Turbine is focused and opinionated. Here's what it doesn't do:
 
 ## Guides
 
-- **[Migrating from Prisma](./docs/migrate-from-prisma.md)** — API mapping table, side-by-side `findMany`, and notes on the differences
+- **[Quick Start](https://turbineorm.dev/quickstart)** — zero-to-first-query in five minutes
+- **[API Reference](https://turbineorm.dev/queries)** — every `findMany` / `findUnique` / `create` / `update` / `delete` option, the full operator table, and `pipeline()` semantics
+- **[Relations](https://turbineorm.dev/relations)** — deep `with` clause, nested options, relation filters (`some` / `every` / `none`), payload-size guidance
+- **[Transactions & Pipelines](https://turbineorm.dev/transactions)** — isolation levels, nested SAVEPOINTs, retry loops for `DeadlockError` and `SerializationFailureError`
+- **[Schema & Migrations](https://turbineorm.dev/schema)** — `defineSchema()`, auto-diff migrations, checksum validation
+- **[Serverless & Edge](https://turbineorm.dev/serverless)** — Neon, Vercel Postgres, Cloudflare Hyperdrive, Supabase walkthroughs
+- **[CLI](https://turbineorm.dev/cli)** — every command, flag, and config option
+- **[Typed Errors](https://turbineorm.dev/errors)** — error code reference, `wrapPgError()` translation, retry patterns
+- **[Migrating from Prisma](https://turbineorm.dev/migrate-from-prisma)** — API mapping table, side-by-side `findMany`, and notes on the differences
 
 ## Requirements
 

package/dist/adapters/cockroachdb.d.ts

@@ -0,0 +1,40 @@
+/**
+ * turbine-orm — CockroachDB adapter
+ *
+ * CockroachDB speaks the PostgreSQL wire protocol but has key differences:
+ *
+ * 1. **No advisory locks** — `pg_try_advisory_lock()` is not supported.
+ *    This adapter uses a `_turbine_lock` table with `SELECT FOR UPDATE NOWAIT`
+ *    as a concurrency mechanism for migrations.
+ *
+ * 2. **No `SET LOCAL statement_timeout`** — CockroachDB uses
+ *    `SET transaction_timeout` (v23.1+) for per-transaction time limits.
+ *
+ * 3. **`pg_indexes` view** — CockroachDB supports `pg_indexes` since v22.1
+ *    but the `indexdef` column may not match Postgres exactly. We use
+ *    `SHOW INDEXES` as a more reliable alternative.
+ *
+ * 4. **`pg_class.reltuples`** — Not reliable in CockroachDB. We use
+ *    `crdb_internal.table_row_statistics` for row estimates.
+ *
+ * Known limitations with Turbine on CockroachDB:
+ * - `json_agg` works but NULL ordering within aggregates may differ
+ * - `SERIAL` columns use `unique_rowid()` instead of sequences
+ * - Schema introspection via information_schema works for tables, columns,
+ *   constraints; pg_catalog has gaps for some metadata
+ * - Pipeline batching works (extended query protocol is supported)
+ *
+ * @example
+ * ```ts
+ * import { cockroachdb } from 'turbine-orm/adapters';
+ *
+ * // In turbine.config.ts:
+ * export default {
+ *   url: process.env.DATABASE_URL,
+ *   adapter: cockroachdb,
+ * };
+ * ```
+ */
+import type { DatabaseAdapter } from './index.js';
+export declare const cockroachdb: DatabaseAdapter;
+//# sourceMappingURL=cockroachdb.d.ts.map

package/dist/adapters/cockroachdb.js

@@ -0,0 +1,172 @@
+/**
+ * turbine-orm — CockroachDB adapter
+ *
+ * CockroachDB speaks the PostgreSQL wire protocol but has key differences:
+ *
+ * 1. **No advisory locks** — `pg_try_advisory_lock()` is not supported.
+ *    This adapter uses a `_turbine_lock` table with `SELECT FOR UPDATE NOWAIT`
+ *    as a concurrency mechanism for migrations.
+ *
+ * 2. **No `SET LOCAL statement_timeout`** — CockroachDB uses
+ *    `SET transaction_timeout` (v23.1+) for per-transaction time limits.
+ *
+ * 3. **`pg_indexes` view** — CockroachDB supports `pg_indexes` since v22.1
+ *    but the `indexdef` column may not match Postgres exactly. We use
+ *    `SHOW INDEXES` as a more reliable alternative.
+ *
+ * 4. **`pg_class.reltuples`** — Not reliable in CockroachDB. We use
+ *    `crdb_internal.table_row_statistics` for row estimates.
+ *
+ * Known limitations with Turbine on CockroachDB:
+ * - `json_agg` works but NULL ordering within aggregates may differ
+ * - `SERIAL` columns use `unique_rowid()` instead of sequences
+ * - Schema introspection via information_schema works for tables, columns,
+ *   constraints; pg_catalog has gaps for some metadata
+ * - Pipeline batching works (extended query protocol is supported)
+ *
+ * @example
+ * ```ts
+ * import { cockroachdb } from 'turbine-orm/adapters';
+ *
+ * // In turbine.config.ts:
+ * export default {
+ *   url: process.env.DATABASE_URL,
+ *   adapter: cockroachdb,
+ * };
+ * ```
+ */
+// ---------------------------------------------------------------------------
+// Lock table SQL
+// ---------------------------------------------------------------------------
+const LOCK_TABLE = '_turbine_lock';
+/**
+ * DDL for the table-based lock mechanism. The table holds a single row per
+ * lock ID. `SELECT ... FOR UPDATE NOWAIT` on this row serves as a mutex.
+ */
+const CREATE_LOCK_TABLE_SQL = `
+  CREATE TABLE IF NOT EXISTS "${LOCK_TABLE}" (
+    lock_id INT PRIMARY KEY,
+    acquired_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    acquired_by TEXT
+  )
+`;
+// ---------------------------------------------------------------------------
+// Introspection query overrides
+// ---------------------------------------------------------------------------
+/**
+ * CockroachDB index introspection via SHOW INDEXES.
+ * This returns a different shape than pg_indexes, so the consumer
+ * needs to handle the transformation. However, since we're providing this
+ * as a drop-in SQL string for the existing introspection flow, we use
+ * CockroachDB's pg_indexes compatibility view but with a fallback query
+ * that produces the same columns.
+ *
+ * CockroachDB's pg_indexes is compatible since v22.1 — we keep this
+ * override for older versions or when indexdef is incomplete.
+ */
+const SQL_INDEXES_CRDB = `
+  SELECT
+    tablename,
+    indexname,
+    indexdef
+  FROM pg_indexes
+  WHERE schemaname = $1
+`;
+/**
+ * Row estimates using crdb_internal. Falls back gracefully if the view
+ * doesn't exist (permissions issue) — returns 0 rows in that case.
+ */
+const SQL_ROW_ESTIMATES_CRDB = `
+  SELECT
+    t.name AS relname,
+    COALESCE(s.estimated_row_count, 0)::text AS reltuples
+  FROM crdb_internal.tables t
+  LEFT JOIN crdb_internal.table_row_statistics s
+    ON s.table_id = t.table_id
+  WHERE t.schema_name = $1
+    AND t.database_name = current_database()
+`;
+/**
+ * Enum introspection — CockroachDB supports pg_type/pg_enum since v20.2.
+ * The standard query works, but we include it explicitly so the override
+ * mechanism is complete.
+ */
+const SQL_ENUMS_CRDB = `
+  SELECT t.typname, e.enumlabel
+  FROM pg_type t
+  JOIN pg_enum e ON t.oid = e.enumtypid
+  JOIN pg_catalog.pg_namespace n ON n.oid = t.typnamespace
+  WHERE n.nspname = $1
+  ORDER BY t.typname, e.enumsortorder
+`;
+// ---------------------------------------------------------------------------
+// Adapter implementation
+// ---------------------------------------------------------------------------
+export const cockroachdb = {
+    name: 'cockroachdb',
+    createLockTableSQL() {
+        return CREATE_LOCK_TABLE_SQL;
+    },
+    async acquireLock(client, lockId) {
+        // Ensure the lock table exists
+        await client.query(CREATE_LOCK_TABLE_SQL);
+        // Insert the lock row if it doesn't exist (idempotent)
+        await client.query(`INSERT INTO "${LOCK_TABLE}" (lock_id) VALUES ($1) ON CONFLICT (lock_id) DO NOTHING`, [lockId]);
+        // Try to acquire the row lock with NOWAIT — fails immediately if held
+        try {
+            await client.query('BEGIN');
+            await client.query(`SELECT lock_id FROM "${LOCK_TABLE}" WHERE lock_id = $1 FOR UPDATE NOWAIT`, [lockId]);
+            // Update the acquired metadata
+            await client.query(`UPDATE "${LOCK_TABLE}" SET acquired_at = now(), acquired_by = current_user WHERE lock_id = $1`, [lockId]);
+            // Note: we leave the transaction OPEN — the lock is held until
+            // releaseLock() commits or rolls back.
+            return true;
+        }
+        catch (err) {
+            // NOWAIT throws error code 55P03 (lock_not_available) if the row is locked
+            const pgErr = err;
+            if (pgErr.code === '55P03') {
+                try {
+                    await client.query('ROLLBACK');
+                }
+                catch {
+                    /* ignore rollback errors */
+                }
+                return false;
+            }
+            // Any other error — rollback and re-throw
+            try {
+                await client.query('ROLLBACK');
+            }
+            catch {
+                /* ignore */
+            }
+            throw err;
+        }
+    },
+    async releaseLock(client, _lockId) {
+        // Commit the transaction opened in acquireLock to release the FOR UPDATE lock
+        try {
+            await client.query('COMMIT');
+        }
+        catch {
+            // If commit fails, try rollback (either way, lock is released)
+            try {
+                await client.query('ROLLBACK');
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    },
+    introspectionOverrides: {
+        indexes: SQL_INDEXES_CRDB,
+        enums: SQL_ENUMS_CRDB,
+        rowEstimates: SQL_ROW_ESTIMATES_CRDB,
+    },
+    statementTimeout(seconds) {
+        // CockroachDB v23.1+ supports transaction_timeout
+        return `SET transaction_timeout = '${seconds}s'`;
+    },
+};
+//# sourceMappingURL=cockroachdb.js.map

package/dist/adapters/index.d.ts

@@ -0,0 +1,107 @@
+/**
+ * turbine-orm — Database adapter interface
+ *
+ * Adapters allow Turbine to work with PostgreSQL-compatible databases that
+ * have subtle differences (e.g. CockroachDB, YugabyteDB). The default
+ * behavior remains standard PostgreSQL — adapters only override specific
+ * operations where compatibility gaps exist.
+ *
+ * @example
+ * ```ts
+ * import { cockroachdb } from 'turbine-orm/adapters';
+ *
+ * // Pass to TurbineCliConfig or migration functions
+ * const config = { url: process.env.DATABASE_URL, adapter: cockroachdb };
+ * ```
+ */
+import type { PgCompatPoolClient } from '../client.js';
+/**
+ * Override individual introspection SQL queries for databases where
+ * pg_catalog or information_schema behaves differently.
+ */
+export interface IntrospectionOverrides {
+    /** Override the pg_indexes query (CockroachDB uses crdb_internal or show indexes) */
+    indexes: string;
+    /** Override the pg_enum query */
+    enums: string;
+    /** Override the row count estimation query (pg_class reltuples) */
+    rowEstimates: string;
+}
+/**
+ * A DatabaseAdapter encapsulates dialect-specific behavior for databases
+ * that speak the PostgreSQL wire protocol but differ in implementation.
+ *
+ * All methods are optional except `name`. Turbine falls through to standard
+ * PostgreSQL behavior for any method not provided by the adapter.
+ */
+export interface DatabaseAdapter {
+    /** Identifier for the adapter (e.g. 'postgresql', 'cockroachdb') */
+    readonly name: string;
+    /**
+     * Acquire a concurrency lock for migrations.
+     * PostgreSQL uses `pg_try_advisory_lock`. CockroachDB uses a lock table.
+     *
+     * @returns `true` if the lock was successfully acquired.
+     */
+    acquireLock(client: PgCompatPoolClient, lockId: number): Promise<boolean>;
+    /**
+     * Release the concurrency lock acquired by `acquireLock`.
+     */
+    releaseLock(client: PgCompatPoolClient, lockId: number): Promise<void>;
+    /**
+     * Optional overrides for introspection queries where the default
+     * information_schema/pg_catalog queries don't work.
+     */
+    introspectionOverrides?: Partial<IntrospectionOverrides>;
+    /**
+     * Generate the SQL to set a statement timeout within a transaction.
+     * PostgreSQL uses `SET LOCAL statement_timeout = '<n>s'`.
+     * CockroachDB uses `SET transaction_timeout = '<n>s'` (v23.1+).
+     *
+     * @param seconds — timeout in seconds
+     * @returns the SQL string to execute
+     */
+    statementTimeout?(seconds: number): string;
+    /**
+     * SQL to create the lock table used by table-based locking adapters.
+     * Called during `ensureTrackingTable` when the adapter uses table locks.
+     */
+    createLockTableSQL?(): string;
+}
+/**
+ * The default PostgreSQL adapter. Uses pg_try_advisory_lock, standard
+ * pg_catalog queries, and SET LOCAL statement_timeout.
+ */
+export declare const postgresql: DatabaseAdapter;
+/**
+ * Google AlloyDB adapter. AlloyDB is PostgreSQL with Google's columnar storage
+ * engine. It is wire-protocol and catalog-compatible — no adapter overrides
+ * are needed. All Turbine features (json_agg, advisory locks, introspection,
+ * migrations) work identically to standard PostgreSQL.
+ *
+ * This export exists for documentation and explicit configuration:
+ *
+ * ```ts
+ * import { alloydb } from 'turbine-orm/adapters';
+ * const config = { url: process.env.DATABASE_URL, adapter: alloydb };
+ * ```
+ */
+export declare const alloydb: DatabaseAdapter;
+/**
+ * TimescaleDB adapter. Timescale is a PostgreSQL extension that adds
+ * hypertables, continuous aggregates, and time-series optimizations.
+ * Standard tables and hypertables both introspect via information_schema
+ * identically. Advisory locks, json_agg, and all other Turbine features
+ * work without modification.
+ *
+ * This export exists for documentation and explicit configuration:
+ *
+ * ```ts
+ * import { timescale } from 'turbine-orm/adapters';
+ * const config = { url: process.env.DATABASE_URL, adapter: timescale };
+ * ```
+ */
+export declare const timescale: DatabaseAdapter;
+export { cockroachdb } from './cockroachdb.js';
+export { yugabytedb } from './yugabytedb.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/index.js

@@ -0,0 +1,83 @@
+/**
+ * turbine-orm — Database adapter interface
+ *
+ * Adapters allow Turbine to work with PostgreSQL-compatible databases that
+ * have subtle differences (e.g. CockroachDB, YugabyteDB). The default
+ * behavior remains standard PostgreSQL — adapters only override specific
+ * operations where compatibility gaps exist.
+ *
+ * @example
+ * ```ts
+ * import { cockroachdb } from 'turbine-orm/adapters';
+ *
+ * // Pass to TurbineCliConfig or migration functions
+ * const config = { url: process.env.DATABASE_URL, adapter: cockroachdb };
+ * ```
+ */
+// ---------------------------------------------------------------------------
+// Default PostgreSQL adapter (no-op — standard behavior)
+// ---------------------------------------------------------------------------
+/**
+ * The default PostgreSQL adapter. Uses pg_try_advisory_lock, standard
+ * pg_catalog queries, and SET LOCAL statement_timeout.
+ */
+export const postgresql = {
+    name: 'postgresql',
+    async acquireLock(client, lockId) {
+        const result = await client.query(`SELECT pg_try_advisory_lock($1) AS locked`, [lockId]);
+        return result.rows[0]?.locked ?? false;
+    },
+    async releaseLock(client, lockId) {
+        await client.query(`SELECT pg_advisory_unlock($1)`, [lockId]);
+    },
+    statementTimeout(seconds) {
+        return `SET LOCAL statement_timeout = '${seconds}s'`;
+    },
+};
+// ---------------------------------------------------------------------------
+// AlloyDB — fully PostgreSQL-compatible, no adapter logic needed
+// ---------------------------------------------------------------------------
+/**
+ * Google AlloyDB adapter. AlloyDB is PostgreSQL with Google's columnar storage
+ * engine. It is wire-protocol and catalog-compatible — no adapter overrides
+ * are needed. All Turbine features (json_agg, advisory locks, introspection,
+ * migrations) work identically to standard PostgreSQL.
+ *
+ * This export exists for documentation and explicit configuration:
+ *
+ * ```ts
+ * import { alloydb } from 'turbine-orm/adapters';
+ * const config = { url: process.env.DATABASE_URL, adapter: alloydb };
+ * ```
+ */
+export const alloydb = {
+    ...postgresql,
+    name: 'alloydb',
+};
+// ---------------------------------------------------------------------------
+// TimescaleDB — PostgreSQL extension, fully compatible
+// ---------------------------------------------------------------------------
+/**
+ * TimescaleDB adapter. Timescale is a PostgreSQL extension that adds
+ * hypertables, continuous aggregates, and time-series optimizations.
+ * Standard tables and hypertables both introspect via information_schema
+ * identically. Advisory locks, json_agg, and all other Turbine features
+ * work without modification.
+ *
+ * This export exists for documentation and explicit configuration:
+ *
+ * ```ts
+ * import { timescale } from 'turbine-orm/adapters';
+ * const config = { url: process.env.DATABASE_URL, adapter: timescale };
+ * ```
+ */
+export const timescale = {
+    ...postgresql,
+    name: 'timescale',
+};
+// ---------------------------------------------------------------------------
+// Re-exports
+// ---------------------------------------------------------------------------
+export { cockroachdb } from './cockroachdb.js';
+export { yugabytedb } from './yugabytedb.js';
+//# sourceMappingURL=index.js.map

package/dist/adapters/yugabytedb.d.ts

@@ -0,0 +1,52 @@
+/**
+ * turbine-orm — YugabyteDB adapter
+ *
+ * YugabyteDB is a distributed SQL database that speaks the PostgreSQL wire
+ * protocol. It supports most PostgreSQL features including json_agg,
+ * subqueries, CTEs, and the standard information_schema.
+ *
+ * Key differences from PostgreSQL that this adapter addresses:
+ *
+ * 1. **Advisory locks are per-node** — `pg_try_advisory_lock()` is supported
+ *    but only scoped to the tserver node handling the connection. In a
+ *    multi-node cluster, two concurrent `turbine migrate` runs routed to
+ *    different nodes would both acquire the "same" advisory lock. This adapter
+ *    provides a table-based distributed lock using `SELECT FOR UPDATE NOWAIT`
+ *    which is cluster-wide via YugabyteDB's distributed transactions.
+ *
+ * 2. **Sequences may have gaps** — YugabyteDB uses distributed sequences.
+ *    SERIAL/BIGSERIAL columns work correctly but may produce non-contiguous
+ *    IDs under concurrent inserts. This is purely cosmetic and does not affect
+ *    Turbine's behavior.
+ *
+ * 3. **pg_catalog** — Mostly complete. `pg_indexes`, `pg_type`, `pg_enum`,
+ *    `information_schema.columns` all work. Row estimate via `pg_class.reltuples`
+ *    may be stale or zero on recently created tables (YugabyteDB's stats
+ *    collection is asynchronous). This adapter provides an override that
+ *    falls back to `yb_table_properties` when available.
+ *
+ * Features that work identically to PostgreSQL (no adapter override needed):
+ * - `json_agg` / `json_build_object` — fully supported
+ * - Correlated subqueries — fully supported
+ * - `COALESCE`, `LIMIT`, `OFFSET`, `ORDER BY` — fully supported
+ * - `information_schema` for table/column/constraint introspection
+ * - Extended query protocol (parameterized queries, pipeline batching)
+ * - Transactions with `SAVEPOINT` (nested transactions)
+ * - `FOR UPDATE` / `FOR SHARE` row-level locking
+ * - All WHERE operators (LIKE, ILIKE, IN, etc.)
+ * - Array and JSON column types
+ *
+ * @example
+ * ```ts
+ * import { yugabytedb } from 'turbine-orm/adapters';
+ *
+ * // In turbine.config.ts:
+ * export default {
+ *   url: process.env.DATABASE_URL,
+ *   adapter: yugabytedb,
+ * };
+ * ```
+ */
+import type { DatabaseAdapter } from './index.js';
+export declare const yugabytedb: DatabaseAdapter;
+//# sourceMappingURL=yugabytedb.d.ts.map