turbine-orm 0.15.0 → 0.18.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`] };
     },
 };

package/dist/cjs/cli/index.js

@@ -14,6 +14,7 @@
  *   turbine seed                  — Run seed file
  *   turbine status                — Show schema summary
  *   turbine studio                — Launch local read-only web UI
+ *   turbine observe               — Launch metrics dashboard (requires TURBINE_OBSERVE_URL)
  *
  * Usage:
  *   DATABASE_URL=postgres://... npx turbine generate
@@ -63,6 +64,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 observe_js_1 = require("./observe.js");
 const studio_js_1 = require("./studio.js");
 const ui_js_1 = require("./ui.js");
 function parseArgs() {
@@ -1005,6 +1007,65 @@ async function cmdStudio(args, config) {
     });
 }
 // ---------------------------------------------------------------------------
+// Command: observe
+// ---------------------------------------------------------------------------
+async function cmdObserve(args) {
+    (0, ui_js_1.banner)();
+    const url = process.env.TURBINE_OBSERVE_URL;
+    if (!url) {
+        (0, ui_js_1.error)('TURBINE_OBSERVE_URL environment variable is required for the observe command.');
+        (0, ui_js_1.newline)();
+        console.log(`  ${(0, ui_js_1.dim)('Set it to the Postgres connection string where metrics are stored.')}`);
+        console.log(`  ${(0, ui_js_1.dim)('Example:')} ${(0, ui_js_1.cyan)('TURBINE_OBSERVE_URL=postgres://... npx turbine observe')}`);
+        (0, ui_js_1.newline)();
+        process.exit(1);
+    }
+    const port = args.port ?? 4984;
+    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);
+    }
+    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.`));
+    }
+    const spinner = new ui_js_1.Spinner('Connecting to metrics database').start();
+    let handle;
+    try {
+        handle = await (0, observe_js_1.startObserve)({ url, port, host, openBrowser });
+        spinner.succeed('Observe dashboard is running');
+    }
+    catch (err) {
+        spinner.fail(`Failed to start Observe: ${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 Observe')}  ${(0, ui_js_1.dim)('— query metrics dashboard')}`,
+        '',
+        `  ${(0, ui_js_1.cyan)('URL:')}  ${(0, ui_js_1.bold)(handle.url)}`,
+        '',
+        (0, ui_js_1.dim)('Open the URL above in your browser. Press Ctrl+C to stop.'),
+    ].join('\n'), { title: (0, ui_js_1.bold)((0, ui_js_1.cyan)('Observe')), padding: 1 }));
+    (0, ui_js_1.newline)();
+    await new Promise((resolve) => {
+        const shutdown = async () => {
+            console.log((0, ui_js_1.dim)('\n  shutting down…'));
+            try {
+                await handle.dispose();
+            }
+            catch {
+                /* ignore */
+            }
+            resolve();
+        };
+        process.once('SIGINT', shutdown);
+        process.once('SIGTERM', shutdown);
+    });
+}
+// ---------------------------------------------------------------------------
 // Subcommand help
 // ---------------------------------------------------------------------------
 function showSubcommandHelp(command) {
@@ -1288,6 +1349,9 @@ async function main() {
             case 'studio':
                 await cmdStudio(args, config);
                 break;
+            case 'observe':
+                await cmdObserve(args);
+                break;
             default:
                 (0, ui_js_1.error)(`Unknown command: ${(0, ui_js_1.bold)(args.command)}`);
                 (0, ui_js_1.newline)();

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

@@ -0,0 +1,182 @@
+"use strict";
+// Embedded HTML for the Turbine Observe dashboard.
+// Same pattern as studio-ui.generated.ts but hand-authored (no build step needed).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OBSERVE_HTML = void 0;
+exports.OBSERVE_HTML = `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <meta name="color-scheme" content="dark" />
+  <title>Turbine Observe</title>
+  <style>
+    :root {
+      --bg: #0a0a0b;
+      --bg-elev: #111113;
+      --bg-hover: #1a1a1d;
+      --border: #26262b;
+      --text: #e6e6ea;
+      --text-dim: #8a8a93;
+      --accent: #60a5fa;
+      --green: #4ade80;
+      --red: #f87171;
+      --orange: #fb923c;
+      --purple: #a78bfa;
+      --mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+      --sans: system-ui, -apple-system, sans-serif;
+      --radius: 6px;
+    }
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { background: var(--bg); color: var(--text); font-family: var(--sans); font-size: 14px; padding: 24px; }
+    h1 { font-size: 20px; margin-bottom: 4px; }
+    .subtitle { color: var(--text-dim); margin-bottom: 24px; }
+    .controls { display: flex; gap: 8px; margin-bottom: 24px; }
+    .controls button {
+      background: var(--bg-elev); border: 1px solid var(--border); border-radius: var(--radius);
+      color: var(--text); padding: 6px 12px; cursor: pointer; font-size: 13px;
+    }
+    .controls button.active { border-color: var(--accent); color: var(--accent); }
+    .card {
+      background: var(--bg-elev); border: 1px solid var(--border); border-radius: var(--radius);
+      padding: 16px; margin-bottom: 16px;
+    }
+    .card h2 { font-size: 14px; color: var(--text-dim); margin-bottom: 12px; text-transform: uppercase; letter-spacing: 0.5px; }
+    table { width: 100%; border-collapse: collapse; font-family: var(--mono); font-size: 12px; }
+    th { text-align: left; padding: 6px 8px; color: var(--text-dim); border-bottom: 1px solid var(--border); }
+    td { padding: 6px 8px; border-bottom: 1px solid var(--border); }
+    .num { text-align: right; }
+    .error-rate { color: var(--red); }
+    .low-error { color: var(--green); }
+    svg { width: 100%; height: 200px; }
+    .chart-line { fill: none; stroke-width: 1.5; }
+    .line-avg { stroke: var(--accent); }
+    .line-p95 { stroke: var(--orange); }
+    .line-p99 { stroke: var(--red); }
+    .legend { display: flex; gap: 16px; margin-top: 8px; font-size: 12px; color: var(--text-dim); }
+    .legend span::before { content: ''; display: inline-block; width: 12px; height: 2px; margin-right: 4px; vertical-align: middle; }
+    .legend .l-avg::before { background: var(--accent); }
+    .legend .l-p95::before { background: var(--orange); }
+    .legend .l-p99::before { background: var(--red); }
+    .empty { color: var(--text-dim); text-align: center; padding: 40px; }
+  </style>
+</head>
+<body>
+  <h1>Turbine Observe</h1>
+  <p class="subtitle">Query performance metrics</p>
+  <div class="controls">
+    <button data-range="1h" class="active">1h</button>
+    <button data-range="6h">6h</button>
+    <button data-range="24h">24h</button>
+    <button data-range="7d">7d</button>
+  </div>
+  <div class="card" id="latency-card">
+    <h2>Latency over time</h2>
+    <div id="chart"></div>
+    <div class="legend">
+      <span class="l-avg">avg</span>
+      <span class="l-p95">p95</span>
+      <span class="l-p99">p99</span>
+    </div>
+  </div>
+  <div class="card" id="models-card">
+    <h2>Top models</h2>
+    <div id="models-table"></div>
+  </div>
+  <div class="card" id="errors-card">
+    <h2>Error rates</h2>
+    <div id="errors-table"></div>
+  </div>
+  <script>
+    let currentRange = '1h';
+    const token = document.cookie.match(/turbine_observe_token=([a-f0-9]+)/)?.[1] || '';
+    const headers = { 'x-turbine-token': token };
+
+    document.querySelector('.controls').addEventListener('click', e => {
+      if (e.target.tagName !== 'BUTTON') return;
+      document.querySelectorAll('.controls button').forEach(b => b.classList.remove('active'));
+      e.target.classList.add('active');
+      currentRange = e.target.dataset.range;
+      refresh();
+    });
+
+    async function fetchJson(path) {
+      const res = await fetch(path, { headers });
+      if (!res.ok) return null;
+      return res.json();
+    }
+
+    function buildSvgPath(points, width, height, maxY) {
+      if (points.length === 0) return '';
+      const xStep = width / Math.max(points.length - 1, 1);
+      return points.map((y, i) => {
+        const px = i * xStep;
+        const py = height - (y / maxY) * height;
+        return (i === 0 ? 'M' : 'L') + px.toFixed(1) + ',' + py.toFixed(1);
+      }).join(' ');
+    }
+
+    function renderChart(data) {
+      const el = document.getElementById('chart');
+      if (!data || data.length === 0) { el.innerHTML = '<p class="empty">No data yet</p>'; return; }
+      const width = 800; const height = 180;
+      const allVals = data.flatMap(d => [d.avg_ms, d.p95_ms, d.p99_ms]);
+      const maxY = Math.max(...allVals, 1) * 1.1;
+      const avgPath = buildSvgPath(data.map(d => d.avg_ms), width, height, maxY);
+      const p95Path = buildSvgPath(data.map(d => d.p95_ms), width, height, maxY);
+      const p99Path = buildSvgPath(data.map(d => d.p99_ms), width, height, maxY);
+      el.innerHTML = '<svg viewBox="0 0 ' + width + ' ' + height + '" preserveAspectRatio="none">'
+        + '<path class="chart-line line-avg" d="' + avgPath + '"/>'
+        + '<path class="chart-line line-p95" d="' + p95Path + '"/>'
+        + '<path class="chart-line line-p99" d="' + p99Path + '"/>'
+        + '</svg>';
+    }
+
+    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>'
+          + '<td class="num">' + row.count + '</td>'
+          + '<td class="num">' + row.avg_ms.toFixed(1) + '</td>'
+          + '<td class="num">' + row.p95_ms.toFixed(1) + '</td>'
+          + '<td class="num">' + row.p99_ms.toFixed(1) + '</td></tr>';
+      }
+      html += '</tbody></table>';
+      el.innerHTML = html;
+    }
+
+    function renderErrors(data) {
+      const el = document.getElementById('errors-table');
+      if (!data || data.length === 0) { el.innerHTML = '<p class="empty">No errors</p>'; return; }
+      let html = '<table><thead><tr><th>Model</th><th>Action</th><th class="num">Total</th><th class="num">Errors</th><th class="num">Rate</th></tr></thead><tbody>';
+      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>'
+          + '<td class="num">' + row.count + '</td>'
+          + '<td class="num">' + row.error_count + '</td>'
+          + '<td class="num ' + cls + '">' + rate + '%</td></tr>';
+      }
+      html += '</tbody></table>';
+      el.innerHTML = html;
+    }
+
+    async function refresh() {
+      const [latency, models] = await Promise.all([
+        fetchJson('/api/latency?range=' + currentRange),
+        fetchJson('/api/models?range=' + currentRange),
+      ]);
+      renderChart(latency);
+      renderModels(models);
+      // Derive errors from models data
+      const withErrors = (models || []).filter(m => m.error_count > 0);
+      renderErrors(withErrors);
+    }
+
+    refresh();
+    setInterval(refresh, 60000);
+  </script>
+</body>
+</html>`;