@bakery-framework/orm 2.0.0-alpha.9 → 2.0.0-rc.2

package/README.md

@@ -24,9 +24,9 @@ export const posts = table('posts', {
 ```
 
 Register it so the query builder is typed. Without this block everything still
-runs — the columns are just permissive `any`:
+runs: the columns are just permissive `any`:
 
-```ts no-check — ./schema is the sibling file from the block above, which only exists in a real app
+```ts no-check: ./schema is the sibling file from the block above, which only exists in a real app
 // orm/index.ts
 import type { InferOptionals, InferSchema, InferViews } from '@bakery-framework/orm'
 import * as model from './schema'
@@ -54,7 +54,7 @@ const rows = await DB.from('posts').selectAll('posts').array()
 await DB.Insert.into('posts').values({ title: 'Hello', body: 'World' }).run()
 ```
 
-Identifiers are snake_cased on the way to SQL — `createdAt` becomes
+Identifiers are snake_cased on the way to SQL: `createdAt` becomes
 `created_at`. Values always bind as parameters.
 
 ## Schema sync
@@ -68,7 +68,7 @@ process.exit(0)
 
 Diffs the database against your schema and applies the difference, prompting
 before anything destructive. `NODE_ENV=production` makes destructive changes
-refuse rather than prompt — set it on any deployed host.
+refuse rather than prompt. Set it on any deployed host.
 
 ## Adapters
 
@@ -78,11 +78,11 @@ round-trips in CI, which is not the same as being battle-tested.
 
 ## License
 
-MIT with the Commons Clause v1.0 — see [LICENSE](./LICENSE).
+MIT with the Commons Clause v1.0. See [LICENSE](./LICENSE).
 
-**Not an OSI-approved licence.** The Commons Clause removes the right to *sell*
-the software — meaning to charge for a product or service whose value derives
+**Not an OSI-approved license.** The Commons Clause removes the right to *sell*
+the software: meaning to charge for a product or service whose value derives
 substantially from it, hosting and support included. Everything else the MIT
-licence grants is unchanged: use it, modify it, ship it inside your own product.
-If your organisation only permits OSI-approved dependencies, this will not pass
+license grants is unchanged: use it, modify it, ship it inside your own product.
+If your organization only permits OSI-approved dependencies, this will not pass
 that check.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bakery-framework/orm",
-  "version": "2.0.0-alpha.9",
+  "version": "2.0.0-rc.2",
   "description": "Bakery database layer: adapters, query builder, schema sync and backup.",
   "keywords": [
     "bakery",
@@ -51,9 +51,9 @@
     "!src/tests"
   ],
   "engines": {
-    "bun": ">=1.3.14"
+    "bun": ">=1.4.0"
   },
   "dependencies": {
-    "@bakery-framework/core": "^2.0.0-alpha.9"
+    "@bakery-framework/core": "^2.0.0-rc.2"
   }
 }

package/src/adapters/base.ts

@@ -10,7 +10,7 @@ import type { Driver as RegisteredDriver } from './registry'
 export namespace SQLAdapter {
   /**
    * Kept as `SQLAdapter.Driver` because that is what the ~40 existing call
-   * sites say, but the list itself now lives in `registry.ts` — a namespace
+   * sites say, but the list itself now lives in `registry.ts`: a namespace
    * member cannot be declaration-merged from another package, and adding a
    * driver has to be possible from outside.
    */
@@ -35,10 +35,21 @@ export namespace SQLAdapter {
   }
   export interface TableDetails {
     name: string
-    rowCount: number
+    /**
+     * `null` unless the caller asked for counts. A `COUNT(*)` is a full scan
+     * on SQLite and Postgres, and `getSchema()` is on the write path (every
+     * explorer write introspects to resolve row identity), so the scan is paid
+     * only where a number is actually displayed. `null`, not `0`: a count that
+     * was never taken must not read as an empty table.
+     */
+    rowCount: number | null
     columns: TableColumnInfo[]
     indexes: TableIndexInfo[]
   }
+  export interface SchemaOptions {
+    /** Take the per-table `COUNT(*)`. Off by default. See `rowCount`. */
+    rowCounts?: boolean
+  }
   export interface TableDataResult {
     rows: any[]
     totalRows: number
@@ -50,7 +61,7 @@ export namespace SQLAdapter {
   // as in `sync/types.ts`, and this copy had fallen behind: no `length`, no
   // `_enum`, no `_oldColumn`/`_transform`, and a `type` union missing `bigint`
   // and `json`. The three sync call sites that cast to it were therefore
-  // *erasing* the fields at the exact point they are read — harmless only
+  // *erasing* the fields at the exact point they are read: harmless only
   // because `colDef` takes `unknown`. One declaration now, in `sync/types.ts`.
 
   export type RowRecord = MapOf<any>
@@ -62,7 +73,33 @@ export namespace SQLAdapter {
   export interface TableDataOptions extends FilterSortOptions {
     page: number
     pageSize: number
+    /**
+     * A total the caller already has, so the `COUNT(*)` can be skipped.
+     *
+     * **The count is almost the whole cost of a page.** Measured on a
+     * 200,000-row SQLite table with a page size of 50, reading page 101:
+     *
+     *     count, no filter    11.7 ms      rows, no filter    0.4 ms
+     *     count, filtered     51.3 ms      rows, filtered     1.6 ms
+     *
+     * 97% of the work either way. The rows come off an index and stop at the
+     * page; the count has to visit every row that matches, and a filtered
+     * count visits them a second time after the rows query already did.
+     *
+     * Opt-in and caller-asserted, because it trades a guarantee for that.
+     * Passing a total says "I counted, with exactly these filters" - an
+     * adapter cannot check it, and a wrong one shows a wrong row count and a
+     * wrong page count. It never affects which rows come back, so the
+     * failure mode is a stale readout rather than wrong data. Paging through
+     * a table while another writer inserts is exactly when it goes stale, and
+     * exactly when re-counting on every page is least worth it.
+     *
+     * Ignored unless it is a non-negative finite number, so a bad value
+     * degrades to the count rather than to a negative page total.
+     */
+    knownTotal?: number
   }
+
   export interface NameRow {
     name: string
   }
@@ -79,7 +116,7 @@ export namespace SQLAdapter {
    * The slice of a Bun `SQL` handle that transaction nesting needs.
    *
    * Structural rather than `SQL`, because the base class holds `sql` as
-   * `unknown` — each adapter narrows it — and because both members are
+   * `unknown` (each adapter narrows it), and because both members are
    * verified by probe rather than by the type: `savepoint` is present on the
    * root connection and on every transaction and savepoint handle in Bun
    * 1.3.14, on all three dialects.
@@ -112,7 +149,7 @@ export namespace SQLAdapter {
  * 32,766 for every dialect, deliberately below the two that could go higher.
  * The counter that overflows is 16 bits and it does not *fail* on overflow, it
  * wraps: a 120,000-parameter insert reported `expected 54464 values, received
- * 120000` — 120000 − 65536 — which reads like memory corruption rather than a
+ * 120000` (120000 − 65536), which reads like memory corruption rather than a
  * limit being hit. Half the 16-bit ceiling leaves room for whatever bookkeeping
  * a driver adds on top of the parameters we counted, and the cost of the extra
  * round trips is nothing next to the bytes those parameters weigh.
@@ -124,14 +161,14 @@ export const DEFAULT_MAX_QUERY_PARAMS = 32766
  * open one from?
  *
  * A duck check, because `value instanceof SQL` is unusable: Bun's `SQL` export
- * has no `prototype` property at all — it is `undefined` as of 1.3.14 — and
+ * has no `prototype` property at all. It is `undefined` as of 1.3.14, and
  * `instanceof` against it does not return false, it **throws**
  * `instanceof called on an object with an invalid prototype property` for every
  * object operand. The MySQL and Postgres constructors read as if they tested
  * this and did not: `instanceof` short-circuits to false for a primitive
  * *before* it touches the right operand, so the string form never reached the
- * throw and the only caller that passes a real handle — `transaction()`,
- * wrapping the connection Bun hands its callback — failed every time it ran.
+ * throw and the only caller that passes a real handle (`transaction()`,
+ * wrapping the connection Bun hands its callback) failed every time it ran.
  *
  * `typeof` covers `function` as well as `object` because a Bun connection is
  * callable: it is the tagged-template entry point, with `unsafe` hung off it.
@@ -156,8 +193,8 @@ export function quoteIdentifier(name: string, quoteChar: string): string {
 /**
  * How many rows one `iterate()` chunk fetches. See {@link pagedIterate}.
  *
- * Big enough that the round trips are amortised, small enough that the point of
- * streaming — never holding the whole result — survives. Not a tuning knob
+ * Big enough that the round trips are amortized, small enough that the point of
+ * streaming (never holding the whole result) survives. Not a tuning knob
  * anyone has measured; it is a default, and `createExecutor` takes an override.
  */
 export const DEFAULT_STREAM_CHUNK = 500
@@ -166,7 +203,7 @@ export const DEFAULT_STREAM_CHUNK = 500
  * `iterate()`, built out of `all()` by paging.
  *
  * **Bun cannot stream.** As of 1.3.14 an `SQLQuery` is a thenable and nothing
- * more — no `Symbol.asyncIterator`, no `Symbol.iterator`, and its own methods
+ * more, no `Symbol.asyncIterator`, no `Symbol.iterator`, and its own methods
  * (`raw`, `simple`, `values`, `execute`, `run`) all resolve the whole result.
  * The adapters used to hand their raw query object to `for await`, which is why
  * `iterate` threw `… .iterate is not a function` on **every** dialect and why
@@ -180,17 +217,45 @@ export const DEFAULT_STREAM_CHUNK = 500
  * ```
  *
  * Verified on all three dialects against live servers, including a statement
- * that already carries its own `ORDER BY` or `LIMIT` — the derived table
+ * that already carries its own `ORDER BY` or `LIMIT`: the derived table
  * contains it, so the window composes rather than colliding. MySQL needs the
  * alias; the other two tolerate it.
  *
  * **What this is not.** It is not a server-side cursor, and the difference is
  * observable, so say it plainly: the statement is re-executed once per chunk,
  * and chunk boundaries are only stable under a total order. Rows inserted or
- * deleted mid-walk can therefore be seen twice or missed — the same hazard
+ * deleted mid-walk can therefore be seen twice or missed: the same hazard
  * offset pagination has, and exactly what `seek()` exists to avoid. What it
  * does buy is the thing people reach for streaming to get: memory bounded by
  * the chunk instead of by the result.
+ *
+ * **What it costs, and why it is not one number.** The statement is
+ * re-executed per chunk, so the total is the chunk count times whatever one
+ * window costs, and what one window costs depends entirely on whether the
+ * ordering can be served from an index. If it cannot, every chunk sorts the
+ * whole result and throws away the offset, which is quadratic in the chunk
+ * count. Measured on 100,000 rows, a chunk size of 500, so 200 statements:
+ *
+ *     sqlite    ORDER BY the primary key     all 180 ms   iterate    593 ms     3x
+ *     sqlite    ORDER BY an unindexed column all 275 ms   iterate 35,687 ms   130x
+ *     postgres  ORDER BY the primary key     all  83 ms   iterate  1,590 ms    19x
+ *     postgres  ORDER BY an unindexed column all 126 ms   iterate 12,767 ms   101x
+ *
+ * Thirty-five seconds to walk what `all()` returns in 275 ms. The backlog
+ * recorded a flat "393x", which is the right neighborhood for the unindexed
+ * case and says nothing about the case a caller can fix: **order by something
+ * indexed and the cost collapses by 40x.**
+ *
+ * The two dialects differ for different reasons. Postgres pays a network round
+ * trip per chunk, which is why its indexed case is 19x where SQLite's is 3x.
+ * SQLite pays nothing for the trip and everything for the sort, which is why
+ * its unindexed case is the worst of the four.
+ *
+ * So: reach for this when the result does not fit in memory, not when it is
+ * merely large. If it fits, `all()` is between 3 and 130 times faster. If it
+ * does not, index the column you order by, and prefer `seek()` where the shape
+ * allows it: that is keyset pagination and it has neither the cost nor the
+ * skipped-row hazard described above.
  */
 export function pagedIterate(
   all: SQLAdapter.Executor['all'],
@@ -215,16 +280,16 @@ export function createExecutor(
   run: SQLAdapter.Executor['run'],
   driver: SQLAdapter.Driver,
   options: {
-    /** Replace the paging walker — for a driver that can genuinely stream. */
+    /** Replace the paging walker: for a driver that can genuinely stream. */
     iterate?: SQLAdapter.Executor['iterate']
     chunkSize?: number
   } = {},
 ): SQLAdapter.Executor {
   const iterate = options.iterate ?? pagedIterate(all, options.chunkSize)
   // `get` and `values` call the raw `all` rather than `exec.all`, which is a
-  // behavioural detail worth stating: it is what keeps one executed statement
+  // behavioral detail worth stating: it is what keeps one executed statement
   // to exactly one observer event. Routing them through the observed `exec.all`
-  // would report every `.get()` twice — once as `get`, once as `all` — and a
+  // would report every `.get()` twice (once as `get`, once as `all`), and a
   // "slowest queries" panel built on double-counted rows is worse than none.
   return {
     all: observe(driver, 'all', all, rows =>
@@ -263,7 +328,7 @@ export abstract class SQLAdapter {
    * The database this connection is pointed at, or `undefined`.
    *
    * Parsed from the URL rather than asked of the server, because the one caller
-   * — normalising a stored view body — runs inside the diff and must not add a
+   * (normalizing a stored view body) runs inside the diff and must not add a
    * round trip to it. SQLite has no such name and needs none: it does not
    * qualify a view's tables in the first place.
    *
@@ -281,7 +346,7 @@ export abstract class SQLAdapter {
   }
 
   /**
-   * Placeholder ceiling for a single statement — see
+   * Placeholder ceiling for a single statement. See
    * {@link DEFAULT_MAX_QUERY_PARAMS} for why it is one number and not three.
    *
    * A getter rather than a field so a dialect that genuinely differs can
@@ -292,6 +357,47 @@ export abstract class SQLAdapter {
     return DEFAULT_MAX_QUERY_PARAMS
   }
 
+  /**
+   * Whether a caller-supplied total can be used in place of a `COUNT(*)`.
+   *
+   * One rule in one place, because all three adapters answer it and a dialect
+   * that disagreed would be a bug rather than a capability. A static on the
+   * class rather than a function in the namespace: the namespace is declared
+   * above the class it merges with, so it can hold types and not values.
+   */
+  static usableTotal(value: unknown): value is number {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0
+  }
+
+  /**
+   * A cheap value that changes whenever the schema changes, or `null`.
+   *
+   * The capability is expressed by the return, not by a boolean beside it: a
+   * dialect that cannot answer this cheaply returns `null` and its callers
+   * fall back to asking the schema directly. That is the default here, so a
+   * new adapter is correct without implementing anything.
+   *
+   * **It must not move for ordinary DML.** A value that changed on every
+   * `INSERT` would still be *correct* as a cache key and useless as one,
+   * invalidating on the busiest thing a database does. SQLite's
+   * `PRAGMA schema_version` has exactly the right semantics, verified rather
+   * than assumed: it advances on `CREATE TABLE`, on `ALTER TABLE ... ADD
+   * COLUMN` and on `DROP TABLE`, and stays put across an `INSERT`.
+   *
+   * A method rather than one of the capability *getters* above because it
+   * costs a round trip. Those describe the dialect and are answered from
+   * nothing; this one asks the server.
+   *
+   * Postgres and MySQL return `null`. Neither exposes a single counter for
+   * this - Postgres has no schema-level equivalent of `schema_version`, and
+   * MySQL's `information_schema` would have to be aggregated, which is the
+   * expense being avoided. Adding one later is a per-adapter override and
+   * needs no change here or in any caller.
+   */
+  async schemaFingerprint(): Promise<string | null> {
+    return null
+  }
+
   constructor(
     public readonly driver: SQLAdapter.Driver,
     public readonly filename?: string,
@@ -315,7 +421,7 @@ export abstract class SQLAdapter {
    *
    * Set by {@link transaction} on the child it just built, never by a
    * constructor. Inferring it from "was I handed an open connection?" would be
-   * a guess — a pooled handle is open too, and issuing `SAVEPOINT` outside a
+   * a guess: a pooled handle is open too, and issuing `SAVEPOINT` outside a
    * transaction block is an error on Postgres and a silent no-op on MySQL.
    * Only `transaction` knows for certain, because it is what opened the thing.
    */
@@ -328,18 +434,18 @@ export abstract class SQLAdapter {
   protected abstract withConnection(sql: unknown): SQLAdapter
 
   /**
-   * Run `callback` atomically — `BEGIN` at the top level, `SAVEPOINT` within an
+   * Run `callback` atomically: `BEGIN` at the top level, `SAVEPOINT` within an
    * enclosing transaction.
    *
    * The dispatch is the whole point. Bun refuses a nested `BEGIN` outright
    * (`cannot call begin inside a transaction use savepoint() instead`, verbatim
    * on all three dialects), so before this, any two transactional functions
-   * that composed — `createUser()` called from `importUsers()`, both perfectly
-   * reasonable alone — crashed the moment they met.
+   * that composed (`createUser()` called from `importUsers()`, both perfectly
+   * reasonable alone) crashed the moment they met.
    *
    * A failed inner block rolls back to its own savepoint and nothing more, so
    * an outer transaction that catches the error keeps its own work. It only
-   * gets the whole thing if it lets the error propagate — which is the same
+   * gets the whole thing if it lets the error propagate, which is the same
    * rule a single transaction already follows.
    */
   async transaction<T>(
@@ -366,7 +472,7 @@ export abstract class SQLAdapter {
    * A table-level `FOREIGN KEY` clause, for inclusion in `CREATE TABLE`.
    *
    * Emitted inline rather than by `ALTER` wherever possible, because SQLite has
-   * no `ALTER TABLE ADD FOREIGN KEY` at all — inline is the only spelling all
+   * no `ALTER TABLE ADD FOREIGN KEY` at all: inline is the only spelling all
    * three dialects share.
    */
   foreignKeyClause(fk: SyncTypes.ForeignKeyInfo): string {
@@ -396,8 +502,8 @@ export abstract class SQLAdapter {
    * One spelling for a referential action, whatever the dialect called it.
    *
    * Postgres reports a single character rather than a word; MySQL and SQLite
-   * report the word. Anything unrecognised becomes `NO ACTION` — the SQL
-   * default — so a dialect that grows a new code cannot make the diff churn.
+   * report the word. Anything unrecognized becomes `NO ACTION` (the SQL
+   * default), so a dialect that grows a new code cannot make the diff churn.
    */
   static normalizeForeignKeyAction(raw: unknown): SyncTypes.ForeignKeyAction {
     const v = String(raw ?? '')
@@ -434,7 +540,7 @@ export abstract class SQLAdapter {
    *
    * `cols` names the unique columns that decide "already there"; `targets` are
    * the columns to overwrite, empty meaning "insert if absent". Both arrive as
-   * declared — snake-casing and quoting happen here, so the caller never has to
+   * declared: snake-casing and quoting happen here, so the caller never has to
    * know which dialect it is talking to.
    */
   upsertClause(cols: string[], targets: string[]): string {
@@ -451,7 +557,7 @@ export abstract class SQLAdapter {
    * Which end of a batched multi-row insert `lastInsertRowid` refers to.
    *
    * A large insert is split into batches, so the id has to be taken from one of
-   * them — and the dialects do not agree which. SQLite and Postgres report the
+   * them, and the dialects do not agree which. SQLite and Postgres report the
    * *last* row written; MySQL's `insertId` reports the *first* of the block.
    * Taking the matching end keeps each dialect's own answer true rather than
    * inventing a third one.
@@ -477,7 +583,7 @@ export abstract class SQLAdapter {
    * A rebuild is `CREATE t_temp` → copy → `DROP TABLE t` →
    * `RENAME t_temp TO t`,
    * and two of the three dialects refuse to run it while a view still names `t`
-   * — at different steps, and with different messages:
+   *: at different steps, and with different messages:
    *
    * - **SQLite** refuses the *rename*: `error in view v: no such table: main.t`
    * - **Postgres** refuses the *drop*: `cannot drop table t because other
@@ -486,7 +592,7 @@ export abstract class SQLAdapter {
    *   it resolves a view's tables at query time rather than binding them at
    *   creation.
    *
-   * So this is `true` by default and MySQL is the exception — the reverse of
+   * So this is `true` by default and MySQL is the exception: the reverse of
    * how it first reads. Where it holds, the planner drops declared views before
    * the rebuild phase and recreates them a moment later; where it does not, the
    * drop is skipped and the views are simply left alone.
@@ -496,7 +602,7 @@ export abstract class SQLAdapter {
   }
 
   /**
-   * `INTERSECT ALL` and `EXCEPT ALL` — the duplicate-preserving forms.
+   * `INTERSECT ALL` and `EXCEPT ALL`: the duplicate-preserving forms.
    *
    * `UNION ALL` is universal and is not covered by this; only the other two
    * are. MySQL grew them in 8.0.31 and Postgres has always had them; SQLite
@@ -511,7 +617,7 @@ export abstract class SQLAdapter {
    * `FULL OUTER JOIN`.
    *
    * Postgres has it; SQLite gained it in 3.39 and the version Bun bundles has
-   * it. **MySQL has never had it**, at any version — the workaround there is a
+   * it. **MySQL has never had it**, at any version: the workaround there is a
    * `LEFT JOIN` unioned with a `RIGHT JOIN`, which is a different query rather
    * than a flag, so the builder refuses instead of rewriting silently.
    */
@@ -534,7 +640,9 @@ export abstract class SQLAdapter {
     ).run()
   }
 
-  abstract getSchema(): Promise<SQLAdapter.TableDetails[]>
+  abstract getSchema(
+    options?: SQLAdapter.SchemaOptions,
+  ): Promise<SQLAdapter.TableDetails[]>
 
   /**
    * Foreign keys as the database has them, keyed by the tuple that identifies
@@ -553,7 +661,7 @@ export abstract class SQLAdapter {
    *
    * Names are deliberately excluded. SQLite's `PRAGMA foreign_key_list` does
    * not report one, so a name-keyed diff would see every SQLite foreign key as
-   * new on every sync — the perpetual-rebuild failure this project has hit
+   * new on every sync: the perpetual-rebuild failure this project has hit
    * repeatedly. The tuple is the same on all three dialects.
    */
   static foreignKeyId(fk: {
@@ -582,7 +690,7 @@ export abstract class SQLAdapter {
         refTable: String(r.parent),
         refCols: [] as string[],
         name: key,
-        // Normalised here, not at the call site: Postgres reports a single
+        // Normalized here, not at the call site: Postgres reports a single
         // character where MySQL reports a word, and the diff has to compare one
         // vocabulary or it replaces every key on every sync.
         onDelete: SQLAdapter.normalizeForeignKeyAction(r.on_delete),
@@ -713,7 +821,7 @@ export abstract class SQLAdapter {
   protected async preSync(_tx: SQLAdapter): Promise<void> {}
   protected async postSync(_tx: SQLAdapter): Promise<void> {}
   /**
-   * Patterns recognised when reading a default back *out* of the database.
+   * Patterns recognized when reading a default back *out* of the database.
    * Matched loosely (parens stripped, uppercased, `includes`), so a prefix
    * fragment is a perfectly good entry here.
    */
@@ -722,8 +830,8 @@ export abstract class SQLAdapter {
   /**
    * The complete SQL expression emitted *into* DDL for a `%dateNow%` default.
    *
-   * Deliberately separate from `dateNowDefaults`. Conflating the two — emitting
-   * `dateNowDefaults[0]` — is what produced `DEFAULT (EXTRACT(EPOCH FROM)` on
+   * Deliberately separate from `dateNowDefaults`. Conflating the two (emitting
+   * `dateNowDefaults[0]`) is what produced `DEFAULT (EXTRACT(EPOCH FROM)` on
    * Postgres and `DEFAULT (UNIX_TIMESTAMP)` on MySQL: a prefix is fine to match
    * against and fatal to emit. SQLite only escaped because its match pattern
    * happened to be a complete expression.
@@ -752,7 +860,7 @@ export abstract class SQLAdapter {
 
   /**
    * Loose match: parens stripped, uppercased, substring. A prefix fragment is a
-   * perfectly good entry in the pattern lists — and is fatal to *emit*, which
+   * perfectly good entry in the pattern lists, and is fatal to *emit*, which
    * is the whole reason the emitted expression is a separate field.
    */
   private matchesMarker(
@@ -771,12 +879,12 @@ export abstract class SQLAdapter {
   /**
    * The declared width of a **sized** text column, or `undefined`.
    *
-   * The guard is the entire point, and it is not defensive coding — it is a
+   * The guard is the entire point, and it is not defensive coding: it is a
    * measured result. MySQL reports `character_maximum_length = 65535` for an
    * unsized `TEXT` column, where Postgres reports `null`. Take the number
    * unconditionally and every `Field.Text()` column reads back as
    * `length: 65535`, the schema says nothing, the two never agree, and MySQL
-   * rebuilds the table on every sync forever — the exact failure that kept
+   * rebuilds the table on every sync forever, the exact failure that kept
    * `length` out of the diff until it could be checked against real servers.
    *
    * So: a width counts only when the dialect also calls the column a *sized*
@@ -799,8 +907,7 @@ export abstract class SQLAdapter {
   /**
    * A `CHECK (col IN (…))` clause restricting a column to a set of values.
    *
-   * Takes the column name because a CHECK has to name it. Values bind nowhere —
-   * this is DDL — so they are quoted the same way `formatDefault` quotes a
+   * Takes the column name because a CHECK has to name it. Values bind nowhere (   * this is DDL), so they are quoted the same way `formatDefault` quotes a
    * string default, by doubling the single quote.
    */
   protected enumClause(column: string, values: string[]): string {
@@ -815,7 +922,7 @@ export abstract class SQLAdapter {
     const isStr = typeof def === 'string'
     if (isStr && def.toUpperCase() === 'NULL') return null
     // `def.trim() !== ''` first, because `Number('')` is `0` and `Number(' ')`
-    // is `0` — so an empty-string default came back as the *number* zero. The
+    // is `0`, so an empty-string default came back as the *number* zero. The
     // schema then said `''`, the database said `0`, and the column was rebuilt
     // on every single sync, forever.
     //
@@ -850,22 +957,21 @@ export abstract class SQLAdapter {
   }
 
   /**
-   * The `LIKE` escape character — `!`, and deliberately **not** a backslash.
+   * The `LIKE` escape character: `!`, and deliberately **not** a backslash.
    *
-   * A backslash is the obvious choice and is unusable here. MySQL processes
-   * backslash escapes inside string literals where SQLite and Postgres do not,
-   * so the clause would need to differ per dialect; and worse, Postgres never
-   * receives what is written. `normalizePostgresSQL` treats `\'` as an escaped
-   * quote — MySQL's rule, applied to every dialect — so `ESCAPE '\'` leaves the
-   * string literal *open*, swallows the rest of the statement, and the driver
-   * reports `syntax error at or near "OFFSET"` from a clause several tokens
-   * later.
+   * A backslash is the obvious choice and is still the wrong one. MySQL
+   * processes backslash escapes inside string literals where SQLite and
+   * Postgres do not, so `ESCAPE '\'` would need a per-dialect spelling, and
+   * the whole point of one escape character is one clause for all three.
    *
-   * That normalizer behaviour is a real defect and is not fixed here: a test
-   * pins it (`a backslash escape keeps the character it escapes`), and changing
-   * it would change every literal the framework emits. Choosing a character
-   * with no meaning to any of the three parsers sidesteps it entirely, and one
-   * spelling for all dialects beats a capability getter per dialect.
+   * The Postgres normalizer used to make this worse: it applied MySQL's rule
+   * to every dialect, so `'\'` swallowed its own closing quote and the driver
+   * reported a syntax error several tokens later. That defect is fixed (the
+   * scanner now has no opinion about backslashes, matching the server), and
+   * `a backslash in a literal is a character, not an escape` pins it. `!` stays
+   * regardless, because MySQL's literal-level escaping is the server's real
+   * behavior, not a scanner bug, and a character with no meaning to any of the
+   * three parsers needs no capability getter.
    */
   protected readonly likeEscape = '!'
 
@@ -877,7 +983,7 @@ export abstract class SQLAdapter {
    * Make a value match literally under `LIKE`.
    *
    * Without this a search for `50%` matches every row and one for `a_b` matches
-   * `axb` — `%` and `_` are the wildcards, and the filter passed user input
+   * `axb`: `%` and `_` are the wildcards, and the filter passed user input
    * through untouched. The escape character itself goes first, or escaping it
    * afterwards would double the ones this method just added.
    */
@@ -933,7 +1039,7 @@ export abstract class SQLAdapter {
    * One filter, as SQL. Returns `null` when the filter says nothing.
    *
    * `params` is appended to rather than returned, because an operator may bind
-   * one value, two, or none at all — `IS NULL` has nothing to bind, and
+   * one value, two, or none at all: `IS NULL` has nothing to bind, and
    * pretending otherwise is how a placeholder count drifts from its arguments.
    */
   private filterClause(
@@ -953,8 +1059,8 @@ export abstract class SQLAdapter {
 
     const { op, value } = raw as { op?: string; value?: unknown }
 
-    // No value to bind, and none expected — these two are the whole reason a
-    // filter cannot be modelled as a plain column/value pair.
+    // No value to bind, and none expected: these two are the whole reason a
+    // filter cannot be modeled as a plain column/value pair.
     if (op === 'null') return `${quoted} IS NULL`
     if (op === 'notnull') return `${quoted} IS NOT NULL`
 
@@ -1231,6 +1337,19 @@ export class DatabaseStatement {
   values(...params: any[]) {
     return this.connection.execute.values(this.sql, params)
   }
+  /**
+   * Walk the result a chunk at a time, holding only the chunk.
+   *
+   * **Not a cursor, and not cheap.** Bun cannot stream, so this pages: the
+   * statement becomes a derived table and is re-executed once per 500 rows.
+   * On 100,000 rows that is 200 statements, and the total depends on whether
+   * the ordering is indexed: 3x `all()` on SQLite ordered by a primary key,
+   * **130x** ordered by a column with no index (35.7 seconds against 275 ms).
+   * The full table and the reasoning are on {@link pagedIterate}.
+   *
+   * Use it when the result does not fit in memory. When it does, `all()` is
+   * faster by between 3 and 130 times.
+   */
   iterate(...params: any[]) {
     return this.connection.execute.iterate(this.sql, params)
   }