turbine-orm 0.16.0 → 0.19.0

package/README.md

@@ -1,6 +1,6 @@
 # turbine-orm
 
-110 KB. One runtime dependency. The Postgres ORM that ships light and locks tight.
+One dependency. No WASM engine. The Postgres ORM that ships light and locks tight.
 
 ```
 npm install turbine-orm
@@ -10,20 +10,20 @@ npm install turbine-orm
 
 ## Why Turbine?
 
-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:
+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:
 
-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.
+1. **One runtime dependency (`pg`).** No engine binary, no WASM adapter, no adapter packages to keep in lockstep. The main entry bundles to ~30 KB gzipped (~109 KB minified); the edge entry to ~21 KB gzipped. 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 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.
 
-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.
+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.
 
 ## Benchmarks
 
-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.
+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. _Measured April 2026 on turbine-orm 0.7.1; the core read path these scenarios exercise is unchanged through 0.17.0 — see [`benchmarks/RESULTS.md`](./benchmarks/RESULTS.md) to reproduce._
 
 | Scenario | Turbine | Prisma 7 | Drizzle v2 |
 |---|---|---|---|
@@ -43,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.
 
-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.
+Performance is at parity with Prisma and Drizzle — the real reasons to choose Turbine are elsewhere: **one dependency and no WASM engine** (vs Prisma's 1.6 MB WASM query engine), 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`
@@ -118,6 +118,62 @@ const user = await db.users.findUnique({
 // user.posts is Post[] -- resolved in the same query
 ```
 
+### Many-to-many relations
+
+Turbine auto-detects pure junction tables during `generate` — a table whose primary key is exactly two single-column foreign keys and which carries no other columns (e.g. `posts_tags(post_id, tag_id)`). Both endpoints gain a many-to-many relation you can load like any other:
+
+```typescript
+const posts = await db.posts.findMany({
+  with: { tags: true }, // each post comes back with its tags array
+});
+
+// Nested where / orderBy / limit work on the m2m target too
+const post = await db.posts.findFirst({
+  where: { id: 1 },
+  with: { tags: { where: { name: 'sql' }, orderBy: { name: 'asc' }, limit: 5 } },
+});
+```
+
+A junction table that carries extra columns (a "payload") is treated as a first-class entity, so it stays an ordinary `hasMany` — that's by design. For those, or for any junction you want to wire up by hand, declare the relation explicitly in your code-first schema:
+
+```typescript
+import { defineSchema } from 'turbine-orm';
+
+export default defineSchema({
+  posts: {
+    id:    { type: 'serial', primaryKey: true },
+    title: { type: 'text', notNull: true },
+    manyToMany: [
+      { name: 'tags', target: 'tags', through: 'postsTags',
+        sourceKey: 'postId', targetKey: 'tagId' },
+    ],
+  },
+  // ...tags and postsTags table definitions
+});
+```
+
+`sourceKey`/`targetKey` are the junction columns referencing each side's primary key; add `references` if the source side is keyed on something other than `id`.
+
+### Self-relations
+
+A self-referencing foreign key (e.g. `categories.parent_id → categories.id`) introspects to a `belongsTo` *and* a `hasMany` on the same table, so parent and child queries just work — including nested trees:
+
+```typescript
+// A category with its parent and its children
+const category = await db.categories.findFirst({
+  where: { id: 2 },
+  with: { parent: true, children: true },
+});
+
+// Walk a level deeper
+const tree = await db.categories.findFirst({
+  where: { id: 1 },
+  with: { children: { with: { children: true } } },
+});
+```
+
+When a table has a single self-referencing FK, Turbine auto-names the relations after the table: the `belongsTo` is named for the singular (`category`) and the `hasMany` for the table (`categories`). Rename them in your code-first schema if you prefer `parent`/`children`.
+
 ### create
 
 ```typescript
@@ -216,6 +272,29 @@ const stats = await db.raw<{ day: Date; count: number }>`
 `;
 ```
 
+### Typed raw SQL (`db.sql<T>`)
+
+`db.sql<T>` is the typed escape hatch: you supply the row shape and get a thenable query with `.one()` and `.scalar()` helpers. Every `${value}` is bound as a `$N` parameter — never interpolated — so injection isn't possible even with hostile input.
+
+```typescript
+// Awaiting the query returns T[]
+const users = await db.sql<{ id: number; name: string }>`
+  SELECT id, name FROM users WHERE org_id = ${orgId}
+`;
+
+// .one() returns T | null
+const user = await db.sql<{ id: number; name: string }>`
+  SELECT id, name FROM users WHERE id = ${42}
+`.one();
+
+// .scalar() returns the first column of the first row, or null
+const total = await db.sql<{ count: number }>`
+  SELECT COUNT(*)::int AS count FROM users
+`.scalar();
+```
+
+Reach for `db.sql<T>` when you want a hand-written query with a known return type; use `db.raw` when you don't need the typing or the helpers.
+
 ### Case-insensitive search
 
 ```typescript
@@ -305,10 +384,95 @@ 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).
+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).
 
 Full reference with `wrapPgError()` translation, retry patterns for `DeadlockError` / `SerializationFailureError`, and safe vs verbose message modes: **[turbineorm.dev/errors](https://turbineorm.dev/errors)**.
 
+### groupBy with HAVING
+
+`groupBy` aggregates rows by one or more columns. Add a `having` clause to filter the resulting groups by their aggregates. Every comparison value is parameterized.
+
+```typescript
+// Users with more than one post
+const prolific = await db.posts.groupBy({
+  by: ['userId'],
+  _count: true,
+  having: { _count: { gt: 1 } },
+});
+
+// Groups whose summed view count clears a threshold
+const popular = await db.posts.groupBy({
+  by: ['published'],
+  _sum: { viewCount: true },
+  having: { viewCount: { _sum: { gte: 100 } } },
+});
+```
+
+Filter on the group count with `_count`, or on a column aggregate with `{ column: { _sum | _avg | _min | _max: { ... } } }`. Operators are `gt`, `gte`, `lt`, `lte`, `in`, and `notIn` (a bare number is shorthand for equality). `having` predicates combine with `AND`, and `where` filters rows *before* grouping while `having` filters groups *after*.
+
+### Multi-tenant queries with RLS session context
+
+Set transaction-local Postgres settings (GUCs) so PostgreSQL Row-Level Security policies that call `current_setting()` filter rows for you. Pass `sessionContext` to `$transaction`, or use the `$withSession` shorthand.
+
+```typescript
+// Postgres policy: USING (tenant_id = current_setting('app.current_tenant')::int)
+const rows = await db.$transaction(
+  async (tx) => tx.documents.findMany(),
+  { sessionContext: { 'app.current_tenant': tenantId } },
+);
+
+// Shorthand for a single-purpose session
+const rows2 = await db.$withSession(
+  { 'app.current_tenant': tenantId },
+  async (tx) => tx.documents.findMany(),
+);
+```
+
+Each entry is applied as `SELECT set_config(name, value, true)` right after `BEGIN`, so the setting is scoped to the transaction and resets automatically on commit. Values may be strings, numbers, or booleans (coerced to strings). Invalid setting names throw `ValidationError` and roll the transaction back before any query runs.
+
+### Realtime with LISTEN/NOTIFY
+
+Subscribe to a Postgres channel with `$listen` and publish to it with `$notify`. The handler receives the notification payload as a string.
+
+```typescript
+const sub = await db.$listen('order_created', (payload) => {
+  console.log('new order:', payload);
+});
+
+await db.$notify('order_created', JSON.stringify({ id: 1 }));
+
+// Later, when you're done
+await sub.unsubscribe();
+```
+
+`$listen` holds a dedicated connection open for the lifetime of the subscription, so it requires a real persistent pool — it is not available over serverless HTTP drivers. `$notify` is a single round-trip and works everywhere. Channel names are validated as plain identifiers; the payload is always bound as a parameter.
+
+## Vector search (pgvector)
+
+Query a `vector` column for nearest neighbors. Requires the [pgvector](https://github.com/pgvector/pgvector) extension and a `vector` column on your table.
+
+**KNN ranking** — order by distance to a query vector and take the closest rows:
+
+```typescript
+const similar = await db.items.findMany({
+  orderBy: { embedding: { distance: { to: queryVector, metric: 'cosine' } } },
+  limit: 5,
+});
+// queryVector is a number[]; nearest-first by default (direction: 'desc' to invert)
+```
+
+**Distance filter** — keep only rows within a distance threshold:
+
+```typescript
+const close = await db.items.findMany({
+  where: { embedding: { distance: { to: queryVector, metric: 'l2', lt: 0.3 } } },
+});
+```
+
+`metric` selects the pgvector operator: `'l2'` → `<->` (Euclidean), `'cosine'` → `<=>` (cosine distance), `'ip'` → `<#>` (negative inner product). Distance filters accept `lt`, `lte`, `gt`, and `gte`. The query vector is always bound as `$n::vector` — never interpolated.
+
+> **Note:** pg has no built-in parser for the `vector` type, so a fetched `vector` column comes back as a string literal like `'[1,2,3]'` unless you register a parser (e.g. via pgvector's own client helpers). Querying by distance works regardless.
+
 ## WHERE Operator Reference
 
 Every operator supported by the `where` clause. Operators compose freely with `AND`, `OR`, `NOT`, and the relation filters `some` / `every` / `none`.
@@ -573,7 +737,7 @@ Priority order: CLI flags > environment variables (`DATABASE_URL`) > config file
 
 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.
 
-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.
+The query strategy is table stakes now. What isn't table stakes: the one-dependency, no-WASM footprint, 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
 
@@ -595,25 +759,29 @@ Turbine maps Postgres types to TypeScript:
 
 | | **Turbine** | **Prisma** | **Drizzle** | **Kysely** |
 |---|---|---|---|---|
-| **Install size** | ~110 KB (`pg` only) | ~1.6 MB (WASM engine) | ~0 KB (no runtime) | ~0 KB (no runtime) |
+| **Engine / runtime** | No engine binary (`pg` only) | Client + 1.6 MB WASM engine | No engine | No engine |
 | **Runtime deps** | 1 (`pg`) | `@prisma/client` + adapter | 0 | 0 |
+| **Main bundle (gzip)** | ~30 KB | dominated by 1.6 MB WASM | ~7 KB core | small |
 | **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 |
+| **Edge runtime** | One import swap, ~21 KB gzip | 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`) |
+| **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 |
 
-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.
+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.
 
 ## Limitations
 
 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.
-- **No full-text search operators.** TSVECTOR/TSQUERY are not exposed in the query builder. Use `db.raw` for full-text queries.
+- **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.
 
 ## Examples

package/dist/adapters/cockroachdb.js

@@ -165,8 +165,10 @@ export const cockroachdb = {
         rowEstimates: SQL_ROW_ESTIMATES_CRDB,
     },
     statementTimeout(seconds) {
-        // CockroachDB v23.1+ supports transaction_timeout
-        return { sql: `SET transaction_timeout = $1`, params: [`${seconds}s`] };
+        // CockroachDB v23.1+ supports transaction_timeout. `SET ... = $1` cannot
+        // take a bind parameter, so use the parameterizable set_config() form
+        // (is_local=true scopes it to the current transaction).
+        return { sql: `SELECT set_config('transaction_timeout', $1, true)`, params: [`${seconds}s`] };
     },
 };
 //# sourceMappingURL=cockroachdb.js.map

package/dist/adapters/index.js

@@ -31,7 +31,10 @@ export const postgresql = {
         await client.query(`SELECT pg_advisory_unlock($1)`, [lockId]);
     },
     statementTimeout(seconds) {
-        return { sql: `SET LOCAL statement_timeout = $1`, params: [`${seconds}s`] };
+        // `SET LOCAL ... = $1` is a Postgres syntax error — SET does not accept
+        // bind parameters. `set_config(name, value, is_local=true)` is the
+        // parameterizable, transaction-local equivalent.
+        return { sql: `SELECT set_config('statement_timeout', $1, true)`, params: [`${seconds}s`] };
     },
 };
 // ---------------------------------------------------------------------------

package/dist/adapters/yugabytedb.js

@@ -149,8 +149,10 @@ export const yugabytedb = {
         rowEstimates: SQL_ROW_ESTIMATES_YBDB,
     },
     statementTimeout(seconds) {
-        // YugabyteDB supports standard PostgreSQL statement_timeout
-        return { sql: `SET LOCAL statement_timeout = $1`, params: [`${seconds}s`] };
+        // YugabyteDB supports standard PostgreSQL statement_timeout. `SET LOCAL`
+        // cannot take a bind parameter, so use the parameterizable, transaction-
+        // local set_config() form.
+        return { sql: `SELECT set_config('statement_timeout', $1, true)`, params: [`${seconds}s`] };
     },
 };
 //# sourceMappingURL=yugabytedb.js.map

package/dist/cjs/adapters/cockroachdb.js

@@ -168,7 +168,9 @@ exports.cockroachdb = {
         rowEstimates: SQL_ROW_ESTIMATES_CRDB,
     },
     statementTimeout(seconds) {
-        // CockroachDB v23.1+ supports transaction_timeout
-        return { sql: `SET transaction_timeout = $1`, params: [`${seconds}s`] };
+        // CockroachDB v23.1+ supports transaction_timeout. `SET ... = $1` cannot
+        // take a bind parameter, so use the parameterizable set_config() form
+        // (is_local=true scopes it to the current transaction).
+        return { sql: `SELECT set_config('transaction_timeout', $1, true)`, params: [`${seconds}s`] };
     },
 };

package/dist/cjs/adapters/index.js

@@ -34,7 +34,10 @@ exports.postgresql = {
         await client.query(`SELECT pg_advisory_unlock($1)`, [lockId]);
     },
     statementTimeout(seconds) {
-        return { sql: `SET LOCAL statement_timeout = $1`, params: [`${seconds}s`] };
+        // `SET LOCAL ... = $1` is a Postgres syntax error — SET does not accept
+        // bind parameters. `set_config(name, value, is_local=true)` is the
+        // parameterizable, transaction-local equivalent.
+        return { sql: `SELECT set_config('statement_timeout', $1, true)`, params: [`${seconds}s`] };
     },
 };
 // ---------------------------------------------------------------------------

package/dist/cjs/adapters/yugabytedb.js

@@ -152,7 +152,9 @@ exports.yugabytedb = {
         rowEstimates: SQL_ROW_ESTIMATES_YBDB,
     },
     statementTimeout(seconds) {
-        // YugabyteDB supports standard PostgreSQL statement_timeout
-        return { sql: `SET LOCAL statement_timeout = $1`, params: [`${seconds}s`] };
+        // YugabyteDB supports standard PostgreSQL statement_timeout. `SET LOCAL`
+        // cannot take a bind parameter, so use the parameterizable, transaction-
+        // local set_config() form.
+        return { sql: `SELECT set_config('statement_timeout', $1, true)`, params: [`${seconds}s`] };
     },
 };