turbine-orm 0.19.2 → 0.21.0

package/README.md

@@ -1,6 +1,6 @@
 # turbine-orm
 
-One dependency. No WASM engine. The Postgres ORM that ships light and locks tight.
+The Postgres ORM your DBA will sign off on. A read-only Studio that can't touch prod, errors that never leak PII, one dependency, and checksummed migrations.
 
 ```
 npm install turbine-orm
@@ -10,16 +10,16 @@ npm install turbine-orm
 
 ## Why Turbine?
 
-Prisma ships a 1.6 MB WASM query engine. Drizzle ships zero runtime but no Studio, no typed errors, no migration checksums. Turbine ships **one dependency (`pg`) and no engine binary**, and bundles six things no other TS ORM has together:
+Every TS ORM now resolves nested relations in a single `json_agg` query — Prisma 7 and Drizzle v2 both ship it, and so does Turbine. That part is table stakes. The reason to reach for Turbine is the **safety bundle**: the boxes a DBA ticks before a query layer goes anywhere near production. It's the only TypeScript ORM that ships all six of these together:
 
-1. **One runtime dependency (`pg`).** No engine binary, no WASM adapter, no adapter packages to keep in lockstep. The main entry bundles to ~31 kB brotli (~109 KB minified); the edge entry to ~22 kB brotli. Prisma's WASM query 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 — since v0.19 — no raw-SQL surface at all: queries are composed in the ORM's own validated builder. 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.
+1. **Read-only Studio your DBA will approve.** `npx turbine studio` spins up a loopback-bound web UI with 192-bit auth tokens, `BEGIN READ ONLY` transactions, and — since v0.19 — no raw-SQL surface at all: queries are composed in the ORM's own validated builder. The only TS ORM Studio that physically cannot mutate your database.
+2. **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.
+3. **One runtime dependency (`pg`).** No engine binary, no WASM adapter, no adapter packages to keep in lockstep. The main entry bundles to ~31 kB brotli (~109 KB minified); the edge entry to ~22 kB brotli. Prisma's WASM query engine alone is 1.6 MB.
 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.
+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.
 
-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 one-dependency, no-WASM footprint, the read-only Studio, and the error messages that never leak user data.
+See [How It Works](#how-it-works) for the `json_agg` query strategy itself — but the query strategy isn't why you'd pick Turbine. The safety bundle above is: a Studio that can't mutate prod, errors that never leak PII, one dependency, and checksummed migrations.
 
 ## Benchmarks
 
@@ -404,7 +404,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), `TURBINE_E008` (UniqueConstraint), `TURBINE_E009` (ForeignKey), `TURBINE_E010` (NotNullViolation), `TURBINE_E011` (CheckConstraint), `TURBINE_E012` (Deadlock), `TURBINE_E013` (SerializationFailure), `TURBINE_E014` (Pipeline), `TURBINE_E015` (OptimisticLock), `TURBINE_E016` (ExclusionConstraint).
+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), `TURBINE_E015` (OptimisticLock), `TURBINE_E016` (ExclusionConstraint), `TURBINE_E017` (UnsupportedFeature — a Postgres-only feature invoked on another engine).
 
 Full reference with `wrapPgError()` translation, retry patterns for `DeadlockError` / `SerializationFailureError`, and safe vs verbose message modes: **[turbineorm.dev/errors](https://turbineorm.dev/errors)**.
 
@@ -705,12 +705,12 @@ Turbine's core is driver-agnostic: pass any pg-compatible pool to `TurbineConfig
 // app/api/users/route.ts
 import { Pool } from '@neondatabase/serverless';
 import { turbineHttp } from 'turbine-orm/serverless';
-import { schema } from '@/generated/turbine/metadata';
+import { SCHEMA } from '@/generated/turbine/metadata';
 
 export const runtime = 'edge';
 
 const pool = new Pool({ connectionString: process.env.DATABASE_URL });
-const db = turbineHttp(pool, schema);
+const db = turbineHttp(pool, SCHEMA);
 
 export async function GET() {
   const users = await db.table('users').findMany({
@@ -726,22 +726,22 @@ export async function GET() {
 ```ts
 import { createPool } from '@vercel/postgres';
 import { turbineHttp } from 'turbine-orm/serverless';
-import { schema } from './generated/turbine/metadata.js';
+import { SCHEMA } from './generated/turbine/metadata.js';
 
 const pool = createPool({ connectionString: process.env.POSTGRES_URL });
-const db = turbineHttp(pool, schema);
+const db = turbineHttp(pool, SCHEMA);
 ```
 
 ### Supabase (direct Postgres — no HTTP proxy needed)
 
 ```ts
 import { TurbineClient } from 'turbine-orm';
-import { schema } from './generated/turbine/metadata.js';
+import { SCHEMA } from './generated/turbine/metadata.js';
 
 const db = new TurbineClient({
   connectionString: process.env.SUPABASE_DB_URL,
   ssl: { rejectUnauthorized: false },
-}, schema);
+}, SCHEMA);
 ```
 
 ### Cloudflare Workers
@@ -749,12 +749,12 @@ const db = new TurbineClient({
 ```ts
 import { Pool } from '@neondatabase/serverless';
 import { turbineHttp } from 'turbine-orm/serverless';
-import { schema } from './generated/turbine/metadata';
+import { SCHEMA } from './generated/turbine/metadata';
 
 export default {
   async fetch(req: Request, env: Env) {
     const pool = new Pool({ connectionString: env.DATABASE_URL });
-    const db = turbineHttp(pool, schema);
+    const db = turbineHttp(pool, SCHEMA);
     const users = await db.table('users').findMany({ limit: 10 });
     return Response.json(users);
   },
@@ -769,6 +769,70 @@ export default {
 
 When Turbine receives an external pool, `db.disconnect()` is a no-op: the caller owns the pool's lifecycle.
 
+## Database engines
+
+Turbine is **Postgres-first** — `import { TurbineClient } from 'turbine-orm'` targets PostgreSQL, and the safety bundle above is built around it. When you need another database, the same typed API runs on **SQLite**, **MySQL 8**, and **SQL Server** through subpath exports. Multi-engine is *additive*, not a pivot: pick the engine that fits, keep the same `findMany` / `with` / `where` API.
+
+The root install stays one dependency (`pg`). Each engine's driver is its own concern: SQLite needs nothing (Node's built-in `node:sqlite`), MySQL and SQL Server use **optional peer dependencies** you install only if you use them.
+
+```bash
+# SQLite — zero extra deps (Node >= 22.5, built-in node:sqlite)
+npm install turbine-orm
+
+# MySQL 8 — optional peer
+npm install turbine-orm mysql2
+
+# SQL Server 2016+ — optional peer
+npm install turbine-orm mssql
+```
+
+Each engine ships a factory that returns the same `TurbineClient`:
+
+```ts
+// SQLite — synchronous; pass a file path, ':memory:', or an open DatabaseSync
+import { turbineSqlite } from 'turbine-orm/sqlite';
+import { SCHEMA } from './generated/turbine/metadata.js';
+
+const db = turbineSqlite(':memory:', SCHEMA);
+const users = await db.users.findMany({ with: { posts: true }, limit: 10 });
+```
+
+```ts
+// MySQL 8 — async; connection string, mysql2 config, or an existing mysql2 pool
+import { turbineMysql } from 'turbine-orm/mysql';
+import { SCHEMA } from './generated/turbine/metadata.js';
+
+const db = await turbineMysql('mysql://user:pass@localhost:3306/app', SCHEMA);
+```
+
+```ts
+// SQL Server 2016+ — async; connection string, mssql config, or an existing pool
+import { turbineMssql } from 'turbine-orm/mssql';
+import { SCHEMA } from './generated/turbine/metadata.js';
+
+const db = await turbineMssql('mssql://sa:Passw0rd!@localhost:1433/app', SCHEMA);
+```
+
+### Capability matrix
+
+Everything is honest about what ports and what doesn't. Features marked **PG-only** throw a typed `UnsupportedFeatureError` (`TURBINE_E017`) on other engines rather than silently degrading.
+
+| Feature | PostgreSQL | SQLite | MySQL 8 | SQL Server |
+|---|:---:|:---:|:---:|:---:|
+| Single-query nested `with` | ✓ `json_agg` | ✓ `json_group_array` | ✓ `JSON_ARRAYAGG` | ✓ `FOR JSON PATH` |
+| Transactions + savepoints | ✓ | ✓ (single-writer) | ✓ | ✓ |
+| Streaming (`findManyStream`) | ✓ | ✓ | ✓ | ✓ |
+| Migrations (`turbine migrate` CLI) | ✓ | PG-only (CLI) | PG-only (CLI) | PG-only (CLI) |
+| pgvector distance / KNN | ✓ | ✗ E017 | ✗ E017 | ✗ E017 |
+| LISTEN/NOTIFY realtime | ✓ | ✗ E017 | ✗ E017 | ✗ E017 |
+| RLS `sessionContext` | ✓ | ✗ E017 | ✗ E017 | ✗ E017 |
+
+✗ E017 = throws `UnsupportedFeatureError`. The full matrix (atomic updates, introspection, optimistic locking, per-cell mechanics) is on [turbineorm.dev/engines](https://turbineorm.dev/engines).
+
+**Engine notes:** SQLite uses `RETURNING` (≥ 3.35) just like Postgres. MySQL has no `RETURNING`, so writes re-`SELECT` the affected row and **`createMany` returns `[]`** (the rows ARE inserted — re-query if you need them). SQL Server returns rows via `OUTPUT`/`MERGE`; `DISTINCT ON` is Postgres-only. Only Postgres streams via a true cursor (constant memory); the other engines' `findManyStream` materializes the result then yields it in batches. Optimistic locking throws `OptimisticLockError` on all engines (on MySQL the conflict is detected from the version-checked UPDATE's affected-row count). The `turbine` CLI (`generate`, `migrate`) is currently PostgreSQL-only — point the engine factories at a hand-written or programmatically introspected `SCHEMA`.
+
+Full setup, signatures, and the complete support matrix: **[turbineorm.dev/engines](https://turbineorm.dev/engines)**.
+
 ## Configuration
 
 Create `turbine.config.ts` in your project root (or run `npx turbine init`):
@@ -829,7 +893,7 @@ Turbine maps Postgres types to TypeScript:
 | **Many-to-many** | Auto-detected from junctions | Implicit/explicit | Explicit `relations()` | Manual joins |
 | **Vector search** | Built-in `distance` / KNN | Preview / raw | Extension API | Manual |
 | **LISTEN/NOTIFY** | `$listen` / `$notify` | None | None | None |
-| **Multi-DB** | PostgreSQL only | PG, MySQL, SQLite, MSSQL | PG, MySQL, SQLite | PG, MySQL, SQLite |
+| **Multi-DB** | Postgres-first (+ SQLite/MySQL/MSSQL engines) | PG, MySQL, SQLite, MSSQL | PG, MySQL, SQLite | PG, MySQL, SQLite |
 
 All three ORMs now do single-query nested loads — that's table stakes. Turbine's real differentiators: no engine binary or WASM — just one dependency (`pg`), vs Prisma's 1.6 MB WASM query engine; 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.
 
@@ -837,7 +901,7 @@ All three ORMs now do single-query nested loads — that's table stakes. Turbine
 
 Turbine is focused and opinionated. Here's what it doesn't do:
 
-- **PostgreSQL only.** No MySQL, SQLite, or MSSQL. By design — going deep on one database enables the performance advantage and the edge-runtime story.
+- **Postgres-first.** PostgreSQL is the default and primary target — going deep on one database is what enables the safety bundle and the edge-runtime story. SQLite, MySQL 8, and SQL Server engines are available as additive subpath exports (see [Database engines](#database-engines)), but several flagship features (pgvector, LISTEN/NOTIFY, RLS `sessionContext`) are Postgres-only and throw `UnsupportedFeatureError` elsewhere.
 - **Full-text search** is available via a `search` filter — `where: { title: { search: 'hello & world', config: 'english' } }` compiles to a parameterized `to_tsvector(...) @@ to_tsquery(...)`. For advanced ranking (`ts_rank`, weighted vectors) use `db.raw`.
 - **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.
 

package/dist/adapters/cockroachdb.js

@@ -54,15 +54,10 @@ const CREATE_LOCK_TABLE_SQL = `
 // 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.
+ * CockroachDB index introspection via the pg_indexes compatibility view.
+ * CockroachDB exposes pg_indexes (compatible since v22.1) with the same
+ * tablename/indexname/indexdef columns as PostgreSQL, so the standard
+ * introspection flow consumes this drop-in SQL string unchanged.
  */
 const SQL_INDEXES_CRDB = `
   SELECT

package/dist/cjs/adapters/cockroachdb.js

@@ -57,15 +57,10 @@ const CREATE_LOCK_TABLE_SQL = `
 // 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.
+ * CockroachDB index introspection via the pg_indexes compatibility view.
+ * CockroachDB exposes pg_indexes (compatible since v22.1) with the same
+ * tablename/indexname/indexdef columns as PostgreSQL, so the standard
+ * introspection flow consumes this drop-in SQL string unchanged.
  */
 const SQL_INDEXES_CRDB = `
   SELECT

package/dist/cjs/cli/index.js

@@ -964,9 +964,10 @@ async function cmdStudio(args, config) {
         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.
+    // Warn loudly when an explicit non-loopback --host is used — the user is
+    // opting in, so we proceed rather than refuse. 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.`));
@@ -1039,6 +1040,8 @@ async function cmdObserve(args) {
         console.log((0, ui_js_1.red)(`✗ invalid port: ${args.port}`));
         process.exit(1);
     }
+    // Warn loudly when an explicit non-loopback --host is used — the user is
+    // opting in, so we proceed rather than refuse.
     if (host !== '127.0.0.1' && host !== 'localhost' && host !== '::1') {
         console.log((0, ui_js_1.warn)(`Observe 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 metrics.`));

package/dist/cjs/cli/observe-ui.js

@@ -132,12 +132,22 @@ exports.OBSERVE_HTML = `<!doctype html>
         + '</svg>';
     }
 
+    function escapeHtml(s) {
+      if (s == null) return '';
+      return String(s)
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+    }
+
     function renderModels(data) {
       const el = document.getElementById('models-table');
       if (!data || data.length === 0) { el.innerHTML = '<p class="empty">No data yet</p>'; return; }
       let html = '<table><thead><tr><th>Model</th><th>Action</th><th class="num">Count</th><th class="num">Avg (ms)</th><th class="num">P95 (ms)</th><th class="num">P99 (ms)</th></tr></thead><tbody>';
       for (const row of data) {
-        html += '<tr><td>' + row.model + '</td><td>' + row.action + '</td>'
+        html += '<tr><td>' + escapeHtml(row.model) + '</td><td>' + escapeHtml(row.action) + '</td>'
           + '<td class="num">' + row.count + '</td>'
           + '<td class="num">' + row.avg_ms.toFixed(1) + '</td>'
           + '<td class="num">' + row.p95_ms.toFixed(1) + '</td>'
@@ -154,7 +164,7 @@ exports.OBSERVE_HTML = `<!doctype html>
       for (const row of data) {
         const rate = row.count > 0 ? (row.error_count / row.count * 100).toFixed(1) : '0.0';
         const cls = parseFloat(rate) > 5 ? 'error-rate' : 'low-error';
-        html += '<tr><td>' + row.model + '</td><td>' + row.action + '</td>'
+        html += '<tr><td>' + escapeHtml(row.model) + '</td><td>' + escapeHtml(row.action) + '</td>'
           + '<td class="num">' + row.count + '</td>'
           + '<td class="num">' + row.error_count + '</td>'
           + '<td class="num ' + cls + '">' + rate + '%</td></tr>';

package/dist/cjs/cli/observe.js

@@ -116,13 +116,12 @@ function isAuthorized(req, expectedToken) {
     return false;
 }
 function constantTimeEqual(a, b) {
-    if (a.length !== b.length)
-        return false;
-    let result = 0;
-    for (let i = 0; i < a.length; i++) {
-        result |= a.charCodeAt(i) ^ b.charCodeAt(i);
-    }
-    return result === 0;
+    // Hash both inputs to fixed-length 32-byte SHA-256 digests before comparing.
+    // This makes the comparison constant-length (timingSafeEqual never throws on a
+    // length mismatch) and leaks neither length nor content via timing.
+    const ah = (0, node_crypto_1.createHash)('sha256').update(a).digest();
+    const bh = (0, node_crypto_1.createHash)('sha256').update(b).digest();
+    return (0, node_crypto_1.timingSafeEqual)(ah, bh);
 }
 // ---------------------------------------------------------------------------
 // API handlers

package/dist/cjs/cli/studio.js

@@ -237,13 +237,12 @@ function checkRateLimit(limiter, token) {
     return { allowed: true, resetAt: entry.resetAt };
 }
 function constantTimeEqual(a, b) {
-    if (a.length !== b.length)
-        return false;
-    let result = 0;
-    for (let i = 0; i < a.length; i++) {
-        result |= a.charCodeAt(i) ^ b.charCodeAt(i);
-    }
-    return result === 0;
+    // Hash both inputs to fixed-length 32-byte SHA-256 digests before comparing.
+    // This makes the comparison constant-length (timingSafeEqual never throws on a
+    // length mismatch) and leaks neither length nor content via timing.
+    const ah = (0, node_crypto_1.createHash)('sha256').update(a).digest();
+    const bh = (0, node_crypto_1.createHash)('sha256').update(b).digest();
+    return (0, node_crypto_1.timingSafeEqual)(ah, bh);
 }
 /**
  * Build a helpful "unknown table" error that lists the available tables so the

package/dist/cjs/client.js

@@ -29,6 +29,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TurbineClient = exports.TransactionClient = void 0;
 exports.withRetry = withRetry;
 const pg_1 = __importDefault(require("pg"));
+const dialect_js_1 = require("./dialect.js");
 const errors_js_1 = require("./errors.js");
 const observe_js_1 = require("./observe.js");
 const pipeline_js_1 = require("./pipeline.js");
@@ -89,11 +90,14 @@ class TransactionClient {
     queryOptions;
     tableCache = new Map();
     savepointCounter = 0;
+    /** Active SQL dialect — owns savepoint keywords and raw-SQL placeholders. */
+    dialect;
     constructor(client, schema, middlewares, queryOptions) {
         this.client = client;
         this.schema = schema;
         this.middlewares = middlewares;
         this.queryOptions = queryOptions;
+        this.dialect = queryOptions?.dialect ?? dialect_js_1.postgresDialect;
         // Auto-create typed table accessors for all tables in the schema
         for (const tableName of Object.keys(schema.tables)) {
             const camelName = tableName.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
@@ -127,14 +131,14 @@ class TransactionClient {
      */
     async $transaction(fn) {
         const savepointName = `sp_${++this.savepointCounter}`;
-        await this.client.query(`SAVEPOINT ${savepointName}`);
+        await this.client.query(this.dialect.savepointStatement(savepointName));
         try {
             const result = await fn(this);
-            await this.client.query(`RELEASE SAVEPOINT ${savepointName}`);
+            await this.client.query(this.dialect.releaseSavepointStatement(savepointName));
             return result;
         }
         catch (err) {
-            await this.client.query(`ROLLBACK TO SAVEPOINT ${savepointName}`);
+            await this.client.query(this.dialect.rollbackToSavepointStatement(savepointName));
             throw err;
         }
     }
@@ -146,7 +150,7 @@ class TransactionClient {
         strings.forEach((str, i) => {
             sql += str;
             if (i < values.length) {
-                sql += `$${i + 1}`;
+                sql += this.dialect.paramPlaceholder(i + 1);
             }
         });
         try {
@@ -200,6 +204,8 @@ class TurbineClient {
     schema;
     static int8ParserRegistered = false;
     logging;
+    /** Active SQL dialect — owns transaction keywords, set_config, raw-SQL placeholders, capability flags. */
+    dialect;
     tableCache = new Map();
     middlewares = [];
     queryListeners = new Set();
@@ -245,6 +251,7 @@ class TurbineClient {
             TurbineClient.int8ParserRegistered = true;
         }
         this.logging = config.logging ?? false;
+        this.dialect = config.dialect ?? dialect_js_1.postgresDialect;
         this.schema = schema;
         // Respect env var kill switch
         const envDisablePrepared = typeof process !== 'undefined' && process.env?.TURBINE_DISABLE_PREPARED === '1';
@@ -473,7 +480,7 @@ class TurbineClient {
         strings.forEach((str, i) => {
             sql += str;
             if (i < values.length) {
-                sql += `$${i + 1}`;
+                sql += this.dialect.paramPlaceholder(i + 1);
             }
         });
         if (this.logging) {
@@ -518,7 +525,7 @@ class TurbineClient {
      * ```
      */
     sql(strings, ...values) {
-        const { sql, params } = (0, typed_sql_js_1.buildTypedSql)(strings, values);
+        const { sql, params } = (0, typed_sql_js_1.buildTypedSql)(strings, values, this.dialect);
         return new typed_sql_js_1.TypedSqlQuery(this.pool, sql, params, this.logging);
     }
     // -------------------------------------------------------------------------
@@ -538,13 +545,13 @@ class TurbineClient {
     async transaction(fn) {
         const client = await this.pool.connect();
         try {
-            await client.query('BEGIN');
+            await client.query(this.dialect.beginStatement());
             const result = await fn(client);
-            await client.query('COMMIT');
+            await client.query(this.dialect.commitStatement());
             return result;
         }
         catch (err) {
-            await client.query('ROLLBACK');
+            await client.query(this.dialect.rollbackStatement());
             throw err;
         }
         finally {
@@ -595,14 +602,10 @@ class TurbineClient {
         };
         let timedOut = false;
         try {
-            // BEGIN with optional isolation level
-            let beginSQL = 'BEGIN';
-            if (options?.isolationLevel) {
-                const level = ISOLATION_LEVELS[options.isolationLevel];
-                if (level)
-                    beginSQL += ` ISOLATION LEVEL ${level}`;
-            }
-            await client.query(beginSQL);
+            // BEGIN with optional isolation level — the dialect owns the keyword and
+            // BEGIN+isolation composition (Postgres appends ` ISOLATION LEVEL …`).
+            const isolationSql = options?.isolationLevel ? ISOLATION_LEVELS[options.isolationLevel] : undefined;
+            await client.query(this.dialect.beginStatement(isolationSql));
             // Apply transaction-local session context (RLS / multi-tenant GUCs).
             // Order matters: BEGIN -> isolation level (above) -> set_config loop ->
             // user fn. Any error here propagates to the catch below and rolls back
@@ -610,12 +613,16 @@ class TurbineClient {
             // is_local=true) — the parameterizable, transaction-scoped equivalent of
             // SET LOCAL — so both name and value are BOUND params, never interpolated.
             if (options?.sessionContext) {
+                if (!this.dialect.supportsRLS) {
+                    throw new errors_js_1.UnsupportedFeatureError('sessionContext (RLS session GUCs)', this.dialect.name, 'set_config-based row-level-security context requires PostgreSQL.');
+                }
                 for (const [name, value] of Object.entries(options.sessionContext)) {
                     if (!GUC_NAME_REGEX.test(name)) {
                         throw new errors_js_1.ValidationError(`[turbine] Invalid session-context GUC name "${name}" — must match ` +
                             '/^[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)?$/ (optionally namespaced, e.g. "app.current_tenant")');
                     }
-                    await client.query('SELECT set_config($1, $2, true)', [name, String(value)]);
+                    const cfg = this.dialect.buildSetSessionConfig(name, String(value));
+                    await client.query(cfg.sql, cfg.params);
                 }
             }
             // Create the transaction client with typed table accessors
@@ -661,7 +668,7 @@ class TurbineClient {
             else {
                 result = await fn(tx);
             }
-            await client.query('COMMIT');
+            await client.query(this.dialect.commitStatement());
             if (this.logging) {
                 console.log('[turbine] Transaction committed');
             }
@@ -674,7 +681,7 @@ class TurbineClient {
             // when its socket was closed).
             if (!timedOut && !released) {
                 try {
-                    await client.query('ROLLBACK');
+                    await client.query(this.dialect.rollbackStatement());
                 }
                 catch {
                     // Best-effort rollback — the connection may have died mid-query.
@@ -741,6 +748,9 @@ class TurbineClient {
      * ```
      */
     async $listen(channel, handler) {
+        if (!this.dialect.supportsListenNotify) {
+            throw new errors_js_1.UnsupportedFeatureError('$listen (LISTEN/NOTIFY realtime)', this.dialect.name, 'Realtime pub/sub requires PostgreSQL.');
+        }
         (0, realtime_js_1.validateChannel)(channel);
         const quoted = (0, utils_js_1.quoteIdent)(channel);
         if (this.logging) {
@@ -766,6 +776,9 @@ class TurbineClient {
      * ```
      */
     async $notify(channel, payload) {
+        if (!this.dialect.supportsListenNotify) {
+            throw new errors_js_1.UnsupportedFeatureError('$notify (LISTEN/NOTIFY realtime)', this.dialect.name, 'Realtime pub/sub requires PostgreSQL.');
+        }
         (0, realtime_js_1.validateChannel)(channel);
         if (this.logging) {
             console.log(`[turbine] NOTIFY ${channel}`);