@zaisma/game-server 1.6.0 → 1.8.0

package/bin/node-parts.js

@@ -96,7 +96,8 @@ export function localDatabase(file) {
         statement.setReadBigInts(true);
         for (const row of statement.iterate(...values)) {
           if (rows.length >= DATABASE_LIMITS.maximumRowCount) throw tooManyRows();
-          rows.push(checkedRow(numbersFrom(row)));
+          // node:sqlite gives an INTEGER as a BigInt and a REAL as a number: a REAL as big as 1e20 is no whole number to refuse.
+          rows.push(checkedRow(numbersFrom(row), new Set(Object.entries(row).filter(([, columnValue]) => typeof columnValue === "number").map(([column]) => column))));
         }
         return rows;
       });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zaisma/game-server",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "Run your Zaisma game server: the same rooms on Zaisma or on your own server.",
   "license": "MIT",
   "homepage": "https://zaisma.com",

package/src/database.d.ts

@@ -76,18 +76,22 @@ export declare function checkPlayerId(playerId: unknown): string;
 /** What erasePlayer says when a table's foreign key refuses the delete. */
 export declare function eraseRefused(tableName: string, error: unknown): DatabaseError;
 export declare const DATABASE_LIMITS: {
-    /** One statement's SQL. */
+    /** One statement's SQL, in characters. */
     readonly maximumSqlCharacterCount: 100000;
+    /** One statement's SQL, in UTF-8 bytes: Cloudflare's SQLite takes 100 KB, so text in other scripts is held to it too. */
+    readonly maximumSqlSizeBytes: 100000;
     /** Values for one statement's ?s. */
     readonly maximumValueCount: 100;
-    /** One text or blob value, in a query and in the database. */
+    /** One text or blob value a game server or query binds. */
     readonly maximumValueSizeBytes: number;
+    /** One text or blob value in an import, which brings back every row an export wrote: what the database holds in a value. */
+    readonly maximumImportValueSizeBytes: number;
     /** Statements in one batch. */
     readonly maximumStatementCount: 100;
     /** Rows one statement may answer; past it, page with LIMIT and OFFSET or a WHERE. */
     readonly maximumRowCount: 10000;
 };
-export type DatabaseErrorCode = "bad_sql" | "bad_values" | "bad_player_id" | "too_many_rows" | "hosting_paused" | "database_full" | "database_unavailable";
+export type DatabaseErrorCode = "bad_sql" | "bad_values" | "bad_player_id" | "too_many_rows" | "hosting_paused" | "database_full" | "database_unavailable" | "integer_too_large";
 /** A call the database refused, with a code, what happened and what to do (like the developer API's errors, docs/NAMING.md). */
 export declare class DatabaseError extends Error {
     readonly code: DatabaseErrorCode;
@@ -110,12 +114,18 @@ export type DatabaseAnswer<T> = {
 export declare function readDatabaseAnswer<T>(answer: DatabaseAnswer<T>): T;
 /** Run work, answering its result or the DatabaseError it threw; any other error is SQLite's (bad_sql). */
 export declare function answerDatabase<T>(work: () => T): DatabaseAnswer<T>;
+/**
+ * The PRAGMAs Cloudflare's SQLite runs; it refuses the rest (user_version, journal_mode…) with SQLITE_AUTH, so both
+ * runtimes refuse them. defer_foreign_keys is what an import's part runs first, in its transaction.
+ */
+export declare const ALLOWED_PRAGMAS: readonly string[];
 /**
  * Check one statement and its values before it runs: one statement only, no transaction control,
- * values of the kinds SQLite takes. Throws a DatabaseError; answers the statement to run (without a
- * trailing ; or comment, which SQLite in a Durable Object takes as an empty statement) and its values.
+ * nothing Cloudflare's SQLite refuses, values of the kinds SQLite takes. Throws a DatabaseError; answers the
+ * statement to run (without a trailing ; or comment, which SQLite in a Durable Object takes as an empty
+ * statement) and its values. A text or blob value may be up to maximumValueSizeBytes (an import's: more).
  */
-export declare function checkStatement(sql: unknown, values: unknown): {
+export declare function checkStatement(sql: unknown, values: unknown, maximumValueSizeBytes?: number): {
     sql: string;
     values: DatabaseValue[];
 };
@@ -128,9 +138,12 @@ export declare function checkBatch(statements: unknown): {
 export declare function plainRow(row: Record<string, unknown>): DatabaseRow;
 /**
  * A row as a game's query gets it: plainRow, refusing a whole number past 2^53, which JavaScript would
- * round (a game would read a different number than the one stored). Dumps and previews keep plainRow.
+ * round (a game would read a different number than the one stored): integer_too_large. Dumps and previews keep
+ * plainRow. realColumns names the columns that hold REALs, which can be as big (1e20) and are not refused.
  */
-export declare function checkedRow(row: Record<string, unknown>): DatabaseRow;
+export declare function checkedRow(row: Record<string, unknown>, realColumns?: ReadonlySet<string>): DatabaseRow;
+/** A whole number past 2^53 in a result, which JavaScript can't hold exactly. */
+export declare function integerTooLarge(column: string): DatabaseError;
 export declare function tooManyRows(): DatabaseError;
 /** One statement in a piece of SQL, as scanStatements finds it. */
 export interface ScannedStatement {

package/src/database.js

@@ -39,18 +39,22 @@ export function eraseRefused(tableName, error) {
     return new DatabaseError("bad_sql", `Erasing the player from ${tableName} failed, so nothing was erased: SQLite: ${sqliteMessage}`, "Give the foreign key ON DELETE CASCADE, or turn deleted_account_erase_enabled off and erase in your own order.");
 }
 export const DATABASE_LIMITS = {
-    /** One statement's SQL. */
+    /** One statement's SQL, in characters. */
     maximumSqlCharacterCount: 100_000,
+    /** One statement's SQL, in UTF-8 bytes: Cloudflare's SQLite takes 100 KB, so text in other scripts is held to it too. */
+    maximumSqlSizeBytes: 100_000,
     /** Values for one statement's ?s. */
     maximumValueCount: 100,
-    /** One text or blob value, in a query and in the database. */
+    /** One text or blob value a game server or query binds. */
     maximumValueSizeBytes: 1024 * 1024,
+    /** One text or blob value in an import, which brings back every row an export wrote: what the database holds in a value. */
+    maximumImportValueSizeBytes: 2 * 1024 * 1024,
     /** Statements in one batch. */
     maximumStatementCount: 100,
     /** Rows one statement may answer; past it, page with LIMIT and OFFSET or a WHERE. */
     maximumRowCount: 10_000,
 };
-const DATABASE_ERROR_CODES = ["bad_sql", "bad_values", "bad_player_id", "too_many_rows", "hosting_paused", "database_full", "database_unavailable"];
+const DATABASE_ERROR_CODES = ["bad_sql", "bad_values", "bad_player_id", "too_many_rows", "hosting_paused", "database_full", "database_unavailable", "integer_too_large"];
 /** A call the database refused, with a code, what happened and what to do (like the developer API's errors, docs/NAMING.md). */
 export class DatabaseError extends Error {
     code;
@@ -86,16 +90,49 @@ export function answerDatabase(work) {
 }
 // Statements that run their own transactions or reach other files. batch() is the transaction.
 const REFUSED_FIRST_WORDS = new Set(["BEGIN", "COMMIT", "END", "ROLLBACK", "SAVEPOINT", "RELEASE", "ATTACH", "DETACH"]);
+/**
+ * The PRAGMAs Cloudflare's SQLite runs; it refuses the rest (user_version, journal_mode…) with SQLITE_AUTH, so both
+ * runtimes refuse them. defer_foreign_keys is what an import's part runs first, in its transaction.
+ */
+export const ALLOWED_PRAGMAS = ["table_info", "table_xinfo", "table_list", "index_list", "index_info", "index_xinfo", "foreign_key_list", "foreign_key_check", "defer_foreign_keys", "quick_check", "integrity_check", "optimize"];
+/** Functions Cloudflare's SQLite refuses, which would answer in the Node runner. */
+const REFUSED_FUNCTIONS = ["sqlite_version", "sqlite_source_id", "load_extension"];
+/** SQL with its quotes, names and comments blanked, so a word is only found where it's SQL. */
+function sqlWithoutQuotes(sql) {
+    return sql.replace(/'(?:[^']|'')*'|"(?:[^"]|"")*"|`[^`]*`|\[[^\]]*\]|--[^\n]*|\/\*[\s\S]*?\*\//g, " ");
+}
+/** What Cloudflare's SQLite refuses and Node's would run: PRAGMAs outside ALLOWED_PRAGMAS, TEMP objects and unauthorized functions. */
+function checkRefusedByCloudflare(sql, leadingWords) {
+    const [firstWord = "", secondWord = ""] = leadingWords;
+    const bare = sqlWithoutQuotes(sql);
+    if (firstWord === "PRAGMA") {
+        const pragmaName = /^\s*PRAGMA\s+(?:\w+\s*\.\s*)?(\w+)/i.exec(bare)?.[1]?.toLowerCase() ?? "";
+        if (!ALLOWED_PRAGMAS.includes(pragmaName)) {
+            throw new DatabaseError("bad_sql", `PRAGMA ${pragmaName || "…"} isn't allowed: Zaisma's database doesn't take it, and neither does your own server's runner, so a query runs the same in both.`, `Allowed: ${ALLOWED_PRAGMAS.map((name) => `PRAGMA ${name}`).join(", ")}. To keep a schema version, use a table of your own, like CREATE TABLE schema_version (version_number INTEGER NOT NULL).`);
+        }
+    }
+    if (firstWord === "CREATE" && (secondWord === "TEMP" || secondWord === "TEMPORARY")) {
+        throw new DatabaseError("bad_sql", `CREATE ${secondWord} isn't allowed: the database keeps no temporary tables or objects.`, "Make an ordinary table and drop it when done, or use a WITH query for a result you only need inside one statement.");
+    }
+    const refusedFunction = REFUSED_FUNCTIONS.find((name) => new RegExp(`\\b${name}\\s*\\(`, "i").test(bare));
+    if (refusedFunction)
+        throw new DatabaseError("bad_sql", `${refusedFunction}() isn't allowed: Zaisma's database doesn't take it, and neither does your own server's runner.`, "Keep what you need to know about the database (a schema version, say) in a table of your own.");
+}
 /**
  * Check one statement and its values before it runs: one statement only, no transaction control,
- * values of the kinds SQLite takes. Throws a DatabaseError; answers the statement to run (without a
- * trailing ; or comment, which SQLite in a Durable Object takes as an empty statement) and its values.
+ * nothing Cloudflare's SQLite refuses, values of the kinds SQLite takes. Throws a DatabaseError; answers the
+ * statement to run (without a trailing ; or comment, which SQLite in a Durable Object takes as an empty
+ * statement) and its values. A text or blob value may be up to maximumValueSizeBytes (an import's: more).
  */
-export function checkStatement(sql, values) {
+export function checkStatement(sql, values, maximumValueSizeBytes = DATABASE_LIMITS.maximumValueSizeBytes) {
     if (typeof sql !== "string" || !sql.trim())
         throw new DatabaseError("bad_sql", "The SQL isn't text.", 'Give one SQL statement as text, like "SELECT * FROM scores WHERE player_id = ?".');
     if (sql.length > DATABASE_LIMITS.maximumSqlCharacterCount)
         throw new DatabaseError("bad_sql", `The SQL is ${sql.length} characters.`, `Keep one statement under ${DATABASE_LIMITS.maximumSqlCharacterCount} characters, and pass data as values instead of writing it into the SQL.`);
+    // Cloudflare's limit is in bytes: three bytes a character at most, so short statements need no count.
+    const sqlSizeBytes = sql.length * 3 <= DATABASE_LIMITS.maximumSqlSizeBytes ? 0 : new TextEncoder().encode(sql).length;
+    if (sqlSizeBytes > DATABASE_LIMITS.maximumSqlSizeBytes)
+        throw new DatabaseError("bad_sql", `The SQL is ${sqlSizeBytes} bytes.`, `Keep one statement under ${DATABASE_LIMITS.maximumSqlSizeBytes} bytes (UTF-8), and pass data as values instead of writing it into the SQL.`);
     const statements = scanStatements(sql);
     if (statements.length === 0)
         throw new DatabaseError("bad_sql", "The SQL has only comments.", 'Give one SQL statement, like "SELECT * FROM scores WHERE player_id = ?".');
@@ -104,21 +141,22 @@ export function checkStatement(sql, values) {
     const firstWord = statements[0].leadingWords[0] ?? "";
     if (REFUSED_FIRST_WORDS.has(firstWord))
         throw new DatabaseError("bad_sql", `${firstWord} isn't allowed.`, "For a transaction, use a batch (room.database.batch([{ sql, values }, ...]) in a game server, batch_database through the API): its statements all happen or none do.");
+    checkRefusedByCloudflare(sql.slice(statements[0].startIndex, statements[0].endIndex), statements[0].leadingWords);
     const given = values === undefined || values === null ? [] : values;
     if (!Array.isArray(given))
         throw new DatabaseError("bad_values", "values isn't a list.", 'Give the values for the ?s as a list, in order, like ["player_8f3k2m", 1200].');
     if (given.length > DATABASE_LIMITS.maximumValueCount)
         throw new DatabaseError("bad_values", `There are ${given.length} values.`, `Give up to ${DATABASE_LIMITS.maximumValueCount} values per statement; split big inserts into several statements in one batch.`);
-    return { sql: sql.slice(0, statements[0].endIndex), values: given.map(checkValue) };
+    return { sql: sql.slice(0, statements[0].endIndex), values: given.map((givenValue, i) => checkValue(givenValue, i, maximumValueSizeBytes)) };
 }
 /** One value for a ?, the i-th (from 0). */
-function checkValue(givenValue, i) {
+function checkValue(givenValue, i, maximumValueSizeBytes) {
     if (typeof givenValue === "number" && Number.isInteger(givenValue) && !Number.isSafeInteger(givenValue))
         throw new DatabaseError("bad_values", `Value ${i + 1} is a whole number past 2^53, which JavaScript can't hold exactly.`, "Store it as text, like String(value), and read it back as text.");
     if (givenValue === null || typeof givenValue === "string" || givenValue instanceof Uint8Array || (typeof givenValue === "number" && Number.isFinite(givenValue))) {
         const sizeBytes = typeof givenValue === "string" ? new TextEncoder().encode(givenValue).length : givenValue instanceof Uint8Array ? givenValue.byteLength : 0;
-        if (sizeBytes > DATABASE_LIMITS.maximumValueSizeBytes)
-            throw new DatabaseError("bad_values", `Value ${i + 1} is ${sizeBytes} bytes.`, `Keep each text or blob under ${DATABASE_LIMITS.maximumValueSizeBytes / 1024 / 1024} MB; store big files somewhere else and keep a link here.`);
+        if (sizeBytes > maximumValueSizeBytes)
+            throw new DatabaseError("bad_values", `Value ${i + 1} is ${sizeBytes} bytes.`, `Keep each text or blob under ${maximumValueSizeBytes / 1024 / 1024} MB; store big files somewhere else and keep a link here.`);
         return givenValue;
     }
     const kind = typeof givenValue === "boolean" ? "true or false" : typeof givenValue === "number" ? String(givenValue) : Array.isArray(givenValue) ? "a list" : typeof givenValue;
@@ -150,17 +188,21 @@ export function plainRow(row) {
 }
 /**
  * A row as a game's query gets it: plainRow, refusing a whole number past 2^53, which JavaScript would
- * round (a game would read a different number than the one stored). Dumps and previews keep plainRow.
+ * round (a game would read a different number than the one stored): integer_too_large. Dumps and previews keep
+ * plainRow. realColumns names the columns that hold REALs, which can be as big (1e20) and are not refused.
  */
-export function checkedRow(row) {
+export function checkedRow(row, realColumns) {
     const plain = plainRow(row);
     for (const [column, columnValue] of Object.entries(plain)) {
-        if (typeof columnValue === "number" && Number.isInteger(columnValue) && !Number.isSafeInteger(columnValue)) {
-            throw new DatabaseError("bad_sql", `Column ${column} holds a whole number past 2^53, which JavaScript can't hold exactly.`, `Read it as text with CAST(${column} AS TEXT).`);
-        }
+        if (typeof columnValue === "number" && Number.isInteger(columnValue) && !Number.isSafeInteger(columnValue) && !realColumns?.has(column))
+            throw integerTooLarge(column);
     }
     return plain;
 }
+/** A whole number past 2^53 in a result, which JavaScript can't hold exactly. */
+export function integerTooLarge(column) {
+    return new DatabaseError("integer_too_large", `Column ${column} holds a whole number past 2^53 (9,007,199,254,740,991), which JavaScript can't hold exactly.`, `Read it as text with CAST(${column} AS TEXT), or store 64-bit IDs as TEXT.`);
+}
 export function tooManyRows() {
     return new DatabaseError("too_many_rows", `The statement answered more than ${DATABASE_LIMITS.maximumRowCount} rows.`, "Ask for fewer with LIMIT (and OFFSET or a WHERE on the last row for the next page), or count with SELECT count(*).");
 }

package/src/dump.d.ts

@@ -54,7 +54,10 @@ export interface ImportPlan {
  * statements, and leaves out what sqlite3 writes around them (the transaction, PRAGMAs, ANALYZE and its
  * sqlite_stat1 rows). The values in an INSERT become values for ?s, since Zaisma's database takes
  * statements up to 100 KB and a row of a dump can be bigger; unistr('…'), which sqlite3 writes for text with
- * line breaks, becomes the text it stands for. AUTOINCREMENT's counters only ever go up.
+ * line breaks, becomes the text it stands for. AUTOINCREMENT's counters only ever go up. The tables are made
+ * first, so a row can refer to a table made after it. A search table in sqlite3's own dump (its
+ * `INSERT INTO sqlite_schema` under writable_schema, and its shadow tables) becomes its CREATE VIRTUAL TABLE, filled again
+ * from its _content rows with their rowids.
  */
 export declare function importStatements(dumpSql: string): ImportPlan;
 /** The start of a statement, for an error. */

package/src/dump.js

@@ -53,8 +53,12 @@ export function dumpPart(read, cursor, partSizeBytes = DUMP_LIMITS.exportPartSiz
     };
     let tableIndex = 0;
     let position = null;
-    if (cursor === null)
+    if (cursor === null) {
         add(DUMP_START);
+        // Every table is made before any row goes in, so a row can refer to a table made after it.
+        for (const table of tables)
+            add(`${table.sql};\n`);
+    }
     else {
         position = readCursor(cursor);
         tableIndex = tables.findIndex((table) => table.name === position.table_name);
@@ -63,29 +67,39 @@ export function dumpPart(read, cursor, partSizeBytes = DUMP_LIMITS.exportPartSiz
     }
     for (; tableIndex < tables.length; tableIndex++) {
         const table = tables[tableIndex];
-        if (!position)
-            add(`${table.sql};\n`);
-        position ??= { table_name: table.name, last_rowid_number: table.is_without_rowid ? null : 0, dumped_row_count: 0 };
+        position ??= { table_name: table.name, last_rowid_number: null, last_key: null };
         const columns = select("SELECT name, hidden = 0 AS is_insertable, pk AS primary_key_number FROM pragma_table_xinfo(?) ORDER BY cid", [table.name]);
         // Generated columns, and a virtual table's hidden ones, can't be inserted: the INSERTs name the rest.
         const insertedColumns = columns.filter((column) => column.is_insertable === 1);
-        const insertInto = `INSERT INTO ${quoteName(table.name)}${insertedColumns.length < columns.length ? `(${insertedColumns.map((column) => quoteName(column.name)).join(",")})` : ""} VALUES(`;
+        // A search table's rows are known by their rowids, so they go in with them.
+        const isVirtual = table.table_kind === "virtual";
+        const insertInto = `INSERT INTO ${quoteName(table.name)}${insertedColumns.length < columns.length || isVirtual ? `(${[...(isVirtual ? ["rowid"] : []), ...insertedColumns.map((column) => quoteName(column.name))].join(",")})` : ""} VALUES(`;
         // quote() writes each value as SQL, the way sqlite3's .dump does: 'text' with '' for a quote, X'…' for bytes.
         const valuesSql = insertedColumns.map((column, i) => `quote(${quoteName(column.name)}) AS value_${i}`).join(", ");
+        // A table with a declared primary key is read in its key order (rowid last, where it has one), so a row the game deletes or
+        // replaces on the other side of the cursor can't move it; a table without one, in rowid order.
         const primaryKey = columns.filter((column) => column.primary_key_number > 0).sort((first, second) => first.primary_key_number - second.primary_key_number);
+        const tableName = quoteName(table.name);
+        const keyExpressions = primaryKey.length ? [...primaryKey.map((column) => `${tableName}.${quoteName(column.name)}`), ...(table.is_without_rowid ? [] : [`${tableName}.rowid`])] : [];
         while (true) {
-            const rows = position.last_rowid_number === null
-                ? select(`SELECT ${valuesSql} FROM ${quoteName(table.name)} ORDER BY ${primaryKey.map((column) => quoteName(column.name)).join(", ")} LIMIT ${PAGE_ROW_COUNT} OFFSET ?`, [position.dumped_row_count])
-                : select(`SELECT rowid AS paging_rowid, ${valuesSql} FROM ${quoteName(table.name)} WHERE rowid > ? ORDER BY rowid LIMIT ${PAGE_ROW_COUNT}`, [position.last_rowid_number]);
+            let rows;
+            if (keyExpressions.length) {
+                const keySql = keyExpressions.map((expression, i) => `typeof(${expression}) AS key_type_${i}, CASE typeof(${expression}) WHEN 'text' THEN ${expression} WHEN 'blob' THEN hex(${expression}) WHEN 'null' THEN NULL ELSE quote(${expression}) END AS key_text_${i}`).join(", ");
+                const after = keyAfter(keyExpressions, position.last_key);
+                rows = select(`SELECT ${keySql}${valuesSql ? `, ${valuesSql}` : ""} FROM ${tableName}${after.sql ? ` WHERE ${after.sql}` : ""} ORDER BY ${keyExpressions.join(", ")} LIMIT ${PAGE_ROW_COUNT}`, after.values);
+            }
+            else {
+                rows = select(`SELECT rowid AS paging_rowid${valuesSql ? `, ${valuesSql}` : ""} FROM ${tableName} WHERE rowid > ? ORDER BY rowid LIMIT ${PAGE_ROW_COUNT}`, [position.last_rowid_number ?? 0]);
+            }
             for (const row of rows) {
-                const insert = `${insertInto}${insertedColumns.map((_, i) => row[`value_${i}`]).join(",")});\n`;
+                const insert = `${insertInto}${[...(isVirtual ? [row.paging_rowid] : []), ...insertedColumns.map((_, i) => row[`value_${i}`])].join(",")});\n`;
                 // The part ends before a row that would take it past partSizeBytes; the next starts with that row.
                 if (hasRows && dumpSizeBytes + utf8SizeBytes(insert) > partSizeBytes)
                     return { dumpSql, nextCursor: writeCursor(position), readRowCount };
                 add(insert);
                 hasRows = true;
-                if (position.last_rowid_number === null)
-                    position.dumped_row_count++;
+                if (keyExpressions.length)
+                    position.last_key = keyExpressions.map((_, i) => ({ key_type: row[`key_type_${i}`], key_text: row[`key_text_${i}`] }));
                 else
                     position.last_rowid_number = row.paging_rowid;
             }
@@ -131,26 +145,135 @@ function readCursor(cursor) {
     catch {
         throw new DumpCursorError("The cursor isn't one an export answered.");
     }
-    const { table_name: tableName, last_rowid_number: lastRowidNumber, dumped_row_count: dumpedRowCount } = (position ?? {});
-    if (typeof tableName !== "string" || !(lastRowidNumber === null || Number.isInteger(lastRowidNumber)) || !Number.isInteger(dumpedRowCount))
+    const { table_name: tableName, last_rowid_number: lastRowidNumber, last_key: lastKey } = (position ?? {});
+    const isKey = (key) => {
+        const { key_type: keyType, key_text: keyText } = (key ?? {});
+        return (keyType === "null" ? keyText === null : (keyType === "integer" || keyType === "real" || keyType === "text" || keyType === "blob") && typeof keyText === "string") && (keyType !== "integer" || /^-?\d+$/.test(keyText)) && (keyType !== "real" || /^-?[0-9.]+(e[+-]?\d+)?$/i.test(keyText)) && (keyType !== "blob" || /^([0-9A-Fa-f]{2})*$/.test(keyText));
+    };
+    if (typeof tableName !== "string" || !(lastRowidNumber === null || Number.isInteger(lastRowidNumber)) || !(lastKey === null || (Array.isArray(lastKey) && lastKey.length > 0 && lastKey.length <= 64 && lastKey.every(isKey))))
         throw new DumpCursorError("The cursor isn't one an export answered.");
-    return { table_name: tableName, last_rowid_number: lastRowidNumber, dumped_row_count: dumpedRowCount };
+    return { table_name: tableName, last_rowid_number: lastRowidNumber, last_key: lastKey };
+}
+/**
+ * The WHERE for the rows after a key, for ORDER BY the key's columns: one OR per column, each holding the ones before it equal
+ * and itself greater (NULLs sort first). The key's values are bound, numbers as text SQLite casts back, so none loses digits.
+ */
+function keyAfter(keyExpressions, lastKey) {
+    if (!lastKey)
+        return { sql: "", values: [] };
+    if (lastKey.length !== keyExpressions.length)
+        throw new DumpCursorError("The cursor isn't one an export answered.");
+    const values = [];
+    const operand = (key) => {
+        values.push(key.key_type === "blob" ? Uint8Array.from({ length: key.key_text.length / 2 }, (_, byteIndex) => parseInt(key.key_text.slice(byteIndex * 2, byteIndex * 2 + 2), 16)) : key.key_text);
+        return key.key_type === "integer" ? "CAST(? AS INTEGER)" : key.key_type === "real" ? "CAST(? AS REAL)" : "?";
+    };
+    const terms = keyExpressions.map((expression, i) => {
+        const conditions = keyExpressions.slice(0, i).map((earlier, earlierIndex) => (lastKey[earlierIndex].key_type === "null" ? `${earlier} IS NULL` : `${earlier} IS ${operand(lastKey[earlierIndex])}`));
+        conditions.push(lastKey[i].key_type === "null" ? `${expression} IS NOT NULL` : `${expression} > ${operand(lastKey[i])}`);
+        return `(${conditions.join(" AND ")})`;
+    });
+    return { sql: terms.join(" OR "), values };
 }
 const IMPORT_FIX = "Import takes a dump's CREATE and INSERT statements, as sqlite3's .dump or export_database writes them; it only adds. Run other changes with query_database or batch_database.";
+/** The name a statement starts with after `CREATE TABLE [IF NOT EXISTS]` or `INSERT INTO`, however it's quoted. */
+function tableNameAfter(text, introduction) {
+    const match = new RegExp(`^${introduction.source}\\s*(?:"((?:[^"]|"")*)"|'((?:[^']|'')*)'|\`([^\`]*)\`|\\[([^\\]]*)\\]|(\\w+))`, "i").exec(text);
+    if (!match)
+        return null;
+    const [, doubleQuoted, singleQuoted, backQuoted, bracketed, bare] = match;
+    return doubleQuoted?.replaceAll('""', '"') ?? singleQuoted?.replaceAll("''", "'") ?? backQuoted ?? bracketed ?? bare ?? null;
+}
+/** The shadow tables an FTS5 table makes for itself: sqlite3's .dump writes them as ordinary tables, and a search table makes them again. */
+const FTS5_SHADOW_SUFFIXES = ["data", "idx", "content", "docsize", "config"];
+const SEARCH_TABLE_FIX = "Import takes a search table made with fts5. For others, import the database file instead: npx @zaisma/cli database import <slug> game.sqlite.";
+/** The columns of an fts5(…) table from its CREATE VIRTUAL TABLE: the arguments that aren't options (name=value). */
+function searchColumnNames(createSql) {
+    const openIndex = createSql.indexOf("(", createSql.search(/fts5/i));
+    const closeIndex = createSql.lastIndexOf(")");
+    if (openIndex === -1 || closeIndex <= openIndex)
+        return [];
+    const argumentTexts = [];
+    let current = "";
+    let openParenthesisCount = 0;
+    let quote = null;
+    for (const character of createSql.slice(openIndex + 1, closeIndex)) {
+        if (quote) {
+            current += character;
+            if (character === quote)
+                quote = null;
+        }
+        else if (character === "'" || character === '"' || character === "`") {
+            quote = character;
+            current += character;
+        }
+        else if (character === "(") {
+            openParenthesisCount++;
+            current += character;
+        }
+        else if (character === ")") {
+            openParenthesisCount--;
+            current += character;
+        }
+        else if (character === "," && openParenthesisCount === 0) {
+            argumentTexts.push(current);
+            current = "";
+        }
+        else
+            current += character;
+    }
+    argumentTexts.push(current);
+    const names = [];
+    for (const argument of argumentTexts) {
+        const trimmed = argument.trim();
+        if (!trimmed || /^[\w.]+\s*=/.test(trimmed))
+            continue;
+        const first = /^(?:"((?:[^"]|"")*)"|'([^']*)'|`([^`]*)`|\[([^\]]*)\]|(\w+))/.exec(trimmed);
+        const name = first?.[1]?.replaceAll('""', '"') ?? first?.[2] ?? first?.[3] ?? first?.[4] ?? first?.[5];
+        if (name)
+            names.push(name);
+    }
+    return names;
+}
 /**
  * Reads a part of a dump into the statements to run. Import only adds: it takes CREATE and INSERT
  * statements, and leaves out what sqlite3 writes around them (the transaction, PRAGMAs, ANALYZE and its
  * sqlite_stat1 rows). The values in an INSERT become values for ?s, since Zaisma's database takes
  * statements up to 100 KB and a row of a dump can be bigger; unistr('…'), which sqlite3 writes for text with
- * line breaks, becomes the text it stands for. AUTOINCREMENT's counters only ever go up.
+ * line breaks, becomes the text it stands for. AUTOINCREMENT's counters only ever go up. The tables are made
+ * first, so a row can refer to a table made after it. A search table in sqlite3's own dump (its
+ * `INSERT INTO sqlite_schema` under writable_schema, and its shadow tables) becomes its CREATE VIRTUAL TABLE, filled again
+ * from its _content rows with their rowids.
  */
 export function importStatements(dumpSql) {
     const statements = [];
     const scanned = scanStatements(dumpSql);
     let skippedStatementCount = 0;
+    const textOf = (scannedStatement) => dumpSql.slice(scannedStatement.startIndex, scannedStatement.endIndex);
+    const refuseAt = (statementNumber, text, message, fix = IMPORT_FIX) => new DatabaseError("bad_sql", `Statement ${statementNumber} of the dump (${preview(text)}): ${message}`, fix);
+    // sqlite3's .dump creates a virtual table by writing its row in the schema table: those come first, so the shadow tables are known.
+    const searchTables = new Map();
+    const shadowNames = new Map();
+    scanned.forEach((scannedStatement, i) => {
+        const [firstWord = "", secondWord = "", thirdWord = ""] = scannedStatement.leadingWords;
+        if (!(firstWord === "INSERT" && secondWord === "INTO" && (thirdWord === "SQLITE_SCHEMA" || thirdWord === "SQLITE_MASTER")))
+            return;
+        const text = textOf(scannedStatement);
+        const match = /^INSERT\s+INTO\s+sqlite_(?:schema|master)\s*\([^)]*\)\s*VALUES\s*\(\s*'table'\s*,\s*'((?:[^']|'')*)'\s*,\s*'(?:[^']|'')*'\s*,\s*\d+\s*,\s*'((?:[^']|'')*)'\s*\)$/i.exec(text);
+        const createSql = match?.[2]?.replaceAll("''", "'");
+        if (!match || !createSql || !/^CREATE\s+VIRTUAL\s+TABLE\s/i.test(createSql))
+            throw refuseAt(i + 1, text, "it writes to the schema table, and only a virtual table's can be read from there.");
+        if (!/\bUSING\s+fts5\b/i.test(createSql))
+            throw refuseAt(i + 1, text, "this virtual table isn't an fts5 search table.", SEARCH_TABLE_FIX);
+        const name = match[1].replaceAll("''", "'");
+        const table = { name, createSql, columnNames: searchColumnNames(createSql) };
+        searchTables.set(i, table);
+        for (const suffix of FTS5_SHADOW_SUFFIXES)
+            shadowNames.set(`${name}_${suffix}`.toLowerCase(), { ...table, suffix });
+    });
     scanned.forEach((scannedStatement, i) => {
         const statementNumber = i + 1;
-        const text = dumpSql.slice(scannedStatement.startIndex, scannedStatement.endIndex);
+        const text = textOf(scannedStatement);
         const [firstWord = "", secondWord = "", thirdWord = ""] = scannedStatement.leadingWords;
         const words = scannedStatement.leadingWords.join(" ");
         const isSkipped = ["BEGIN", "COMMIT", "END", "ROLLBACK", "ANALYZE"].includes(firstWord) ||
@@ -162,7 +285,30 @@ export function importStatements(dumpSql) {
             skippedStatementCount++;
             return;
         }
-        const refuse = (message) => new DatabaseError("bad_sql", `Statement ${statementNumber} of the dump (${preview(text)}): ${message}`, IMPORT_FIX);
+        const refuse = (message) => refuseAt(statementNumber, text, message);
+        if (firstWord === "INSERT" && secondWord === "INTO" && (thirdWord === "SQLITE_SCHEMA" || thirdWord === "SQLITE_MASTER")) {
+            statements.push({ sql: searchTables.get(i).createSql, values: [], statementNumber });
+            return;
+        }
+        if (shadowNames.size) {
+            const shadow = shadowNames.get(tableNameAfter(text, firstWord === "CREATE" ? /CREATE\s+TABLE(?:\s+IF\s+NOT\s+EXISTS)?/ : /INSERT\s+INTO/)?.toLowerCase() ?? "");
+            if (shadow && (firstWord === "CREATE" || firstWord === "INSERT")) {
+                if (firstWord === "CREATE" || shadow.suffix !== "content") {
+                    skippedStatementCount++;
+                    return;
+                }
+                // The rows of a search table are in its _content, by rowid; they go back in through the table itself.
+                const bound = bindLiterals(text, refuse);
+                const insertInto = `INSERT INTO ${quoteName(shadow.name)}(${["rowid", ...shadow.columnNames.map(quoteName)].join(",")}) VALUES(`;
+                const replaced = bound.sql.replace(/^INSERT\s+INTO\s+(?:"(?:[^"]|"")*"|\w+)\s+VALUES\s*\(/i, insertInto);
+                if (replaced === bound.sql)
+                    throw refuse("a search table's content rows are INSERT INTO \"name_content\" VALUES(…).");
+                if (bound.values.length > DATABASE_LIMITS.maximumValueCount)
+                    throw new DatabaseError("bad_values", `Statement ${statementNumber} of the dump (${preview(text)}) has ${bound.values.length} text and blob values.`, `Give each row its own INSERT, as sqlite3's .dump does: the database takes up to ${DATABASE_LIMITS.maximumValueCount} values a statement.`);
+                statements.push({ sql: replaced, values: bound.values, statementNumber });
+                return;
+            }
+        }
         if (firstWord === "CREATE") {
             statements.push({ sql: text, values: [], statementNumber });
             return;
@@ -188,7 +334,9 @@ export function importStatements(dumpSql) {
             throw new DatabaseError("bad_values", `Statement ${statementNumber} of the dump (${preview(text)}) has ${bound.values.length} text and blob values.`, `Give each row its own INSERT, as sqlite3's .dump does: the database takes up to ${DATABASE_LIMITS.maximumValueCount} values a statement.`);
         statements.push({ sql: bound.sql, values: bound.values, statementNumber });
     });
-    return { statements, statementCount: scanned.length, skippedStatementCount };
+    // Tables first, in the order given, then the rest in theirs: a row may refer to a table made after it.
+    const isTable = (statement) => /^CREATE\s+(?:VIRTUAL\s+)?TABLE\s/i.test(statement.sql);
+    return { statements: [...statements.filter(isTable), ...statements.filter((statement) => !isTable(statement))], statementCount: scanned.length, skippedStatementCount };
 }
 /** The start of a statement, for an error. */
 export function preview(text) {