@zhin.js/gateway 1.1.2 → 1.3.0

package/lib/database/config.js

@@ -53,6 +53,32 @@ function normalizeRedisDatabase(value) {
     }
     return normalized;
 }
+/** `database.console` (ADR 0059 §4; port of the instance's check): PostgreSQL / MySQL only. */
+function normalizeConsoleCredential(config) {
+    if (!('console' in config) || config.console === undefined)
+        return;
+    const value = config.console;
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw configurationError('database.console', '必须是对象 { user, password }');
+    const block = { ...value };
+    // `${ZHIN_DB_CONSOLE_*}` not set (yet): no restricted account — raw SQL stays off, the rest works.
+    if ((block.user === undefined || block.user === '') && (block.password === undefined || block.password === '')) {
+        delete config.console;
+        return;
+    }
+    normalizeRequiredText(block, 'user', 'database.console.user', 'ZHIN_DB_CONSOLE_USER=zhin_console_xxxxxxxx');
+    if (typeof block.password !== 'string' || block.password === '') {
+        throw configurationError('database.console.password', '不能为空', 'ZHIN_DB_CONSOLE_PASSWORD=…（zhin db console-role 生成）');
+    }
+    if (String(block.user) === String(config.user ?? '')) {
+        throw configurationError('database.console.user', '不能与主账号 database.user 相同（原始 SQL 只在受限账号上执行）');
+    }
+    for (const key of Object.keys(block)) {
+        if (key !== 'user' && key !== 'password')
+            throw configurationError(`database.console.${key}`, '不支持（只有 user 与 password）');
+    }
+    config.console = Object.freeze({ user: block.user, password: block.password });
+}
 /** Validates an expanded `database` block (port of `normalizeDatabaseHostConfig`). */
 export function normalizeProjectDatabaseConfig(input) {
     const dialect = input.dialect;
@@ -60,6 +86,9 @@ export function normalizeProjectDatabaseConfig(input) {
         throw new TypeError(`数据库配置 database.dialect 不支持 ${JSON.stringify(dialect)}；可选值为 sqlite、mysql、pg、mongodb、redis、memory。`);
     }
     const config = { ...input, dialect };
+    if (dialect !== 'pg' && dialect !== 'mysql')
+        delete config.console;
+    delete config.denyAttach;
     switch (dialect) {
         case 'mysql':
             normalizeOptionalText(config, 'host', 'database.host', 'DB_HOST=127.0.0.1');
@@ -69,6 +98,7 @@ export function normalizeProjectDatabaseConfig(input) {
             config.port = normalizePort(config.port, 'database.port', 'DB_PORT=3306');
             if (config.port === undefined)
                 delete config.port;
+            normalizeConsoleCredential(config);
             break;
         case 'pg':
             normalizeOptionalText(config, 'host', 'database.host', 'DB_HOST=127.0.0.1');
@@ -78,6 +108,7 @@ export function normalizeProjectDatabaseConfig(input) {
             config.port = normalizePort(config.port, 'database.port', 'DB_PORT=5432');
             if (config.port === undefined)
                 delete config.port;
+            normalizeConsoleCredential(config);
             break;
         case 'mongodb':
             normalizeRequiredText(config, 'url', 'database.url', 'DB_URL=mongodb://127.0.0.1:27017');

package/lib/database/console-role.d.ts

@@ -0,0 +1,35 @@
+import { type ConsoleCredentialDialect } from '@zhin.js/database';
+export declare const CONSOLE_ROLE_USER_ENV = "ZHIN_DB_CONSOLE_USER";
+export declare const CONSOLE_ROLE_PASSWORD_ENV = "ZHIN_DB_CONSOLE_PASSWORD";
+/** Stands for the password in `--print-sql` output (the real one is only written to `.env`). */
+export declare const CONSOLE_ROLE_PASSWORD_PLACEHOLDER = "<ZHIN_DB_CONSOLE_PASSWORD>";
+export declare class ConsoleRoleError extends Error {
+    readonly code: 'unsupported' | 'unavailable' | 'pending_migration' | 'denied';
+    constructor(code: 'unsupported' | 'unavailable' | 'pending_migration' | 'denied', message: string, options?: {
+        cause?: unknown;
+    });
+}
+export interface SetupConsoleRoleOptions {
+    readonly projectRoot: string;
+    /** Selects `.env.<environment>` for `${…}` (default `development`). */
+    readonly environment?: string;
+    /** Role name (default `zhin_console_<hash of the project root>`). */
+    readonly role?: string;
+    /**
+     * Do not create the account: write the password to `.env` and the reference to the config,
+     * and return the statements for a DBA (password shown as {@link CONSOLE_ROLE_PASSWORD_PLACEHOLDER}).
+     */
+    readonly printSql?: boolean;
+}
+export interface SetupConsoleRoleResult {
+    readonly dialect: ConsoleCredentialDialect;
+    readonly user: string;
+    /** Created / rotated by this run (false with `printSql`). */
+    readonly provisioned: boolean;
+    /** The statements (password replaced by the placeholder). */
+    readonly statements: readonly string[];
+    readonly envFile: string;
+}
+export declare function setupConsoleRole(options: SetupConsoleRoleOptions): Promise<SetupConsoleRoleResult>;
+/** The default role name of a project (what `zhin db console-role` creates). */
+export declare function defaultConsoleRoleName(projectRoot: string): string;

package/lib/database/console-role.js

@@ -0,0 +1,108 @@
+/**
+ * `zhin db console-role` and `zhin doctor --fix` (ADR 0059 §4): create the restricted database
+ * account raw Console SQL runs on (PostgreSQL / MySQL), with the main account, store its password
+ * in `.env` and reference it from `database.console`. Never run at instance start: the instance
+ * only probes the account (and refreshes PostgreSQL grants).
+ */
+import { join } from 'node:path';
+import { createConfigDocument } from '@zhin.js/runtime';
+import { DEFAULT_ROOT_CONFIG_FILE_NAME } from '@zhin.js/plugin-runtime';
+import { consoleRoleName, generateConsolePassword, planConsoleRole, provisionConsoleRole, scrubSecret, } from '@zhin.js/database';
+import { ConsoleConfigurationStore } from '../config/configuration.js';
+import { readEnvFile, writeEnvFile } from '../config/environment-files.js';
+import { upsertDotenv } from '../iam/setup-service.js';
+import { IAM_TABLES } from '../iam/tables.js';
+import { findConfigFile } from '../project/config-file.js';
+import { loadExpandedProjectConfig, resolveProjectDatabaseConfig } from './config.js';
+import { ProjectDatabase } from './project-database.js';
+export const CONSOLE_ROLE_USER_ENV = 'ZHIN_DB_CONSOLE_USER';
+export const CONSOLE_ROLE_PASSWORD_ENV = 'ZHIN_DB_CONSOLE_PASSWORD';
+/** Stands for the password in `--print-sql` output (the real one is only written to `.env`). */
+export const CONSOLE_ROLE_PASSWORD_PLACEHOLDER = `<${CONSOLE_ROLE_PASSWORD_ENV}>`;
+export class ConsoleRoleError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = 'ConsoleRoleError';
+    }
+}
+const ENV_REFERENCE = { user: `\${${CONSOLE_ROLE_USER_ENV}}`, password: `\${${CONSOLE_ROLE_PASSWORD_ENV}}` };
+export async function setupConsoleRole(options) {
+    const { projectRoot } = options;
+    const expanded = await loadExpandedProjectConfig(projectRoot, options.environment ?? 'development');
+    const config = await resolveProjectDatabaseConfig(projectRoot, expanded);
+    if (config.dialect !== 'pg' && config.dialect !== 'mysql') {
+        throw new ConsoleRoleError('unsupported', `项目数据库是 ${config.dialect}：只有 PostgreSQL / MySQL 需要受限账号（SQLite 的 Console 账号在另一个文件里，且实例连接拒绝 ATTACH）`);
+    }
+    const dialect = config.dialect;
+    const main = new ProjectDatabase(config);
+    try {
+        await main.start();
+    }
+    catch (error) {
+        throw new ConsoleRoleError('unavailable', `无法用主账号连接项目数据库：${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    const password = generateConsolePassword();
+    let statements;
+    let user;
+    try {
+        // The old console_* tables would be inside a MySQL database-wide grant: import them first.
+        const legacy = await main.tableExists(Object.values(IAM_TABLES));
+        if (legacy.length) {
+            throw new ConsoleRoleError('pending_migration', `项目数据库里还有旧版的 Console 账号表（${legacy.join(', ')}）：先运行 zhin start 或 zhin console migrate 完成迁移`);
+        }
+        const run = (sql, params) => main.query(sql, params);
+        const request = { dialect, projectKey: projectRoot, password, ...(options.role ? { role: options.role } : {}) };
+        if (options.printSql) {
+            const plan = await planConsoleRole(run, request);
+            statements = plan.statements;
+            user = plan.user;
+        }
+        else {
+            try {
+                const plan = await provisionConsoleRole(run, request);
+                statements = plan.statements;
+                user = plan.user;
+            }
+            catch (error) {
+                // The message never carries the new password (provisionConsoleRole scrubs; scrub again here).
+                throw new ConsoleRoleError('denied', scrubSecret(`主账号无法创建受限账号（${error instanceof Error ? error.message : String(error)}）；改用 zhin db console-role --print-sql 把 SQL 交给 DBA 执行`, [password]));
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof ConsoleRoleError)
+            throw error;
+        throw new ConsoleRoleError('unavailable', scrubSecret(error instanceof Error ? error.message : String(error), [password]));
+    }
+    finally {
+        await main.stop().catch(() => undefined);
+    }
+    // The password lives only in .env (ADR 0057); the config references it.
+    await writeEnvFile(projectRoot, '.env', upsertDotenv(await readEnvFile(projectRoot, '.env'), {
+        [CONSOLE_ROLE_USER_ENV]: user,
+        [CONSOLE_ROLE_PASSWORD_ENV]: password,
+    }));
+    const store = new ConsoleConfigurationStore({
+        projectRoot,
+        document: createConfigDocument(join(projectRoot, findConfigFile(projectRoot) ?? DEFAULT_ROOT_CONFIG_FILE_NAME)),
+    });
+    const document = await store.readDocument();
+    const block = document.database && typeof document.database === 'object' && !Array.isArray(document.database)
+        ? document.database
+        : { dialect };
+    await store.setKey('database', { ...block, console: { ...ENV_REFERENCE } });
+    return Object.freeze({
+        dialect,
+        user,
+        provisioned: !options.printSql,
+        // PostgreSQL statements carry a SCRAM verifier, never the password; MySQL's are shown with a placeholder.
+        statements: Object.freeze(statements.map(statement => scrubSecret(statement, [password]).split('[redacted]').join(CONSOLE_ROLE_PASSWORD_PLACEHOLDER))),
+        envFile: '.env',
+    });
+}
+/** The default role name of a project (what `zhin db console-role` creates). */
+export function defaultConsoleRoleName(projectRoot) {
+    return consoleRoleName(projectRoot);
+}

package/lib/database/gateway-store.d.ts

@@ -0,0 +1,43 @@
+import type { DatabaseHostModel } from '@zhin.js/plugin-runtime';
+import { type ProjectDatabaseTransaction } from './project-database.js';
+/** Project-relative path of the gateway store. */
+export declare const GATEWAY_STORE_FILE: string;
+/** Key / value table of the gateway store (`schema_version`, `legacy_import`). */
+export declare const GATEWAY_META_TABLE = "gateway_meta";
+/** Schema version written to `gateway_meta.schema_version`. */
+export declare const GATEWAY_STORE_SCHEMA_VERSION = 1;
+export interface GatewayStore {
+    /** Absolute path of `gateway.db`. */
+    readonly filename: string;
+    /**
+     * Random id of this store (`gateway_meta.store_id`), also written to the marker in the project
+     * database (ADR 0059 §3 修订): a new or different gateway.db is noticed instead of reopening setup.
+     */
+    readonly storeId: string;
+    readonly started: boolean;
+    readonly models: {
+        get(name: string): DatabaseHostModel | undefined;
+    };
+    /** JSON value of a `gateway_meta` key, or undefined. */
+    getMeta<T = unknown>(key: string, trx?: ProjectDatabaseTransaction): Promise<T | undefined>;
+    setMeta(key: string, value: unknown, trx?: ProjectDatabaseTransaction): Promise<void>;
+    deleteMeta(key: string, trx?: ProjectDatabaseTransaction): Promise<void>;
+    /** A write transaction (`BEGIN IMMEDIATE`: also the lock between the gateway and the CLI). */
+    transaction<T>(callback: (trx: ProjectDatabaseTransaction) => Promise<T>): Promise<T>;
+    query<T = unknown>(sql: string, params?: unknown[]): Promise<T>;
+    /** Rows in each of the access-control tables. */
+    counts(trx?: ProjectDatabaseTransaction): Promise<Readonly<Record<string, number>>>;
+    /** A consistent copy of `gateway.db` (0600). */
+    backupTo(destination: string): Promise<void>;
+    close(): Promise<void>;
+}
+export interface OpenGatewayStoreOptions {
+    /** Overrides the file (tests). Default `<projectRoot>/.zhin/gateway.db`. */
+    readonly filename?: string;
+    /** `SQLITE_BUSY` async retry budget (default {@link GATEWAY_SQLITE_BUSY_RETRY_MS}). */
+    readonly busyRetryMs?: number;
+}
+/** `<projectRoot>/.zhin/gateway.db`. */
+export declare function gatewayStorePath(projectRoot: string): string;
+/** Opens (creating if needed) the gateway store with its tables. */
+export declare function openGatewayStore(projectRoot: string, options?: OpenGatewayStoreOptions): Promise<GatewayStore>;

package/lib/database/gateway-store.js

@@ -0,0 +1,90 @@
+/**
+ * The gateway's own store `.zhin/gateway.db` (ADR 0059 §1): the six Console access-control
+ * tables (`IAM_TABLES`) and `gateway_meta`, in SQLite whatever dialect the project database
+ * uses. Owner-only (0600, `-wal` / `-shm` included).
+ *
+ * Opened only by the gateway, by `zhin console …` while no gateway runs, and by a standalone
+ * instance (`zhin start --standalone`, development and tests only: there the instance process
+ * holds both connections, so there is no process isolation). A supervised instance never opens
+ * it, and its own SQLite connection refuses `ATTACH` (`denyAttach`).
+ */
+import { randomBytes } from 'node:crypto';
+import { chmodSync, closeSync, existsSync, mkdirSync, openSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { defineConsoleIamTables, IAM_TABLES } from '../iam/tables.js';
+import { GATEWAY_SQLITE_BUSY_RETRY_MS, ProjectDatabase } from './project-database.js';
+/** Project-relative path of the gateway store. */
+export const GATEWAY_STORE_FILE = join('.zhin', 'gateway.db');
+/** Key / value table of the gateway store (`schema_version`, `legacy_import`). */
+export const GATEWAY_META_TABLE = 'gateway_meta';
+/** Schema version written to `gateway_meta.schema_version`. */
+export const GATEWAY_STORE_SCHEMA_VERSION = 1;
+const META_DEFINITION = Object.freeze({
+    key: { type: 'text', length: 64, primary: true, nullable: false },
+    value: { type: 'text', nullable: false },
+});
+/** `<projectRoot>/.zhin/gateway.db`. */
+export function gatewayStorePath(projectRoot) {
+    return join(projectRoot, GATEWAY_STORE_FILE);
+}
+function restrict(file) {
+    if (process.platform === 'win32')
+        return;
+    if (existsSync(file))
+        chmodSync(file, 0o600);
+}
+/** Opens (creating if needed) the gateway store with its tables. */
+export async function openGatewayStore(projectRoot, options = {}) {
+    const filename = options.filename ?? gatewayStorePath(projectRoot);
+    mkdirSync(dirname(filename), { recursive: true });
+    // Create the file owner-only before SQLite does (it would follow the umask); SQLite gives the
+    // -wal / -shm files the mode of the database file.
+    if (!existsSync(filename))
+        closeSync(openSync(filename, 'a', 0o600));
+    restrict(filename);
+    const database = new ProjectDatabase({ dialect: 'sqlite', filename, busyRetryMs: options.busyRetryMs ?? GATEWAY_SQLITE_BUSY_RETRY_MS });
+    defineConsoleIamTables(database);
+    database.define(GATEWAY_META_TABLE, META_DEFINITION);
+    await database.start();
+    for (const suffix of ['', '-wal', '-shm'])
+        restrict(`${filename}${suffix}`);
+    const run = (sql, params, trx) => (trx ? trx.query(sql, params) : database.query(sql, params));
+    let storeId = '';
+    const store = {
+        filename,
+        get storeId() { return storeId; },
+        get started() { return database.started; },
+        models: database.models,
+        async getMeta(key, trx) {
+            const rows = await run(`SELECT value FROM ${GATEWAY_META_TABLE} WHERE key = ?`, [key], trx);
+            return rows[0] ? JSON.parse(rows[0].value) : undefined;
+        },
+        async setMeta(key, value, trx) {
+            await run(`INSERT INTO ${GATEWAY_META_TABLE} (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value`, [key, JSON.stringify(value)], trx);
+        },
+        async deleteMeta(key, trx) {
+            await run(`DELETE FROM ${GATEWAY_META_TABLE} WHERE key = ?`, [key], trx);
+        },
+        transaction: callback => database.transaction(callback),
+        query: (sql, params) => database.query(sql, params),
+        async counts(trx) {
+            const out = {};
+            for (const table of Object.values(IAM_TABLES)) {
+                const [row] = await run(`SELECT count(*) AS n FROM "${table}"`, [], trx);
+                out[table] = Number(row?.n ?? 0);
+            }
+            return Object.freeze(out);
+        },
+        backupTo: destination => database.backupTo(destination),
+        close: () => database.stop(),
+    };
+    if (await store.getMeta('schema_version') === undefined)
+        await store.setMeta('schema_version', GATEWAY_STORE_SCHEMA_VERSION);
+    storeId = await store.getMeta('store_id') ?? '';
+    if (!storeId) {
+        // Insert-if-absent: two processes opening a new store agree on one id.
+        await database.query(`INSERT INTO ${GATEWAY_META_TABLE} (key, value) VALUES ('store_id', ?) ON CONFLICT(key) DO NOTHING`, [JSON.stringify(randomBytes(16).toString('hex'))]);
+        storeId = await store.getMeta('store_id') ?? '';
+    }
+    return Object.freeze(store);
+}

package/lib/database/index.d.ts

@@ -1,2 +1,4 @@
 export * from './config.js';
+export * from './gateway-store.js';
 export * from './project-database.js';
+export * from './console-role.js';

package/lib/database/index.js

@@ -1,2 +1,4 @@
 export * from './config.js';
+export * from './gateway-store.js';
 export * from './project-database.js';
+export * from './console-role.js';

package/lib/database/project-database.d.ts

@@ -14,6 +14,21 @@ export declare const DATABASE_BUSY_RETRY_AFTER_SECONDS = 2;
 export declare function isDatabaseBusyError(error: unknown): boolean;
 /** `503 { code: 'database_busy' }` with `Retry-After`. */
 export declare function databaseBusyResponse(extra?: Readonly<Record<string, unknown>>): Response;
+/** One statement inside {@link ProjectDatabase.transaction}. */
+export interface ProjectDatabaseTransaction {
+    query<T = unknown>(sql: string, params?: unknown[]): Promise<T>;
+}
+/** The gateway's marker in the project database. */
+export interface StoreMarker {
+    readonly storeId: string;
+    readonly migratedAt: number;
+}
+/** Rows keyed by table name. */
+export type TableRows = Readonly<Record<string, readonly Record<string, unknown>[]>>;
+/** Rows read per batch by {@link ProjectDatabase.readSnapshot}. */
+export declare const SNAPSHOT_BATCH_SIZE = 500;
+/** A quoted table name for `dialect`. */
+export declare function quoteTableName(dialect: string, name: string): string;
 /** One database connection; tables are defined before {@link start}. */
 export declare class ProjectDatabase {
     #private;
@@ -26,6 +41,36 @@ export declare class ProjectDatabase {
     readonly models: Readonly<{
         get: (name: string) => DatabaseHostModel | undefined;
     }>;
+    /** Whether raw SQL / transactions are available (SQLite, MySQL, PostgreSQL). */
+    get relational(): boolean;
+    /** One raw statement (gateway-internal: the gateway store, the legacy import and its revert). */
+    query<T = unknown>(sql: string, params?: unknown[]): Promise<T>;
+    /** A transaction (SQLite write transactions are `BEGIN IMMEDIATE`). */
+    transaction<T>(callback: (trx: ProjectDatabaseTransaction) => Promise<T>, options?: {
+        readOnly?: boolean;
+        repeatableRead?: boolean;
+    }): Promise<T>;
+    /** SQLite: a consistent copy of the file at `destination` (0600). */
+    backupTo(destination: string): Promise<void>;
+    /** Which of `names` exist as tables (collections), read from the system catalog without defining them. */
+    tableExists(names: readonly string[]): Promise<string[]>;
+    /**
+     * All rows of `tables`, read in batches of {@link SNAPSHOT_BATCH_SIZE} ordered by `id`. SQL
+     * dialects read inside one read-only repeatable-read transaction (one snapshot); MongoDB reads
+     * the collections one after another.
+     */
+    readSnapshot(tables: readonly string[]): Promise<TableRows>;
+    /**
+     * Drops `tables` if they exist: in one transaction on SQLite / PostgreSQL, one by one on MySQL
+     * (DDL commits implicitly) and MongoDB, where an interrupted run resumes with the rest.
+     */
+    dropTables(tables: readonly string[]): Promise<void>;
+    /** The gateway's marker (ADR 0059 §3 修订): which gateway.db holds the Console accounts, or undefined. */
+    readStoreMarker(): Promise<StoreMarker | undefined>;
+    /** Writes (replaces) the marker. */
+    writeStoreMarker(marker: StoreMarker): Promise<void>;
+    /** Removes the marker (revert to a version without it). */
+    deleteStoreMarker(): Promise<void>;
     start(): Promise<void>;
     stop(): Promise<void>;
 }

package/lib/database/project-database.js

@@ -1,10 +1,11 @@
 /**
- * The gateway's own connection to the project database (ADR 0054 §7). It defines and serves only
- * the tables the gateway owns (`console_*`, ADR 0049); the instance opens the same database for
- * everything else. SQLite runs in WAL mode (`@zhin.js/database`), so both processes can hold the
- * file open.
+ * A connection the gateway opens itself (ADR 0054 §7, ADR 0059): its own store
+ * `.zhin/gateway.db` (`openGatewayStore`), and — only while importing the Console tables an
+ * earlier version left in the project database, reverting that import, or testing a connection
+ * in the setup wizard — a short-lived connection to the project database. SQLite runs in WAL
+ * mode (`@zhin.js/database`), so several processes can hold a file open.
  */
-import { isSqliteBusyError, Registry } from '@zhin.js/database';
+import { GATEWAY_STORE_MARKER_TABLE, isSqliteBusyError, Registry } from '@zhin.js/database';
 /**
  * How long a gateway statement retries `SQLITE_BUSY` while the instance holds the write lock
  * (`busyRetryMs` in `@zhin.js/database`). The retry backs off asynchronously, so the gateway's
@@ -40,6 +41,22 @@ export function databaseBusyResponse(extra = {}) {
         },
     });
 }
+function markerOf(row) {
+    return Object.freeze({ storeId: String(row.store_id ?? ''), migratedAt: Number(row.migrated_at ?? 0) });
+}
+const SQL_DIALECTS = new Set(['sqlite', 'mysql', 'pg']);
+/** Rows read per batch by {@link ProjectDatabase.readSnapshot}. */
+export const SNAPSHOT_BATCH_SIZE = 500;
+const BACKTICK = String.fromCharCode(96);
+/** A quoted table name for `dialect`. */
+export function quoteTableName(dialect, name) {
+    return dialect === 'mysql'
+        ? BACKTICK + name.split(BACKTICK).join(BACKTICK + BACKTICK) + BACKTICK
+        : `"${name.replace(/"/gu, '""')}"`;
+}
+function placeholder(dialect, index) {
+    return dialect === 'pg' ? `$${index}` : '?';
+}
 function wrapModel(model) {
     return Object.freeze({
         select: (...fields) => {
@@ -68,7 +85,8 @@ export class ProjectDatabase {
     #started = false;
     constructor(config) {
         this.config = config;
-        const { dialect, ...connection } = config;
+        // `console` (the restricted Console account, ADR 0059) and `denyAttach` (instance only) never reach the driver.
+        const { dialect, console: _console, denyAttach: _denyAttach, ...connection } = config;
         // No synchronous busy_timeout: it would block the gateway's event loop (ADR 0054 §7).
         const options = dialect === 'sqlite' && connection.busyRetryMs === undefined
             ? { ...connection, busyRetryMs: GATEWAY_SQLITE_BUSY_RETRY_MS }
@@ -107,6 +125,194 @@ export class ProjectDatabase {
             return model;
         },
     });
+    /** Whether raw SQL / transactions are available (SQLite, MySQL, PostgreSQL). */
+    get relational() {
+        return SQL_DIALECTS.has(this.config.dialect);
+    }
+    #requireStarted() {
+        if (!this.#started)
+            throw new Error('Database is not connected');
+    }
+    #requireSql() {
+        this.#requireStarted();
+        if (!this.relational)
+            throw new Error(`Raw SQL is not supported by '${this.config.dialect}'`);
+    }
+    /** One raw statement (gateway-internal: the gateway store, the legacy import and its revert). */
+    async query(sql, params) {
+        this.#requireSql();
+        return this.#db.query(sql, params);
+    }
+    /** A transaction (SQLite write transactions are `BEGIN IMMEDIATE`). */
+    async transaction(callback, options) {
+        this.#requireSql();
+        return this.#db.transaction(trx => callback({ query: (sql, params) => trx.query(sql, params) }), {
+            ...(options?.readOnly ? { readOnly: true } : {}),
+            ...(options?.repeatableRead ? { isolationLevel: 'REPEATABLE_READ' } : {}),
+        });
+    }
+    /** SQLite: a consistent copy of the file at `destination` (0600). */
+    async backupTo(destination) {
+        this.#requireStarted();
+        if (this.config.dialect !== 'sqlite' || typeof this.#db.dialect?.backupTo !== 'function') {
+            throw new Error(`File backups need SQLite (current: ${this.config.dialect})`);
+        }
+        await this.#db.dialect.backupTo(destination);
+    }
+    /** Which of `names` exist as tables (collections), read from the system catalog without defining them. */
+    async tableExists(names) {
+        this.#requireStarted();
+        if (!names.length)
+            return [];
+        const { dialect } = this.config;
+        let present;
+        if (dialect === 'sqlite') {
+            const rows = await this.query(`SELECT name FROM sqlite_master WHERE type = 'table' AND name IN (${names.map(() => '?').join(', ')})`, [...names]);
+            present = rows.map(row => row.name);
+        }
+        else if (dialect === 'pg') {
+            present = [];
+            for (const name of names) {
+                const [row] = await this.query('SELECT to_regclass($1) IS NOT NULL AS present', [quoteTableName('pg', name)]);
+                if (row?.present === true)
+                    present.push(name);
+            }
+        }
+        else if (dialect === 'mysql') {
+            const rows = await this.query(`SELECT TABLE_NAME AS name FROM information_schema.TABLES WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME IN (${names.map(() => '?').join(', ')})`, [...names]);
+            present = rows.map(row => String(row.name ?? row.TABLE_NAME));
+        }
+        else if (dialect === 'mongodb') {
+            const rows = await this.#db.query({ collection: names[0], operation: 'listCollections', filter: { name: { $in: [...names] } } });
+            present = rows.map(row => row.name);
+        }
+        else {
+            return [];
+        }
+        return names.filter(name => present.includes(name));
+    }
+    /**
+     * All rows of `tables`, read in batches of {@link SNAPSHOT_BATCH_SIZE} ordered by `id`. SQL
+     * dialects read inside one read-only repeatable-read transaction (one snapshot); MongoDB reads
+     * the collections one after another.
+     */
+    async readSnapshot(tables) {
+        this.#requireStarted();
+        const { dialect } = this.config;
+        const out = {};
+        if (dialect === 'mongodb') {
+            for (const table of tables) {
+                const rows = [];
+                let after;
+                for (;;) {
+                    const batch = await this.#db.query({
+                        collection: table,
+                        operation: 'find',
+                        filter: after === undefined ? {} : { id: { $gt: after } },
+                        sort: { id: 1 },
+                        limit: SNAPSHOT_BATCH_SIZE,
+                    });
+                    for (const document of batch) {
+                        const { _id: _ignored, ...row } = document;
+                        rows.push(row);
+                    }
+                    if (batch.length < SNAPSHOT_BATCH_SIZE)
+                        break;
+                    after = batch[batch.length - 1].id;
+                }
+                out[table] = rows;
+            }
+            return Object.freeze(out);
+        }
+        this.#requireSql();
+        await this.transaction(async (trx) => {
+            for (const table of tables) {
+                const rows = [];
+                let after;
+                for (;;) {
+                    const where = after === undefined ? '' : ` WHERE id > ${placeholder(dialect, 1)}`;
+                    const batch = await trx.query(`SELECT * FROM ${quoteTableName(dialect, table)}${where} ORDER BY id LIMIT ${SNAPSHOT_BATCH_SIZE}`, after === undefined ? [] : [after]);
+                    rows.push(...batch.map(row => ({ ...row })));
+                    if (batch.length < SNAPSHOT_BATCH_SIZE)
+                        break;
+                    after = batch[batch.length - 1].id;
+                }
+                out[table] = rows;
+            }
+        }, { readOnly: true, repeatableRead: dialect !== 'sqlite' });
+        return Object.freeze(out);
+    }
+    /**
+     * Drops `tables` if they exist: in one transaction on SQLite / PostgreSQL, one by one on MySQL
+     * (DDL commits implicitly) and MongoDB, where an interrupted run resumes with the rest.
+     */
+    async dropTables(tables) {
+        this.#requireStarted();
+        const { dialect } = this.config;
+        if (dialect === 'mongodb') {
+            for (const table of await this.tableExists(tables)) {
+                await this.#db.query({ collection: table, operation: 'dropCollection', filter: {} });
+            }
+            return;
+        }
+        this.#requireSql();
+        const statements = tables.map(table => `DROP TABLE IF EXISTS ${quoteTableName(dialect, table)}`);
+        if (dialect === 'mysql') {
+            for (const statement of statements)
+                await this.query(statement);
+            return;
+        }
+        await this.transaction(async (trx) => {
+            for (const statement of statements)
+                await trx.query(statement);
+        });
+    }
+    /** The gateway's marker (ADR 0059 §3 修订): which gateway.db holds the Console accounts, or undefined. */
+    async readStoreMarker() {
+        this.#requireStarted();
+        const { dialect } = this.config;
+        if (!(await this.tableExists([GATEWAY_STORE_MARKER_TABLE])).length)
+            return undefined;
+        if (dialect === 'mongodb') {
+            const [row] = await this.#db.query({ collection: GATEWAY_STORE_MARKER_TABLE, operation: 'find', filter: { id: 'gateway' }, limit: 1 });
+            return row ? markerOf(row) : undefined;
+        }
+        const [row] = await this.query(`SELECT store_id, migrated_at FROM ${quoteTableName(dialect, GATEWAY_STORE_MARKER_TABLE)} WHERE id = ${placeholder(dialect, 1)}`, ['gateway']);
+        return row ? markerOf(row) : undefined;
+    }
+    /** Writes (replaces) the marker. */
+    async writeStoreMarker(marker) {
+        this.#requireStarted();
+        const { dialect } = this.config;
+        if (dialect === 'mongodb') {
+            await this.#db.query({ collection: GATEWAY_STORE_MARKER_TABLE, operation: 'deleteMany', filter: { id: 'gateway' } });
+            await this.#db.query({ collection: GATEWAY_STORE_MARKER_TABLE, operation: 'insertOne', filter: {} }, [{ id: 'gateway', store_id: marker.storeId, migrated_at: marker.migratedAt }]);
+            return;
+        }
+        this.#requireSql();
+        const table = quoteTableName(dialect, GATEWAY_STORE_MARKER_TABLE);
+        await this.query(`CREATE TABLE IF NOT EXISTS ${table} (id VARCHAR(32) NOT NULL PRIMARY KEY, store_id VARCHAR(64) NOT NULL, migrated_at BIGINT NOT NULL)`);
+        if (dialect === 'pg') {
+            // The main account's default privileges would grant it to the restricted Console account
+            // (ADR 0059 §4): take that, and PUBLIC's, away at once. (MySQL grants that account the whole
+            // database; there only the text guard and the start-up probe keep it off this table.)
+            await this.query(`REVOKE ALL ON TABLE ${table} FROM PUBLIC`);
+            // Every role the default privileges (or anyone) granted it to, the console account included,
+            // whether or not this connection knows `database.console`.
+            const grantees = await this.query(`SELECT DISTINCT a.grantee::regrole::text AS grantee
+        FROM pg_class c, aclexplode(c.relacl) a WHERE c.oid = to_regclass($1) AND a.grantee <> c.relowner AND a.grantee <> 0`, [table]);
+            for (const { grantee } of grantees)
+                await this.query(`REVOKE ALL ON TABLE ${table} FROM ${grantee}`);
+        }
+        await this.transaction(async (trx) => {
+            await trx.query(`DELETE FROM ${table} WHERE id = ${placeholder(dialect, 1)}`, ['gateway']);
+            await trx.query(`INSERT INTO ${table} (id, store_id, migrated_at) VALUES (${placeholder(dialect, 1)}, ${placeholder(dialect, 2)}, ${placeholder(dialect, 3)})`, ['gateway', marker.storeId, marker.migratedAt]);
+        });
+    }
+    /** Removes the marker (revert to a version without it). */
+    async deleteStoreMarker() {
+        await this.dropTables([GATEWAY_STORE_MARKER_TABLE]);
+    }
     async start() {
         if (this.#started)
             return;