cross-sqlite-client 0.1.0 → 0.2.0

package/README.md

@@ -90,7 +90,7 @@ function TodoList() {
   if (dbError) return <ErrorMessage error={dbError} />;
   if (!isDbReady || !dbClient) return null;
 
-  // dbClient.select<T>(sql, params?) / dbClient.execute(sql, params?) / dbClient.close()
+  // dbClient.select<T>(sql, params?) / dbClient.execute(sql, params?) / dbClient.executeBatch(statements) / dbClient.close()
   // ...
 }
 ```
@@ -101,11 +101,12 @@ function TodoList() {
 
 | Export | What it is |
 |---|---|
-| `createDbClient(options)` | Resolves the adapter, initializes it, runs pending migrations, returns `Promise<DbClient>`. |
+| `createDbClient(options)` | Resolves the adapter, initializes it, applies `pragmas`, runs pending migrations, returns `Promise<DbClient>`. If PRAGMA/migration setup fails, the already-opened connection is closed before the error propagates. |
 | `runMigrations(db, migrations, options?)` | The migration runner `createDbClient` uses internally — call it directly if you're not going through `createDbClient`. |
-| `defaultExecutor` | The migration executor used when `migrationOptions.executor` isn't set — runs each statement with no transaction. |
-| `DbClient` (type) | `{ select<T>(sql, params?), execute(sql, params?), close() }` — see below. |
+| `defaultExecutor` | The migration executor used when `migrationOptions.executor` isn't set — runs all of a migration's statements via `executeBatch()`, with no transaction. |
+| `DbClient` (type) | `{ select<T>(sql, params?), execute(sql, params?), executeBatch(statements), close() }` — see below. |
 | `DbAdapter` / `DbAdapterConfig` (types) | The interface each `createXAdapter()` factory returns / the `{ name }` config passed to `initialize()`. |
+| `BatchStatement` / `Logger` (types) | `string \| { sql, params? }` for `executeBatch()` / the diagnostics channel (`{ warn, error }`, defaults to `console`). |
 | `Migration` / `MigrationExecutor` / `MigrationOptions` (types) | See [Writing migrations](#writing-migrations). |
 | `DbError` and subclasses | See [Errors](#errors). |
 
@@ -119,10 +120,41 @@ import { createDbClient, runMigrations, defaultExecutor } from "cross-sqlite-cli
 interface DbClient {
   select<T>(sql: string, params?: unknown[]): Promise<T[]>;
   execute(sql: string, params?: unknown[]): Promise<{ lastInsertId?: number; rowsAffected?: number }>;
+  executeBatch(statements: BatchStatement[]): Promise<void>;
   close(): Promise<void>;
 }
 ```
 
+`executeBatch()` runs a batch of statements in order with **no cross-statement
+transaction guarantee** — when every statement is parameterless, the web and
+memory adapters join them into a single SQL string and send it to the
+underlying engine in one call (the web adapter saves one Worker round-trip per
+statement); if *any* statement carries bound params, the whole batch falls
+back to running one by one. The library deliberately does not
+offer a business-facing transaction API: pooled-connection adapters (Tauri)
+can't guarantee `BEGIN`/`COMMIT` land on the same physical connection, so
+business multi-statement writes should be idempotent instead.
+
+`createDbClient()` also accepts two optional fields:
+
+```ts
+await createDbClient({
+  name: "my-app",
+  adapter,
+  migrations: APP_MIGRATIONS,
+  // Applied right after initialize, before migrations. Keys must be identifiers;
+  // string values must be enum-like tokens (WAL, NORMAL, ...); booleans become 0/1;
+  // numbers are inlined as-is.
+  // Note: on pooled-connection adapters (Tauri), connection-level pragmas such as
+  // foreign_keys/busy_timeout only apply to one pooled connection and silently won't
+  // hold for later queries (createDbClient logs a warning); database-level pragmas
+  // like journal_mode/user_version work everywhere.
+  pragmas: { foreign_keys: true, journal_mode: "WAL" },
+  // Diagnostics channel for library warnings/errors (default: console).
+  logger: myLogger, // { warn(message, ...args), error(message, ...args) }
+});
+```
+
 ### Adapters
 
 Each `createXAdapter()` call returns a fresh, independent `DbAdapter` instance
@@ -145,8 +177,9 @@ for why that matters.
 | Option | Default | Meaning |
 |---|---|---|
 | `timeoutMs` | `15000` | How long to wait for the SQLite worker to become ready before `initialize()` rejects. Without this, a failed worker-script load would leave `initialize()` pending forever. |
-| `fallbackToMemory` | `true` | Whether to silently use `:memory:` when OPFS isn't available, instead of throwing. See [COOP/COEP](#coopcoep-required-for-opfs-persistence). |
+| `fallbackToMemory` | `true` | Whether to silently use `:memory:` when OPFS isn't available — including when the OPFS probe passes but opening the file fails — instead of throwing. See [COOP/COEP](#coopcoep-required-for-opfs-persistence). |
 | `singleTabLock` | `true` | Whether to coordinate access to the same OPFS file across browser tabs. See [Multi-tab coordination](#multi-tab-coordination). |
+| `logger` | `console` | Where diagnostics go (OPFS-fallback warnings, worker errors). Pass your own `{ warn, error }` to route them into your logging/telemetry. |
 
 **`createTauriAdapter()`** and **`createMemoryAdapter()`** take no options.
 `createMemoryAdapter()` is meant for tests — see [Testing](#testing).
@@ -162,7 +195,9 @@ Two things worth knowing about `DatabaseProvider`:
 
 - **No `retry`.** The `client` prop only ever settles once — retrying means
   passing it a *new* promise, which re-triggers initialization because the
-  prop reference changed:
+  prop reference changed. The moment the prop changes, the context drops back
+  to fully-not-ready (`dbClient: null`, `isDbReady: false`) until the new
+  promise resolves — consumers never see the old connection during the window:
 
   ```tsx
   function App() {
@@ -195,10 +230,12 @@ interface Migration {
 }
 ```
 
-- **Versions must start at 1.** With no migrations applied yet, `runMigrations`
-  treats the current version as `0`; a migration with `version: 0` would never
-  satisfy `version > currentVersion` and would be silently skipped forever.
-  `runMigrations` throws immediately if any `version <= 0`.
+- **Versions must be unique positive integers.** With no migrations applied
+  yet, `runMigrations` treats the current version as `0`; a migration with
+  `version: 0` would never satisfy `version > currentVersion` and would be
+  silently skipped forever. `runMigrations` throws immediately if any version
+  is not a positive integer, or if two migrations share a version. (They don't
+  have to start at 1 or be consecutive — gaps are fine.)
 - **Every statement must be safe to re-run.** There is no cross-platform
   transaction guarantee (see below), so if a migration fails partway, the next
   startup re-runs the *entire* version from scratch. Stick to
@@ -206,11 +243,33 @@ interface Migration {
   non-idempotent change (e.g. renaming a column), check the current schema
   state first — e.g. `SELECT 1 FROM pragma_table_info('t') WHERE name = '...'`
   — and skip the step if it's already done, rather than relying on rollback.
+- **Failures surface as `DbMigrationError`.** The runner wraps whatever the
+  executor threw into a `DbMigrationError` carrying the failing `.version`.
+  `createDbClient()` additionally closes the already-opened connection before
+  re-throwing, so a failed startup leaks no worker, OPFS file handle, or tab
+  lock — retrying (e.g. with a fresh client promise) starts clean.
+- **Late migrations below the current version are not silently dropped.** If
+  the database already applied `[1, 2, 5]` and a new app build ships the
+  missing `3`/`4`, those versions are below `MAX(version)` and would normally
+  be skipped forever; the runner logs a `logger.warn` naming them instead.
+  They are *not* auto-applied — out-of-order application can break schema
+  evolution assumptions — so apply such hotfixes deliberately.
+
+`runMigrations(db, migrations, options?)` (and `createDbClient`'s
+`migrationOptions`) accepts:
+
+```ts
+interface MigrationOptions {
+  tableName?: string;    // version table name, default "schema_version"; identifiers only
+  executor?: MigrationExecutor; // see the next section
+  logger?: Logger;       // overrides createDbClient's logger for migration diagnostics
+}
+```
 
 ## Custom migration executors and `singleConnection`
 
-The default executor (`defaultExecutor`) runs each migration statement
-independently, with no transaction. `adapters/web` also exports a
+The default executor (`defaultExecutor`) runs each migration's statements via
+`executeBatch()`, with no transaction. `adapters/web` also exports a
 `transactionalExecutor` that wraps a migration in `BEGIN`/`COMMIT`/`ROLLBACK` —
 but that's only safe on an adapter whose `singleConnection` is `true` (a real,
 single persistent connection). `@tauri-apps/plugin-sql`'s backend is a
@@ -281,6 +340,10 @@ it to show something like "this app is already open in another tab." Pass
 retry/`SQLITE_BUSY` behavior. This only ever applies to the OPFS-backed path —
 `:memory:` is private per tab, so there's nothing to coordinate there.
 
+The lock primitive itself, `tryAcquireTabLock(lockName)`, is also exported
+from `cross-sqlite-client/adapters/web` for apps that need the same
+best-effort cross-tab coordination for something other than the database.
+
 ## Errors
 
 Every adapter throws one of these (all extend `DbError extends Error`, and all
@@ -290,7 +353,8 @@ accept an optional `cause`):
 |---|---|
 | `DbError` | Generic/usage errors, e.g. calling `select()`/`execute()` before `initialize()` resolves, or after `close()`. |
 | `DbInitializationError` | `adapter.initialize()` failed (worker/OPFS/Tauri-load failure, etc.). |
-| `DbExecutionError` (has `.sql` and `.params`) | A `select()`/`execute()` call failed. |
+| `DbExecutionError` (has `.sql` and `.params`) | A `select()`/`execute()`/`executeBatch()` call failed. |
+| `DbMigrationError` (has `.version`) | A migration failed; wraps the underlying error as `cause`. Thrown by `runMigrations`/`createDbClient`. |
 | `DbCloseError` | `client.close()` failed. |
 | `DbTabLockError` | (Web adapter only, `singleTabLock: true`) Another tab already holds the database. |
 
@@ -326,6 +390,10 @@ await runMigrations(client, APP_MIGRATIONS);
 Each `createMemoryAdapter()` call is a fresh, independent instance, so
 separate tests (or parallel tests in the same process) don't share state.
 
+The library's own suite (`pnpm test`) covers the migration runner, the client
+lifecycle, and the React bindings; CI (`.github/workflows/ci.yml`) runs lint,
+typecheck, tests, build, and `publint` on Node 20/22.
+
 ## Known limitations
 
 - **`lastInsertId` precision.** `DbClient.execute()`'s `lastInsertId` is typed
@@ -342,3 +410,47 @@ separate tests (or parallel tests in the same process) don't share state.
   that could serve as a middle tier, but it wasn't wired in as of this
   writing — pursue it if you need persistence in deployments that can't
   achieve cross-origin isolation (see [COOP/COEP](#coopcoep-required-for-opfs-persistence)).
+
+## Runtime environment notes
+
+Deployment/runtime behaviors that are deliberate tradeoffs rather than bugs:
+
+- **bfcache-frozen tabs hold the database lock.** `singleTabLock` uses the Web
+  Locks API; a tab frozen by the browser's back/forward cache (rather than
+  closed) keeps holding its lock, so other tabs keep getting `DbTabLockError`
+  until the frozen tab is discarded. Locks of genuinely closed or crashed tabs
+  are released by the browser automatically.
+- **No Web Locks API → no cross-tab coordination.** On old browsers or
+  insecure (non-HTTPS) contexts, `singleTabLock` silently degrades to no
+  coordination: multiple tabs can open the same OPFS file at once, and
+  contention then surfaces later as catchable "database is locked"
+  (`SQLITE_BUSY`) errors from sqlite-wasm itself.
+- **The in-memory fallback loses data on reload.** When OPFS is unavailable
+  and `fallbackToMemory` is on, everything works but nothing persists. The
+  adapter emits a `logger.warn` when this happens — pass your own `logger` if
+  the app needs to detect it and warn the user.
+
+## Versioning
+
+This package is pre-1.0: **minor releases may contain breaking changes**
+(0.2.0 added a required `executeBatch` to `DbClient`, which breaks custom
+adapter/client implementations at compile time). Pin exact versions, and read
+the [CHANGELOG](CHANGELOG.md) when upgrading.
+
+## Contributing
+
+PRs that change shippable code must include a changeset (`pnpm changeset`) —
+CI enforces this via `changeset status`. Docs-only or chore PRs can opt out
+with `pnpm changeset --empty`.
+
+## Releasing
+
+Releases are published by CI from tags, never from a local machine:
+
+1. `pnpm changeset version` — bumps `package.json` and updates `CHANGELOG.md`
+   from pending changesets; commit the result.
+2. Tag that commit `vX.Y.Z` (matching the new version) and push the tag.
+3. `.github/workflows/release.yml` does a clean checkout of the tag, re-runs
+   the full verification chain (build, typecheck, lint, test, publint), and
+   publishes with `--provenance`. Requires an `NPM_TOKEN` repository secret
+   with publish rights on the package.

package/README.zh-CN.md

@@ -74,7 +74,7 @@ function TodoList() {
   if (dbError) return <ErrorMessage error={dbError} />;
   if (!isDbReady || !dbClient) return null;
 
-  // dbClient.select<T>(sql, params?) / dbClient.execute(sql, params?) / dbClient.close()
+  // dbClient.select<T>(sql, params?) / dbClient.execute(sql, params?) / dbClient.executeBatch(statements) / dbClient.close()
   // ...
 }
 ```
@@ -85,11 +85,12 @@ function TodoList() {
 
 | 导出 | 说明 |
 |---|---|
-| `createDbClient(options)` | 初始化适配器、执行待应用迁移，返回 `Promise<DbClient>`。 |
+| `createDbClient(options)` | 初始化适配器、应用 `pragmas`、执行待应用迁移，返回 `Promise<DbClient>`。若 PRAGMA/迁移阶段失败，会先关闭已打开的连接再向上抛错。 |
 | `runMigrations(db, migrations, options?)` | `createDbClient` 内部使用的迁移运行器；不经过 `createDbClient` 时可直接调用。 |
-| `defaultExecutor` | 未设置 `migrationOptions.executor` 时使用的默认迁移执行器：逐条执行语句，无事务包裹。 |
-| `DbClient`（类型） | `{ select<T>(sql, params?), execute(sql, params?), close() }` —— 详见下文。 |
+| `defaultExecutor` | 未设置 `migrationOptions.executor` 时使用的默认迁移执行器：通过 `executeBatch()` 执行一个迁移的全部语句，无事务包裹。 |
+| `DbClient`（类型） | `{ select<T>(sql, params?), execute(sql, params?), executeBatch(statements), close() }` —— 详见下文。 |
 | `DbAdapter` / `DbAdapterConfig`（类型） | 各 `createXAdapter()` 工厂返回的接口 / 传给 `initialize()` 的 `{ name }` 配置。 |
+| `BatchStatement` / `Logger`（类型） | `executeBatch()` 的语句类型 `string \| { sql, params? }` / 诊断输出通道（`{ warn, error }`，默认 `console`）。 |
 | `Migration` / `MigrationExecutor` / `MigrationOptions`（类型） | 见[编写迁移](#编写迁移)。 |
 | `DbError` 及子类 | 见[错误](#错误)。 |
 
@@ -103,10 +104,31 @@ import { createDbClient, runMigrations, defaultExecutor } from "cross-sqlite-cli
 interface DbClient {
   select<T>(sql: string, params?: unknown[]): Promise<T[]>;
   execute(sql: string, params?: unknown[]): Promise<{ lastInsertId?: number; rowsAffected?: number }>;
+  executeBatch(statements: BatchStatement[]): Promise<void>;
   close(): Promise<void>;
 }
 ```
 
+`executeBatch()` 按顺序执行一批语句，**无跨语句事务保证**——全部语句不带绑定参数时，web 和 memory 适配器会把它们拼成一条 SQL 一次性发给底层引擎（web 适配器每条语句省一次 Worker 往返）；只要批内有**任何**一条带参语句，整批退化为逐条 `execute()`。库刻意不提供业务侧事务 API：连接池型适配器（Tauri）无法保证 `BEGIN`/`COMMIT` 落在同一条物理连接上，因此业务多语句写入应自行保证幂等。
+
+`createDbClient()` 还接受两个可选字段：
+
+```ts
+await createDbClient({
+  name: "my-app",
+  adapter,
+  migrations: APP_MIGRATIONS,
+  // initialize 之后、迁移之前应用。key 必须是合法标识符；
+  // 字符串值必须是枚举式 token（WAL、NORMAL……）；boolean 会转成 0/1；number 原样拼入。
+  // 注意：在连接池型适配器（Tauri）上，foreign_keys/busy_timeout 这类连接级 PRAGMA 只对
+  // 池中一条连接生效，后续查询会静默失效（createDbClient 会打告警日志）；journal_mode/
+  // user_version 这类库级 PRAGMA 不受影响。
+  pragmas: { foreign_keys: true, journal_mode: "WAL" },
+  // 库告警/错误的诊断输出通道（默认 console）。
+  logger: myLogger, // { warn(message, ...args), error(message, ...args) }
+});
+```
+
 ### 适配器
 
 每次调用 `createXAdapter()` 都会返回一个**全新的、相互独立的** `DbAdapter` 实例（没有模块级单例状态），因此同一进程里可以放心创建多个——例如测试里。
@@ -124,8 +146,9 @@ interface DbClient {
 | 选项 | 默认值 | 说明 |
 |---|---|---|
 | `timeoutMs` | `15000` | 等待 SQLite Worker 就绪的超时时间；若 Worker 脚本加载失败，不设超时会让 `initialize()` 永远 pending。 |
-| `fallbackToMemory` | `true` | OPFS 不可用时是否静默回退到 `:memory:`，而不是抛错。详见 [COOP/COEP](#opfs-持久化需要-coopcoep)。 |
+| `fallbackToMemory` | `true` | OPFS 不可用时是否静默回退到 `:memory:`（包括探测通过但打开 OPFS 文件失败的情况），而不是抛错。详见 [COOP/COEP](#opfs-持久化需要-coopcoep)。 |
 | `singleTabLock` | `true` | 是否跨浏览器标签页协调对同一 OPFS 文件的访问。详见[多标签页协调](#多标签页协调)。 |
+| `logger` | `console` | 诊断信息（OPFS 降级告警、Worker 错误）的输出位置。传入自己的 `{ warn, error }` 可接入应用的日志/监控。 |
 
 **`createTauriAdapter()`** 和 **`createMemoryAdapter()`** 不接受选项。`createMemoryAdapter()` 用于测试——见[测试](#测试)。
 
@@ -138,7 +161,7 @@ interface DbClient {
 
 关于 `DatabaseProvider` 有两点值得注意：
 
-- **没有内置 `retry`。** `client` prop 只会进入最终状态一次——重试意味着传给它一个**新的 Promise**，prop 引用变化会重新触发初始化：
+- **没有内置 `retry`。** `client` prop 只会进入最终状态一次——重试意味着传给它一个**新的 Promise**，prop 引用变化会重新触发初始化。prop 变化的瞬间，context 会先回到完全未就绪状态（`dbClient: null`、`isDbReady: false`），直到新 Promise resolve——窗口期内消费方不会看到旧连接：
 
   ```tsx
   function App() {
@@ -164,12 +187,24 @@ interface Migration {
 }
 ```
 
-- **版本号必须从 1 开始。** 没有应用任何迁移时，`runMigrations` 把当前版本视为 `0`；一个 `version: 0` 的迁移永远满足不了 `version > currentVersion`，会被永久静默跳过。`runMigrations` 会在传入 `version <= 0` 时立即抛错。
+- **版本号必须是唯一的正整数。** 没有应用任何迁移时，`runMigrations` 把当前版本视为 `0`；一个 `version: 0` 的迁移永远满足不了 `version > currentVersion`，会被永久静默跳过。传入不是正整数的版本号（包括 `1.5` 这类）、或两个迁移共用同一个版本号时，`runMigrations` 会立即抛错。（不要求从 1 开始、也不要求连续——跳号是可以的。）
 - **每条语句都必须可安全重跑。** 跨平台事务没有统一保证（原因见下文），因此如果某次迁移执行到一半失败，下次启动会**从头重跑整个 version**。新 schema 请使用 `CREATE TABLE/INDEX IF NOT EXISTS`。未来若要写不可重跑的操作（例如重命名列），先查询当前 schema 状态——例如 `SELECT 1 FROM pragma_table_info('t') WHERE name = '...'`——已完成就跳过，而不是依赖回滚。
+- **失败以 `DbMigrationError` 暴露。** 运行器会把执行器抛出的错误包装成携带失败 `.version` 的 `DbMigrationError`。`createDbClient()` 在向上抛错前还会先关闭已打开的连接，因此一次失败的启动不会泄漏 Worker、OPFS 文件句柄或标签页锁——重试（比如换一个新的 client Promise）可以从干净状态开始。
+- **低于当前版本的"迟到迁移"不会被静默丢弃。** 如果数据库已应用 `[1, 2, 5]` 而新构建补发了缺失的 `3`/`4`，这些版本低于 `MAX(version)`，默认情况下会被永远跳过；运行器会用 `logger.warn` 点名它们。它们**不会**被自动补跑——乱序应用可能破坏 schema 演进假设——这类 hotfix 请显式处理。
+
+`runMigrations(db, migrations, options?)`（以及 `createDbClient` 的 `migrationOptions`）接受：
+
+```ts
+interface MigrationOptions {
+  tableName?: string;    // 版本表名，默认 "schema_version"；仅限合法标识符
+  executor?: MigrationExecutor; // 见下一节
+  logger?: Logger;       // 覆盖 createDbClient 的 logger，仅作用于迁移阶段的诊断输出
+}
+```
 
 ## 自定义迁移执行器与 `singleConnection`
 
-默认执行器（`defaultExecutor`）逐条独立执行迁移语句，无事务包裹。`adapters/web` 还导出了 `transactionalExecutor`，它把一次迁移包在 `BEGIN`/`COMMIT`/`ROLLBACK` 里——但这只在 `singleConnection: true` 的适配器上安全（真正的一条持久连接）。`@tauri-apps/plugin-sql` 的底层是连接池（`sqlx::Pool<Sqlite>`），多次 `execute()` 调用不保证落在同一条物理连接上，`BEGIN` 和 `COMMIT` 跨调用拆散后甚至可能不报错。`createDbClient()` 会在你把一个标记为 `requiresSingleConnection: true` 的执行器传给 `singleConnection: false` 的适配器时，提前抛错。
+默认执行器（`defaultExecutor`）通过 `executeBatch()` 执行每个迁移的全部语句，无事务包裹。`adapters/web` 还导出了 `transactionalExecutor`，它把一次迁移包在 `BEGIN`/`COMMIT`/`ROLLBACK` 里——但这只在 `singleConnection: true` 的适配器上安全（真正的一条持久连接）。`@tauri-apps/plugin-sql` 的底层是连接池（`sqlx::Pool<Sqlite>`），多次 `execute()` 调用不保证落在同一条物理连接上，`BEGIN` 和 `COMMIT` 跨调用拆散后甚至可能不报错。`createDbClient()` 会在你把一个标记为 `requiresSingleConnection: true` 的执行器传给 `singleConnection: false` 的适配器时，提前抛错。
 
 这个检查基于显式标记，而不是把执行器和 `defaultExecutor` 做引用相等比较：`transactionalExecutor` 通过 `Object.assign(fn, { requiresSingleConnection: true })` 携带标记。如果你也写了一个管理事务的自定义执行器，请用同样方式标记。完全不碰事务的执行器（例如只加日志）不需要这个标记，即使传给连接池适配器也不会被拒绝。
 
@@ -201,6 +236,8 @@ sqlite-wasm 的 `opfs` VFS 自带锁协议，因此两个标签页同时写同
 
 默认开启 `singleTabLock: true` 时，`createWebAdapter()` 会在打开数据库文件前用 [Web Locks API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Locks_API) 申请一个命名锁。如果另一个标签页已经持有该锁，`initialize()` 会立即以 `DbTabLockError` reject，而不是让应用在之后的某次随机查询里才发现失败——捕获它之后可以展示「该应用已在另一个标签页打开」之类的提示。传 `singleTabLock: false` 可跳过此行为，只依赖 sqlite-wasm 自身的重试/`SQLITE_BUSY` 处理。它只对 OPFS 持久化路径生效——`:memory:` 每个标签页互相独立，无需协调。
 
+锁原语本身 `tryAcquireTabLock(lockName)` 也从 `cross-sqlite-client/adapters/web` 导出，应用如果需要为数据库之外的资源做同样的跨标签页尽力协调，可以直接使用。
+
 ## 错误
 
 所有适配器都抛出以下错误类（全部继承 `DbError extends Error`，均可选传入 `cause`）：
@@ -209,7 +246,8 @@ sqlite-wasm 的 `opfs` VFS 自带锁协议，因此两个标签页同时写同
 |---|---|
 | `DbError` | 通用/用法错误，例如 `initialize()` 还没 resolve 就调用 `select()`/`execute()`，或 `close()` 之后调用。 |
 | `DbInitializationError` | `adapter.initialize()` 失败（Worker/OPFS/Tauri 加载失败等）。 |
-| `DbExecutionError`（带 `.sql` 和 `.params`） | `select()`/`execute()` 调用失败。 |
+| `DbExecutionError`（带 `.sql` 和 `.params`） | `select()`/`execute()`/`executeBatch()` 调用失败。 |
+| `DbMigrationError`（带 `.version`） | 某条迁移失败；底层错误包装在 `cause` 里。由 `runMigrations`/`createDbClient` 抛出。 |
 | `DbCloseError` | `client.close()` 失败。 |
 | `DbTabLockError` | （仅 Web 适配器，`singleTabLock: true`）另一个标签页已持有数据库锁。 |
 
@@ -240,7 +278,33 @@ await runMigrations(client, APP_MIGRATIONS);
 
 每次 `createMemoryAdapter()` 调用都是一个全新的独立实例，因此不同测试（或同一进程里的并行测试）不会共享状态。
 
+库自身的测试套件（`pnpm test`）覆盖迁移运行器、客户端生命周期和 React 绑定；CI（`.github/workflows/ci.yml`）在 Node 20/22 上运行 lint、typecheck、测试、构建和 `publint`。
+
 ## 已知限制
 
 - **`lastInsertId` 精度。** `DbClient.execute()` 返回的 `lastInsertId` 类型是 `number`。Web 适配器会把 SQLite 的 `sqlite3_last_insert_rowid()`（64 位 `bigint`，最大 2^63-1）通过 `Number()` 转换，因此超过 `Number.MAX_SAFE_INTEGER`（2^53-1）时会丢失精度。对典型本地优先应用不是问题（需要单表超过 9 千万亿行才会触发），但如果你需要精确的大整数 rowid，请用专门的 `SELECT last_insert_rowid()` 查询读取。
 - **没有 OPFS 降级层。** OPFS/跨源隔离不可用时，`createWebAdapter()` 只有两种状态：完整 OPFS 持久化，或完全没有持久化的 `:memory:`。sqlite-wasm 提供了基于 `localStorage`/`sessionStorage` 的 `kvvfs` 后端，可作为中间层，但当前版本尚未接入——如果你需要在无法达到跨源隔离的部署环境里获得持久化，可以考虑接入它（见 [COOP/COEP](#opfs-持久化需要-coopcoep)）。
+
+## 运行环境说明
+
+以下是刻意的设计取舍，而非缺陷：
+
+- **bfcache 冻结的标签页会一直持有数据库锁。** `singleTabLock` 基于 Web Locks API；被浏览器前进/后退缓存（bfcache）冻结（而非关闭）的标签页会持续持有锁，其他标签页会一直收到 `DbTabLockError`，直到被冻结的标签页被丢弃。真正关闭或崩溃的标签页，其锁会由浏览器自动释放。
+- **没有 Web Locks API → 没有跨标签页协调。** 在老旧浏览器或非安全（非 HTTPS）上下文中，`singleTabLock` 会静默退化为不做协调：多个标签页可以同时打开同一个 OPFS 文件，竞争会在此后以 sqlite-wasm 抛出的可捕获的 "database is locked"（`SQLITE_BUSY`）错误形式暴露。
+- **内存降级模式下刷新页面会丢数据。** OPFS 不可用且 `fallbackToMemory` 开启时，一切功能正常但不持久化。发生降级时适配器会发出 `logger.warn`——如果应用需要感知并向用户提示，请传入自己的 `logger`。
+
+## 版本策略
+
+本包处于 0.x 阶段：**minor 版本可能包含破坏性变更**（0.2.0 就给 `DbClient` 新增了必选方法 `executeBatch`，自定义 adapter/client 的实现会在编译期报错）。请锁定精确版本号，升级前阅读 [CHANGELOG](CHANGELOG.md)。
+
+## 贡献
+
+改动可发布代码的 PR 必须附带 changeset（`pnpm changeset`）——CI 会通过 `changeset status` 强制检查。纯文档或杂务类 PR 可以用 `pnpm changeset --empty` 豁免。
+
+## 发布
+
+发布由 CI 从 tag 触发，绝不从本地机器发出：
+
+1. `pnpm changeset version`——根据待发布的 changeset 更新 `package.json` 版本号和 `CHANGELOG.md`，提交结果。
+2. 给该提交打上与新版本一致的 `vX.Y.Z` tag 并推送。
+3. `.github/workflows/release.yml` 会干净地 checkout 该 tag，重跑完整验证链（build、typecheck、lint、test、publint），并以 `--provenance` 发布。需要在仓库 secrets 中配置有发布权限的 `NPM_TOKEN`。

package/dist/adapters/memory.d.ts

@@ -1,4 +1,4 @@
-import { n as DbAdapter } from "../types-XKvAFU82.js";
+import { r as DbAdapter } from "../types-Dm9OqT6i.js";
 //#region src/adapters/memory.d.ts
 /**
  * 内存适配器（测试用）。基于 @sqlite.org/sqlite-wasm 官方支持的 Node 单线程用法

package/dist/adapters/memory.js

@@ -1,4 +1,4 @@
-import { i as DbInitializationError, n as DbError, r as DbExecutionError, t as DbCloseError } from "../errors-D9KnLHTp.js";
+import { i as DbInitializationError, n as DbError, r as DbExecutionError, t as DbCloseError } from "../errors-DwJZz1Jx.js";
 import sqlite3InitModule from "@sqlite.org/sqlite-wasm";
 //#region src/adapters/memory.ts
 /**
@@ -12,32 +12,53 @@ import sqlite3InitModule from "@sqlite.org/sqlite-wasm";
 function createMemoryAdapter() {
 	let sqlite3 = null;
 	let db = null;
+	let initPromise = null;
+	function requireDb() {
+		if (!db) throw new DbError("[Memory DB] Database not initialized. Call initialize() first.");
+		return db;
+	}
 	const client = {
 		async select(sql, params = []) {
-			if (!db) throw new DbError("[Memory DB] Database not initialized. Call initialize() first.");
+			const d = requireDb();
 			try {
-				return db.selectObjects(sql, params);
+				return d.selectObjects(sql, params);
 			} catch (error) {
 				throw new DbExecutionError(sql, params, error);
 			}
 		},
 		async execute(sql, params = []) {
-			if (!db || !sqlite3) throw new DbError("[Memory DB] Database not initialized. Call initialize() first.");
+			const d = requireDb();
 			try {
-				db.exec({
+				d.exec({
 					sql,
 					bind: params
 				});
-				const rowsAffected = db.changes(false, false);
+				const rowsAffected = d.changes(false, false);
 				return {
-					lastInsertId: db.pointer !== void 0 ? Number(sqlite3.capi.sqlite3_last_insert_rowid(db.pointer)) : void 0,
+					lastInsertId: d.pointer !== void 0 ? Number(sqlite3.capi.sqlite3_last_insert_rowid(d.pointer)) : void 0,
 					rowsAffected
 				};
 			} catch (error) {
 				throw new DbExecutionError(sql, params, error);
 			}
 		},
+		async executeBatch(statements) {
+			const d = requireDb();
+			if (statements.length === 0) return;
+			if (statements.every((s) => typeof s === "string" || s.params === void 0 || s.params.length === 0)) {
+				d.exec({ sql: statements.map((s) => typeof s === "string" ? s : s.sql).join("\n;\n") });
+				return;
+			}
+			for (const statement of statements) {
+				const sql = typeof statement === "string" ? statement : statement.sql;
+				const params = typeof statement === "string" ? [] : statement.params ?? [];
+				await client.execute(sql, params);
+			}
+		},
 		async close() {
+			const pending = initPromise;
+			initPromise = null;
+			if (pending) await pending.catch(() => {});
 			try {
 				db?.close();
 			} catch (error) {
@@ -47,17 +68,27 @@ function createMemoryAdapter() {
 			}
 		}
 	};
+	async function doInitialize() {
+		try {
+			sqlite3 = await sqlite3InitModule();
+			db = new sqlite3.oo1.DB(":memory:", "c");
+			return client;
+		} catch (error) {
+			sqlite3 = null;
+			db = null;
+			throw new DbInitializationError(error);
+		}
+	}
 	return {
 		singleConnection: true,
-		async initialize() {
-			if (db) return client;
-			try {
-				sqlite3 = await sqlite3InitModule();
-				db = new sqlite3.oo1.DB(":memory:", "c");
-				return client;
-			} catch (error) {
-				throw new DbInitializationError(error);
+		initialize() {
+			if (!initPromise) {
+				initPromise = doInitialize();
+				initPromise.catch(() => {
+					initPromise = null;
+				});
 			}
+			return initPromise;
 		}
 	};
 }

package/dist/adapters/tauri.d.ts

@@ -1,11 +1,16 @@
-import { n as DbAdapter } from "../types-XKvAFU82.js";
+import { r as DbAdapter } from "../types-Dm9OqT6i.js";
 //#region src/adapters/tauri.d.ts
 /**
- * Tauri (@tauri-apps/plugin-sql) 适配器。每次调用 createTauriAdapter() 返回一个状态独立的
- * 新实例——db 保存在这个函数的闭包里，不是模块级单例。
+ * Tauri (@tauri-apps/plugin-sql) 适配器。
+ *
+ * 注意：plugin-sql 的 Sqlite.load 在插件侧按数据库路径全局缓存连接——两个同名（同 name）
+ * 的适配器实例共享底层连接，其中一个 close 另一个也会断。要多个真正独立的连接，用不同的
+ * name（即不同的数据库文件）。
  *
  * singleConnection 为 false：@tauri-apps/plugin-sql 底层是 sqlx::Pool<Sqlite> 连接池，
  * 每次 execute()/select() 调用独立获取/归还一个物理连接，不保证跨调用落在同一条连接上。
+ * 这也是库不提供业务侧事务 API 的原因：BEGIN 和 COMMIT 可能被拆到两条物理连接上而不报
+ * 任何错。
  */
 export declare function createTauriAdapter(): DbAdapter;
 //#endregion

package/dist/adapters/tauri.js

@@ -1,28 +1,38 @@
-import { i as DbInitializationError, n as DbError, r as DbExecutionError, t as DbCloseError } from "../errors-D9KnLHTp.js";
+import { i as DbInitializationError, n as DbError, r as DbExecutionError, t as DbCloseError } from "../errors-DwJZz1Jx.js";
 import Sqlite from "@tauri-apps/plugin-sql";
 //#region src/adapters/tauri.ts
 /**
-* Tauri (@tauri-apps/plugin-sql) 适配器。每次调用 createTauriAdapter() 返回一个状态独立的
-* 新实例——db 保存在这个函数的闭包里，不是模块级单例。
+* Tauri (@tauri-apps/plugin-sql) 适配器。
+*
+* 注意：plugin-sql 的 Sqlite.load 在插件侧按数据库路径全局缓存连接——两个同名（同 name）
+* 的适配器实例共享底层连接，其中一个 close 另一个也会断。要多个真正独立的连接，用不同的
+* name（即不同的数据库文件）。
 *
 * singleConnection 为 false：@tauri-apps/plugin-sql 底层是 sqlx::Pool<Sqlite> 连接池，
 * 每次 execute()/select() 调用独立获取/归还一个物理连接，不保证跨调用落在同一条连接上。
+* 这也是库不提供业务侧事务 API 的原因：BEGIN 和 COMMIT 可能被拆到两条物理连接上而不报
+* 任何错。
 */
 function createTauriAdapter() {
 	let db = null;
+	let initPromise = null;
+	function requireDb() {
+		if (!db) throw new DbError("[Tauri DB] Database not initialized. Call initialize() first.");
+		return db;
+	}
 	const client = {
 		async select(sql, params = []) {
-			if (!db) throw new DbError("[Tauri DB] Database not initialized. Call initialize() first.");
+			const d = requireDb();
 			try {
-				return await db.select(sql, params);
+				return await d.select(sql, params);
 			} catch (error) {
 				throw new DbExecutionError(sql, params, error);
 			}
 		},
 		async execute(sql, params = []) {
-			if (!db) throw new DbError("[Tauri DB] Database not initialized. Call initialize() first.");
+			const d = requireDb();
 			try {
-				const result = await db.execute(sql, params);
+				const result = await d.execute(sql, params);
 				return {
 					lastInsertId: result.lastInsertId,
 					rowsAffected: result.rowsAffected
@@ -31,26 +41,44 @@ function createTauriAdapter() {
 				throw new DbExecutionError(sql, params, error);
 			}
 		},
+		async executeBatch(statements) {
+			for (const statement of statements) {
+				const sql = typeof statement === "string" ? statement : statement.sql;
+				const params = typeof statement === "string" ? [] : statement.params ?? [];
+				await client.execute(sql, params);
+			}
+		},
 		async close() {
+			const pending = initPromise;
+			initPromise = null;
+			if (pending) await pending.catch(() => {});
 			if (db) try {
-				if (!await db.close()) throw new DbCloseError();
+				const current = db;
+				db = null;
+				if (!await current.close()) throw new DbCloseError();
 			} catch (error) {
 				throw error instanceof DbCloseError ? error : new DbCloseError(error);
-			} finally {
-				db = null;
 			}
 		}
 	};
+	async function doInitialize(config) {
+		try {
+			db = await Sqlite.load(`sqlite:${config.name}.db`);
+			return client;
+		} catch (error) {
+			throw new DbInitializationError(error);
+		}
+	}
 	return {
 		singleConnection: false,
-		async initialize(config) {
-			if (db) return client;
-			try {
-				db = await Sqlite.load(`sqlite:${config.name}.db`);
-				return client;
-			} catch (error) {
-				throw new DbInitializationError(error);
+		initialize(config) {
+			if (!initPromise) {
+				initPromise = doInitialize(config);
+				initPromise.catch(() => {
+					initPromise = null;
+				});
 			}
+			return initPromise;
 		}
 	};
 }

package/dist/adapters/web.d.ts

@@ -1,9 +1,9 @@
-import { n as DbAdapter, o as MigrationExecutor } from "../types-XKvAFU82.js";
+import { c as MigrationExecutor, o as Logger, r as DbAdapter } from "../types-Dm9OqT6i.js";
 //#region src/adapters/web.d.ts
 export interface WebAdapterOptions {
   /** 等待 Worker 就绪的超时时间（毫秒），超时后 initialize() 会 reject 而不是永远 pending */
   timeoutMs?: number;
-  /** OPFS 不可用（不支持/未跨域隔离/初始化失败）时是否静默退化为内存模式，默认 true */
+  /** OPFS 不可用（不支持/未跨域隔离/探测或打开失败）时是否静默退化为内存模式，默认 true */
   fallbackToMemory?: boolean;
   /**
    * 用 Web Locks API（navigator.locks）在同一 origin 的多个标签页/窗口之间协调对同一个
@@ -21,10 +21,12 @@ export interface WebAdapterOptions {
    * 不受这个选项影响。
    */
   singleTabLock?: boolean;
+  /** 诊断输出（OPFS 降级告警、worker 错误等），默认 console */
+  logger?: Logger;
 }
 /**
  * 用 Web Locks API 尝试（不等待）拿到一个跨标签页命名锁。拿不到（另一个标签页已持有）时
- * resolve 到 null；拿到时返回一个 release() 函数，调用方后续必须调用它来释放锁。
+ * 返回 null；拿到时返回一个 release() 函数，调用方后续必须调用它来释放锁。
  *
  * 实现上依赖一个常见技巧：navigator.locks.request() 的回调函数返回什么 Promise，锁就持有到
  * 那个 Promise settle 为止；这里让回调返回一个我们自己创建、直到 release() 被调用才会 resolve
@@ -37,7 +39,5 @@ export declare function tryAcquireTabLock(lockName: string): Promise<(() => void
  * 实例（例如测试）。
  */
 export declare function createWebAdapter(options?: WebAdapterOptions): DbAdapter;
-export declare const transactionalExecutor: MigrationExecutor & {
-  requiresSingleConnection: true;
-};
+export declare const transactionalExecutor: MigrationExecutor;
 //#endregion