dbgate-sqlite-dumper 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,1893 @@
+import { a as SqliteConnectionInput, A as AcquiredSqliteConnection, S as SqliteConnection, b as SqliteExecResult, c as SqliteRow, d as SqliteErrorInfo } from './types-CTyJTzB6.cjs';
+export { e as SqliteColumnValue, f as SqliteConnectionSource, g as SqliteParameterValue, h as SqliteQuery, i as SqliteQueryResult, j as SqliteStreamOptions, k as isSqliteConnectionSource } from './types-CTyJTzB6.cjs';
+import { Writable, Readable } from 'node:stream';
+
+/**
+ * Normalizes a {@link SqliteConnectionInput} into an acquired connection with
+ * a release callback. A direct connection resolves immediately with a no-op
+ * release and `dedicated: false` (the caller may be sharing it); a source is
+ * asked for one handle through its own `acquire()`, which is what snapshot
+ * consistency requires.
+ */
+declare function acquireSqliteConnection(input: SqliteConnectionInput, signal?: AbortSignal): Promise<AcquiredSqliteConnection>;
+/** Runs one statement through `execute()` when the adapter has it, else through `query()`. */
+declare function executeStatement(connection: SqliteConnection, sql: string, signal?: AbortSignal): Promise<SqliteExecResult>;
+/**
+ * Coerces an integer-valued catalog cell to a JavaScript number.
+ *
+ * Adapters may return SQLite `INTEGER`s as `number` or `bigint`; catalog
+ * values (column positions, flags, `user_version`) always fit in a double,
+ * so either shape is accepted here.
+ */
+declare function toNumber(value: unknown, fallback?: number): number;
+/** Coerces a text-valued catalog cell to a string, or `null` for SQL `NULL`. */
+declare function toText(value: unknown): string | null;
+
+/**
+ * How a dump obtains a consistent view of the database.
+ *
+ * - `'snapshot'` (default) — opens a read transaction (as a `SAVEPOINT`, see
+ *   below) and performs one read inside it before anything else, so every
+ *   table is read from the same state of the file. In WAL mode that is a
+ *   true snapshot and writers carry on unblocked; in rollback-journal mode
+ *   the transaction holds a `SHARED` lock, which keeps writers out until the
+ *   dump finishes. Either way the result is consistent — it is the same
+ *   mechanism the native `.dump` uses (`SAVEPOINT dump`).
+ * - `'none'` — no transaction; each statement reads whatever is committed
+ *   when it runs. Only safe when nothing else writes to the database.
+ */
+type SqliteConsistencyMode = 'snapshot' | 'none';
+interface SqliteDumpSessionOptions {
+    readonly consistency?: SqliteConsistencyMode;
+}
+interface SqliteDumpSession {
+    readonly consistency: SqliteConsistencyMode;
+    /**
+     * `true` when the handle was already inside a transaction the caller
+     * opened, so the dump reads within *their* transaction and sees their
+     * uncommitted changes. Reported so a caller can tell.
+     */
+    readonly joinedExistingTransaction: boolean;
+    /**
+     * Ends the read transaction. Idempotent. Never throws for a handle that is
+     * already closed — cleanup must not mask the error that caused it.
+     */
+    finish(): Promise<void>;
+}
+/**
+ * Opens the dump's read session.
+ *
+ * A `SAVEPOINT` rather than `BEGIN`: outside a transaction the two are the
+ * same (a savepoint then starts a deferred transaction), but inside one a
+ * `BEGIN` fails while a savepoint nests. A caller who is already in a
+ * transaction therefore gets a dump of what *they* see instead of an error.
+ *
+ * A deferred transaction does not take its read lock until the first read,
+ * so the session performs one immediately — otherwise the snapshot would be
+ * taken lazily by whichever catalog query happened to come first, which is
+ * the same thing but leaves the guarantee to an accident of ordering.
+ */
+declare function beginSqliteDumpSession(connection: SqliteConnection, options?: SqliteDumpSessionOptions, signal?: AbortSignal): Promise<SqliteDumpSession>;
+
+/** Normalized SQLite library version. */
+interface SqliteVersion {
+    /** Raw `sqlite_version()` string, e.g. `"3.45.1"`. */
+    readonly versionString: string;
+    readonly majorVersion: number;
+    readonly minorVersion: number;
+    readonly patchVersion: number;
+    /**
+     * The numeric form SQLite itself uses for `SQLITE_VERSION_NUMBER`:
+     * `major * 1000000 + minor * 1000 + patch`. `3045001` for 3.45.1.
+     */
+    readonly versionNumber: number;
+    /** `sqlite_source_id()`, identifying the exact check-in, when available. */
+    readonly sourceId?: string;
+}
+/**
+ * Capabilities derived once from {@link SqliteVersion}. These describe what
+ * the SQLite library behind a handle understands; they are used both for the
+ * source (which catalog pragmas introspection may use) and, through
+ * `compatibility/`, for a restore target (what DDL it can accept).
+ */
+interface SqliteCapabilities {
+    /** `WITHOUT ROWID` tables; 3.8.2+. */
+    readonly supportsWithoutRowid: boolean;
+    /** Multi-row `INSERT ... VALUES (...), (...)`; 3.7.11+. */
+    readonly supportsMultiRowValues: boolean;
+    /** Table-valued pragma functions (`pragma_table_info(...)`); 3.16.0+. */
+    readonly supportsPragmaFunctions: boolean;
+    /** `PRAGMA table_xinfo`, which reports hidden and generated columns; 3.26.0+. */
+    readonly supportsTableXinfo: boolean;
+    /** Generated (`GENERATED ALWAYS AS`) columns; 3.31.0+. */
+    readonly supportsGeneratedColumns: boolean;
+    /** The `sqlite_schema` alias for `sqlite_master`; 3.33.0+. */
+    readonly supportsSqliteSchemaAlias: boolean;
+    /** `PRAGMA writable_schema=RESET`; 3.35.0+. */
+    readonly supportsWritableSchemaReset: boolean;
+    /** `STRICT` tables; 3.37.0+. */
+    readonly supportsStrictTables: boolean;
+    /** `PRAGMA table_list`, which reports `WITHOUT ROWID`, `STRICT` and shadow tables; 3.37.0+. */
+    readonly supportsTableList: boolean;
+}
+/**
+ * Parses a `sqlite_version()` string. Only the leading `major.minor.patch`
+ * is interpreted; anything after it is kept verbatim for reporting.
+ */
+declare function parseSqliteVersion(versionString: string): {
+    majorVersion: number;
+    minorVersion: number;
+    patchVersion: number;
+    versionNumber: number;
+};
+
+/**
+ * Detects the SQLite library version behind a handle.
+ *
+ * This is the version of the library the *driver* links, which is not
+ * necessarily the version of the `sqlite3` command-line shell installed on
+ * the same machine — `better-sqlite3`, for instance, bundles its own. The
+ * difference matters for one thing in a dump: `REAL` values are rendered by
+ * SQLite's own `printf`, whose digit generation changed between releases.
+ */
+declare function detectSqliteVersion(connection: SqliteConnection, signal?: AbortSignal): Promise<SqliteVersion>;
+
+/**
+ * Derives {@link SqliteCapabilities} from a detected {@link SqliteVersion}.
+ *
+ * Gating is by `versionNumber` (`major*1000000 + minor*1000 + patch`), so a
+ * capability is gated at the exact release that shipped it. Each gate is the
+ * release named in SQLite's own change log for that feature.
+ */
+declare function detectSqliteCapabilities(version: SqliteVersion): SqliteCapabilities;
+
+type SqliteObjectKind = 'database' | 'table' | 'virtualTable' | 'column' | 'index' | 'view' | 'trigger' | 'foreignKey';
+/** Identifies the object a diagnostic is about. */
+interface SqliteObjectReference {
+    readonly kind: SqliteObjectKind;
+    /** Schema the object lives in (`main`, or an attached database's name). */
+    readonly schemaName: string;
+    readonly name: string;
+    /** Owning table, for columns, indexes, triggers and foreign keys. */
+    readonly parentName?: string;
+}
+type SqliteDiagnosticSeverity = 'info' | 'warning' | 'error';
+/**
+ * A structured diagnostic surfaced by introspection, archive planning,
+ * rendering, data export or restore. Diagnostics are never thrown as
+ * exceptions for recoverable conditions; callers inspect them explicitly
+ * instead of parsing log text.
+ */
+interface SqliteDiagnostic {
+    readonly severity: SqliteDiagnosticSeverity;
+    /** Stable machine-readable identifier, e.g. `"user-version-not-dumped"`. */
+    readonly code: string;
+    readonly message: string;
+    readonly objectReference?: SqliteObjectReference;
+}
+
+/**
+ * The normalized SQLite schema model.
+ *
+ * SQLite stores every schema object's DDL verbatim in `sqlite_schema.sql`,
+ * and that text — not a reconstruction from the column model — is what a
+ * dump emits, exactly as the native `.dump` does. The structured fields
+ * exist for everything else: archive planning, selection, data export
+ * column lists, compatibility checks and diagnostics.
+ */
+/** What kind of table a `type = 'table'` row of `sqlite_schema` is. */
+type SqliteTableKind = 
+/** An ordinary table. */
+'table'
+/** `CREATE VIRTUAL TABLE ... USING module(...)`. */
+ | 'virtual'
+/** A table a virtual table module created to store its own data (`ft_data`, `rt_node`, ...). */
+ | 'shadow'
+/** `sqlite_sequence`, `sqlite_stat1`, `sqlite_stat4`, and any other `sqlite_` table. */
+ | 'system';
+/**
+ * `hidden` as `PRAGMA table_xinfo` reports it: `0` an ordinary column,
+ * `1` a hidden column of a virtual table, `2` a `VIRTUAL` generated column,
+ * `3` a `STORED` generated column.
+ */
+type SqliteColumnHidden = 0 | 1 | 2 | 3;
+interface SqliteColumn {
+    /** 0-based position, as `PRAGMA table_xinfo` numbers it (`cid`). */
+    readonly cid: number;
+    readonly name: string;
+    /** The declared type exactly as written (`VARCHAR(20)`, `INTEGER`, or `''` for none). */
+    readonly declaredType: string;
+    readonly notNull: boolean;
+    /** Default value expression text as written, or `null` for none. */
+    readonly defaultValue: string | null;
+    /** 1-based position within the primary key, `0` when not part of it. */
+    readonly primaryKeyPosition: number;
+    readonly hidden: SqliteColumnHidden;
+    readonly generated: 'none' | 'virtual' | 'stored';
+}
+interface SqliteTable {
+    readonly name: string;
+    readonly kind: SqliteTableKind;
+    /** `rowid` of this table's row in `sqlite_schema`; native dump order is by it. */
+    readonly schemaRowid: number;
+    /** Verbatim `sqlite_schema.sql`. */
+    readonly sql: string;
+    readonly withoutRowid: boolean;
+    readonly strict: boolean;
+    readonly hasAutoincrement: boolean;
+    /** For a virtual table, the module named in `USING` (`fts5`, `rtree`, ...). */
+    readonly virtualModule?: string;
+    /** For a shadow table, the virtual table that owns it. */
+    readonly ownerVirtualTable?: string;
+    /**
+     * The column that aliases the rowid (`INTEGER PRIMARY KEY`), or `null`
+     * when the table has a separate, hidden rowid — the case in which a plain
+     * dump renumbers rows, and `preserveRowids` exists to prevent that. Always
+     * `null` for a `WITHOUT ROWID` table.
+     */
+    readonly rowidAliasColumn: string | null;
+    /** Columns in `cid` order, including hidden and generated ones. */
+    readonly columns: readonly SqliteColumn[];
+}
+interface SqliteIndexColumn {
+    /** Column name, or `null` for an expression key part. */
+    readonly name: string | null;
+    readonly cid: number;
+    readonly descending: boolean;
+    readonly collation: string | null;
+}
+interface SqliteIndex {
+    readonly name: string;
+    readonly tableName: string;
+    readonly schemaRowid: number;
+    /**
+     * Verbatim `CREATE INDEX` text, or `null` for an automatic index SQLite
+     * built for a `UNIQUE`/`PRIMARY KEY` constraint. Those carry no DDL of
+     * their own: they are recreated by the table's `CREATE TABLE`.
+     */
+    readonly sql: string | null;
+    readonly isUnique: boolean;
+    /** `'c'` created by `CREATE INDEX`, `'u'` a `UNIQUE` constraint, `'pk'` a `PRIMARY KEY`. */
+    readonly origin: 'c' | 'u' | 'pk';
+    readonly isPartial: boolean;
+    /** Key columns only, in index order. */
+    readonly columns: readonly SqliteIndexColumn[];
+}
+interface SqliteView {
+    readonly name: string;
+    readonly schemaRowid: number;
+    readonly sql: string;
+}
+interface SqliteTrigger {
+    readonly name: string;
+    /** The table (or, for `INSTEAD OF`, view) the trigger is attached to. */
+    readonly tableName: string;
+    readonly schemaRowid: number;
+    readonly sql: string;
+}
+interface SqliteForeignKeyColumn {
+    readonly from: string;
+    /** Referenced column, or `null` when the constraint names only the table (its primary key). */
+    readonly to: string | null;
+}
+interface SqliteForeignKey {
+    readonly tableName: string;
+    /** `PRAGMA foreign_key_list` id; unique per table. */
+    readonly id: number;
+    readonly referencedTableName: string;
+    readonly columns: readonly SqliteForeignKeyColumn[];
+    readonly onUpdate: string;
+    readonly onDelete: string;
+    readonly match: string;
+}
+/** One row of `sqlite_sequence`: an `AUTOINCREMENT` table's high-water mark. */
+interface SqliteSequence {
+    readonly tableName: string;
+    /** Read as text so a value past 2^53 is carried exactly. */
+    readonly value: string;
+}
+interface SqliteDatabase {
+    /** The schema that was introspected: `main`, or an attached database's name. */
+    readonly schemaName: string;
+    /** `PRAGMA encoding`: `UTF-8`, `UTF-16le` or `UTF-16be`. */
+    readonly encoding: string;
+    /** `PRAGMA user_version`, which applications use for their own migrations. */
+    readonly userVersion: number;
+    /** `PRAGMA application_id`. */
+    readonly applicationId: number;
+    readonly pageSize?: number;
+    readonly tables: readonly SqliteTable[];
+    readonly indexes: readonly SqliteIndex[];
+    readonly views: readonly SqliteView[];
+    readonly triggers: readonly SqliteTrigger[];
+    readonly foreignKeys: readonly SqliteForeignKey[];
+    readonly sequences: readonly SqliteSequence[];
+}
+
+/**
+ * Caller-facing object selection.
+ *
+ * Names are exact SQLite identifiers: they are matched against the names in
+ * `sqlite_schema` and are never treated as wildcard patterns (unlike the
+ * native `.dump ?PATTERN?`, which takes a `LIKE` pattern).
+ *
+ * **Case sensitivity** follows SQLite's own rule for identifiers: ASCII
+ * letters compare case-insensitively (`Orders` and `orders` are the same
+ * table), and nothing else is folded.
+ */
+interface DumpSelection {
+    /** Exact table names to include. When omitted, all non-excluded tables are included. */
+    readonly tables?: readonly string[];
+    /** Exact table names to exclude, applied after {@link tables}. */
+    readonly excludeTables?: readonly string[];
+    /** Exact view names to include. When omitted, all non-excluded views are included. */
+    readonly views?: readonly string[];
+    readonly excludeViews?: readonly string[];
+    /**
+     * Exact trigger names to include. A trigger is dumped only when the table
+     * (or view) it is attached to is dumped too.
+     */
+    readonly triggers?: readonly string[];
+    readonly excludeTriggers?: readonly string[];
+    /**
+     * Exact index names to exclude. Indexes otherwise follow their table: a
+     * selected table brings every index defined on it.
+     */
+    readonly excludeIndexes?: readonly string[];
+    /**
+     * Tables whose *structure* is dumped but whose rows are not. Useful for
+     * large log or cache tables. A table excluded through
+     * {@link excludeTables} is omitted entirely instead.
+     */
+    readonly dataExcludedTables?: readonly string[];
+}
+/**
+ * Which object kinds participate in the dump at all, independent of the
+ * per-name filters in {@link DumpSelection}. All default to `true`, which is
+ * what the native `.dump` includes.
+ */
+interface DumpObjectKinds {
+    readonly includeTables?: boolean;
+    readonly includeViews?: boolean;
+    readonly includeIndexes?: boolean;
+    readonly includeTriggers?: boolean;
+    /**
+     * Virtual tables (`CREATE VIRTUAL TABLE ... USING fts5(...)`) and the
+     * shadow tables that hold their data.
+     */
+    readonly includeVirtualTables?: boolean;
+    /**
+     * `sqlite_sequence` (the `AUTOINCREMENT` counters) and the `sqlite_stat*`
+     * tables `ANALYZE` maintains. The native `.dump --nosys` turns this off.
+     */
+    readonly includeSystemTables?: boolean;
+}
+interface NormalizedDumpSelection {
+    readonly tables?: ReadonlySet<string>;
+    readonly excludeTables: ReadonlySet<string>;
+    readonly views?: ReadonlySet<string>;
+    readonly excludeViews: ReadonlySet<string>;
+    readonly triggers?: ReadonlySet<string>;
+    readonly excludeTriggers: ReadonlySet<string>;
+    readonly excludeIndexes: ReadonlySet<string>;
+    readonly dataExcludedTables: ReadonlySet<string>;
+    /** `true` when any filter at all was given, i.e. the dump may be a subset of the database. */
+    readonly isPartial: boolean;
+}
+
+/** Folds a name the way SQLite compares identifiers: ASCII letters only. */
+declare function foldSqliteName(name: string): string;
+declare function normalizeDumpSelection(selection?: DumpSelection): NormalizedDumpSelection;
+declare function isTableSelected(name: string, selection: NormalizedDumpSelection): boolean;
+declare function isViewSelected(name: string, selection: NormalizedDumpSelection): boolean;
+declare function isTriggerSelected(name: string, selection: NormalizedDumpSelection): boolean;
+declare function isIndexSelected(name: string, selection: NormalizedDumpSelection): boolean;
+/** True when the table's *rows* should be skipped while its structure is still dumped. */
+declare function isTableDataExcluded(name: string, selection: NormalizedDumpSelection): boolean;
+
+/** True when `name` is an SQLite keyword, compared case-insensitively as SQLite does. */
+declare function isSqliteKeyword(name: string): boolean;
+/** The number of keywords known to {@link isSqliteKeyword}; exported for tests. */
+declare const SQLITE_KEYWORD_COUNT: number;
+/**
+ * Upper-cases ASCII letters only, which is how SQLite compares identifiers
+ * and keywords: its case folding is ASCII-only (`sqlite3UpperToLower`), so
+ * `ß` and `Dž` are never folded and a locale-aware `toUpperCase()` would
+ * disagree with the engine.
+ */
+declare function toAsciiUpperCase(value: string): string;
+/** Lower-cases ASCII letters only; see {@link toAsciiUpperCase}. */
+declare function toAsciiLowerCase(value: string): string;
+/**
+ * Whether the native shell would quote `name`, and with what — a port of
+ * `quoteChar()` from SQLite's `shell.c`:
+ *
+ * ```c
+ * if( !IsAlpha(zName[0]) && zName[0]!='_' ) return '"';
+ * for(i=0; zName[i]; i++){
+ *   if( !IsAlnum(zName[i]) && zName[i]!='_' ) return '"';
+ * }
+ * return sqlite3_keyword_check(zName, i) ? '"' : 0;
+ * ```
+ *
+ * `IsAlpha`/`IsAlnum` are the C-locale classifications, so any non-ASCII
+ * character forces quoting.
+ */
+declare function needsIdentifierQuoting(name: string): boolean;
+/**
+ * Double-quotes an identifier, doubling any embedded `"`. Always quotes.
+ *
+ * Used for every query this package *runs*. Quoting unconditionally there
+ * removes the whole question of which words are reserved in which SQLite
+ * release; the output-shaping decision, where the native layout matters, is
+ * {@link quoteIdentifierIfNeeded}.
+ */
+declare function quoteIdentifier(name: string): string;
+/**
+ * Quotes an identifier exactly when the native `.dump` would
+ * ({@link needsIdentifierQuoting}), so `INSERT INTO t` stays unquoted while
+ * `INSERT INTO "order"` and `INSERT INTO "a b"` are quoted.
+ */
+declare function quoteIdentifierIfNeeded(name: string): string;
+/** `"schema"."name"`, for queries against an attached database. */
+declare function quoteQualifiedIdentifier(schemaName: string, name: string): string;
+
+/**
+ * SQL literal rendering, ported from the functions SQLite's own shell uses
+ * for `.dump` (`shell.c`), so a value renders exactly as `sqlite3` renders
+ * it.
+ *
+ * SQLite string literals have exactly one escape: a `'` inside the literal
+ * is doubled. There are **no** backslash escapes — `'\n'` is a backslash
+ * followed by the letter `n` — which is why the shell cannot write a newline
+ * as `\n` and instead wraps the literal in a `replace()` call (see
+ * {@link renderEscapedStringLiteral}).
+ *
+ * Every function here works on a JavaScript string in which each code unit
+ * may be either a real character or — for text that is not valid UTF-8 — one
+ * byte (a `latin1` "byte string"). The characters the escaping reacts to
+ * (`'`, `\n`, `\r`) are ASCII, and no byte of a multi-byte UTF-8 sequence can
+ * be mistaken for one, so the same code is correct for both representations.
+ */
+/**
+ * `output_quoted_string()`: `'...'` with every `'` doubled, newlines and
+ * carriage returns written raw. The shell uses this form under
+ * `.dump --newlines`.
+ */
+declare function renderQuotedStringLiteral(text: string): string;
+/**
+ * `output_quoted_escaped_string()`: the form the native `.dump` uses by
+ * default.
+ *
+ * A literal containing neither `\n` nor `\r` is written as a plain quoted
+ * string. Otherwise each newline is replaced by a placeholder that does not
+ * otherwise occur in the text (`\n`, else `\012`, else `(\n0)`, ...) and the
+ * literal is wrapped in `replace(..., '<placeholder>', char(10))` — and the
+ * same for carriage returns with `char(13)` — so that the dump keeps one
+ * statement per line and survives any tool that normalizes line endings.
+ *
+ * ```sql
+ * replace('line one\nline two','\n',char(10))
+ * replace(replace('a\r\nb','\r',char(13)),'\n',char(10))
+ * ```
+ */
+declare function renderEscapedStringLiteral(text: string): string;
+type TextLiteralStyle = 'escaped' | 'raw-newlines';
+/**
+ * Renders a `TEXT` value as a SQL expression.
+ *
+ * SQLite text may contain `NUL` characters, which the native shell cannot
+ * represent at all: it handles values as C strings, so everything after the
+ * first `NUL` is silently dropped from the dump. This package keeps them,
+ * joining the pieces with `||char(0)||` — an expression that evaluates to
+ * the identical value in a database of any text encoding. Text with no
+ * `NUL`, which is all text in practice, renders exactly as the shell renders
+ * it.
+ */
+declare function renderTextLiteral(text: string, style?: TextLiteralStyle): string;
+/**
+ * `output_hex_blob()`: `X'...'` in lower-case hexadecimal, which is how the
+ * native `.dump` writes every `BLOB`. An empty blob is `X''`.
+ */
+declare function renderBlobLiteral(value: Uint8Array): string;
+/**
+ * Renders a string as a plain single-quoted SQL literal, for text this
+ * package composes itself (table names in `INSERT INTO sqlite_schema ...`,
+ * `sqlite_sequence` filters).
+ */
+declare function quoteStringLiteral(text: string): string;
+
+declare function redactSecrets(text: string): string;
+
+/**
+ * Incremental output sink for rendered dump text.
+ *
+ * `write` accepts a `Buffer` as well as a `string` because a SQLite dump is
+ * not necessarily valid UTF-8. SQLite does not validate the encoding of the
+ * text it stores, and the native `.dump` command writes a `TEXT` value's
+ * bytes out exactly as stored — so a value holding bytes that are not valid
+ * UTF-8 produces a dump line that is not valid UTF-8 either. Routing those
+ * bytes through a JavaScript string would replace every invalid sequence
+ * with U+FFFD and silently corrupt the data, so that path hands the writer a
+ * `Buffer` instead.
+ *
+ * Implementations never close the underlying resource; callers own its
+ * lifecycle.
+ */
+interface DumpWriter {
+    /** Writes one chunk, resolving once it is safe to write again (respects backpressure). */
+    write(chunk: string | Buffer, signal?: AbortSignal): Promise<void>;
+    /** Total bytes written so far. */
+    readonly bytesWritten: number;
+}
+
+/**
+ * Writes incrementally to a caller-owned `Writable`, honoring backpressure
+ * (awaiting the stream's own `drain` when `write()` returns `false`) and
+ * `AbortSignal` cancellation. Never calls `end()`/`close()` on the stream.
+ *
+ * `Buffer` chunks are written verbatim; `string` chunks are encoded as
+ * UTF-8. See {@link DumpWriter} for why both shapes exist.
+ */
+declare class StreamDumpWriter implements DumpWriter {
+    private readonly stream;
+    private bytes;
+    private writeError;
+    constructor(stream: Writable);
+    get bytesWritten(): number;
+    write(chunk: string | Buffer, signal?: AbortSignal): Promise<void>;
+}
+
+/**
+ * In-memory {@link DumpWriter}, for tests and bounded previews. Not for
+ * production dump sizes.
+ *
+ * Accumulates `Buffer`s rather than strings so a dump containing text that
+ * is not valid UTF-8 round-trips byte-exactly; {@link toString} is a
+ * convenience for the common all-text case and will replace invalid UTF-8
+ * with U+FFFD, so use {@link toBuffer} when binary fidelity matters.
+ */
+declare class BufferDumpWriter implements DumpWriter {
+    private readonly chunks;
+    private bytes;
+    get bytesWritten(): number;
+    write(chunk: string | Buffer, signal?: AbortSignal): Promise<void>;
+    toBuffer(): Buffer;
+    toString(): string;
+}
+
+/**
+ * Every kind of entry the archive planner can produce.
+ *
+ * These map one-to-one onto what the native `.dump` writes:
+ *
+ * - `table` — a table's structure: its verbatim `CREATE TABLE`, or for the
+ *   two system tables the statement that prepares them
+ *   (`DELETE FROM sqlite_sequence;`, `ANALYZE sqlite_schema;`).
+ * - `tableData` — the table's rows, as `INSERT` statements.
+ * - `virtualTable` — a `CREATE VIRTUAL TABLE`, recreated the way the native
+ *   `.dump` recreates it: by inserting its row into `sqlite_schema` under
+ *   `PRAGMA writable_schema=ON`, *without* running the module's
+ *   constructor. Its data lives in its shadow tables, which are ordinary
+ *   `table`/`tableData` entries of their own — that is what makes the
+ *   restored index byte-identical to the source instead of rebuilt.
+ * - `index`, `trigger`, `view` — verbatim DDL, after all table data.
+ */
+type ArchiveObjectType = 'table' | 'tableData' | 'virtualTable' | 'index' | 'trigger' | 'view';
+/**
+ * Emission sections, in output order. They mirror the two passes the native
+ * `.dump` makes over `sqlite_schema`:
+ *
+ * 1. `tables` — every table, in `sqlite_schema` rowid order (creation
+ *    order), each immediately followed by its rows, with `sqlite_sequence`
+ *    moved last so the `AUTOINCREMENT` counters are set *after* the inserts
+ *    that would otherwise advance them.
+ * 2. `schema` — indexes, triggers and views, in `sqlite_schema` rowid order.
+ *    After the data on purpose: an index built once over loaded rows is
+ *    faster than one maintained row by row, and a trigger created before
+ *    the load would fire once per inserted row.
+ */
+type DumpSection = 'tables' | 'schema';
+/**
+ * `hard`: the restore fails, or produces a wrong result, if the order is
+ * violated. `preference`: the order is meaningful but a violation is
+ * harmless — a foreign key between two tables is the canonical case, since
+ * `PRAGMA foreign_keys=OFF` at the top of the dump makes any table order
+ * restorable, which is exactly what allows circular foreign keys.
+ */
+type ArchiveDependencyStrength = 'hard' | 'preference';
+/** One directed edge from an entry to another entry it depends on. */
+interface ArchiveDependency {
+    readonly targetDumpId: string;
+    readonly strength: ArchiveDependencyStrength;
+}
+/**
+ * One immutable, restore-orderable unit of the archive. Entries carry no SQL
+ * text; rendering derives text from the model object identified by `name`
+ * at render time.
+ */
+interface ArchiveEntry {
+    readonly dumpId: string;
+    readonly identity: string;
+    readonly objectType: ArchiveObjectType;
+    readonly section: DumpSection;
+    readonly schemaName: string;
+    readonly name: string;
+    /** Owning table, for `tableData`, `index` and `trigger` entries. */
+    readonly parentName?: string;
+    /** For `table` and `tableData` entries: which kind of table. */
+    readonly tableKind?: SqliteTableKind;
+    /**
+     * For the rows of `sqlite_sequence` and `sqlite_stat*` in a *partial* dump:
+     * the tables whose rows are kept. A dump of a subset of tables must not
+     * carry — or, on restore, reset — the counters and statistics of tables
+     * it does not contain. Absent when every row is dumped.
+     */
+    readonly systemRowFilter?: readonly string[];
+    readonly dependsOn: readonly ArchiveDependency[];
+    /**
+     * This entry's 0-based position in {@link DumpArchiveInspection.entries}.
+     * Omitted when `valid` is `false`, since no such order exists.
+     */
+    readonly sequenceNumber?: number;
+}
+/** A set of entries mutually blocking each other via *hard* dependencies only; no valid order exists. */
+interface ArchiveCycle {
+    readonly memberDumpIds: readonly string[];
+}
+/**
+ * A hard dependency the planned order does not satisfy. Always empty for a
+ * plan built from a consistent model — it is reported rather than silently
+ * reordered, because the emission order is fixed by native compatibility, so
+ * a violation means a model or planning bug that reordering would only hide.
+ */
+interface UnsatisfiedDependency {
+    readonly fromDumpId: string;
+    readonly toDumpId: string;
+}
+interface DumpArchiveInspection {
+    readonly valid: boolean;
+    /**
+     * In emission order, with `sequenceNumber` set, when `valid` is `true`.
+     * When `valid` is `false` the same entries are present in the same
+     * deterministic order, but without `sequenceNumber`.
+     */
+    readonly entries: readonly ArchiveEntry[];
+    readonly diagnostics: readonly SqliteDiagnostic[];
+    /** Unresolved hard-dependency cycles. Always present; empty when `valid` is `true`. */
+    readonly cycles: readonly ArchiveCycle[];
+    /** Hard dependencies the emission order violates. Always present; empty when `valid` is `true`. */
+    readonly unsatisfiedDependencies: readonly UnsatisfiedDependency[];
+}
+type DumpMode = 'full' | 'schema-only' | 'data-only';
+
+declare function assignDumpSection(objectType: ArchiveObjectType): DumpSection;
+declare function dumpSectionPriority(section: DumpSection): number;
+declare function tableGroupPriority(objectType: ArchiveObjectType): number;
+
+interface ArchiveIdentityInput {
+    readonly objectType: ArchiveObjectType;
+    readonly schemaName: string;
+    readonly name: string;
+    readonly parentName?: string;
+}
+declare function createArchiveIdentity(input: ArchiveIdentityInput): string;
+
+interface InspectDumpArchiveOptions {
+    readonly mode?: DumpMode;
+    readonly selection?: NormalizedDumpSelection;
+    readonly objectKinds?: DumpObjectKinds;
+}
+/** `sqlite3_strglob("sqlite_stat?", name)` — the tables `ANALYZE` maintains. */
+declare function isStatisticsTableName(name: string): boolean;
+/** The native shell compares this name with `strcmp`, so case-sensitively. */
+declare const SEQUENCE_TABLE_NAME = "sqlite_sequence";
+/**
+ * Converts a normalized {@link SqliteDatabase} into an ordered,
+ * dependency-validated set of {@link ArchiveEntry} objects.
+ *
+ * Independent of SQL text, output streams and connections: it decides only
+ * *what* is dumped and in *what order*. The order is the native `.dump`'s —
+ * see {@link DumpSection} — which is creation order (`sqlite_schema` rowid)
+ * rather than a topological sort. Creation order is itself a valid
+ * dependency order for everything SQLite checks at `CREATE` time, and the
+ * dump's `PRAGMA foreign_keys=OFF` covers the rest. Dependencies are still
+ * recorded and then *verified* against that order, so a model or planning
+ * bug surfaces as `valid: false` rather than as an unrestorable dump.
+ */
+declare function inspectDumpArchive(database: SqliteDatabase, options?: InspectDumpArchiveOptions): DumpArchiveInspection;
+
+interface IntrospectSqliteOptions {
+    /**
+     * Schema to introspect: `main` (default), `temp`, or the name of an
+     * attached database.
+     */
+    readonly schemaName?: string;
+}
+interface SqliteIntrospectionResult {
+    readonly database: SqliteDatabase;
+    readonly version: SqliteVersion;
+    readonly capabilities: SqliteCapabilities;
+    readonly diagnostics: readonly SqliteDiagnostic[];
+}
+/**
+ * Reads the complete schema of one SQLite database into a normalized
+ * {@link SqliteDatabase}.
+ *
+ * Every object comes from `sqlite_schema` (read through its historical name
+ * `sqlite_master`, which every release accepts), in rowid order — the order
+ * the native `.dump` uses. Column, index and foreign-key detail comes from
+ * the table-valued pragma functions where the library has them, falling back
+ * to the plain `PRAGMA` statements otherwise.
+ *
+ * Runs entirely on the one handle it is given, in sequence, and never writes.
+ */
+declare function introspectSqlite(connection: SqliteConnection, options?: IntrospectSqliteOptions, signal?: AbortSignal): Promise<SqliteIntrospectionResult>;
+
+/**
+ * Small, deliberately conservative helpers for reading facts out of the
+ * verbatim DDL SQLite keeps in `sqlite_schema.sql`, for the few facts no
+ * catalog pragma reports on every supported version.
+ */
+/**
+ * Blanks out string literals, quoted identifiers and comments (keeping
+ * their length), so a keyword search cannot match text *inside* them —
+ * `DEFAULT 'AUTOINCREMENT'` is not an autoincrement column.
+ */
+declare function maskSqlLiterals(sql: string): string;
+/** `true` when the `CREATE TABLE` text declares an `AUTOINCREMENT` column. */
+declare function declaresAutoincrement(sql: string): boolean;
+/**
+ * Table options after the closing parenthesis of a `CREATE TABLE`
+ * (`WITHOUT ROWID`, `STRICT`, in any combination). Used only when the
+ * library is too old for `PRAGMA table_list`, which reports both directly.
+ */
+declare function parseTableOptions(sql: string): {
+    withoutRowid: boolean;
+    strict: boolean;
+};
+/** The module named in `CREATE VIRTUAL TABLE name USING module(...)`. */
+declare function parseVirtualTableModule(sql: string): string | undefined;
+
+type DumpProgressPhase = 'connecting' | 'detecting-version' | 'starting-snapshot' | 'introspecting' | 'planning-archive' | 'rendering-schema' | 'exporting-data' | 'finalizing';
+/** The dump section a progress event belongs to, mirroring the native `.dump` output order. */
+type DumpProgressSection = 'header' | 'table-structure' | 'table-data' | 'virtual-table' | 'index' | 'trigger' | 'view' | 'footer';
+interface DumpProgressEvent {
+    readonly phase: DumpProgressPhase;
+    readonly message?: string;
+    readonly section?: DumpProgressSection;
+    /** Archive entries rendered so far, and the total planned. */
+    readonly objectsProcessed?: number;
+    readonly objectsTotal?: number;
+    /** Name of the object currently being rendered/exported. */
+    readonly objectName?: string;
+    /** Schema being dumped (`main`, or an attached database's name). */
+    readonly schemaName?: string;
+    readonly tableName?: string;
+    /** Rows exported from the current table. */
+    readonly rowsExported?: number;
+    /** Bytes written to the output so far. */
+    readonly bytesWritten?: number;
+    /** Lifecycle of a table data export. */
+    readonly exportState?: 'started' | 'progress' | 'finished' | 'failed' | 'cancelled';
+}
+type DumpProgressCallback = (event: DumpProgressEvent) => void;
+type RestoreProgressPhase = 'connecting' | 'preflight' | 'parsing' | 'executing' | 'finalizing';
+interface RestoreProgressEvent {
+    readonly phase: RestoreProgressPhase;
+    readonly message?: string;
+    /** Statements executed plus statements failed so far. */
+    readonly statementsProcessed?: number;
+    /** The statement currently being parsed/executed, 0-based in source order. */
+    readonly statementIndex?: number;
+    /**
+     * Running total of rows changed across every statement executed so far;
+     * see `SqlDumpRestoreResult.rowsRestored`.
+     */
+    readonly rowsRestored?: number;
+    /** Bytes of the source consumed by the parser so far. */
+    readonly bytesConsumed?: number;
+    /**
+     * The object the current statement creates or fills, read from the
+     * statement itself (`CREATE TABLE t`, `INSERT INTO t`), when recognizable.
+     * A native `.dump` carries no section banners, so this is the only way a
+     * long restore can say where it is.
+     */
+    readonly currentObject?: string;
+    /** Lifecycle of the current execution attempt. */
+    readonly executionState?: 'started' | 'finished' | 'failed';
+    /** Details of the statement failure, emitted immediately with `executionState: 'failed'`. */
+    readonly error?: {
+        readonly statementIndex: number;
+        readonly location: {
+            readonly startLine: number;
+            readonly endLine: number;
+        };
+        readonly sqlPreview: string;
+        readonly message: string;
+    };
+}
+type RestoreProgressCallback = (event: RestoreProgressEvent) => void;
+
+interface PlainSqlRenderOptions {
+    /**
+     * Wrap the dump in `PRAGMA foreign_keys=OFF;` / `BEGIN TRANSACTION;` …
+     * `COMMIT;`, exactly as the native `.dump` does. Defaults to `true`, and
+     * turning it off produces a `session-guards-disabled` warning.
+     *
+     * These are not decoration. `foreign_keys=OFF` is what lets tables be
+     * created and filled in creation order whatever references what —
+     * circular foreign keys included — and the transaction is what makes the
+     * restore both atomic and fast: without it every `INSERT` is its own
+     * transaction, and its own disk sync. A data-only dump never carries them,
+     * matching `.dump --data-only`.
+     */
+    readonly includeSessionGuards?: boolean;
+    /**
+     * Emit the `/* WARNING: Script requires that SQLITE_DBCONFIG_DEFENSIVE be
+     * disabled *\/` line the native `.dump` writes first when the dump
+     * contains virtual tables. Defaults to `true`.
+     */
+    readonly includeHeaderComments?: boolean;
+    /**
+     * Emit `DROP ... IF EXISTS` before each object's `CREATE`, so the dump can
+     * be restored over an existing copy. Defaults to `false`: the native
+     * `.dump` has no such option, and a dump restored into a fresh database
+     * does not need it.
+     */
+    readonly addDropStatements?: boolean;
+    /**
+     * Emit `PRAGMA user_version=…;` and `PRAGMA application_id=…;` before the
+     * final `COMMIT`, when either is non-zero. Defaults to `false`, matching
+     * the native `.dump` — which does not carry them, so an application that
+     * versions its schema through `user_version` loses that version in a
+     * native round trip. When they are not dumped, a non-zero value is
+     * reported as a `user-version-not-dumped` / `application-id-not-dumped`
+     * warning.
+     */
+    readonly includeDatabaseSettings?: boolean;
+    /**
+     * Write `sqlite_master` instead of `sqlite_schema` in the two places the
+     * dump names the schema table (`ANALYZE sqlite_schema;` and the virtual
+     * table `INSERT INTO sqlite_schema ...`). Defaults to `false`. The
+     * `sqlite_schema` spelling needs SQLite 3.33.0 or later on the restoring
+     * side; set this for a dump that must restore on something older.
+     */
+    readonly legacySchemaTableName?: boolean;
+    /**
+     * How to react to an archive entry that cannot be rendered. `'error'`
+     * (default) fails the render; `'warn-omit'` skips the entry and records a
+     * warning diagnostic.
+     */
+    readonly unsupportedFeaturePolicy?: 'error' | 'warn-omit';
+}
+interface ResolvedPlainSqlRenderOptions {
+    readonly includeSessionGuards: boolean;
+    readonly includeHeaderComments: boolean;
+    readonly addDropStatements: boolean;
+    readonly includeDatabaseSettings: boolean;
+    readonly legacySchemaTableName: boolean;
+    readonly unsupportedFeaturePolicy: 'error' | 'warn-omit';
+}
+declare function resolvePlainSqlRenderOptions(options?: PlainSqlRenderOptions): ResolvedPlainSqlRenderOptions;
+interface PlainSqlRenderRequest {
+    readonly database: SqliteDatabase;
+    readonly archive: DumpArchiveInspection;
+    readonly writer: DumpWriter;
+    readonly options?: PlainSqlRenderOptions;
+    readonly signal?: AbortSignal;
+    readonly onProgress?: DumpProgressCallback;
+    /** Source library version; informational. */
+    readonly sourceVersion?: SqliteVersion;
+    /** Which dump mode produced `archive`. Defaults to `'full'`. */
+    readonly mode?: DumpMode;
+    /**
+     * Called for each `tableData` entry, for callers that can actually stream
+     * the rows (see `dumpSqlite`, which supplies this backed by a live
+     * connection). Resolve `true` once the rows have been written to
+     * `writer`; resolve `false` to fall back to the default "not rendered"
+     * warning for that entry.
+     */
+    readonly onTableData?: (entry: ArchiveEntry) => Promise<boolean>;
+}
+interface PlainSqlRenderResult {
+    readonly bytesWritten: number;
+    readonly renderedDumpIds: readonly string[];
+    readonly skippedDumpIds: readonly string[];
+    readonly warnings: readonly SqliteDiagnostic[];
+    readonly cancelled: boolean;
+}
+
+/** The native `.dump` preamble: integrity checks off, then one transaction around everything. */
+declare const SESSION_GUARD_HEADER = "PRAGMA foreign_keys=OFF;\nBEGIN TRANSACTION;\n";
+declare const SESSION_GUARD_FOOTER = "COMMIT;\n";
+declare const WRITABLE_SCHEMA_ON = "PRAGMA writable_schema=ON;\n";
+declare const WRITABLE_SCHEMA_OFF = "PRAGMA writable_schema=OFF;\n";
+/**
+ * `printSchemaLine()` from `shell.c`: how the native `.dump` writes a
+ * table's stored `CREATE TABLE` text.
+ *
+ * Two details are reproduced exactly, because both change the bytes:
+ *
+ * - **A trailing comment.** SQLite stores DDL verbatim, so it can end in a
+ *   `--` comment (which would swallow an appended `;`) or even an
+ *   unterminated `/*` comment (which SQLite accepts at end of input). When
+ *   the text contains either, the shell tries appending nothing, `*\/` and a
+ *   newline, in that order, and keeps the first variant that
+ *   `sqlite3_complete()` accepts once `;` is added.
+ * - **`IF NOT EXISTS` for quoted names.** A `CREATE TABLE` whose name is
+ *   written in single or double quotes becomes
+ *   `CREATE TABLE IF NOT EXISTS`. Virtual table modules create their shadow
+ *   tables with exactly that spelling (`CREATE TABLE 'ft_data'(...)`), and
+ *   by the time the dump reaches them on restore, a module may already have
+ *   created them.
+ */
+declare function renderSchemaLine(sql: string, tail?: string): string;
+/**
+ * How `run_table_dump_query()` in `shell.c` writes an index, trigger or view:
+ * the stored text, then `;` — on a line of its own if the text contains
+ * `--` anywhere, so a trailing line comment cannot swallow it. (The test is
+ * a plain substring search, so a `--` inside a string literal triggers it
+ * too, and does here.)
+ */
+declare function renderSchemaObject(sql: string): string;
+/**
+ * A virtual table, recreated the way the native `.dump` does it: by writing
+ * its row into `sqlite_schema` directly (under `PRAGMA writable_schema=ON`)
+ * instead of running `CREATE VIRTUAL TABLE`.
+ *
+ * Running the `CREATE` would invoke the module's constructor, which for most
+ * modules creates and initializes the shadow tables — and the dump is about
+ * to recreate those itself, with the source's exact contents. Writing the
+ * schema row leaves the shadow tables to the dump, so an FTS index or R-tree
+ * comes back byte-identical rather than rebuilt.
+ */
+declare function renderVirtualTable(name: string, sql: string, schemaTableName: string): string;
+/**
+ * The statement that prepares a system table for its rows.
+ *
+ * - `sqlite_sequence` is emptied, so the `AUTOINCREMENT` counters that
+ *   follow replace — rather than duplicate — the counters the preceding
+ *   inserts advanced. A partial dump only resets the counters of the tables
+ *   it contains.
+ * - `sqlite_stat1`/`sqlite_stat4` are created, if missing, by analyzing the
+ *   (trivial) schema table, which is how the native `.dump` guarantees they
+ *   exist before inserting into them.
+ */
+declare function renderSystemTablePrelude(name: string, schemaTableName: string, systemRowFilter: readonly string[] | undefined): string;
+type DroppableKind = 'TABLE' | 'INDEX' | 'TRIGGER' | 'VIEW';
+/** `DROP <kind> IF EXISTS <name>;`, for `addDropStatements`. */
+declare function renderDrop(kind: DroppableKind, name: string): string;
+/** `PRAGMA user_version=…;` / `PRAGMA application_id=…;`, for `includeDatabaseSettings`. */
+declare function renderDatabaseSettings(userVersion: number, applicationId: number): string;
+
+/**
+ * Renders a validated {@link DumpArchiveInspection} as plain SQL in the
+ * native `.dump` layout — the same statements, in the same order, spelled
+ * the same way.
+ *
+ * Purely a function of the static model and the archive plan: it never
+ * queries the database, which is why row data has to arrive through the
+ * `onTableData` hook (see `exportTableDataAsInserts` for the streaming
+ * implementation `dumpSqlite` supplies).
+ */
+declare function renderPlainSql(request: PlainSqlRenderRequest): Promise<PlainSqlRenderResult>;
+
+interface TableDataExportOptions {
+    /** Row-fetch hint passed through to `connection.stream()`. */
+    readonly streamBatchSize?: number;
+    /**
+     * Emit multi-row `INSERT INTO t VALUES(...),(...)` statements rather than
+     * one statement per row. Defaults to `false`, matching the native `.dump`.
+     *
+     * One row per statement is not slow in SQLite: the whole dump runs inside
+     * one transaction, so each `INSERT` is an in-memory b-tree update rather
+     * than a disk sync. Multi-row statements make the file smaller and the
+     * restore somewhat faster, at the cost of native byte-identity.
+     */
+    readonly extendedInsert?: boolean;
+    /** With {@link extendedInsert}: maximum rows per statement. Defaults to 500. */
+    readonly maxRowsPerStatement?: number;
+    /**
+     * With {@link extendedInsert}: approximate maximum size, in bytes, of one
+     * statement. Defaults to 1 MiB — far below SQLite's own 1 GB
+     * `SQLITE_MAX_SQL_LENGTH`, so a statement never approaches the limit, and
+     * small enough to keep restore memory modest. A statement is closed once
+     * the next row would exceed it; a single larger row is still emitted
+     * alone, since one row cannot be split.
+     */
+    readonly maxStatementBytes?: number;
+    /**
+     * Keep each row's `rowid` by naming it in the `INSERT`
+     * (`INSERT INTO t(rowid,a,b) VALUES(...)`), for tables whose rowid is not
+     * already a declared column. The native `.dump --preserve-rowids`.
+     *
+     * Defaults to `false`, as natively. Without it such a table's rows get
+     * fresh rowids on restore, numbered from 1 in dump order — which matters
+     * when anything refers to them: an external-content FTS index, an
+     * application storing rowids, or a `VACUUM`-sensitive process.
+     */
+    readonly preserveRowids?: boolean;
+    /**
+     * Write newlines and carriage returns inside string literals raw, instead
+     * of the native default `replace('...\n...','\n',char(10))` form. The
+     * native `.dump --newlines`. Defaults to `false`.
+     */
+    readonly rawNewlines?: boolean;
+}
+interface TableDataExportRequest {
+    readonly connection: SqliteConnection;
+    /** Schema the table lives in: `main`, `temp`, or an attached database's name. */
+    readonly schemaName: string;
+    readonly table: SqliteTable;
+    readonly writer: DumpWriter;
+    /**
+     * `PRAGMA encoding` of the database. Text values are read as their stored
+     * bytes in a UTF-8 database; see `columnValueSelect`. Defaults to `UTF-8`.
+     */
+    readonly encoding?: string;
+    /**
+     * For `sqlite_sequence` and the `sqlite_stat*` tables only: keep just the
+     * rows that belong to these tables. Used by partial dumps; see
+     * `ArchiveEntry.systemRowFilter`.
+     */
+    readonly systemRowFilter?: readonly string[];
+    readonly options?: TableDataExportOptions;
+    readonly signal?: AbortSignal;
+    readonly onProgress?: DumpProgressCallback;
+}
+interface TableDataExportResult {
+    readonly rowsExported: number;
+    readonly bytesWritten: number;
+    readonly statementsWritten: number;
+    readonly cancelled: boolean;
+    readonly warnings: readonly SqliteDiagnostic[];
+}
+
+/**
+ * Accumulates SQL fragments that may be text *or* raw bytes.
+ *
+ * A `TEXT` value holding bytes that are not valid UTF-8 is written out raw,
+ * exactly as the native `.dump` writes it, so a statement cannot always be
+ * assembled as a JavaScript string. Joining through a string would replace
+ * every invalid sequence with U+FFFD and corrupt the data silently.
+ *
+ * The all-text case — which is every row of every ordinary database — stays
+ * on the fast path: parts are joined with `String.prototype.join` and no
+ * `Buffer` is allocated at all. Only a builder that has actually been handed
+ * bytes falls back to `Buffer.concat`.
+ */
+declare class SqlChunkBuilder {
+    private readonly parts;
+    private byteLength;
+    private hasBytes;
+    /** UTF-8 byte length of everything appended so far. */
+    get length(): number;
+    get isEmpty(): boolean;
+    append(part: string | Buffer): this;
+    /** Appends everything from `other`, leaving `other` untouched. */
+    appendBuilder(other: SqlChunkBuilder): this;
+    /** The accumulated content, as a `string` when it is all text and a `Buffer` otherwise. */
+    build(): string | Buffer;
+}
+
+/**
+ * The select-list for one column: its storage class, and a value shaped so
+ * that only exact representations cross the driver boundary.
+ *
+ * - `INTEGER` → decimal text, so a 64-bit value is exact whatever the
+ *   driver would have done with it;
+ * - `REAL` → the literal text, see {@link realLiteralExpression};
+ * - `TEXT` → the stored bytes (`CAST(... AS BLOB)`), so text that is not
+ *   valid UTF-8 is not "repaired" by the driver's decoder on the way out.
+ *   In a UTF-16 database those bytes would be UTF-16, so there the value is
+ *   read as text instead and the driver's (lossless, for valid UTF-16)
+ *   conversion is used;
+ * - `BLOB` → the bytes; `NULL` → `NULL`.
+ */
+declare function columnValueSelect(column: string, index: number, utf8Database: boolean): string;
+/**
+ * Renders column `index` of a row produced by {@link columnValueSelect} as
+ * the SQL literal the native `.dump` writes for it.
+ *
+ * Returns a `Buffer` only for text that is not valid UTF-8: the shell writes
+ * such bytes out raw, and so does this package, so the dump reproduces the
+ * stored value exactly (see `DumpWriter` for why that cannot go through a
+ * string).
+ */
+declare function renderColumnLiteral(row: SqliteRow, index: number, textStyle: TextLiteralStyle): string | Buffer;
+
+/**
+ * The columns the native `.dump` inserts: those `PRAGMA table_info` lists,
+ * which excludes generated columns and the hidden columns of virtual tables.
+ * Generated columns cannot be inserted into; SQLite recomputes them.
+ */
+declare function insertableColumns(table: SqliteTable): SqliteColumn[];
+/**
+ * The name under which `preserveRowids` can address a table's rowid, as
+ * `tableColumnList()` in `shell.c` decides it: never for a `WITHOUT ROWID`
+ * table or one whose rowid is already a declared `INTEGER PRIMARY KEY`, and
+ * otherwise the first of `rowid`, `_rowid_`, `oid` that no column is named.
+ */
+declare function preservableRowidName(table: SqliteTable): string | null;
+/**
+ * Streams one table's rows as `INSERT` statements in the native `.dump`
+ * layout.
+ *
+ * Requires a live connection; this is deliberately separate from
+ * `renderPlainSql`, which renders schema objects from the static model and
+ * never touches the database.
+ *
+ * Rows are read in the table's natural order — no `ORDER BY`, exactly like
+ * the native `.dump`. For an ordinary table that is rowid order, and for a
+ * `WITHOUT ROWID` table primary-key order, so two dumps of an unchanged
+ * database are identical.
+ *
+ * Memory is bounded by one statement plus a small output buffer: rows are
+ * consumed from a stream and written as they are rendered, so a table of any
+ * size dumps in constant memory.
+ */
+declare function exportTableDataAsInserts(request: TableDataExportRequest): Promise<TableDataExportResult>;
+
+/**
+ * A restore target's capabilities have the same shape as a source's, but the
+ * two stay distinct concepts: a source's describe what introspection may
+ * use, a target's what DDL it can accept.
+ */
+type TargetCapabilities = SqliteCapabilities;
+
+interface TargetCompatibilityOptions {
+    /**
+     * Virtual table modules the target has (`PRAGMA module_list`), when known.
+     * Without it, module availability is not checked.
+     */
+    readonly modules?: ReadonlySet<string>;
+    /** The dump names `sqlite_master` rather than `sqlite_schema`; see `PlainSqlRenderOptions`. */
+    readonly legacySchemaTableName?: boolean;
+    /** The dump uses multi-row `INSERT ... VALUES (...), (...)`. */
+    readonly extendedInsert?: boolean;
+}
+/**
+ * Reports what a dump of `database` needs that `target` cannot provide.
+ *
+ * Feature-level rather than statement-level: the dump carries SQLite's own
+ * stored DDL, so what can be checked is which features the source model
+ * actually uses — which turns "restore failed with a syntax error at line
+ * 4713" into "the target is SQLite 3.31 and this dump contains STRICT
+ * tables".
+ *
+ * Never throws: callers decide whether an unsupported feature blocks the
+ * restore or is merely reported.
+ */
+declare function checkTargetCompatibility(database: SqliteDatabase, target: TargetCapabilities, options?: TargetCompatibilityOptions): SqliteDiagnostic[];
+
+/**
+ * Database state this package deliberately does not dump.
+ *
+ * Every one of these is either a property of the database *file* rather
+ * than of its contents, or lives outside SQL entirely. Rather than silently
+ * omitting them — which would make a dump look complete when it is not —
+ * each is described here so `unsupportedFeatureDiagnostics()` can report
+ * them, and `docs/known-limitations.md` can list them with the same wording.
+ */
+declare const UNSUPPORTED_FEATURES: readonly {
+    readonly code: string;
+    readonly summary: string;
+    readonly detail: string;
+}[];
+/** The {@link UNSUPPORTED_FEATURES} as `info` diagnostics, for a UI that lists what a dump does not include. */
+declare function unsupportedFeatureDiagnostics(): SqliteDiagnostic[];
+
+interface PreflightRestoreRequest {
+    readonly connection: SqliteConnectionInput;
+    /**
+     * The model of the database the dump was taken from (from
+     * `introspectSqlite`). With it, the report answers "what does this dump
+     * need that this target cannot do"; without it, only "what can this target
+     * do".
+     */
+    readonly database?: SqliteDatabase;
+    readonly options?: TargetCompatibilityOptions & {
+        /** The dump was rendered with `addDropStatements`, so existing objects are replaced rather than conflicting. */
+        readonly addDropStatements?: boolean;
+    };
+    readonly signal?: AbortSignal;
+}
+interface PreflightRestoreReport {
+    readonly version: SqliteVersion;
+    readonly capabilities: SqliteCapabilities;
+    /** `PRAGMA encoding` of the target. */
+    readonly encoding: string;
+    /** Whether the target enforces foreign keys (`PRAGMA foreign_keys`). */
+    readonly foreignKeysEnabled: boolean;
+    /** Whether the handle is already inside a transaction. `undefined` when the adapter cannot tell. */
+    readonly inTransaction?: boolean;
+    /** Whether the adapter can lift defensive mode for a dump that writes `sqlite_schema`. */
+    readonly canDisableDefensiveMode: boolean;
+    /** Virtual table modules the target has, when `PRAGMA module_list` is available. */
+    readonly modules?: readonly string[];
+    /** `PRAGMA compile_options` of the target, when readable. */
+    readonly compileOptions?: readonly string[];
+    /** Tables, views, indexes and triggers already present in the target's `main` schema. */
+    readonly existingObjects: readonly {
+        readonly type: string;
+        readonly name: string;
+    }[];
+    readonly diagnostics: readonly SqliteDiagnostic[];
+}
+/**
+ * Inspects a restore target before anything is written to it.
+ *
+ * Turns a failure part-way through a restore — `table t already exists`,
+ * `no such module: fts5`, a syntax error on a `STRICT` table — into an
+ * up-front, actionable report. Never writes to the target.
+ */
+declare function preflightRestore(request: PreflightRestoreRequest): Promise<PreflightRestoreReport>;
+
+/** 1-based line range a parsed statement's SQL text occupies in its source. */
+interface StatementSourceLocation {
+    readonly startLine: number;
+    readonly endLine: number;
+}
+
+/**
+ * Anything {@link restoreSqlDump}/{@link streamSqlStatements} can read a dump
+ * from.
+ *
+ * `Buffer`/`Uint8Array` is accepted alongside `string` for a reason that
+ * matters: the native `.dump` writes a `TEXT` value's stored bytes verbatim,
+ * so a database holding text that is not valid UTF-8 produces a dump that is
+ * not valid UTF-8 either. Forcing a caller to `.toString()` such a dump
+ * before restoring it would replace every invalid sequence with U+FFFD and
+ * silently corrupt the data, so the bytes are taken directly instead.
+ *
+ * `Readable` streams are consumed through their own async-iterable protocol
+ * (`for await`), so `fs.createReadStream(path)` needs no adapter.
+ */
+type SqlDumpSource = string | Buffer | Uint8Array | Readable | AsyncIterable<string | Buffer | Uint8Array>;
+
+/** Base class for every error this package throws intentionally. */
+declare class SqliteDumperError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Thrown when an operation stops because its `AbortSignal` was triggered. */
+declare class OperationCancelledError extends SqliteDumperError {
+    constructor(message?: string);
+}
+declare function throwIfAborted(signal: AbortSignal | undefined): void;
+/**
+ * True for both cancellation shapes this package can observe: its own
+ * {@link OperationCancelledError} and the `DOMException` an `AbortSignal`
+ * (or a Node stream aborted through one) raises.
+ */
+declare function isAbortError(error: unknown): boolean;
+
+/** Common base for every error {@link restoreSqlDump} (or its parser) throws intentionally. */
+declare class RestoreError extends SqliteDumperError {
+}
+/**
+ * The input could not be split into statements correctly.
+ *
+ * Always fatal: unlike a statement that fails when executed, a parse failure
+ * means the statement boundaries themselves are not trustworthy, so nothing
+ * after the failure point can be safely executed either.
+ */
+declare class SqlParseError extends RestoreError {
+    readonly line: number;
+    constructor(code: string, message: string, line: number, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * The input ended while a quoted token — a string, a `"`/`` ` ``/`[...]`
+ * identifier — was still open. The script is structurally incomplete (most
+ * often a truncated file) and cannot be split into valid statements.
+ *
+ * An unterminated `/*` comment is *not* reported: SQLite itself accepts a
+ * block comment that runs to the end of the input.
+ */
+declare class MalformedSqlDumpError extends SqlParseError {
+    readonly openConstruct: string;
+    constructor(openConstruct: string, line: number);
+}
+/**
+ * One statement's accumulated text exceeded
+ * {@link SqlStatementParserOptions.maxStatementBytes} before it was
+ * complete.
+ *
+ * A statement must be sent to SQLite whole, so this bounds how much of a
+ * pathological input — a truncated dump, or an unterminated `CREATE TRIGGER`
+ * that swallows the rest of the file — the parser will buffer before giving
+ * up, instead of growing without limit.
+ */
+declare class StatementTooLargeError extends SqlParseError {
+    readonly maxStatementBytes: number;
+    constructor(maxStatementBytes: number, line: number);
+}
+/**
+ * A `sqlite3` shell dot-command was found that would change what the script
+ * does to the database.
+ *
+ * The shell executes lines beginning with `.` itself (`.read`, `.import`,
+ * `.open`, `.load`, `.shell`, ...) before anything reaches SQLite. Commands
+ * that only affect the shell's own presentation (`.mode`, `.headers`,
+ * `.print`, ...) are skipped with a warning; the rest are refused with a
+ * precise diagnostic rather than being silently ignored, which would corrupt
+ * the restore — a `.read` that never runs leaves the referenced file's
+ * objects missing, and an `.import` that never runs leaves a table empty.
+ */
+declare class UnsupportedClientCommandError extends SqlParseError {
+    readonly command: string;
+    constructor(command: string, line: number);
+}
+/**
+ * A statement holds bytes that are not valid UTF-8 outside any string
+ * literal, so it cannot be handed to SQLite as text without corrupting them.
+ *
+ * Invalid UTF-8 *inside* a string literal — which the native `.dump` writes
+ * whenever a `TEXT` value holds such bytes — is handled transparently, by
+ * rewriting the literal into the equivalent `CAST(X'...' AS TEXT)`. Reaching
+ * this error means the bytes are in an identifier or keyword position.
+ */
+declare class InvalidTextEncodingError extends SqlParseError {
+    constructor(message: string, line: number);
+}
+/**
+ * A statement parsed successfully but failed when executed.
+ *
+ * Unlike a parse error this is scoped to one statement: with
+ * `stopOnError: false`, restoration continues with the next one, and this
+ * error's data — never the raw driver error, which can echo back parts of
+ * the failing statement — is what is recorded in
+ * {@link SqlDumpRestoreResult.errors}.
+ */
+declare class RestoreExecutionError extends RestoreError {
+    readonly statementIndex: number;
+    readonly location: StatementSourceLocation;
+    readonly sqlPreview: string;
+    readonly sqliteError?: SqliteErrorInfo;
+    constructor(statementIndex: number, location: StatementSourceLocation, sqlPreview: string, message: string, sqliteError?: SqliteErrorInfo, options?: {
+        cause?: unknown;
+    });
+}
+
+/**
+ * Truncates SQL for inclusion in an error message or a progress event.
+ *
+ * Never a full statement — a single `INSERT` can carry a megabyte of blob —
+ * and never a literal encryption key.
+ */
+declare function safeSqlPreview(sql: string, maximumLength?: number): string;
+/** The warning line the native `.dump` writes first when the dump contains virtual tables. */
+declare const DEFENSIVE_WARNING_COMMENT = "/* WARNING: Script requires that SQLITE_DBCONFIG_DEFENSIVE be disabled */";
+/**
+ * Heuristically detects whether `sample` looks like a SQLite dump — whether
+ * produced by the native `.dump` command or by this package, which write the
+ * same thing.
+ *
+ * A full dump opens with `PRAGMA foreign_keys=OFF;` and
+ * `BEGIN TRANSACTION;`, optionally preceded by the defensive-mode warning
+ * comment; that opening is what is recognized. A `--data-only` dump has no
+ * such preamble and is indistinguishable from any other script of
+ * `INSERT`s, so it is only recognized when it carries the warning comment.
+ *
+ * Only the first few kilobytes need to be supplied; the check never reads
+ * beyond what it is given, so a caller can pass the head of a large file.
+ */
+declare function isSqliteDump(sample: string | Uint8Array): boolean;
+
+/**
+ * A port of SQLite's `sqlite3_complete()` (`complete.c`) — the function the
+ * `sqlite3` shell calls to decide whether the text it has accumulated so far
+ * is one or more *complete* statements, and therefore ready to run.
+ *
+ * Splitting on `;` is not enough, and not in an edge-case way: a trigger
+ * body is a list of statements, each ending in `;`, inside a single
+ * `CREATE TRIGGER ... BEGIN ... END;`. `sqlite3_complete()` recognizes that
+ * with a small state machine over eight token classes, and reproducing that
+ * machine exactly is what makes this package split a script where the shell
+ * does.
+ */
+/** Token classes of the `sqlite3_complete()` state machine. */
+declare const CompleteToken: {
+    readonly Semi: 0;
+    readonly Whitespace: 1;
+    readonly Other: 2;
+    readonly Explain: 3;
+    readonly Create: 4;
+    readonly Temp: 5;
+    readonly Trigger: 6;
+    readonly End: 7;
+};
+type CompleteToken = (typeof CompleteToken)[keyof typeof CompleteToken];
+/**
+ * States of the machine:
+ *
+ * - `0` INVALID — nothing but whitespace/comments seen yet.
+ * - `1` START — at the start of a statement, or just after a complete one.
+ * - `2` NORMAL — inside an ordinary statement.
+ * - `3` EXPLAIN — the statement began with `EXPLAIN`.
+ * - `4` CREATE — the statement began with `CREATE` (or `EXPLAIN CREATE`).
+ * - `5` TRIGGER — inside `CREATE [TEMP] TRIGGER ...`, before or within its body.
+ * - `6` SEMI — just saw a `;` inside a trigger body.
+ * - `7` END — saw `END` right after such a `;`; the next `;` completes the trigger.
+ */
+declare const COMPLETE_TRANSITIONS: readonly (readonly number[])[];
+/** Applies one token to a state. */
+declare function completeTransition(state: number, token: CompleteToken): number;
+/**
+ * `IdChar()` from `complete.c`: letters, digits, `_`, `$`, and every byte (or
+ * code unit) at or above `0x80`, which is how SQLite admits non-ASCII
+ * identifiers without decoding them.
+ */
+declare function isIdentifierCharCode(code: number): boolean;
+/** Classifies a complete identifier-like word the way `sqlite3_complete()` does. */
+declare function classifyWord(word: string): CompleteToken;
+/**
+ * `sqlite3_complete()`: `true` when `sql` ends with a complete statement —
+ * a `;` that is not inside a string, identifier, comment or trigger body,
+ * followed by nothing but whitespace and comments.
+ *
+ * Faithful to the C, including its quirks: an unterminated `/*` comment or
+ * quoted token makes the text incomplete, while a trailing `--` comment
+ * with no newline does not.
+ */
+declare function isCompleteStatement(sql: string): boolean;
+
+/** What a statement is, as far as restore bookkeeping needs to know. */
+interface StatementInfo {
+    /** The statement's first keyword, upper-cased: `CREATE`, `INSERT`, `PRAGMA`, `BEGIN`, ... */
+    readonly verb: string;
+    /** For `CREATE`: the object kind (`TABLE`, `INDEX`, `VIEW`, `TRIGGER`, `VIRTUAL TABLE`). */
+    readonly objectKind?: string;
+    /** The object the statement creates, fills or changes, when recognizable. */
+    readonly objectName?: string;
+    /** For `PRAGMA`: the pragma name, lower-cased, without a schema prefix. */
+    readonly pragmaName?: string;
+    /** For `PRAGMA x = value` / `PRAGMA x(value)`: the value as written, unquoted. */
+    readonly pragmaValue?: string;
+    /**
+     * `begin`, `commit`, `rollback`, `savepoint`, `release` or
+     * `rollback-to-savepoint` for transaction-control statements.
+     */
+    readonly transactionControl?: 'begin' | 'commit' | 'rollback' | 'rollback-to-savepoint' | 'savepoint' | 'release';
+}
+/**
+ * Classifies a statement from its leading tokens.
+ *
+ * Used for restore progress (`currentObject`), for following the script's
+ * own transaction control, and for noticing the session-level pragmas a dump
+ * changes (`foreign_keys`, `writable_schema`) so they can be put back if the
+ * restore stops early.
+ */
+declare function describeStatement(sql: string): StatementInfo;
+
+/**
+ * Converts a statement's bytes into text SQLite can be handed, preserving
+ * every byte.
+ *
+ * SQLite does not validate the encoding of the text it stores, and the
+ * native `.dump` writes a `TEXT` value's bytes exactly as stored — so a value
+ * holding bytes that are not valid UTF-8 appears in the dump as a string
+ * literal that is not valid UTF-8 either. The `sqlite3` shell passes those
+ * bytes straight to `sqlite3_prepare()`, which stores them unchanged. A
+ * JavaScript driver cannot: its statement text is a JavaScript string, and
+ * every invalid sequence would become U+FFFD on the way in.
+ *
+ * So a literal that is not valid UTF-8 is rewritten into an expression that
+ * yields the identical bytes as text, written entirely in ASCII:
+ *
+ * ```sql
+ * 'caf\xE9'   →   (CAST(X'636166e9' AS TEXT))
+ * ```
+ *
+ * In a UTF-8 database (every database the native `.dump` can reproduce
+ * exactly) that is byte-for-byte the value the shell would have stored.
+ * Invalid bytes inside a comment are dropped along with the comment; invalid
+ * bytes anywhere else — in an identifier or keyword position — cannot be
+ * represented and raise {@link InvalidTextEncodingError}.
+ *
+ * `statement` is a byte string: one code unit per byte, as `latin1` decodes
+ * it. Returns the statement as ordinary text, plus how many literals were
+ * rewritten.
+ */
+declare function decodeStatementBytes(statement: string, startLine: number): {
+    sql: string;
+    literalsRewritten: number;
+};
+
+/**
+ * What to do with a `sqlite3` shell dot-command (`.mode csv`, `.read x.sql`).
+ *
+ * - `'skip-presentational'` (default) skips commands that only affect the
+ *   shell's output (`.mode`, `.headers`, `.print`, ...), reporting each, and
+ *   refuses every command that would change what the script does to the
+ *   database (`.read`, `.import`, `.open`, `.load`, ...).
+ * - `'error'` refuses every dot-command.
+ *
+ * `.quit` and `.exit` end the input in both modes, exactly as in the shell.
+ */
+type DotCommandPolicy = 'skip-presentational' | 'error';
+interface SqlStatementParserOptions {
+    /**
+     * Upper bound, in bytes, on one statement's accumulated text.
+     *
+     * Guards against unbounded memory growth from a truncated dump or a
+     * `CREATE TRIGGER` whose `END` is missing. Defaults to 256 MiB — far
+     * larger than any statement a real dump contains, while still bounded.
+     */
+    readonly maxStatementBytes?: number;
+    readonly dotCommands?: DotCommandPolicy;
+}
+interface ParsedStatement {
+    readonly statementIndex: number;
+    /**
+     * Statement text, without its terminating `;` and without the whitespace
+     * and comments that preceded it. Never empty.
+     */
+    readonly sql: string;
+    readonly location: StatementSourceLocation;
+    /** What the statement is, from its leading tokens. */
+    readonly info: StatementInfo;
+    /**
+     * The object the restore is currently working on: this statement's own
+     * object when it names one (`CREATE TABLE t`, `INSERT INTO t`), else the
+     * last one seen. Reported through restore progress.
+     */
+    readonly currentObject?: string;
+    /** Bytes of source the parser had consumed when this statement was emitted. */
+    readonly bytesConsumed: number;
+    /**
+     * How many string literals holding bytes that are not valid UTF-8 were
+     * rewritten to `CAST(X'...' AS TEXT)` so the statement could be sent as
+     * text. See `textEncoding.ts`.
+     */
+    readonly textLiteralsRewritten: number;
+}
+/** A dot-command the parser skipped under `'skip-presentational'`. */
+interface SkippedDotCommand {
+    readonly command: string;
+    readonly line: number;
+}
+/**
+ * An incremental splitter for `sqlite3` scripts that decides statement
+ * boundaries exactly where the `sqlite3` shell does.
+ *
+ * Two layers, both ported from SQLite's own sources:
+ *
+ * - **Tokens and completeness** follow `sqlite3_complete()`
+ *   (see `complete.ts`): `'...'` strings, `"..."`, `` `...` `` and `[...]`
+ *   identifiers, `--` and (non-nesting) `/* *\/` comments, and the state
+ *   machine that keeps the `;`-terminated statements inside a
+ *   `CREATE TRIGGER ... BEGIN ... END;` body in one statement.
+ * - **Lines** follow the shell's `process_input()`: a line starting with `.`
+ *   at column 0, when no SQL is pending, is a dot-command; a line starting
+ *   with `#` there is a comment; a line holding only `GO` or `/` ends the
+ *   pending statement; and a carriage return immediately before a newline is
+ *   dropped, exactly as the shell's line reader drops it.
+ *
+ * The parser runs on **bytes** — chunks are byte strings, one code unit per
+ * byte, as `latin1` decodes them — because a dump is not necessarily valid
+ * UTF-8, and decoding up front would replace invalid bytes with U+FFFD
+ * before the parser ever saw them. Every character it reacts to is ASCII,
+ * and no byte of a multi-byte UTF-8 sequence can be mistaken for one.
+ *
+ * Correctness across chunk boundaries is not assumed: anything whose
+ * meaning depends on what follows — a `-` or `/` that may open a comment, a
+ * `*` that may close one, a `\r` that may precede `\n`, the start of a line
+ * that may be a `GO` line — is carried to the next chunk.
+ *
+ * Memory is bounded by one statement: only the current statement's text and
+ * a few carried bytes are held, and `maxStatementBytes` fails fast on a
+ * pathological input rather than growing without limit.
+ */
+declare class SqlStatementParser {
+    private readonly maxStatementBytes;
+    private readonly dotCommandPolicy;
+    private lex;
+    private completeState;
+    /** Length and (lower-cased, capped) prefix of the identifier being scanned. */
+    private wordLength;
+    private wordPrefix;
+    /** In a block comment: whether the previous byte was `*`. */
+    private blockStar;
+    private openLine;
+    private carry;
+    private parts;
+    private partsBytes;
+    /** True once the pending statement has content other than whitespace and comments. */
+    private hasContent;
+    private statementStartLine;
+    private line;
+    private atLineStart;
+    private firstChunk;
+    private dotText;
+    private dotLine;
+    private nextStatementIndex;
+    private finished;
+    private bytesConsumedTotal;
+    private lastObject;
+    private readonly skipped;
+    constructor(options?: SqlStatementParserOptions);
+    /** Bytes of source consumed so far. */
+    get bytesConsumed(): number;
+    /** Dot-commands skipped so far under the `'skip-presentational'` policy. */
+    get skippedDotCommands(): readonly SkippedDotCommand[];
+    /** `true` once a `.quit`/`.exit` command ended the input. */
+    get stopped(): boolean;
+    /**
+     * Feeds one chunk of the source, as a **byte string** — one code unit per
+     * byte, as produced by `buffer.toString('latin1')`. Callers holding text
+     * should use {@link parseSqlStatements} or {@link streamSqlStatements},
+     * which convert for them.
+     */
+    push(chunk: string): ParsedStatement[];
+    finish(): ParsedStatement[];
+    private scan;
+    /**
+     * Cheap pre-check before the terminator-line lookahead: only a line whose
+     * first non-blank character is `/` or `g` can be one. Keeps the lookahead —
+     * which has to look at the whole line — off the ordinary `INSERT` lines
+     * that make up almost all of a dump.
+     */
+    private mayStartTerminatorLine;
+    private countNewlines;
+    private extendWord;
+    private endWord;
+    /** A terminator line: behave as if the line were `;`. */
+    private completeWithSemicolon;
+    private emit;
+    private handleDotCommand;
+}
+/** Parses a complete, already-in-memory script. A convenience wrapper over {@link SqlStatementParser}. */
+declare function parseSqlStatements(sql: string | Buffer, options?: SqlStatementParserOptions): ParsedStatement[];
+/**
+ * Normalizes any {@link SqlDumpSource} into *byte strings*: one JavaScript
+ * code unit per input byte, via `latin1`. See {@link SqlStatementParser} for
+ * why the parser runs on bytes; a `latin1` decode can also never split a
+ * character across chunks, so no `StringDecoder` is needed.
+ */
+declare function toByteStringChunks(source: SqlDumpSource): AsyncGenerator<string>;
+/**
+ * Streams `source` into {@link ParsedStatement}s without ever buffering the
+ * whole input: at most the current statement's text, plus a few carried
+ * bytes, is held at a time.
+ */
+declare function streamSqlStatements(source: SqlDumpSource, options?: SqlStatementParserOptions, signal?: AbortSignal): AsyncGenerator<ParsedStatement>;
+/** Drives an existing parser over `source`, so a caller can inspect it afterwards. */
+declare function streamWithParser(parser: SqlStatementParser, source: SqlDumpSource, signal?: AbortSignal): AsyncGenerator<ParsedStatement>;
+
+/** Parses a boolean pragma value the way SQLite does (`sqlite3GetBoolean`). */
+declare function isTruthyPragmaValue(value: string | undefined): boolean;
+/**
+ * Follows the connection state a restore script changes, so it can be put
+ * back when the script stops before undoing it itself — or, for the
+ * settings a native dump never undoes, when it finishes.
+ *
+ * Only statements the parser has classified (see `describeStatement`) are
+ * followed: top-level transaction control and the two session pragmas a
+ * dump uses. Text inside row values or trigger bodies is never mistaken for
+ * one, because a statement is classified from its leading tokens only.
+ */
+declare class RestoreSessionState {
+    private initialForeignKeys;
+    private foreignKeysChanged;
+    private writableSchemaOn;
+    private schemaRowsWritten;
+    /** Tracked when the adapter cannot report `isInTransaction()`. */
+    private trackedTransaction;
+    private callerTransaction;
+    /** Records the state to restore to. Call once, before the first statement. */
+    begin(connection: SqliteConnection, signal?: AbortSignal): Promise<void>;
+    /** Whether the handle was already inside a transaction the caller opened. */
+    get joinedCallerTransaction(): boolean;
+    /** Whether any statement wrote virtual-table rows into the schema table. */
+    get wroteSchemaRows(): boolean;
+    /** Call after every statement that executed successfully. */
+    observe(info: StatementInfo): void;
+    /** Whether a transaction the script (not the caller) opened is still open. */
+    scriptTransactionOpen(connection: SqliteConnection): boolean;
+    /**
+     * Puts back what the script changed. Runs without the caller's signal on
+     * purpose: on the cancellation path that signal is already aborted, and
+     * the cleanup must still happen. Returns a description of each change it
+     * undid, for the `session-state-restored` warning.
+     */
+    restore(connection: SqliteConnection, options: {
+        readonly rollbackOpenTransaction: boolean;
+    }): Promise<{
+        readonly rolledBack: boolean;
+        readonly restored: readonly string[];
+    }>;
+}
+/** `sqlite_schema`, `sqlite_master`, and their temp-schema forms. */
+declare function isSchemaTableName(name: string | undefined): boolean;
+
+interface RestoreOptions extends SqlStatementParserOptions {
+    /** Stop at the first statement that fails. Defaults to `true`. */
+    readonly stopOnError?: boolean;
+    /**
+     * Put back the connection state a dump changes, whether or not the
+     * restore runs to the end. Defaults to `true`. Specifically:
+     *
+     * - a transaction the *script* opened (`BEGIN TRANSACTION;`) and never
+     *   closed — because a statement failed, the restore was cancelled, or the
+     *   file was truncated before its `COMMIT` — is rolled back, exactly as the
+     *   `sqlite3` shell's exit would roll it back. Otherwise the caller would
+     *   get the handle back mid-transaction, holding a write lock on the file;
+     * - `PRAGMA foreign_keys` is returned to its value before the restore. A
+     *   native dump turns enforcement off in its first line and never turns it
+     *   back on, which is harmless in a shell that then exits, and a silent
+     *   integrity hazard on a long-lived handle;
+     * - `PRAGMA writable_schema` is turned back off if the script left it on;
+     * - defensive mode is re-enabled if this restore disabled it.
+     */
+    readonly restoreSessionState?: boolean;
+    /**
+     * What to do when a dump recreates virtual tables by writing
+     * `sqlite_schema` directly, as every native `.dump` of such a database
+     * does (see `renderVirtualTable`).
+     *
+     * - `'allow'` (default): when the adapter supports it, lift
+     *   `SQLITE_DBCONFIG_DEFENSIVE` for the duration of the restore (the dump's
+     *   own header says it requires that), and afterwards reload the schema so
+     *   the restored virtual tables are usable on the same handle.
+     * - `'refuse'`: fail every statement that writes the schema table.
+     */
+    readonly schemaWrites?: 'allow' | 'refuse';
+    /**
+     * Transaction handling.
+     *
+     * - `'script'` (default): statements run exactly as written, so the
+     *   dump's own `BEGIN TRANSACTION` / `COMMIT` decide atomicity — which
+     *   for any full dump means the whole restore is one transaction.
+     * - `'wrap'`: this package opens its own transaction before the first
+     *   statement that is not a `PRAGMA`, skips the script's own
+     *   transaction-control statements, and commits at the end — or rolls
+     *   everything back on failure. Useful for a data-only dump, which has no
+     *   transaction of its own and would otherwise commit (and sync to disk)
+     *   once per row.
+     */
+    readonly transaction?: 'script' | 'wrap';
+    /**
+     * After a successful restore, run `PRAGMA foreign_key_check` and report
+     * every violation as a `foreign-key-violation` warning. Defaults to
+     * `false`. A dump is loaded with enforcement off, so a source database
+     * that already violated its own foreign keys restores without complaint;
+     * this makes that visible.
+     */
+    readonly verifyForeignKeys?: boolean;
+    /**
+     * Run `PRAGMA foreign_keys=OFF` before the first statement, and put the
+     * previous value back afterwards. Defaults to `false`.
+     *
+     * A full dump turns enforcement off itself, in its first line. A
+     * data-only dump does not (neither does the native `--data-only`), and
+     * the `sqlite3` shell never needs it to, because the shell starts with
+     * enforcement off — while `better-sqlite3`, like most drivers, turns it on.
+     * Loading a data-only dump whose tables reference each other in both
+     * directions therefore needs this.
+     */
+    readonly disableForeignKeys?: boolean;
+}
+interface SqlDumpRestoreRequest {
+    readonly connection: SqliteConnectionInput;
+    readonly source: SqlDumpSource;
+    readonly options?: RestoreOptions;
+    readonly signal?: AbortSignal;
+    readonly progress?: RestoreProgressCallback;
+}
+/** One statement that parsed successfully but failed when executed. */
+interface RestoreStatementError {
+    readonly statementIndex: number;
+    readonly location: StatementSourceLocation;
+    /** Truncated, secret-redacted preview of the failing statement. */
+    readonly sqlPreview: string;
+    readonly message: string;
+    /** SQLite's own result code, when the adapter can report it. */
+    readonly sqliteError?: SqliteErrorInfo;
+}
+interface SqlDumpRestoreResult {
+    readonly statementsExecuted: number;
+    readonly statementsFailed: number;
+    /**
+     * Sum of the rows changed by every successfully executed statement. In
+     * practice this is rows inserted, since DDL changes none — but it is a
+     * straightforward sum, so a script's own `UPDATE`/`DELETE` statements
+     * contribute too.
+     */
+    readonly rowsRestored: number;
+    /** Bytes of the source consumed. */
+    readonly bytesConsumed: number;
+    readonly errors: readonly RestoreStatementError[];
+    readonly warnings: readonly RestoreWarning[];
+    readonly cancelled: boolean;
+}
+interface RestoreWarning {
+    readonly code: string;
+    readonly message: string;
+    readonly statementIndex?: number;
+}
+
+/**
+ * Restores a plain-SQL dump using only the {@link SqliteConnection}
+ * abstraction — no `sqlite3` shell, no external process.
+ *
+ * The input is split into statements by a streaming parser that reproduces
+ * the `sqlite3` shell's own rules (see `statementParser.ts`), so a script is
+ * executed as the same statements, in the same order, that
+ * `sqlite3 database.db < dump.sql` would execute. Statements run
+ * sequentially on one handle.
+ *
+ * A structural problem with the input — an unterminated string, an
+ * unsupported dot-command, bytes that cannot be represented — throws,
+ * because the statement boundaries past that point cannot be trusted. A
+ * statement that parses but fails in SQLite is recorded in `result.errors`
+ * instead, and unless `stopOnError` (the default) is set, the restore
+ * continues.
+ */
+declare function restoreSqlDump(request: SqlDumpRestoreRequest): Promise<SqlDumpRestoreResult>;
+
+/**
+ * Builds a collision-resistant identity string from ordered parts.
+ *
+ * Parts are length-prefixed rather than joined with a separator, because
+ * SQLite identifiers may contain any character at all — including
+ * whatever separator would otherwise be chosen. Without the prefix,
+ * `["a.b", "c"]` and `["a", "b.c"]` would produce the same identity.
+ */
+declare function createCanonicalIdentity(parts: readonly string[]): string;
+/** Stable short hash of a canonical identity, used as an archive entry's `dumpId`. */
+declare function createDumpId(identity: string): string;
+
+interface DumpSqliteOptions {
+    /** `'full'` (default): schema and data. `'schema-only'`: definitions only. `'data-only'`: rows only. */
+    readonly mode?: DumpMode;
+    /**
+     * Schema to dump: `main` (default), `temp`, or an attached database's name.
+     * The dump itself is schema-less — `CREATE TABLE t`, never
+     * `CREATE TABLE aux.t` — so it restores into whatever database it is run
+     * against, exactly like a native `.dump`.
+     */
+    readonly schemaName?: string;
+    readonly selection?: DumpSelection;
+    /** Which object kinds to include. All default to `true`, which is what the native `.dump` includes. */
+    readonly objectKinds?: DumpObjectKinds;
+    readonly render?: PlainSqlRenderOptions;
+    /** Row rendering and batching options; see `exportTableDataAsInserts`. */
+    readonly dataExport?: TableDataExportOptions;
+    /**
+     * How the dump obtains a consistent view. Defaults to `'snapshot'`; see
+     * {@link SqliteConsistencyMode}.
+     */
+    readonly consistency?: SqliteConsistencyMode;
+}
+interface DumpResult {
+    readonly bytesWritten: number;
+    readonly renderedDumpIds: readonly string[];
+    readonly skippedDumpIds: readonly string[];
+    readonly warnings: readonly SqliteDiagnostic[];
+    readonly cancelled: boolean;
+    /** Total rows written across every exported table. */
+    readonly rowsExported: number;
+    /** Total `INSERT` statements written. */
+    readonly statementsWritten: number;
+}
+
+/**
+ * Runs a complete SQLite dump: acquire one handle, open a read snapshot,
+ * introspect, plan, render, and stream row data — writing plain SQL in the
+ * native `.dump` layout to `output`.
+ *
+ * Everything happens on **one** handle inside **one** read transaction, so
+ * every table is read from the same state of the database even while other
+ * connections write to it. When a source is passed, one handle is acquired
+ * for the whole dump and released afterwards; a bare connection is borrowed
+ * and never closed.
+ */
+declare function dumpSqlite(connectionInput: SqliteConnectionInput, options: DumpSqliteOptions, output: Writable, onProgress?: DumpProgressCallback, signal?: AbortSignal): Promise<DumpResult>;
+
+export { AcquiredSqliteConnection, type ArchiveCycle, type ArchiveDependency, type ArchiveDependencyStrength, type ArchiveEntry, type ArchiveIdentityInput, type ArchiveObjectType, BufferDumpWriter, COMPLETE_TRANSITIONS, CompleteToken, DEFENSIVE_WARNING_COMMENT, type DotCommandPolicy, type DroppableKind, type DumpArchiveInspection, type DumpMode, type DumpObjectKinds, type DumpProgressCallback, type DumpProgressEvent, type DumpProgressPhase, type DumpProgressSection, type DumpResult, type DumpSection, type DumpSelection, type DumpSqliteOptions, type DumpWriter, type InspectDumpArchiveOptions, type IntrospectSqliteOptions, InvalidTextEncodingError, MalformedSqlDumpError, type NormalizedDumpSelection, OperationCancelledError, type ParsedStatement, type PlainSqlRenderOptions, type PlainSqlRenderRequest, type PlainSqlRenderResult, type PreflightRestoreReport, type PreflightRestoreRequest, type ResolvedPlainSqlRenderOptions, RestoreError, RestoreExecutionError, type RestoreOptions, type RestoreProgressCallback, type RestoreProgressEvent, type RestoreProgressPhase, RestoreSessionState, type RestoreStatementError, type RestoreWarning, SEQUENCE_TABLE_NAME, SESSION_GUARD_FOOTER, SESSION_GUARD_HEADER, SQLITE_KEYWORD_COUNT, type SkippedDotCommand, SqlChunkBuilder, type SqlDumpRestoreRequest, type SqlDumpRestoreResult, type SqlDumpSource, SqlParseError, SqlStatementParser, type SqlStatementParserOptions, type SqliteCapabilities, type SqliteColumn, type SqliteColumnHidden, SqliteConnection, SqliteConnectionInput, type SqliteConsistencyMode, type SqliteDatabase, type SqliteDiagnostic, type SqliteDiagnosticSeverity, type SqliteDumpSession, type SqliteDumpSessionOptions, SqliteDumperError, SqliteErrorInfo, SqliteExecResult, type SqliteForeignKey, type SqliteForeignKeyColumn, type SqliteIndex, type SqliteIndexColumn, type SqliteIntrospectionResult, type SqliteObjectKind, type SqliteObjectReference, SqliteRow, type SqliteSequence, type SqliteTable, type SqliteTableKind, type SqliteTrigger, type SqliteVersion, type SqliteView, type StatementInfo, type StatementSourceLocation, StatementTooLargeError, StreamDumpWriter, type TableDataExportOptions, type TableDataExportRequest, type TableDataExportResult, type TargetCapabilities, type TargetCompatibilityOptions, type TextLiteralStyle, UNSUPPORTED_FEATURES, type UnsatisfiedDependency, UnsupportedClientCommandError, WRITABLE_SCHEMA_OFF, WRITABLE_SCHEMA_ON, acquireSqliteConnection, assignDumpSection, beginSqliteDumpSession, checkTargetCompatibility, classifyWord, columnValueSelect, completeTransition, createArchiveIdentity, createCanonicalIdentity, createDumpId, declaresAutoincrement, decodeStatementBytes, describeStatement, detectSqliteCapabilities, detectSqliteVersion, detectSqliteCapabilities as detectTargetCapabilities, dumpSectionPriority, dumpSqlite, executeStatement, exportTableDataAsInserts, foldSqliteName, insertableColumns, inspectDumpArchive, introspectSqlite, isAbortError, isCompleteStatement, isIdentifierCharCode, isIndexSelected, isSchemaTableName, isSqliteDump, isSqliteKeyword, isStatisticsTableName, isTableDataExcluded, isTableSelected, isTriggerSelected, isTruthyPragmaValue, isViewSelected, maskSqlLiterals, needsIdentifierQuoting, normalizeDumpSelection, parseSqlStatements, parseSqliteVersion, parseTableOptions, parseVirtualTableModule, preflightRestore, preservableRowidName, quoteIdentifier, quoteIdentifierIfNeeded, quoteQualifiedIdentifier, quoteStringLiteral, redactSecrets, renderBlobLiteral, renderColumnLiteral, renderDatabaseSettings, renderDrop, renderEscapedStringLiteral, renderPlainSql, renderQuotedStringLiteral, renderSchemaLine, renderSchemaObject, renderSystemTablePrelude, renderTextLiteral, renderVirtualTable, resolvePlainSqlRenderOptions, restoreSqlDump, safeSqlPreview, streamSqlStatements, streamWithParser, tableGroupPriority, throwIfAborted, toAsciiLowerCase, toAsciiUpperCase, toByteStringChunks, toNumber, toText, unsupportedFeatureDiagnostics };