uql-orm 0.77.0 → 0.77.1

package/dist/querier/queryError.d.ts

@@ -1,4 +1,5 @@
 import type { LoggerWrapper } from '../util/logger.js';
+import { type QueryErrorKind } from '../util/uqlError.js';
 /**
  * A driver error tagged by {@link enrichError}: `query` always, `values` only when the logger already
  * surfaces them, since they can carry PII or tokens into whatever serializes the error.
@@ -7,33 +8,6 @@ export interface QueryError extends Error {
     query?: string;
     values?: unknown[];
 }
-/**
- * What a failed query ran into, named the same on every engine. `retryable` is a deadlock, a
- * serialization failure, a lock timeout or a busy database: the transaction can simply run again.
- */
-export type QueryErrorKind = 'uniqueViolation' | 'foreignKeyViolation' | 'notNullViolation' | 'checkViolation' | 'optimisticLock' | 'retryable';
-/**
- * Thrown when an update's `@Field({ version })` no longer matches the row: another writer moved it on,
- * or it is gone. `expected` is what the payload carried, `actual` what the row holds now, `undefined`
- * where there is no row left. `status` is what an HTTP transport answers with.
- */
-export declare class UqlOptimisticLockError extends Error {
-    readonly expected: unknown;
-    readonly actual: unknown;
-    name: string;
-    readonly status = 409;
-    constructor(message: string, expected: unknown, actual: unknown);
-}
-/**
- * Thrown where a write cannot carry the optimistic lock: an update payload without its version, or a
- * method with no version to match. A `TypeError` still, since the caller used the API wrong, but one
- * carrying the `status` an HTTP transport answers with - the request is malformed, not the server's
- * failure, and an untyped client is exactly who reaches this.
- */
-export declare class UqlLockUsageError extends TypeError {
-    name: string;
-    readonly status = 400;
-}
 /**
  * Names what `err` ran into on any engine, or `undefined` for anything else. Pure: the error is only
  * read, so it works on any driver error, whether or not a querier saw it first.

package/dist/querier/queryError.js

@@ -1,29 +1,4 @@
-/**
- * Thrown when an update's `@Field({ version })` no longer matches the row: another writer moved it on,
- * or it is gone. `expected` is what the payload carried, `actual` what the row holds now, `undefined`
- * where there is no row left. `status` is what an HTTP transport answers with.
- */
-export class UqlOptimisticLockError extends Error {
-    expected;
-    actual;
-    name = 'UqlOptimisticLockError';
-    status = 409;
-    constructor(message, expected, actual) {
-        super(message);
-        this.expected = expected;
-        this.actual = actual;
-    }
-}
-/**
- * Thrown where a write cannot carry the optimistic lock: an update payload without its version, or a
- * method with no version to match. A `TypeError` still, since the caller used the API wrong, but one
- * carrying the `status` an HTTP transport answers with - the request is malformed, not the server's
- * failure, and an untyped client is exactly who reaches this.
- */
-export class UqlLockUsageError extends TypeError {
-    name = 'UqlLockUsageError';
-    status = 400;
-}
+import { UqlOptimisticLockError, UqlUsageError } from '../util/uqlError.js';
 /** Postgres, CockroachDB, PGlite and Neon in `code`; Bun SQL in `errno`. */
 const SQLSTATE_KINDS = new Map([
     ['23505', 'uniqueViolation'],
@@ -78,8 +53,8 @@ export function queryErrorKind(err) {
     if (typeof err !== 'object' || err === null) {
         return undefined;
     }
-    if (err instanceof UqlOptimisticLockError) {
-        return 'optimisticLock';
+    if (err instanceof UqlOptimisticLockError || err instanceof UqlUsageError) {
+        return err.kind;
     }
     const { code, errno, number, errorLabels, message } = err;
     const text = typeof message === 'string' ? message : '';

package/dist/sqlite/sqliteDialect.js

@@ -34,9 +34,7 @@ export const SQLITE_FEATURES = {
     serverSideCursors: false,
     correlatedWrites: true,
     rowLocks: false,
-    rowLockWithWindow: true,
     nullsOrdering: 'clause',
-    rowLockOf: true,
     textScoreIndexes: false,
     orderedUpsertReturning: true,
     orderedJsonAggregates: true,

package/dist/type/dialect.d.ts

@@ -135,15 +135,27 @@ export interface DialectFeatures {
      * such a write reads the ids of the rows it names first.
      */
     readonly correlatedWrites: boolean;
+    /**
+     * What the engine's row locks can do, or `false` where it has none: the SQLite family locks the
+     * database and MongoDB has no row lock at all, so both refuse `$lock` rather than ignoring it. One
+     * value rather than a flag each, since the details mean nothing without a lock.
+     */
+    readonly rowLocks: RowLockFeatures | false;
+}
+/** How a dialect spells a row lock, once {@link DialectFeatures.rowLocks} says it has one. */
+export interface RowLockFeatures {
+    /** Whether a lock can be narrowed to one table of a join, `FOR UPDATE OF`, which MariaDB lacks. */
+    readonly of: boolean;
+    /** Whether the lock may share a statement with a window function, which the Postgres family refuses. */
+    readonly withWindow: boolean;
+    /**
+     * Where the lock is spelled: after the statement (`FOR UPDATE`), or as a hint on the table it reads
+     * (`WITH (UPDLOCK)`, SQL Server). A dialect's `lockHint` states the hint itself.
+     */
+    readonly placement: 'suffix' | 'tableHint';
 }
 /** What a SQL engine can do beyond {@link DialectFeatures}, read where a statement is built. */
 export interface SqlDialectFeatures extends DialectFeatures {
-    /** Whether the engine has row locks at all. The SQLite family locks the database instead. */
-    readonly rowLocks: boolean;
-    /** Whether `FOR UPDATE` may share a statement with a window function, which the Postgres family refuses. */
-    readonly rowLockWithWindow: boolean;
-    /** Whether a lock can be narrowed to one table of a join, `FOR UPDATE OF`, which MariaDB lacks. */
-    readonly rowLockOf: boolean;
     /**
      * How a `$sort` states where nulls land: the `NULLS FIRST/LAST` clause, a leading `IS NULL` term
      * (MySQL, MariaDB), or a leading `CASE` (SQL Server, which has no orderable boolean).

package/dist/type/queryAggregate.js

@@ -1,3 +1,4 @@
+import { UqlUsageError } from '../util/uqlError.js';
 const QUERY_AGGREGATE_OPS = ['$count', '$sum', '$avg', '$min', '$max'];
 /**
  * Whether `op` is one of {@link QueryAggregateOp}'s known aggregate operators - validates operator
@@ -17,5 +18,5 @@ export function resolveAggregateOp(key) {
     if (isQueryAggregateOp(key)) {
         return { op: key, distinct: false };
     }
-    throw new TypeError(`unsupported aggregate operator: ${key}`);
+    throw new UqlUsageError(`unsupported aggregate operator: ${key}`);
 }

package/dist/type/queryLock.js

@@ -1,3 +1,4 @@
+import { UqlUsageError } from '../util/uqlError.js';
 const QUERY_LOCK_WAITS = ['nowait', 'skip'];
 function isOneOf(vals, val) {
     return vals.includes(val);
@@ -15,7 +16,7 @@ export function parseQueryLock(lock) {
         return 'block';
     }
     if (!isOneOf(QUERY_LOCK_WAITS, lock.$wait)) {
-        throw new TypeError(`unknown $lock wait policy: ${String(lock.$wait)}`);
+        throw new UqlUsageError(`unknown $lock wait policy: ${String(lock.$wait)}`);
     }
     return lock.$wait;
 }

package/dist/type/queryWhere.d.ts

@@ -1,7 +1,7 @@
 import type { FieldKey, JsonFieldPaths, JsonFieldPathValue, RelationKey, RelationTarget } from './entity.js';
 import type { QuerySelect } from './query.js';
 import type { QueryRaw } from './queryRaw.js';
-import type { ExpandScalar, IsMany, QueryComparableScalar, Scalar } from './utility.js';
+import type { AtLeastOne, ExpandScalar, IsMany, QueryComparableScalar, Scalar } from './utility.js';
 import type { QueryVectorQuery } from './vector.js';
 /**
  * options for full-text-search operator.
@@ -95,12 +95,13 @@ export type QuerySizeComparisonOps = {
 };
 /**
  * Filter by distance to a vector, `{ $near: { $vector: v, $lt: 0.35 } }`: ordered bounds only, since a
- * distance is a float. Each clause names its own `$vector`, and `$distance` falls back to the field's.
- * One with no bound is refused at run time, where `/http` input is checked anyway.
+ * distance is a float, and at least one, since none would filter nothing. Each clause names its own
+ * `$vector`, and `$distance` falls back to the field's. `/http` input is untyped, so the dialect
+ * checks it again at run time.
  */
-export type QueryVectorNear = QueryVectorQuery & {
-    [K in QueryOrderedOp]?: NonNullable<QueryWhereFieldOperatorMap<number>[K]>;
-};
+export type QueryVectorNear = QueryVectorQuery & AtLeastOne<{
+    [K in QueryOrderedOp]: NonNullable<QueryWhereFieldOperatorMap<number>[K]>;
+}>;
 export type QueryWhereFieldOperatorMap<T, Raw = QueryRaw> = {
     /**
      * whether a value is equal to the given value.

package/dist/type/utility.d.ts

@@ -59,6 +59,14 @@ export type RejectKeys<K> = [K] extends [never] ? unknown : Record<K & string, n
 export type ExactlyOne<T> = {
     [K in keyof T]: Readonly<Pick<T, K>> & Partial<Readonly<Record<Exclude<keyof T, K>, never>>>;
 }[keyof T];
+/**
+ * At least one key of `T` with its value, the rest optional: the looser sibling of {@link ExactlyOne},
+ * for options that combine but cannot all be left out. `Pick`, so every key stays linked to `T`'s own
+ * property and renames follow it through.
+ */
+export type AtLeastOne<T> = Partial<T> & {
+    [K in keyof T]: Pick<T, K>;
+}[keyof T];
 export type Unpacked<T> = T extends readonly (infer U)[] ? U : T extends (...args: unknown[]) => infer U ? U : T extends Promise<infer U> ? U : T;
 /**
  * Whether the value a property holds is many rather than one: a to-many relation, a scalar array, a

package/dist/util/dialect.util.js

@@ -4,6 +4,7 @@ import { QueryRaw, resolveAggregateOp, SOFT_DELETE_FILTER, } from '../type/index
 import { DEFAULT_VECTOR_DISTANCE, VECTOR_INDEX_TYPES } from '../type/vector.js';
 import { getFieldKeys, isDatabaseWritten } from './field.util.js';
 import { entityName, getKeys, hasKeys, isOperatorObject, isScalarId, isRecord, isWhereMap, someKey, } from './object.util.js';
+import { UqlUsageError } from './uqlError.js';
 /** The keys of `payload` a write persists as columns. */
 export function filterFieldKeys(meta, payload, callbackKey) {
     return getKeys(payload).filter((key) => {
@@ -194,7 +195,7 @@ export function findVectorSort(sort) {
 export function vectorCandidates(q) {
     const candidates = q.$candidates;
     if (candidates !== undefined && (!Number.isInteger(candidates) || candidates < 1)) {
-        throw new TypeError(`$candidates must be a positive integer, got ${JSON.stringify(candidates)}`);
+        throw new UqlUsageError(`$candidates must be a positive integer, got ${JSON.stringify(candidates)}`);
     }
     return candidates;
 }
@@ -260,7 +261,7 @@ export function isFieldUpdateOp(value) {
  */
 export function fieldUpdateOf(key, value) {
     if (value.$inc !== undefined && value.$mul !== undefined) {
-        throw new TypeError(`'${key}' takes one of $inc and $mul`);
+        throw new UqlUsageError(`'${key}' takes one of $inc and $mul`);
     }
     return value.$inc === undefined ? ['$mul', value.$mul] : ['$inc', value.$inc];
 }
@@ -280,7 +281,7 @@ export function whereIds(meta, ids) {
  */
 export function assertWhere(meta, where) {
     if (!isWhereMap(where)) {
-        throw new TypeError(`$where on '${entityName(meta)}' must be a map of conditions, such as { id: 1 }`);
+        throw new UqlUsageError(`$where on '${entityName(meta)}' must be a map of conditions, such as { id: 1 }`);
     }
 }
 /** Returns a `QueryOptions.filters` value with the built-in soft-delete filter disabled (used by hard delete). */
@@ -353,7 +354,7 @@ export function parseRelationSize(val) {
     }
     const siblings = getKeys(val).filter((key) => key !== '$size');
     if (siblings.length) {
-        throw new TypeError(`$size on a relation cannot be combined with other conditions: ${siblings.join(', ')}`);
+        throw new UqlUsageError(`$size on a relation cannot be combined with other conditions: ${siblings.join(', ')}`);
     }
     return val.$size;
 }
@@ -368,7 +369,7 @@ export function parseSortByCount(val) {
     }
     const siblings = getKeys(val).filter((key) => key !== '$count');
     if (siblings.length) {
-        throw new TypeError(`$count in a $sort cannot be combined with other keys: ${siblings.join(', ')}`);
+        throw new UqlUsageError(`$count in a $sort cannot be combined with other keys: ${siblings.join(', ')}`);
     }
     return val.$count;
 }
@@ -393,13 +394,13 @@ export function parseGroupMap(group, select) {
         const call = select[alias];
         const key = getKeys(call).find((name) => name !== '$where');
         if (key === undefined) {
-            throw new TypeError(`aggregate '${alias}' names no op, only a $where`);
+            throw new UqlUsageError(`aggregate '${alias}' names no op, only a $where`);
         }
         // `$countDistinct` normalizes to `$count` plus a `distinct` flag.
         const { op, distinct } = resolveAggregateOp(key);
         const field = aggregateField(alias, call[key]);
         if (field === undefined && (op !== '$count' || distinct)) {
-            throw new TypeError(`aggregate '${alias}' takes '*' only as a $count`);
+            throw new UqlUsageError(`aggregate '${alias}' takes '*' only as a $count`);
         }
         entries.push({ kind: 'fn', alias, op, distinct, ...(field && { field }), ...(hasKeys(where) ? { where } : {}) });
     }
@@ -409,7 +410,7 @@ export function parseGroupMap(group, select) {
 function groupRefPath(alias, ref) {
     const [key, ...rest] = isRecord(ref) ? getKeys(ref) : [];
     if (!isRecord(ref) || key === undefined || rest.length) {
-        throw new TypeError(`$group '${alias}' names one field by the path to it: got ${JSON.stringify(ref)}`);
+        throw new UqlUsageError(`$group '${alias}' names one field by the path to it: got ${JSON.stringify(ref)}`);
     }
     return ref[key] === true ? [key] : [key, ...groupRefPath(alias, ref[key])];
 }
@@ -420,7 +421,7 @@ function aggregateField(alias, arg) {
     }
     const [field, ...rest] = namedKeys(arg);
     if (field === undefined || rest.length) {
-        throw new TypeError(`aggregate '${alias}' takes one field as { field: true }, or '*': got ${JSON.stringify(arg)}`);
+        throw new UqlUsageError(`aggregate '${alias}' takes one field as { field: true }, or '*': got ${JSON.stringify(arg)}`);
     }
     return field;
 }
@@ -454,7 +455,7 @@ export function isJsonObject(value) {
  */
 export function assertNonNegativeInteger(value, clause) {
     if (!Number.isInteger(value) || value < 0) {
-        throw new TypeError(`${clause} must be a non-negative integer, got ${value}`);
+        throw new UqlUsageError(`${clause} must be a non-negative integer, got ${value}`);
     }
     return value;
 }
@@ -464,7 +465,7 @@ export function assertNonNegativeInteger(value, clause) {
  * SQL and MongoDB refuse the same query with the same words.
  */
 export function throwUnknownAggregateColumn(key, clause) {
-    throw new TypeError(`cannot ${clause} by '${key}': it is neither a $group column nor a $select alias`);
+    throw new UqlUsageError(`cannot ${clause} by '${key}': it is neither a $group column nor a $select alias`);
 }
 /** {@link throwUnknownAggregateColumn} over every key of a clause, for backends that check up front. */
 export function assertAggregateColumns(clauseMap, emitted, clause) {
@@ -529,7 +530,7 @@ export function textSortOf(sort) {
  */
 export function rankedTextSearch(where) {
     if (!where?.$text) {
-        throw new TypeError('$sort by $text ranks by the $text at the root of $where, which this query has none of');
+        throw new UqlUsageError('$sort by $text ranks by the $text at the root of $where, which this query has none of');
     }
     return where.$text;
 }
@@ -551,5 +552,5 @@ export function textSearchFields(meta, search) {
     const declared = fulltext.length
         ? `${fulltext.length} fulltext indexes to choose from`
         : 'no fulltext index to search';
-    throw new TypeError(`$text on '${name}' names no $fields, and '${name}' declares ${declared}. Name them with $fields.`);
+    throw new UqlUsageError(`$text on '${name}' names no $fields, and '${name}' declares ${declared}. Name them with $fields.`);
 }

package/dist/util/relationQuery.util.js

@@ -1,5 +1,6 @@
 import { QUERY_BOOLEAN_CLAUSES, QUERY_NUMBER_CLAUSES, QUERY_OBJECT_CLAUSES, QUERY_STATEMENT_CLAUSES, } from '../type/query.js';
 import { getKeys, isRecord, someKey } from './object.util.js';
+import { UqlUsageError } from './uqlError.js';
 /** What a query populating nothing requests, shared: most reads populate nothing, and ask on every one. */
 const NOTHING_REQUESTED = Object.freeze({
     requestedKeys: Object.freeze([]),
@@ -65,7 +66,7 @@ function assertJoinableRelationQuery(relKey, value) {
     }
     for (const [key, reason] of JOINED_RELATION_REJECTED_KEYS) {
         if (key in value) {
-            throw new TypeError(`'${key}' is not supported inside $populate of the to-one relation '${relKey}': ${reason}.`);
+            throw new UqlUsageError(`'${key}' is not supported inside $populate of the to-one relation '${relKey}': ${reason}.`);
         }
     }
 }
@@ -138,7 +139,7 @@ export function parseRelationQueryValue(value) {
     if (isRecord(value)) {
         const statementOnly = QUERY_STATEMENT_CLAUSES.find((clause) => clause in value);
         if (statementOnly) {
-            throw new TypeError(`'${statementOnly}' applies to the whole statement, not to a populated relation. Move it to the top level of the query.`);
+            throw new UqlUsageError(`'${statementOnly}' applies to the whole statement, not to a populated relation. Move it to the top level of the query.`);
         }
     }
     if (isRelationQueryObject(value)) {
@@ -152,7 +153,7 @@ export function parseRelationQueryValue(value) {
         return { query: { $select: selectMap }, required: false, nested: false };
     }
     if (value !== undefined && value !== null && value !== true && value !== 1) {
-        throw new TypeError(`Invalid relation query value '${String(value)}'. Expected true/1, relation query object, or relation $populate array.`);
+        throw new UqlUsageError(`Invalid relation query value '${String(value)}'. Expected true/1, relation query object, or relation $populate array.`);
     }
     return { query: {}, required: false, nested: false };
 }

package/dist/util/uqlError.d.ts

@@ -0,0 +1,39 @@
+/**
+ * What a failed query ran into, named the same on every engine - what {@link queryErrorKind} answers
+ * with, whether a driver raised the error or UQL did. `retryable` is a deadlock, a serialization
+ * failure, a lock timeout or a busy database: the transaction can simply run again. `usage` is the
+ * caller's own mistake, which running it again will not fix.
+ */
+export type QueryErrorKind = 'uniqueViolation' | 'foreignKeyViolation' | 'notNullViolation' | 'checkViolation' | 'optimisticLock' | 'retryable' | 'usage';
+/**
+ * Thrown where the caller used the API in a way no statement can carry out: an update payload with no
+ * version, a `$lock` outside a transaction, a method with no version to match. A `TypeError` still,
+ * since the call itself is wrong, but one carrying the `status` an HTTP transport answers with - the
+ * request is malformed, not the server's failure, and an untyped client is exactly who reaches this.
+ */
+export declare class UqlUsageError extends TypeError {
+    name: string;
+    /** What `queryErrorKind` answers, so a caller branches on it rather than on the class. */
+    readonly kind = "usage";
+    /** What an HTTP transport answers with. */
+    readonly status = 400;
+}
+/**
+ * @deprecated since 0.77.1 - use {@link UqlUsageError}, which every misuse throws, lock or not. The
+ * same class under both names, so an existing `instanceof` keeps working.
+ */
+export declare const UqlLockUsageError: typeof UqlUsageError;
+export type UqlLockUsageError = UqlUsageError;
+/**
+ * Thrown when an update's `@Field({ version })` no longer matches the row: another writer moved it on,
+ * or it is gone. `expected` is what the payload carried, `actual` what the row holds now, `undefined`
+ * where there is no row left.
+ */
+export declare class UqlOptimisticLockError extends Error {
+    readonly expected: unknown;
+    readonly actual: unknown;
+    name: string;
+    readonly kind = "optimisticLock";
+    readonly status = 409;
+    constructor(message: string, expected: unknown, actual: unknown);
+}

package/dist/util/uqlError.js

@@ -0,0 +1,35 @@
+/**
+ * Thrown where the caller used the API in a way no statement can carry out: an update payload with no
+ * version, a `$lock` outside a transaction, a method with no version to match. A `TypeError` still,
+ * since the call itself is wrong, but one carrying the `status` an HTTP transport answers with - the
+ * request is malformed, not the server's failure, and an untyped client is exactly who reaches this.
+ */
+export class UqlUsageError extends TypeError {
+    name = 'UqlUsageError';
+    /** What `queryErrorKind` answers, so a caller branches on it rather than on the class. */
+    kind = 'usage';
+    /** What an HTTP transport answers with. */
+    status = 400;
+}
+/**
+ * @deprecated since 0.77.1 - use {@link UqlUsageError}, which every misuse throws, lock or not. The
+ * same class under both names, so an existing `instanceof` keeps working.
+ */
+export const UqlLockUsageError = UqlUsageError;
+/**
+ * Thrown when an update's `@Field({ version })` no longer matches the row: another writer moved it on,
+ * or it is gone. `expected` is what the payload carried, `actual` what the row holds now, `undefined`
+ * where there is no row left.
+ */
+export class UqlOptimisticLockError extends Error {
+    expected;
+    actual;
+    name = 'UqlOptimisticLockError';
+    kind = 'optimisticLock';
+    status = 409;
+    constructor(message, expected, actual) {
+        super(message);
+        this.expected = expected;
+        this.actual = actual;
+    }
+}

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://uql-orm.dev",
   "description": "The JSON-native TypeScript ORM for Bun, Browsers, Edge, Deno, Node, Workers. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, SQL Server, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
   "license": "MIT",
-  "version": "0.77.0",
+  "version": "0.77.1",
   "type": "module",
   "engines": {
     "node": ">=24"

package/skills/uql-orm/SKILL.md

@@ -82,7 +82,7 @@ export class Post {
 - `@Field({ type: Number, version: true })`, with `[versionKey]?: 'version'` on the class, makes the column an
   optimistic lock: every update payload must carry the version it read (a compile error otherwise), the update
   matches on it and writes the next one, and a write against a row someone else moved on throws
-  `UqlOptimisticLockError` (`status` 409) instead of overwriting it. Save and upsert are refused on such an entity; the update is named by its id, so `updateMany` over a many-row filter is refused too, and delete and restore carry no version.
+  `UqlOptimisticLockError` (kind `optimisticLock`, HTTP 409) instead of overwriting it. Save and upsert are refused on such an entity; the update is named by its id, so `updateMany` over a many-row filter is refused too, and delete and restore carry no version.
 - `defineEntity` defines the same entity without decorators: https://uql-orm.dev/entities/imperative.md
 
 ## Queries
@@ -124,6 +124,12 @@ const users = await pool.findMany(User, {
 - An update takes `{ stock: { $inc: -1 } }` to add, or `$mul` to multiply, in the statement, a NULL counting as 0,
   so a guard in `$where` (`stock: { $gte: 1 }`) makes a decrement race-safe. JSON fields take `$set`, `$unset`,
   `$push`, `$pull`.
+- `$lock: true` locks the rows a read returns (`{ $wait: 'skip' | 'nowait' }` says what to do about a row
+  someone else holds) and needs an open transaction; SQLite, libSQL, Turso, D1 and MongoDB have no row lock and
+  refuse it.
+- `queryErrorKind(err)` names any failure the same on every engine - `uniqueViolation`, `foreignKeyViolation`,
+  `notNullViolation`, `checkViolation`, `optimisticLock`, `retryable`, `usage` - so catch by kind rather than by
+  a driver's code or an `instanceof`.
 - `raw()` embeds SQL anywhere a value or field goes; `pool.all(sql, values)` runs a raw `SELECT`.
 
 ## Connections and transactions