dbgate-sqlite-dumper 0.1.0

package/dist/types-CTyJTzB6.d.cts

@@ -0,0 +1,151 @@
+/**
+ * Client-agnostic SQLite connection abstraction.
+ *
+ * The core package never imports a Node.js driver directly. Callers provide
+ * a {@link SqliteConnection} (or a {@link SqliteConnectionSource} that can
+ * acquire one) implemented by an adapter such as
+ * `dbgate-sqlite-dumper/better-sqlite3`.
+ *
+ * SQLite is an embedded engine, so a "connection" here is one open database
+ * handle. The contract is deliberately the same shape the sibling dumper
+ * packages use for their network drivers, so an application can treat every
+ * dumper the same way.
+ */
+/** Scalar values accepted as bound query parameters (`?` placeholders). */
+type SqliteParameterValue = string | number | bigint | Buffer | Uint8Array | null;
+/** A single SQL statement plus its positional (`?`) parameters. */
+interface SqliteQuery {
+    readonly sql: string;
+    /** Bound in order for each `?` placeholder. Adapters must never string-interpolate these. */
+    readonly parameters?: readonly SqliteParameterValue[];
+}
+/**
+ * Scalar values that can appear in a returned row: SQLite's five storage
+ * classes as JavaScript sees them.
+ *
+ * `INTEGER` may arrive as `number` or `bigint` depending on the adapter; the
+ * core never relies on either for exactness. Row data is read through SQL
+ * that has SQLite itself render every numeric value as text (see
+ * `data/valueQuery.ts`), so a 64-bit integer or a `REAL`'s exact digits
+ * never pass through a JavaScript number on the way into the dump.
+ */
+type SqliteColumnValue = string | number | bigint | Buffer | Uint8Array | null;
+/** A single result row, keyed by column name. */
+interface SqliteRow {
+    readonly [column: string]: SqliteColumnValue;
+}
+/** Buffered result of a non-streaming query. */
+interface SqliteQueryResult<Row extends SqliteRow = SqliteRow> {
+    readonly rows: readonly Row[];
+    /** Result column names, in order, when the adapter can report them. */
+    readonly columns?: readonly string[];
+}
+interface SqliteStreamOptions {
+    readonly signal?: AbortSignal;
+    /**
+     * Hint for adapters that fetch rows in batches. SQLite steps one row at a
+     * time in-process, so most adapters simply ignore it.
+     */
+    readonly batchSize?: number;
+}
+/** Result of executing one statement through {@link SqliteConnection.execute}. */
+interface SqliteExecResult {
+    /**
+     * Rows inserted, updated or deleted by *this* statement — `0` for DDL and
+     * for statements that return rows. Adapters must not report SQLite's
+     * `sqlite3_changes()` for a statement that is not DML, because it still
+     * holds the count from the previous DML statement.
+     */
+    readonly changes: number;
+}
+/** Structured information about a SQLite error, extracted by an adapter. */
+interface SqliteErrorInfo {
+    /** Symbolic (extended) result code, e.g. `SQLITE_CONSTRAINT_UNIQUE`. */
+    readonly code?: string;
+    /** Numeric (extended) result code, e.g. `2067`, when the adapter can report it. */
+    readonly errno?: number;
+    readonly message: string;
+}
+/**
+ * One open SQLite database handle.
+ *
+ * Implementations must serialize statements sent through the same handle.
+ * In particular, while a {@link stream} is being consumed no other statement
+ * is sent on it — this package never interleaves them, because most
+ * synchronous drivers refuse to run a second statement while one is still
+ * stepping.
+ */
+interface SqliteConnection {
+    query<Row extends SqliteRow = SqliteRow>(query: SqliteQuery, signal?: AbortSignal): Promise<SqliteQueryResult<Row>>;
+    /** Streams rows without buffering the full result set in memory. */
+    stream<Row extends SqliteRow = SqliteRow>(query: SqliteQuery, options?: SqliteStreamOptions): AsyncIterable<Row>;
+    /**
+     * Executes one already-complete statement's SQL text with no parameter
+     * binding and no client-side rewriting.
+     *
+     * Restore routes every statement through this rather than `query()`
+     * because a dump's statement text must reach SQLite byte for byte: a driver
+     * that treats `?` or `:name` as a placeholder would corrupt any `INSERT`
+     * carrying one inside a string literal. Adapters that cannot make this
+     * guarantee may omit it; callers then fall back to `query()` with no
+     * parameters.
+     */
+    execute?(sql: string, signal?: AbortSignal): Promise<SqliteExecResult>;
+    /** Extracts structured error fields from a driver error, for diagnostics. */
+    describeError?(error: unknown): SqliteErrorInfo | undefined;
+    /**
+     * Whether a transaction is open on this handle (`!sqlite3_get_autocommit`).
+     *
+     * SQLite has no SQL-level way to ask this, and it matters: a restore that
+     * stops part-way through a dump's own `BEGIN TRANSACTION` must roll it back
+     * before handing the handle back, or the caller inherits an open
+     * transaction holding a write lock on the file. Adapters that cannot answer
+     * may omit it; restore then tracks the script's own transaction statements
+     * instead.
+     */
+    isInTransaction?(): boolean;
+    /**
+     * Turns `SQLITE_DBCONFIG_DEFENSIVE` on or off.
+     *
+     * A dump of a database containing virtual tables recreates them by
+     * inserting into `sqlite_schema` under `PRAGMA writable_schema=ON` — exactly
+     * as the native `.dump` does — and defensive mode forbids that. Restore
+     * uses this, when the adapter provides it, to lift the restriction for the
+     * duration of such a restore and put it back afterwards.
+     */
+    setDefensive?(enabled: boolean): Promise<void>;
+    /**
+     * Requests cancellation of the currently executing statement, if any.
+     * Synchronous drivers cannot interrupt a statement mid-step; they
+     * implement this as a no-op, and cancellation then takes effect between
+     * rows and between statements.
+     */
+    cancel(): Promise<void>;
+}
+/** A connection acquired from a pool-like source, plus its release callback. */
+interface AcquiredSqliteConnection {
+    readonly connection: SqliteConnection;
+    /**
+     * Whether this handle is exclusively held for the duration of the
+     * operation. `false` for a bare {@link SqliteConnection} the caller handed
+     * over directly — it may be shared, so any state this package changes on
+     * it must be restored rather than assumed discarded.
+     */
+    readonly dedicated: boolean;
+    /** Idempotent; safe to call more than once. */
+    release(): Promise<void>;
+}
+/**
+ * Represents a resource that must be acquired to obtain one database
+ * handle, such as a pool of handles onto the same file. Direct
+ * {@link SqliteConnection} instances are borrowed by the library and are
+ * never closed by it.
+ */
+interface SqliteConnectionSource {
+    acquire(signal?: AbortSignal): Promise<AcquiredSqliteConnection>;
+}
+/** Anything the public API accepts in place of a database handle. */
+type SqliteConnectionInput = SqliteConnection | SqliteConnectionSource;
+declare function isSqliteConnectionSource(input: SqliteConnectionInput): input is SqliteConnectionSource;
+
+export { type AcquiredSqliteConnection as A, type SqliteConnection as S, type SqliteConnectionInput as a, type SqliteExecResult as b, type SqliteRow as c, type SqliteErrorInfo as d, type SqliteColumnValue as e, type SqliteConnectionSource as f, type SqliteParameterValue as g, type SqliteQuery as h, type SqliteQueryResult as i, type SqliteStreamOptions as j, isSqliteConnectionSource as k };

package/dist/types-CTyJTzB6.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Client-agnostic SQLite connection abstraction.
+ *
+ * The core package never imports a Node.js driver directly. Callers provide
+ * a {@link SqliteConnection} (or a {@link SqliteConnectionSource} that can
+ * acquire one) implemented by an adapter such as
+ * `dbgate-sqlite-dumper/better-sqlite3`.
+ *
+ * SQLite is an embedded engine, so a "connection" here is one open database
+ * handle. The contract is deliberately the same shape the sibling dumper
+ * packages use for their network drivers, so an application can treat every
+ * dumper the same way.
+ */
+/** Scalar values accepted as bound query parameters (`?` placeholders). */
+type SqliteParameterValue = string | number | bigint | Buffer | Uint8Array | null;
+/** A single SQL statement plus its positional (`?`) parameters. */
+interface SqliteQuery {
+    readonly sql: string;
+    /** Bound in order for each `?` placeholder. Adapters must never string-interpolate these. */
+    readonly parameters?: readonly SqliteParameterValue[];
+}
+/**
+ * Scalar values that can appear in a returned row: SQLite's five storage
+ * classes as JavaScript sees them.
+ *
+ * `INTEGER` may arrive as `number` or `bigint` depending on the adapter; the
+ * core never relies on either for exactness. Row data is read through SQL
+ * that has SQLite itself render every numeric value as text (see
+ * `data/valueQuery.ts`), so a 64-bit integer or a `REAL`'s exact digits
+ * never pass through a JavaScript number on the way into the dump.
+ */
+type SqliteColumnValue = string | number | bigint | Buffer | Uint8Array | null;
+/** A single result row, keyed by column name. */
+interface SqliteRow {
+    readonly [column: string]: SqliteColumnValue;
+}
+/** Buffered result of a non-streaming query. */
+interface SqliteQueryResult<Row extends SqliteRow = SqliteRow> {
+    readonly rows: readonly Row[];
+    /** Result column names, in order, when the adapter can report them. */
+    readonly columns?: readonly string[];
+}
+interface SqliteStreamOptions {
+    readonly signal?: AbortSignal;
+    /**
+     * Hint for adapters that fetch rows in batches. SQLite steps one row at a
+     * time in-process, so most adapters simply ignore it.
+     */
+    readonly batchSize?: number;
+}
+/** Result of executing one statement through {@link SqliteConnection.execute}. */
+interface SqliteExecResult {
+    /**
+     * Rows inserted, updated or deleted by *this* statement — `0` for DDL and
+     * for statements that return rows. Adapters must not report SQLite's
+     * `sqlite3_changes()` for a statement that is not DML, because it still
+     * holds the count from the previous DML statement.
+     */
+    readonly changes: number;
+}
+/** Structured information about a SQLite error, extracted by an adapter. */
+interface SqliteErrorInfo {
+    /** Symbolic (extended) result code, e.g. `SQLITE_CONSTRAINT_UNIQUE`. */
+    readonly code?: string;
+    /** Numeric (extended) result code, e.g. `2067`, when the adapter can report it. */
+    readonly errno?: number;
+    readonly message: string;
+}
+/**
+ * One open SQLite database handle.
+ *
+ * Implementations must serialize statements sent through the same handle.
+ * In particular, while a {@link stream} is being consumed no other statement
+ * is sent on it — this package never interleaves them, because most
+ * synchronous drivers refuse to run a second statement while one is still
+ * stepping.
+ */
+interface SqliteConnection {
+    query<Row extends SqliteRow = SqliteRow>(query: SqliteQuery, signal?: AbortSignal): Promise<SqliteQueryResult<Row>>;
+    /** Streams rows without buffering the full result set in memory. */
+    stream<Row extends SqliteRow = SqliteRow>(query: SqliteQuery, options?: SqliteStreamOptions): AsyncIterable<Row>;
+    /**
+     * Executes one already-complete statement's SQL text with no parameter
+     * binding and no client-side rewriting.
+     *
+     * Restore routes every statement through this rather than `query()`
+     * because a dump's statement text must reach SQLite byte for byte: a driver
+     * that treats `?` or `:name` as a placeholder would corrupt any `INSERT`
+     * carrying one inside a string literal. Adapters that cannot make this
+     * guarantee may omit it; callers then fall back to `query()` with no
+     * parameters.
+     */
+    execute?(sql: string, signal?: AbortSignal): Promise<SqliteExecResult>;
+    /** Extracts structured error fields from a driver error, for diagnostics. */
+    describeError?(error: unknown): SqliteErrorInfo | undefined;
+    /**
+     * Whether a transaction is open on this handle (`!sqlite3_get_autocommit`).
+     *
+     * SQLite has no SQL-level way to ask this, and it matters: a restore that
+     * stops part-way through a dump's own `BEGIN TRANSACTION` must roll it back
+     * before handing the handle back, or the caller inherits an open
+     * transaction holding a write lock on the file. Adapters that cannot answer
+     * may omit it; restore then tracks the script's own transaction statements
+     * instead.
+     */
+    isInTransaction?(): boolean;
+    /**
+     * Turns `SQLITE_DBCONFIG_DEFENSIVE` on or off.
+     *
+     * A dump of a database containing virtual tables recreates them by
+     * inserting into `sqlite_schema` under `PRAGMA writable_schema=ON` — exactly
+     * as the native `.dump` does — and defensive mode forbids that. Restore
+     * uses this, when the adapter provides it, to lift the restriction for the
+     * duration of such a restore and put it back afterwards.
+     */
+    setDefensive?(enabled: boolean): Promise<void>;
+    /**
+     * Requests cancellation of the currently executing statement, if any.
+     * Synchronous drivers cannot interrupt a statement mid-step; they
+     * implement this as a no-op, and cancellation then takes effect between
+     * rows and between statements.
+     */
+    cancel(): Promise<void>;
+}
+/** A connection acquired from a pool-like source, plus its release callback. */
+interface AcquiredSqliteConnection {
+    readonly connection: SqliteConnection;
+    /**
+     * Whether this handle is exclusively held for the duration of the
+     * operation. `false` for a bare {@link SqliteConnection} the caller handed
+     * over directly — it may be shared, so any state this package changes on
+     * it must be restored rather than assumed discarded.
+     */
+    readonly dedicated: boolean;
+    /** Idempotent; safe to call more than once. */
+    release(): Promise<void>;
+}
+/**
+ * Represents a resource that must be acquired to obtain one database
+ * handle, such as a pool of handles onto the same file. Direct
+ * {@link SqliteConnection} instances are borrowed by the library and are
+ * never closed by it.
+ */
+interface SqliteConnectionSource {
+    acquire(signal?: AbortSignal): Promise<AcquiredSqliteConnection>;
+}
+/** Anything the public API accepts in place of a database handle. */
+type SqliteConnectionInput = SqliteConnection | SqliteConnectionSource;
+declare function isSqliteConnectionSource(input: SqliteConnectionInput): input is SqliteConnectionSource;
+
+export { type AcquiredSqliteConnection as A, type SqliteConnection as S, type SqliteConnectionInput as a, type SqliteExecResult as b, type SqliteRow as c, type SqliteErrorInfo as d, type SqliteColumnValue as e, type SqliteConnectionSource as f, type SqliteParameterValue as g, type SqliteQuery as h, type SqliteQueryResult as i, type SqliteStreamOptions as j, isSqliteConnectionSource as k };

package/docs/architecture.md

@@ -0,0 +1,157 @@
+# Architecture
+
+The package is a stack of layers, each usable on its own. Nothing above the `connection`
+layer knows what driver is in use; nothing below the `api` layer knows about a dump as a
+whole.
+
+```
+                     ┌──────────────────────────────────────────┐
+  api/               │ dumpSqlite()  ·  restoreSqlDump()        │  orchestration
+                     └──────────────────────────────────────────┘
+                            │              │            │
+  introspection/  ──────────┘              │            └────── restore/
+    sqlite_schema + pragmas → model        │                     sqlite3_complete + shell
+                                           │                     line rules → statements
+  archive/  ─────── plan: what & in what order
+  renderer/  ────── model + plan → plain SQL text        preflight/  compatibility/
+  data/  ────────── rows → INSERT statements             selection/  security/
+  writer/  ──────── text/bytes → Writable                version/    model/
+                            │
+                     ┌──────────────────────────────────────────┐
+  connection/        │ SqliteConnection (driver-agnostic)       │
+                     └──────────────────────────────────────────┘
+                            │
+  better-sqlite3.ts ─ the only module that knows better-sqlite3 exists
+```
+
+This mirrors `dbgate-mysql-dumper`, `dbgate-pg-dumper`, `dbgate-mssql-dumper` and
+`dbgate-redis-dumper`; the SQLite-specific differences are called out below.
+
+## `connection/` — the driver boundary
+
+`SqliteConnection` is the whole contract between this package and a driver: `query()`,
+`stream()`, and optional `execute()`, `describeError()`, `isInTransaction()` and
+`setDefensive()`, plus `cancel()`. The core never imports a driver, and
+`tests/packageBoundaries.test.ts` fails if it starts to.
+
+SQLite is embedded, so a "connection" is one open database handle. The contract keeps the
+shape of the network drivers' in the sibling packages — including `SqliteConnectionSource`
+for pool-like inputs — so an application can drive every dumper the same way.
+
+### Why one read transaction
+
+A dump runs entirely inside one transaction on one handle (`session.ts`), opened as a
+`SAVEPOINT` so that it nests inside a transaction the caller already has, and with one read
+issued immediately so the snapshot is taken at the start rather than by whichever catalog
+query happens to run first. In WAL mode that is a true snapshot; in rollback-journal mode it
+holds a `SHARED` lock. The native shell does the same (`SAVEPOINT dump`). It is released
+without the caller's `AbortSignal`, so a cancelled dump still ends it.
+
+## `introspection/` — catalog to model
+
+Everything comes from `sqlite_schema` (read as `sqlite_master`, which every release
+accepts), in rowid order, plus the table-valued pragma functions — `table_xinfo`,
+`index_list`, `index_xinfo`, `foreign_key_list`, `table_list` — with a fallback to plain
+`PRAGMA` statements on libraries too old for them. Tables are classified as ordinary,
+virtual, shadow (a virtual table's storage) or system (`sqlite_*`).
+
+### Why the DDL is not reconstructed
+
+SQLite keeps every `CREATE` statement verbatim, and the native `.dump` writes that text.
+Reconstructing DDL from the column model would lose comments, spelling, formatting and any
+clause the model does not know about, for no gain. The model exists for everything else —
+planning, selection, `INSERT` column lists, compatibility checks, diagnostics — which is why
+`renderPlainSql` is a pure function of it.
+
+## `archive/` — the plan
+
+`inspectDumpArchive` turns a model into ordered `ArchiveEntry` objects. It is pure: no SQL
+text, no streams, no connection.
+
+The order is the native `.dump`'s — creation order — not a topological sort. Creation order
+is valid for everything SQLite checks at `CREATE` time (an index after its table, a trigger
+after its table or view), SQLite resolves view and trigger bodies lazily, and the dump's
+`PRAGMA foreign_keys=OFF` makes table order irrelevant to foreign keys. Dependencies are
+still recorded and then _verified_ against that order:
+
+- **`hard`** — a trigger depends on its table's data this way: created before the rows, it
+  would fire for each one.
+- **`preference`** — every foreign key. Recording them as hard edges would report a false
+  cycle for exactly the circular schemas that restore perfectly well.
+
+## `renderer/` — model to text
+
+A port of the parts of `shell.c` that shape `.dump` output — `printSchemaLine()`,
+`run_table_dump_query()`, the virtual-table `INSERT INTO sqlite_schema` — driven by the
+archive, with row data arriving through an `onTableData` hook so the renderer never needs a
+connection. `sqlite3_complete()` itself is ported (in `restore/complete.ts`) because
+`printSchemaLine()` calls it to decide how to terminate DDL that ends in a comment.
+
+## `data/` — rows to `INSERT`
+
+`exportTableDataAsInserts` streams one table in constant memory.
+
+### Why SQLite renders the values
+
+The `SELECT` it runs does not fetch column values; it fetches each value's storage class and
+a representation computed _by SQLite_: integers as text, reals as the finished literal —
+using SQLite's own `printf('%!.20g')`, the formatter the shell uses — and text as its stored
+bytes. Three problems disappear at once: 64-bit integers never become JavaScript numbers;
+`REAL` digits match the shell's exactly, which no JavaScript formatting could; and text that
+is not valid UTF-8 is not "repaired" by the driver's decoder. The core is then exact with
+any driver that can return strings and bytes.
+
+`SqlChunkBuilder` keeps `(string | Buffer)[]` parts and only falls back to `Buffer.concat`
+once it has been handed bytes, so the all-text case stays on the string fast path.
+
+## `restore/` — text to statements
+
+### The parser
+
+`SqlStatementParser` is an incremental scanner over **bytes**: a dump is not necessarily
+valid UTF-8, and `latin1` is a bijection between bytes and code units, so nothing is lost
+and every character the scanner reacts to is ASCII.
+
+It has two layers, both ported: `sqlite3_complete()`'s eight-state machine, which decides
+when a `;` completes a statement (and keeps trigger bodies whole), and the shell's
+`process_input()` line rules — dot-commands and `#` comments at column 0 when nothing is
+pending, `GO`/`/` terminator lines checked with the shell's own `line_is_complete()`
+condition, and the `\r` its line reader drops before each `\n`.
+
+Anything whose meaning depends on the next chunk — a `-` or `/` that may open a comment, a
+`*` that may close one, a `\r` that may precede `\n`, a line start that may be a `GO` line,
+a word that may be a keyword — is carried or kept in state, never guessed.
+`tests/statementParser.test.ts` checks identical output at every chunk size and every split
+point.
+
+### Session cleanup
+
+`RestoreSessionState` follows only classified top-level statements (transaction control,
+`PRAGMA foreign_keys`, `PRAGMA writable_schema`, writes to the schema table), never text
+inside rows or trigger bodies, and puts back what the script changed: it rolls back a
+transaction the script opened and left open, resets `writable_schema`, and returns
+`foreign_keys` to its previous value — which a native dump never does, because it is written
+for a shell that exits.
+
+## `writer/` — text and bytes out
+
+`DumpWriter.write` accepts `string | Buffer` for the reason above. `StreamDumpWriter` honours
+backpressure by gating on `write()`'s return value with the `drain` listener attached in the
+same tick, and never calls `end()` on a caller-owned stream.
+
+## `security/` — quoting and escaping
+
+Two quoting functions, for two jobs. `quoteIdentifier` always double-quotes, and is used for
+every query this package runs. `quoteIdentifierIfNeeded` reproduces the shell's
+`quoteChar()` — quote only non-identifiers and SQLite's 147 keywords — and is used only
+where output must match the native layout. Literal rendering ports
+`output_quoted_escaped_string()`, including `unused_string()`'s placeholder choice.
+
+## Testing strategy
+
+| Suite          | Needs           | What it proves                                                      |
+| -------------- | --------------- | ------------------------------------------------------------------- |
+| `tests/`       | nothing         | Every layer, against in-memory `better-sqlite3` databases.          |
+| `integration/` | `sqlite3` shell | Byte identity, the four-way matrix, shell-script parity, streaming. |
+
+See [round-trip-testing.md](round-trip-testing.md).

package/docs/better-sqlite3-adapter.md

@@ -0,0 +1,83 @@
+# The `better-sqlite3` adapter
+
+```ts
+import { fromBetterSqlite3, connectBetterSqlite3 } from 'dbgate-sqlite-dumper/better-sqlite3';
+```
+
+The only module that knows `better-sqlite3` exists, reachable only through this separate
+entry point. `better-sqlite3` is an optional peer dependency: the type import costs nothing
+at runtime and the value import is dynamic, so the core package — and this module — load
+without it installed. `better-sqlite3` is the driver DbGate's own SQLite plugin uses.
+
+## Ownership
+
+| Function                                | Who closes the database                   |
+| --------------------------------------- | ----------------------------------------- |
+| `fromBetterSqlite3(database)`           | The caller. The database is **borrowed**. |
+| `connectBetterSqlite3(filename, opts?)` | The returned `close()`. Idempotent.       |
+
+`connectBetterSqlite3` passes `opts` straight to the `Database` constructor, so
+`{ readonly: true }` for a dump source, `{ fileMustExist: true }` and the rest all work.
+
+## Behaviour
+
+- **Integers are read as `bigint`** (`safeIntegers(true)`) for every catalog query, so no
+  value is ever rounded. Row data does not depend on this: it is read through SQL that has
+  SQLite render every value as text or bytes (see
+  [supported-data-types.md](supported-data-types.md)).
+- **`stream()` steps the statement with `iterate()`**, one row at a time, yielding between
+  rows — constant memory for a table of any size. While a stream is open, the database
+  cannot run another statement; this package never asks it to.
+- **`execute()` reports a statement's own row count** (`changes`), 0 for DDL — not the
+  count left over from the previous `INSERT`. Text holding several statements, which the
+  parser does not produce but other callers might, falls back to `exec()`.
+- **`isInTransaction()`** is `database.inTransaction`, which is what lets a restore roll
+  back exactly the transaction the script opened.
+- **`setDefensive()`** is `unsafeMode()`, which is how `better-sqlite3` exposes
+  `SQLITE_DBCONFIG_DEFENSIVE` — on by default in `better-sqlite3`. A restore lifts it only
+  for a dump that writes `sqlite_schema` (a virtual-table dump), and puts it back. Unsafe
+  mode also relaxes the driver's own guard against writing while iterating; this package
+  never does that.
+- **`cancel()` is a no-op.** `better-sqlite3` runs each statement synchronously to
+  completion, so cancellation takes effect between rows and between statements — prompt,
+  since every statement a dump or a restore runs is short.
+
+## Foreign keys
+
+`better-sqlite3` turns `foreign_keys` **on** for every database it opens; the `sqlite3`
+shell leaves it off. A full dump turns enforcement off itself, but a data-only dump does
+not, so loading one whose tables reference each other needs `disableForeignKeys: true`
+(see [restore-api.md](restore-api.md)).
+
+## Statistics tables
+
+`better-sqlite3` is built with `SQLITE_ENABLE_STAT4`, so `ANALYZE` — including the
+`ANALYZE sqlite_schema;` a dump runs — creates a `sqlite_stat4` table. A dump of a database
+that has one does not restore on a build without STAT4 (the native `.dump` of it fails the
+same way); `preflightRestore` reports it as `statistics-table-unsupported`.
+
+## Other drivers
+
+Anything that can run SQL can be adapted by implementing `SqliteConnection`:
+
+```ts
+interface SqliteConnection {
+  query(
+    query: { sql: string; parameters?: readonly unknown[] },
+    signal?,
+  ): Promise<{ rows: readonly Row[] }>;
+  stream(query, options?): AsyncIterable<Row>;
+  execute?(sql: string, signal?): Promise<{ changes: number }>; // run text verbatim, no parameter parsing
+  describeError?(error): { code?: string; errno?: number; message: string } | undefined;
+  isInTransaction?(): boolean;
+  setDefensive?(enabled: boolean): Promise<void>;
+  cancel(): Promise<void>;
+}
+```
+
+`query` and `stream` return rows as objects keyed by column name. Values may be any of
+SQLite's storage classes as the driver represents them; the core only relies on text,
+bytes and `null`, which every driver delivers exactly. The optional members degrade
+gracefully: without `execute`, statements go through `query`; without `isInTransaction`,
+restore tracks the script's own `BEGIN`/`COMMIT`; without `setDefensive`, a virtual-table
+dump restores only onto a handle that is not in defensive mode, and preflight says so.