turbine-orm 0.81.0 → 0.90.0

package/README.md

@@ -138,7 +138,7 @@ await db.$transaction(async (tx) => {
 });
 ```
 
-Nested `$transaction` calls become SAVEPOINTs. Isolation levels, timeouts, and `sessionContext` (transaction-local GUCs for Postgres RLS) are options. `tx` deliberately exposes a smaller surface than `db`; reaching for a client-only member is a compile error, not a production surprise. Reference: [turbineorm.dev/transactions](https://turbineorm.dev/transactions).
+Nested `$transaction` calls become SAVEPOINTs. Isolation levels, timeouts, and `sessionContext` (transaction-local GUCs for Postgres RLS) are options. A transaction PostgreSQL rolled back (a statement failed and the callback caught it) rejects instead of reporting a commit, and a `tx` used after its callback settles throws rather than running outside the transaction. `tx` deliberately exposes a smaller surface than `db`; reaching for a client-only member is a compile error, not a production surprise. Reference: [turbineorm.dev/transactions](https://turbineorm.dev/transactions).
 
 ### Pipelining, at the protocol level
 
@@ -191,7 +191,7 @@ const db = turbine({
 });
 ```
 
-A global filter is a `WhereClause` that is AND-merged into every query on a table: reads, relation subqueries targeting it, and the predicates of `update` / `delete` / `upsert`. Values are parameterized. Details: [turbineorm.dev/global-filters](https://turbineorm.dev/global-filters).
+A global filter is a `WhereClause` that is AND-merged into every query on a table: reads, relation subqueries targeting it, and the predicates of `update` / `delete` / `upsert`. Values are parameterized. Keys may be table names or client accessors and are checked when the client is built, and a function filter that returns `undefined` throws instead of running unfiltered. Details: [turbineorm.dev/global-filters](https://turbineorm.dev/global-filters).
 
 ### The UNSAFE symbol
 
@@ -217,7 +217,7 @@ try {
 }
 ```
 
-Every error Turbine raises extends `TurbineError` with a stable code (`TURBINE_E001` through `E018`) and a `docsUrl`; a driver error whose SQLSTATE Turbine does not map stays the driver's own error, carrying that SQLSTATE on `.code`. Error messages carry keys, never values: a `NotFoundError` says `where: { id, email }` without printing the email, so errors are safe to forward to a tracker without a scrubbing rule. Retryable failures (`DeadlockError`, `SerializationFailureError`) expose `isRetryable: true` as a typed const. `err.code` is the check that survives a mixed ESM/CJS module graph, where two copies of the package hold two copies of every class; since 0.78 `instanceof` works across copies too, through a cross-copy brand on every error. Full table: [turbineorm.dev/errors](https://turbineorm.dev/errors).
+Every error Turbine raises extends `TurbineError` with a stable code (`TURBINE_E001` through `E020`) and a `docsUrl`; a driver error whose SQLSTATE Turbine does not map stays the driver's own error, carrying that SQLSTATE on `.code`. Error messages carry keys, never values: a `NotFoundError` says `where: { id, email }` without printing the email, so errors are safe to forward to a tracker without a scrubbing rule. Retryable failures (`DeadlockError`, `SerializationFailureError` and its subclass `LockNotAvailableError`) expose `isRetryable: true` as a typed const. `err.code` is the check that survives a mixed ESM/CJS module graph, where two copies of the package hold two copies of every class; since 0.78 `instanceof` works across copies too, through a cross-copy brand on every error. Full table: [turbineorm.dev/errors](https://turbineorm.dev/errors).
 
 ## Built for agents
 
@@ -254,7 +254,7 @@ The rest of the agent story is structural: query args are fully typed, so a wron
 
 **Destructive migrations need consent.** `migrate up`, `migrate down`, and `push` scan for `DROP TABLE`, `DROP COLUMN`, `TRUNCATE`, unqualified `DELETE` / `UPDATE`, and `ALTER COLUMN ... TYPE`, print an itemized report, and refuse. Interactively you type `destroy my data`, then `yes`; in CI you pass `--allow-destructive`. A refused batch applies nothing. Migrations are SQL files, checksummed with SHA-256, applied under `pg_try_advisory_lock()`.
 
-**PII stays in the database.** Tag a column `pii: true` in the schema and it is excluded from every default projection at the SQL level: `RETURNING "id", "name"` instead of `RETURNING *`. It is also refused as a `groupBy` key and a `_min` / `_max` target. Reading it back takes `includePii: UNSAFE`, per query. A schema with no tagged column emits byte-identical SQL.
+**PII stays in the database.** Tag a column `pii: true` in the schema and it is excluded from every default projection at the SQL level: `RETURNING "id", "name"` instead of `RETURNING *`. It is also refused as a `groupBy` key and a `_min` / `_max` target. Reading it back takes `includePii: UNSAFE`, per query, and naming it in `select` without that throws. A schema with no tagged column emits byte-identical SQL.
 
 **Studio is read-only by default.** `npx turbine studio` binds loopback, authenticates with a per-process token, runs every read inside `BEGIN READ ONLY`, and has no raw-SQL surface: queries are composed in a builder validated identifier by identifier. Without `--write`, the write endpoints do not exist in the router. PII cells are redacted server-side. Try it with no database: `npx turbine-orm@latest studio --demo` boots a seeded in-memory sample. Docs: [turbineorm.dev/studio](https://turbineorm.dev/studio).
 
@@ -272,7 +272,7 @@ Going deep on one database means the parts other ORMs push to raw SQL are typed
 
 ## Serverless and edge
 
-The core is driver-agnostic: hand any pg-compatible pool to `turbineHttp()` and Turbine runs on Vercel Edge, Cloudflare Workers, Deno Deploy, or anywhere else without TCP. The main entry's import graph is held under **93 kB brotli** (edge entry under **74 kB**) with `pg` external, enforced by `size-limit` in CI at those exact numbers; run `npm run size` for the current figure.
+The core is driver-agnostic: hand any pg-compatible pool to `turbineHttp()` and Turbine runs on Vercel Edge, Cloudflare Workers, Deno Deploy, or anywhere else without TCP. The main entry's import graph is held under **147 kB brotli** (edge entry under **116 kB**) with `pg` external, enforced by `size-limit` in CI at those exact numbers; run `npm run size` for the current figure.
 
 ```typescript
 import { Pool } from '@neondatabase/serverless';
@@ -329,7 +329,7 @@ const schema = defineSchema({
 
 const db = turbineSqlite(':memory:', schemaDefToMetadata(schema));
 for (const stmt of schemaToSQL(schema, { dialect: sqliteDialect })) {
-  await db.raw([stmt] as never);
+  await db.rawUnsafe(stmt);
 }
 
 const users = await db
@@ -355,24 +355,24 @@ It is also built to be extended rather than wrapped. All SQL generation routes t
 
 ## Comparison
 
-| | **Turbine** | **Prisma** | **Drizzle** | **Kysely** |
-|---|---|---|---|---|
-| **Engine / runtime** | No engine binary (`pg` only) | Client + TS/WASM query compiler | No engine | No engine |
-| **Runtime deps** | 1 (`pg`) | `@prisma/client` + required driver adapter | 0 | 0 |
-| **Main bundle (brotli)** | under 93 kB import graph (CI-enforced), `pg` external | ~1.6 MB client (TS/WASM compiler) | ~7 KB core | small |
-| **Studio** | Read-only by default | Full CRUD, cloud-hosted | Full CRUD; [Gateway](https://gateway.drizzle.team/) self-hosted, free | 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, under 74 kB brotli (CI-enforced) | Driver adapter + WASM compiler | 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 per relation by default; single-query `relationJoins` is Preview | 1 query, `relations()` re-declaration | Manual (`jsonArrayFrom`) |
-| **Index advice** | `turbine doctor`, offline, `--fix` | Optimize retired March 2026 (cloud Query Insights) | None | None |
-| **MCP server for agents** | 11 read-only tools, PII-redacted | Official MCP server | `drizzle-kit mcp` | None |
-| **Vector search** | Built-in `distance` / KNN | Preview / raw | Extension API | Manual |
-| **LISTEN/NOTIFY** | `$listen` / `$notify` | None | None | None |
-
-Competitor columns last checked 2026-08-22, against Prisma 7 and Drizzle 0.45 (the current `latest`; 1.0 is at rc.4). Cells that make a claim about someone else's pricing or licensing carry a link to that vendor's own page, because those are the cells that go stale silently: this table said Drizzle's Gateway was paid, which was true of the old Drizzle Studio subscription and is not true of Gateway, and nothing in the repo would have caught it. Features marked Preview may change; bundle sizes move release to release. The longer version of this argument, including what is not a reason to switch: [turbineorm.dev/why-turbine](https://turbineorm.dev/why-turbine).
+| | **Turbine** | **Prisma** | **Drizzle** | **Kysely** | **MikroORM** |
+|---|---|---|---|---|---|
+| **Engine / runtime** | No engine binary (`pg` only) | Client + TS/WASM query compiler | No engine | No engine | Kysely as query runner; SQL built by MikroORM (v7) |
+| **Runtime deps** | 1 (`pg`) | `@prisma/client` + required driver adapter | 0 | 0 | `@mikro-orm/core` (0 deps) + a driver package |
+| **Main bundle (brotli)** | under 147 kB import graph (CI-enforced), `pg` external | ~1.6 MB client (TS/WASM compiler) | ~7 KB core | small | |
+| **Studio** | Read-only by default | Full CRUD, cloud-hosted | Full CRUD; [Gateway](https://gateway.drizzle.team/) self-hosted, free | None | AdminJS integration guide (CRUD panel) |
+| **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 | Generated by diffing entities against a snapshot or the database; TS/JS classes |
+| **Edge runtime** | One import swap, under 116 kB brotli (CI-enforced) | Driver adapter + WASM compiler | Native | Native | Cloudflare Workers and Deno (v7) |
+| **Pipeline batching** | Parse/Bind/Execute protocol | Sequential in txn | Sequential | Manual | `flush()` runs queued changes in one transaction |
+| **Typed errors** | `isRetryable` discriminant | Error codes only | None | None | `DriverException` subclasses (`UniqueConstraintViolationException`, ...) |
+| **Nested relations** | 1 query, deep type inference | 1 query per relation by default; single-query `relationJoins` is Preview | 1 query, `relations()` re-declaration | Manual (`jsonArrayFrom`) | `populate`; default `balanced`: joins to-one, one query per to-many relation |
+| **Index advice** | `turbine doctor`, offline, `--fix` | Optimize retired March 2026 (cloud Query Insights) | None | None | |
+| **MCP server for agents** | 11 read-only tools, PII-redacted | Official MCP server | `drizzle-kit mcp` | None | |
+| **Vector search** | Built-in `distance` / KNN | Preview / raw | Extension API | Manual | |
+| **LISTEN/NOTIFY** | `$listen` / `$notify` | None | None | None | |
+
+Competitor columns last checked 2026-08-22, against Prisma 7 and Drizzle 0.45 (the current `latest`; 1.0 is at rc.4). The MikroORM column was checked 2026-10-13 against its 7.2 documentation; a blank cell is one that documentation does not settle. Cells that make a claim about someone else's pricing or licensing carry a link to that vendor's own page, because those are the cells that go stale silently: this table said Drizzle's Gateway was paid, which was true of the old Drizzle Studio subscription and is not true of Gateway, and nothing in the repo would have caught it. Features marked Preview may change; bundle sizes move release to release. The longer version of this argument, including what is not a reason to switch: [turbineorm.dev/why-turbine](https://turbineorm.dev/why-turbine).
 
 ## Limitations
 
@@ -388,13 +388,14 @@ Stated so you do not find out three weeks in:
 | Postgres | TypeScript | Notes |
 |---|---|---|
 | `int2`, `int4`, `float4`, `float8` | `number` | |
-| `int8` / `bigint` | `number` | Values above `Number.MAX_SAFE_INTEGER` come back as `string` to avoid precision loss |
+| `int8` / `bigint` | `number` | Values above `Number.MAX_SAFE_INTEGER` come back as `string` to avoid precision loss; `bigint[]` reads as `string[]` |
 | `numeric`, `money` | `string` | Arbitrary precision, kept exact |
 | `text`, `varchar`, `uuid`, `citext` | `string` | |
 | `timestamptz`, `timestamp`, `date` | `Date` | Zone-less columns read and write as UTC by default (`utcTimestamps`); the full temporal semantics, including `temporalInfinity`, are at [turbineorm.dev/schema](https://turbineorm.dev/schema#zone-less-columns-timestamp-and-date-read-as-utc) |
 | `boolean` | `boolean` | |
 | `json`, `jsonb` | `unknown` | |
 | `bytea` | `Buffer` | |
+| `interval`, `point`, `circle` | object | The driver's parsed form, for example `{ x, y }` for a point |
 | Array types | `T[]` | |
 
 ## Examples

package/dist/checkout.d.ts

@@ -34,10 +34,35 @@ export interface Checkout {
  * `DatabaseError` carrying a SQLSTATE in `.code`, the same property Turbine
  * puts `TURBINE_E0NN` in.
  *
- * Query paths need no equivalent: `pool.query()` opens the connection itself
- * and rejects with the connect error, which the query boundary already wraps.
+ * Query paths reach the same errors through `pool.query()`, which checks out
+ * internally and rejects with the connect error; the query boundary wraps
+ * those, and {@link typeCheckoutTimeouts} types pg-pool's own checkout
+ * failures on the pools Turbine owns.
  */
 export declare function acquireConnection(pool: PgCompatPool): Promise<Checkout>;
+/**
+ * A failed checkout as a typed error.
+ *
+ * pg-pool raises its two checkout failures as plain `Error`s with no code, so
+ * `wrapPgError` (keyed on SQLSTATE and socket codes) passes them through and
+ * the most common production connection failure, an exhausted pool, reached
+ * callers as an untyped error: `instanceof ConnectionError` and
+ * `code === 'TURBINE_E004'` both missed it. Everything else goes through
+ * `wrapPgError` as before.
+ */
+export declare function checkoutError(err: unknown, pool?: unknown): unknown;
+/**
+ * Make every checkout failure of a pool Turbine owns a typed error, for
+ * `pool.query` as well as `pool.connect`.
+ *
+ * {@link acquireConnection} covers the paths that check out explicitly
+ * (transactions, nested writes, streams, pipelines). An ordinary read or write
+ * goes through `pool.query`, which checks out internally via `this.connect`
+ * in callback form, so the conversion has to sit on `connect` itself. Wrapping
+ * the error is all it does. For pools Turbine creates only, the same rule as
+ * the connection guards: a caller's own pool is not Turbine's to patch.
+ */
+export declare function typeCheckoutTimeouts(pool: unknown): void;
 /**
  * Check a connection out and run `opening` on it, retrying ONCE on a fresh
  * connection when `opening` fails with {@link isStaleConnectionError}.

package/dist/checkout.js

@@ -18,7 +18,7 @@
  * write to lose.
  */
 import { guardCheckout, settleEventLoop } from './connection-guard.js';
-import { explainConnectionLoss, isStaleConnectionError, wrapPgError } from './errors.js';
+import { ConnectionError, explainConnectionLoss, isStaleConnectionError, UnsupportedFeatureError, wrapPgError, } from './errors.js';
 /**
  * Check a connection out, as a typed Turbine error when that fails.
  *
@@ -29,19 +29,90 @@ import { explainConnectionLoss, isStaleConnectionError, wrapPgError } from './er
  * `DatabaseError` carrying a SQLSTATE in `.code`, the same property Turbine
  * puts `TURBINE_E0NN` in.
  *
- * Query paths need no equivalent: `pool.query()` opens the connection itself
- * and rejects with the connect error, which the query boundary already wraps.
+ * Query paths reach the same errors through `pool.query()`, which checks out
+ * internally and rejects with the connect error; the query boundary wraps
+ * those, and {@link typeCheckoutTimeouts} types pg-pool's own checkout
+ * failures on the pools Turbine owns.
  */
 export async function acquireConnection(pool) {
+    if (typeof pool.connect !== 'function') {
+        const dialect = pool.dialect?.name;
+        throw new UnsupportedFeatureError('Checking out a connection', typeof dialect === 'string' ? dialect : 'postgresql', 'A transaction, a cursor stream, a pipeline or a write that takes several statements needs a connection ' +
+            'of its own, and this pool has no `connect()` (a stateless HTTP driver). Pass a pool that can check out ' +
+            'a connection, or run single statements.');
+    }
     let client;
     try {
         client = await pool.connect();
     }
     catch (err) {
-        throw wrapPgError(err);
+        throw checkoutError(err, pool);
     }
     return { client, checkout: guardCheckout(client) };
 }
+/** pg-pool's own words for a checkout that waited longer than `connectionTimeoutMillis`. */
+const POOL_TIMEOUT_MESSAGE = 'timeout exceeded when trying to connect';
+/** pg-pool's own words for a checkout from a pool that has been ended. */
+const POOL_ENDED_MESSAGE = 'Cannot use a pool after calling end on the pool';
+/**
+ * A failed checkout as a typed error.
+ *
+ * pg-pool raises its two checkout failures as plain `Error`s with no code, so
+ * `wrapPgError` (keyed on SQLSTATE and socket codes) passes them through and
+ * the most common production connection failure, an exhausted pool, reached
+ * callers as an untyped error: `instanceof ConnectionError` and
+ * `code === 'TURBINE_E004'` both missed it. Everything else goes through
+ * `wrapPgError` as before.
+ */
+export function checkoutError(err, pool) {
+    if (!(err instanceof Error) || err.code !== undefined)
+        return wrapPgError(err);
+    if (err.message === POOL_TIMEOUT_MESSAGE) {
+        const sizing = (pool ?? {});
+        const max = sizing.options?.max;
+        const waitMs = sizing.options?.connectionTimeoutMillis;
+        const waiting = sizing.waitingCount;
+        const occupancy = max !== undefined
+            ? ` All ${max} connections of the pool were checked out${waiting ? ` and ${waiting} other callers were waiting` : ''}.`
+            : '';
+        return new ConnectionError(`Timed out${waitMs ? ` after ${waitMs}ms` : ''} waiting for a free connection from the pool.${occupancy} ` +
+            'Something is holding connections for longer than `connectionTimeoutMs`: long transactions or streams, ' +
+            'or a query on the outer client inside a `$transaction` callback, which needs a second connection ' +
+            'while the transaction holds the first (use `tx` there). Raise `poolSize` if the load is genuine.', { cause: err });
+    }
+    if (err.message === POOL_ENDED_MESSAGE) {
+        return new ConnectionError('The connection pool has been shut down (`disconnect()` or `end()` was called), so no connection can be ' +
+            'checked out. Create a new client, or stop issuing queries after shutting this one down.', { cause: err });
+    }
+    return wrapPgError(err);
+}
+/**
+ * Make every checkout failure of a pool Turbine owns a typed error, for
+ * `pool.query` as well as `pool.connect`.
+ *
+ * {@link acquireConnection} covers the paths that check out explicitly
+ * (transactions, nested writes, streams, pipelines). An ordinary read or write
+ * goes through `pool.query`, which checks out internally via `this.connect`
+ * in callback form, so the conversion has to sit on `connect` itself. Wrapping
+ * the error is all it does. For pools Turbine creates only, the same rule as
+ * the connection guards: a caller's own pool is not Turbine's to patch.
+ */
+export function typeCheckoutTimeouts(pool) {
+    const p = pool;
+    const connect = p.connect;
+    if (typeof connect !== 'function')
+        return;
+    p.connect = (...args) => {
+        const callback = args[0];
+        if (typeof callback === 'function') {
+            return connect.call(p, (err, ...rest) => callback(err ? checkoutError(err, pool) : err, ...rest));
+        }
+        const pending = connect.apply(p, args);
+        return pending.catch((err) => {
+            throw checkoutError(err, pool);
+        });
+    };
+}
 /**
  * Check a connection out and run `opening` on it, retrying ONCE on a fresh
  * connection when `opening` fails with {@link isStaleConnectionError}.

package/dist/cjs/checkout.d.ts

@@ -34,10 +34,35 @@ export interface Checkout {
  * `DatabaseError` carrying a SQLSTATE in `.code`, the same property Turbine
  * puts `TURBINE_E0NN` in.
  *
- * Query paths need no equivalent: `pool.query()` opens the connection itself
- * and rejects with the connect error, which the query boundary already wraps.
+ * Query paths reach the same errors through `pool.query()`, which checks out
+ * internally and rejects with the connect error; the query boundary wraps
+ * those, and {@link typeCheckoutTimeouts} types pg-pool's own checkout
+ * failures on the pools Turbine owns.
  */
 export declare function acquireConnection(pool: PgCompatPool): Promise<Checkout>;
+/**
+ * A failed checkout as a typed error.
+ *
+ * pg-pool raises its two checkout failures as plain `Error`s with no code, so
+ * `wrapPgError` (keyed on SQLSTATE and socket codes) passes them through and
+ * the most common production connection failure, an exhausted pool, reached
+ * callers as an untyped error: `instanceof ConnectionError` and
+ * `code === 'TURBINE_E004'` both missed it. Everything else goes through
+ * `wrapPgError` as before.
+ */
+export declare function checkoutError(err: unknown, pool?: unknown): unknown;
+/**
+ * Make every checkout failure of a pool Turbine owns a typed error, for
+ * `pool.query` as well as `pool.connect`.
+ *
+ * {@link acquireConnection} covers the paths that check out explicitly
+ * (transactions, nested writes, streams, pipelines). An ordinary read or write
+ * goes through `pool.query`, which checks out internally via `this.connect`
+ * in callback form, so the conversion has to sit on `connect` itself. Wrapping
+ * the error is all it does. For pools Turbine creates only, the same rule as
+ * the connection guards: a caller's own pool is not Turbine's to patch.
+ */
+export declare function typeCheckoutTimeouts(pool: unknown): void;
 /**
  * Check a connection out and run `opening` on it, retrying ONCE on a fresh
  * connection when `opening` fails with {@link isStaleConnectionError}.

package/dist/cjs/checkout.js

@@ -20,6 +20,8 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.acquireConnection = acquireConnection;
+exports.checkoutError = checkoutError;
+exports.typeCheckoutTimeouts = typeCheckoutTimeouts;
 exports.openCheckout = openCheckout;
 const connection_guard_js_1 = require("./connection-guard.js");
 const errors_js_1 = require("./errors.js");
@@ -33,19 +35,90 @@ const errors_js_1 = require("./errors.js");
  * `DatabaseError` carrying a SQLSTATE in `.code`, the same property Turbine
  * puts `TURBINE_E0NN` in.
  *
- * Query paths need no equivalent: `pool.query()` opens the connection itself
- * and rejects with the connect error, which the query boundary already wraps.
+ * Query paths reach the same errors through `pool.query()`, which checks out
+ * internally and rejects with the connect error; the query boundary wraps
+ * those, and {@link typeCheckoutTimeouts} types pg-pool's own checkout
+ * failures on the pools Turbine owns.
  */
 async function acquireConnection(pool) {
+    if (typeof pool.connect !== 'function') {
+        const dialect = pool.dialect?.name;
+        throw new errors_js_1.UnsupportedFeatureError('Checking out a connection', typeof dialect === 'string' ? dialect : 'postgresql', 'A transaction, a cursor stream, a pipeline or a write that takes several statements needs a connection ' +
+            'of its own, and this pool has no `connect()` (a stateless HTTP driver). Pass a pool that can check out ' +
+            'a connection, or run single statements.');
+    }
     let client;
     try {
         client = await pool.connect();
     }
     catch (err) {
-        throw (0, errors_js_1.wrapPgError)(err);
+        throw checkoutError(err, pool);
     }
     return { client, checkout: (0, connection_guard_js_1.guardCheckout)(client) };
 }
+/** pg-pool's own words for a checkout that waited longer than `connectionTimeoutMillis`. */
+const POOL_TIMEOUT_MESSAGE = 'timeout exceeded when trying to connect';
+/** pg-pool's own words for a checkout from a pool that has been ended. */
+const POOL_ENDED_MESSAGE = 'Cannot use a pool after calling end on the pool';
+/**
+ * A failed checkout as a typed error.
+ *
+ * pg-pool raises its two checkout failures as plain `Error`s with no code, so
+ * `wrapPgError` (keyed on SQLSTATE and socket codes) passes them through and
+ * the most common production connection failure, an exhausted pool, reached
+ * callers as an untyped error: `instanceof ConnectionError` and
+ * `code === 'TURBINE_E004'` both missed it. Everything else goes through
+ * `wrapPgError` as before.
+ */
+function checkoutError(err, pool) {
+    if (!(err instanceof Error) || err.code !== undefined)
+        return (0, errors_js_1.wrapPgError)(err);
+    if (err.message === POOL_TIMEOUT_MESSAGE) {
+        const sizing = (pool ?? {});
+        const max = sizing.options?.max;
+        const waitMs = sizing.options?.connectionTimeoutMillis;
+        const waiting = sizing.waitingCount;
+        const occupancy = max !== undefined
+            ? ` All ${max} connections of the pool were checked out${waiting ? ` and ${waiting} other callers were waiting` : ''}.`
+            : '';
+        return new errors_js_1.ConnectionError(`Timed out${waitMs ? ` after ${waitMs}ms` : ''} waiting for a free connection from the pool.${occupancy} ` +
+            'Something is holding connections for longer than `connectionTimeoutMs`: long transactions or streams, ' +
+            'or a query on the outer client inside a `$transaction` callback, which needs a second connection ' +
+            'while the transaction holds the first (use `tx` there). Raise `poolSize` if the load is genuine.', { cause: err });
+    }
+    if (err.message === POOL_ENDED_MESSAGE) {
+        return new errors_js_1.ConnectionError('The connection pool has been shut down (`disconnect()` or `end()` was called), so no connection can be ' +
+            'checked out. Create a new client, or stop issuing queries after shutting this one down.', { cause: err });
+    }
+    return (0, errors_js_1.wrapPgError)(err);
+}
+/**
+ * Make every checkout failure of a pool Turbine owns a typed error, for
+ * `pool.query` as well as `pool.connect`.
+ *
+ * {@link acquireConnection} covers the paths that check out explicitly
+ * (transactions, nested writes, streams, pipelines). An ordinary read or write
+ * goes through `pool.query`, which checks out internally via `this.connect`
+ * in callback form, so the conversion has to sit on `connect` itself. Wrapping
+ * the error is all it does. For pools Turbine creates only, the same rule as
+ * the connection guards: a caller's own pool is not Turbine's to patch.
+ */
+function typeCheckoutTimeouts(pool) {
+    const p = pool;
+    const connect = p.connect;
+    if (typeof connect !== 'function')
+        return;
+    p.connect = (...args) => {
+        const callback = args[0];
+        if (typeof callback === 'function') {
+            return connect.call(p, (err, ...rest) => callback(err ? checkoutError(err, pool) : err, ...rest));
+        }
+        const pending = connect.apply(p, args);
+        return pending.catch((err) => {
+            throw checkoutError(err, pool);
+        });
+    };
+}
 /**
  * Check a connection out and run `opening` on it, retrying ONCE on a fresh
  * connection when `opening` fails with {@link isStaleConnectionError}.

package/dist/cjs/cli/code-first-tags.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Code-first column tags for `turbine generate`.
+ *
+ * `pii`, `updatedAt`, `maxLength` and `tsType` exist only in the `defineSchema()`
+ * file: the database has no column for them, so a client generated from
+ * introspection alone returns PII by default, never stamps `updatedAt`, and
+ * types a `jsonb` column as `unknown`. `generate` reads the schema file and
+ * overlays its tags onto the introspected schema with the two functions here.
+ *
+ * Lives under `cli/` because only the CLI uses it. `schemaDefToMetadata` (the
+ * library path) shares the tag list through `declaredTagsOf`.
+ */
+import { type SchemaMetadata } from '../schema.js';
+import type { SchemaDef } from '../schema-builder.js';
+import { type CodeFirstColumnTags } from '../schema-metadata.js';
+/** Declared tags per table (database name), per column (database name). */
+export type CodeFirstTagMap = Map<string, Map<string, CodeFirstColumnTags>>;
+/**
+ * Collect the code-first-only tags a {@link SchemaDef} declares, keyed by the
+ * database table and column they land on (the same `camelToSnake(field)` rule
+ * {@link schemaDefToMetadata} uses). Tables and columns that declare no tag are
+ * absent from the result.
+ *
+ * Introspection can not see these flags, because the database has no column for
+ * them. `turbine generate` overlays them onto the introspected schema with
+ * {@link applyCodeFirstColumnTags}.
+ */
+export declare function extractCodeFirstColumnTags(def: SchemaDef): CodeFirstTagMap;
+/** What {@link applyCodeFirstColumnTags} changed. */
+export interface AppliedColumnTags {
+    /** Tables that received at least one tag. */
+    tables: number;
+    pii: number;
+    updatedAt: number;
+    maxLength: number;
+    /**
+     * Declared `tsType`s, as generator `columnTypes` entries
+     * (`'<table>.<column>'` by database name). Returned rather than written onto
+     * the schema so they go through the generator's own key and type-text
+     * validation, the same as a `columnTypes` entry in the config file.
+     */
+    columnTypes: Record<string, string>;
+}
+/**
+ * Overlay declared tags onto an introspected schema, in place, matching tables
+ * and columns by their database names.
+ *
+ * `pii` and `updatedAt` are set wherever declared. `maxLength` only fills a gap:
+ * the live column's own length wins when introspection read one.
+ *
+ * A `pii` or `updatedAt` tag that names a table or column the database does not
+ * have is an error, never a skip: a typo or an un-pushed schema would otherwise
+ * generate a client that silently returns the column it was tagged to hide.
+ * Every problem is reported at once. `maxLength` is also in the DDL, so a
+ * missing table or column only costs that fill-in. `inScope` lets the caller say
+ * that a missing table was deliberately left out of the client (an `exclude`
+ * filter), which is not an error either.
+ */
+export declare function applyCodeFirstColumnTags(schema: SchemaMetadata, tags: CodeFirstTagMap, options?: {
+    source?: string;
+    inScope?: (table: string) => boolean;
+}): AppliedColumnTags;

package/dist/cjs/cli/code-first-tags.js

@@ -0,0 +1,124 @@
+"use strict";
+/**
+ * Code-first column tags for `turbine generate`.
+ *
+ * `pii`, `updatedAt`, `maxLength` and `tsType` exist only in the `defineSchema()`
+ * file: the database has no column for them, so a client generated from
+ * introspection alone returns PII by default, never stamps `updatedAt`, and
+ * types a `jsonb` column as `unknown`. `generate` reads the schema file and
+ * overlays its tags onto the introspected schema with the two functions here.
+ *
+ * Lives under `cli/` because only the CLI uses it. `schemaDefToMetadata` (the
+ * library path) shares the tag list through `declaredTagsOf`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractCodeFirstColumnTags = extractCodeFirstColumnTags;
+exports.applyCodeFirstColumnTags = applyCodeFirstColumnTags;
+const errors_js_1 = require("../errors.js");
+const introspect_js_1 = require("../introspect.js");
+const utils_js_1 = require("../query/utils.js");
+const schema_js_1 = require("../schema.js");
+const schema_metadata_js_1 = require("../schema-metadata.js");
+/**
+ * Collect the code-first-only tags a {@link SchemaDef} declares, keyed by the
+ * database table and column they land on (the same `camelToSnake(field)` rule
+ * {@link schemaDefToMetadata} uses). Tables and columns that declare no tag are
+ * absent from the result.
+ *
+ * Introspection can not see these flags, because the database has no column for
+ * them. `turbine generate` overlays them onto the introspected schema with
+ * {@link applyCodeFirstColumnTags}.
+ */
+function extractCodeFirstColumnTags(def) {
+    const out = new Map();
+    for (const tableDef of Object.values(def.tables)) {
+        for (const [field, config] of Object.entries(tableDef.columns)) {
+            const tags = (0, schema_metadata_js_1.declaredTagsOf)(config);
+            if (Object.keys(tags).length === 0)
+                continue;
+            let columns = out.get(tableDef.name);
+            if (!columns) {
+                columns = new Map();
+                out.set(tableDef.name, columns);
+            }
+            columns.set((0, schema_js_1.camelToSnake)(field), tags);
+        }
+    }
+    return out;
+}
+/** A tag the database has no column for, so only the schema file can supply it. */
+function isCodeFirstOnly(tags) {
+    return tags.pii === true || tags.updatedAt === true;
+}
+/**
+ * Overlay declared tags onto an introspected schema, in place, matching tables
+ * and columns by their database names.
+ *
+ * `pii` and `updatedAt` are set wherever declared. `maxLength` only fills a gap:
+ * the live column's own length wins when introspection read one.
+ *
+ * A `pii` or `updatedAt` tag that names a table or column the database does not
+ * have is an error, never a skip: a typo or an un-pushed schema would otherwise
+ * generate a client that silently returns the column it was tagged to hide.
+ * Every problem is reported at once. `maxLength` is also in the DDL, so a
+ * missing table or column only costs that fill-in. `inScope` lets the caller say
+ * that a missing table was deliberately left out of the client (an `exclude`
+ * filter), which is not an error either.
+ */
+function applyCodeFirstColumnTags(schema, tags, options = {}) {
+    const applied = { tables: 0, pii: 0, updatedAt: 0, maxLength: 0, columnTypes: {} };
+    const problems = [];
+    for (const [tableName, columns] of tags) {
+        const shown = (0, introspect_js_1.printableCatalogName)(tableName);
+        if (!Object.hasOwn(schema.tables, tableName)) {
+            if (options.inScope && !options.inScope(tableName))
+                continue;
+            if (![...columns.values()].some(isCodeFirstOnly))
+                continue;
+            const near = (0, utils_js_1.closestName)(tableName, Object.keys(schema.tables));
+            problems.push(`table "${shown}" is not in the database${near ? ` (did you mean "${(0, introspect_js_1.printableCatalogName)(near)}"?)` : ''}`);
+            continue;
+        }
+        const table = schema.tables[tableName];
+        let touched = false;
+        for (const [columnName, declared] of columns) {
+            const column = table.columns.find((c) => c.name === columnName);
+            if (!column) {
+                if (!isCodeFirstOnly(declared))
+                    continue;
+                const near = (0, utils_js_1.closestName)(columnName, table.columns.map((c) => c.name));
+                problems.push(`column "${(0, introspect_js_1.printableCatalogName)(columnName)}" on table "${shown}" is not in the database` +
+                    `${near ? ` (did you mean "${(0, introspect_js_1.printableCatalogName)(near)}"?)` : ''}`);
+                continue;
+            }
+            if (declared.pii) {
+                column.pii = true;
+                applied.pii++;
+                touched = true;
+            }
+            if (declared.updatedAt) {
+                column.updatedAt = true;
+                applied.updatedAt++;
+                touched = true;
+            }
+            if (declared.maxLength !== undefined && column.maxLength === undefined) {
+                column.maxLength = declared.maxLength;
+                applied.maxLength++;
+                touched = true;
+            }
+            if (declared.tsType !== undefined) {
+                applied.columnTypes[`${tableName}.${columnName}`] = declared.tsType;
+                touched = true;
+            }
+        }
+        if (touched)
+            applied.tables++;
+    }
+    if (problems.length > 0) {
+        const from = options.source ? ` in ${options.source}` : '';
+        throw new errors_js_1.ValidationError(`Cannot apply the column tags declared${from}: ${problems.join('; ')}. ` +
+            'Run `turbine push` so the database has them, or fix the name in the schema file. ' +
+            'Generating without the tags would return the columns they mark as PII.');
+    }
+    return applied;
+}

package/dist/cjs/cli/compile-query.js

@@ -108,6 +108,9 @@ exports.COLUMN_NAMING_ARG_KEYS = [
     '_avg',
     '_min',
     '_max',
+    // Keys are column names and the result is a stored value (or one equal to it),
+    // the same reason `_min` / `_max` are listed.
+    '_percentile',
 ];
 /**
  * Does this args object carry a key that names a column, AT ANY DEPTH?
@@ -154,6 +157,12 @@ function carriesColumnNamingArg(args, depth = 0) {
 // ---------------------------------------------------------------------------
 // Compile
 // ---------------------------------------------------------------------------
+/**
+ * Any non-array object, class instances included. Deliberately NOT the shared
+ * `isPlainRecord`: the builder walks a `with` (and a `where`) by its own keys
+ * whatever its prototype, so a report that skipped a class-instance `with`
+ * would list no relation while the SQL loads one.
+ */
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }