@h-ai/reldb 1.0.0-beta.2 → 1.0.0-beta.20

package/README.ja.md

@@ -4,33 +4,9 @@
 
 [フレームワークのホーム](../../README.ja.md) · 関連モジュール：[@h-ai/core](../core/README.ja.md)
 
-## 概要
-
 共通の `reldb` オブジェクトで SQLite、PostgreSQL、MySQL を操作するリレーショナルデータベースモジュールです。
 
-接続はヘルスチェック成功後に公開します。初期化失敗時は候補リソースを解放し、解放にも失敗した場合は初期化エラーの `error.ext.cleanupPending` が `true` になります。`reldb.close()` は `Promise<HaiResult<void>>` を返し、初期化を待機して並行する終了処理をまとめます。解放開始後は `isInitialized` が `false` となり、設定と操作は利用できません。解放に失敗したリソースは保持され、次の `close()` または `init()` で再試行します。解放が成功するまで代替接続は作成しません。終了結果を必ず確認してください。
-
-```ts
-const closed = await reldb.close()
-if (!closed.success) {
-  // 障害への対処後に一度再試行し、再失敗はアプリへ報告します。
-  const retried = await reldb.close()
-  if (!retried.success)
-    throw new Error(retried.error.message)
-}
-```
-
-終了処理は既存トランザクションのコミット/ロールバックと解放を待ちます。アプリはトランザクションを終了させてください。SQLite の WAL 設定と worker のハンドシェイクも初期化リソースとして管理します。PostgreSQL の切断済みアイドル接続はプールが除去し、次のクエリで置き換えます。プロセスは終了せず、ログには安全なエラー識別子のみを記録します。
-
-## 主な機能
-
-- 共通 API で SQLite・PostgreSQL・MySQL に接続。
-- パラメーター付き SQL、テーブル・索引管理、ページ取得。
-- トランザクション、CRUD、Repository による業務の読み書き。
-
-## 使い始める
-
-### クイックスタート
+## クイックスタート
 
 ```ts
 import { HaiReldbError, reldb } from '@h-ai/reldb'
@@ -75,135 +51,110 @@ await reldb.close()
 
 `reldb.config` は**機密情報をマスクした設定スナップショット**を返します。DB の `password`、URL 内の認証情報、TLS クライアント秘密鍵 `ssl.key` を非表示にします。状態確認用であり、元の接続情報の再利用には使わないでください。
 
-### 設定
+## 機能
 
-`@h-ai/reldb/schemas` は同じ設定 Schema と型を Zod のみで公開し、DB インスタンスやドライバーを読み込みません。CLI やブラウザーで設定検証に利用できます。MySQL TLS は `false` または厳密なオブジェクトのみで、`{}` は証明書チェーンと DNS ID を検証します。PostgreSQL の真偽値・文字列モード・オブジェクト契約は維持します。
+接続はヘルスチェック成功後に公開します。初期化失敗時は候補リソースを解放し、解放にも失敗した場合は初期化エラーの `error.ext.cleanupPending` が `true` になります。`reldb.close()` は `Promise<HaiResult<void>>` を返し、初期化を待機して並行する終了処理をまとめます。解放開始後は `isInitialized` が `false` となり、設定と操作は利用できません。解放に失敗したリソースは保持され、次の `close()` または `init()` で再試行します。解放が成功するまで代替接続は作成しません。終了結果を必ず確認してください。
 
 ```ts
-import { ReldbConfigSchema } from '@h-ai/reldb/schemas'
-
-const checked = ReldbConfigSchema.safeParse({ type: 'mysql', database: 'shop', ssl: {} })
-if (!checked.success)
-  throw new Error('Invalid database configuration')
-// checked.data.ssl: { rejectUnauthorized: true, verifyIdentity: true }
+const closed = await reldb.close()
+if (!closed.success) {
+  // 障害への対処後に一度再試行し、再失敗はアプリへ報告します。
+  const retried = await reldb.close()
+  if (!retried.success)
+    throw new Error(retried.error.message)
+}
 ```
 
-接続文字列（`url`）または個別フィールド（`host/port/database/user/password`）を指定できます。
+終了処理は既存トランザクションのコミット/ロールバックと解放を待ちます。アプリはトランザクションを終了させてください。SQLite の WAL 設定と worker のハンドシェイクも初期化リソースとして管理します。PostgreSQL の切断済みアイドル接続はプールが除去し、次のクエリで置き換えます。プロセスは終了せず、ログには安全なエラー識別子のみを記録します。
 
-```ts
-// SQLite
-await reldb.init({ type: 'sqlite', database: './data.db' })
+### 操作と入出力
 
-// PostgreSQL
-await reldb.init({ type: 'postgresql', url: 'postgres://user:pass@localhost:5432/mydb', database: 'mydb' })
+本節の完全な初期化手順を先に実行します。例の業務値はホストが検証・認可し、非同期領域結果は success を確認してから data を読みます。void はデータなし完了、null は不存在、同期ファクトリー/ツールは表の型を直接返します。
 
-// MySQL
-await reldb.init({
-  type: 'mysql',
-  host: 'localhost',
-  port: 3306,
-  database: 'mydb',
-  user: 'admin',
-  password: 'secret',
-  mysql: { charset: 'utf8mb4' },
-  pool: { max: 10, acquireTimeout: 5000, queueLimit: 100 },
-})
-```
+表・列・索引・SQL は信頼するコード、params は業務値の束縛、steps は移行手順、options は事前確認/ページ指定。
 
-#### 接続プールと MySQL URL
+#### reldb.ddl
 
-MySQL の `pool` は `max`、`acquireTimeout`、`queueLimit` のみを受け付け、省略時もそれぞれ 10、10000 ミリ秒、1000 を使用します。`min`、`idleTimeout` などの未対応フィールドと未実装の `mysql.timezone` は設定検証で拒否します。アイドル接続は mysql2/サーバーによる切断または `close()` で解放し、最小保持数や設定可能なアイドル回収期限は保証しません。[mysql2 3.24.5 の設定](https://github.com/sidorares/node-mysql2/blob/v3.24.5/typings/mysql/lib/Pool.d.ts)は PostgreSQL と異なります。
+テーブル・列・索引を管理。信頼する識別子、定義または DDL を渡し、成功は void、構造エラーは失敗。
 
-| フィールド       | PostgreSQL（`pool` 指定時の既定値） | MySQL                                  |
-| ---------------- | ----------------------------------- | -------------------------------------- |
-| `max`            | 10                                  | 10、借用中と接続確立中の合計上限       |
-| `min`            | 1、既存接続の保持下限。事前作成なし | 未対応、拒否                           |
-| `idleTimeout`    | 30000 ミリ秒、0 は無効化            | 未対応、拒否                           |
-| `acquireTimeout` | 10000 ミリ秒、0 は無効化            | 10000 ミリ秒、1–2147483647 の整数      |
-| `queueLimit`     | 未対応                              | 1000、待機リクエスト数の上限、正の整数 |
+| 入口                    | 入力引数                         | 成功結果 | 呼出し例                                                                             |
+| ----------------------- | -------------------------------- | -------- | ------------------------------------------------------------------------------------ |
+| `reldb.ddl.createTable` | tableName, columns, ifNotExists  | `void`   | `await reldb.ddl.createTable('orders', { id: { type: 'TEXT', primaryKey: true } })`  |
+| `reldb.ddl.dropTable`   | tableName, ifExists              | `void`   | `await reldb.ddl.dropTable('orders_archive', true)`                                  |
+| `reldb.ddl.addColumn`   | tableName, columnName, columnDef | `void`   | `await reldb.ddl.addColumn('orders', 'note', { type: 'TEXT' })`                      |
+| `reldb.ddl.dropColumn`  | tableName, columnName            | `void`   | `await reldb.ddl.dropColumn('orders', 'note')`                                       |
+| `reldb.ddl.renameTable` | oldName, newName                 | `void`   | `await reldb.ddl.renameTable('orders_draft', 'orders')`                              |
+| `reldb.ddl.createIndex` | tableName, indexName, indexDef   | `void`   | `await reldb.ddl.createIndex('orders', 'orders_status', { columns: ['status'] })`    |
+| `reldb.ddl.dropIndex`   | indexName, ifExists              | `void`   | `await reldb.ddl.dropIndex('orders_status', true)`                                   |
+| `reldb.ddl.raw`         | sql                              | `void`   | `await reldb.ddl.raw('CREATE TABLE IF NOT EXISTS app_marker (id TEXT PRIMARY KEY)')` |
 
-PostgreSQL で `pool` を省略した場合は pg の既定値を使用します。保持と回収の仕様は [pg.Pool](https://node-postgres.com/apis/pool) を参照してください。MySQL の SQL、DDL、CRUD、バッチ、トランザクションは共通の有限 FIFO 待機キューを使います。待機と接続確立に一つの期限を適用し、超過時は `TIMEOUT`、満杯時は `POOL_EXHAUSTED` を返します。期限切れ項目は削除し、遅れて取得した接続は SQL を実行せず解放します。確立処理が完了するまで容量枠を保持します。受領時と処理開始前にも期限を確認しますが、開始済み SQL/トランザクションの実行時間は制限しません。
+#### reldb.sql
 
-MySQL の `close()` は新規・待機リクエストを直ちに拒否し、借用接続、トランザクション、接続確立の完了後にプールを閉じます。`connectTimeout` にも同じ値を使うため、その期限や既存処理を待つ場合があります。アプリはトランザクションを終了してください。環境変数は `HAI_DB_POOL_*` です。`MIN` / `IDLETIMEOUT` は PostgreSQL 専用で、MySQL の `QUEUELIMIT` は待機総数を制限します。
+params で値を束縛して業務データを操作。順に行配列、先頭行/null、書込結果、void、ページを返す。batch は文の配列。
 
-MySQL は `mysql://` の `url` だけでも接続でき、URL がなければ `database` が必須です。URL の host/port/database/user/password を優先し、競合する個別フィールドは接続に使用しません。`pool`、`mysql.charset`、`ssl`、`operationLog` は独立して適用します。query/fragment は拒否し、URL 内の隠れた設定で TLS やプールを変更できません。接続ログの URL は機密情報を伏せます。以下は `HAI_DB_URL` の設定を前提とします：
+| 入口                  | 入力引数    | 成功結果             | 呼出し例                                                                                                         |
+| --------------------- | ----------- | -------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `reldb.sql.query`     | sql, params | `T[]`                | `await reldb.sql.query('SELECT id FROM orders WHERE status = ?', ['pending'])`                                   |
+| `reldb.sql.get`       | sql, params | `T \| null`          | `await reldb.sql.get('SELECT id FROM orders WHERE id = ?', ['o1'])`                                              |
+| `reldb.sql.execute`   | sql, params | `ExecuteResult`      | `await reldb.sql.execute('UPDATE orders SET status = ? WHERE id = ?', ['paid', 'o1'])`                           |
+| `reldb.sql.batch`     | statements  | `void`               | `await reldb.sql.batch([{ sql: 'DELETE FROM orders WHERE id = ?', params: ['o1'] }])`                            |
+| `reldb.sql.queryPage` | options     | `PaginatedResult<T>` | `await reldb.sql.queryPage({ sql: 'SELECT id FROM orders ORDER BY id', pagination: { page: 1, pageSize: 20 } })` |
 
-```ts
-const initialized = await reldb.init({ type: 'mysql', url: process.env.HAI_DB_URL, pool: { max: 10, acquireTimeout: 5000, queueLimit: 100 } })
-if (!initialized.success)
-  throw new Error(initialized.error.message)
-```
+#### reldb.pagination
 
-MySQL の空 `url`（空の環境変数を含む）は host/port/database/user/password を使用します。空でない URL は厳密に検証します。
+ページ処理。normalize はページ指定と上限から正規化値、build は items・total・ページ指定からページオブジェクトを直接返す。
 
-#### MySQL TLS
+| 入口                         | 入力引数                 | 成功結果               | 呼出し例                                                   |
+| ---------------------------- | ------------------------ | ---------------------- | ---------------------------------------------------------- |
+| `reldb.pagination.normalize` | options, overrides       | `NormalizedPagination` | `reldb.pagination.normalize({ page: 1, pageSize: 20 })`    |
+| `reldb.pagination.build`     | items, total, pagination | `PaginatedResult<T>`   | `reldb.pagination.build([], 0, { page: 1, pageSize: 20 })` |
 
-`ssl` を省略するか `false` にすると TLS を使用しません。有効化には厳密なオブジェクトを指定し、空オブジェクトの既定値は `{ rejectUnauthorized: true, verifyIdentity: true }` です。`ca` は信頼する CA の PEM 内容で、省略時は Node の信頼ストアを使います。任意のクライアント `cert` / `key` も PEM 内容で、必ず対で指定します。未知の TLS フィールド、`true`、PostgreSQL の文字列モードは拒否し、任意の設定やコールバックは透過しません。
+#### reldb
 
-[mysql2 3.24.5 の主機名検証](https://github.com/sidorares/node-mysql2/blob/v3.24.5/lib/base/connection.js)は DNS servername に依存します。証明書と名前の両方を検証する場合、IP 接続先は `CONFIG_ERROR` とし、証明書の DNS SAN に一致するホスト名を使います。明示的な `verifyIdentity: false` は証明書チェーンのみを検証します。`rejectUnauthorized: false` はサーバー認証を放棄し、暗号化だけでは相手の身元を確認できません。どちらかの検証を無効にすると固定のリスク警告を記録し、安全な構成とは扱いません。
+永続化の準備。テーブル名から列名、モジュール名・手順・dryRun から移行計画を取得。適用前にバックアップし競合書込を停止。
 
-```ts
-// trustedCaPem は配置時の信頼設定から供給し、任意の接続先証明書をそのまま信頼しません。
-const initialized = await reldb.init({ type: 'mysql', host: 'db.example.com', database: 'app', ssl: { ca: trustedCaPem } })
-if (!initialized.success)
-  throw new Error(initialized.error.message)
-```
-
-TLS テストには OpenSSL（Windows は Git 同梱版も可）とローカルのコンテナー転送が必要です。各実行で CA/秘密鍵を生成・削除し、信頼済み DNS、誤った CA/主機名の拒否、`REQUIRE X509` 認証、実際の `Ssl_cipher` を検証します。検証無効の接続を認証済み TLS の証拠にはしません。
+| 入口                  | 入力引数               | 成功結果              | 呼出し例                                                                |
+| --------------------- | ---------------------- | --------------------- | ----------------------------------------------------------------------- |
+| `reldb.schemaColumns` | table, sql             | `string[]`            | `await reldb.schemaColumns('orders')`                                   |
+| `reldb.migrateSchema` | module, steps, options | `SchemaMigrationPlan` | `await reldb.migrateSchema('orders', migrationSteps, { dryRun: true })` |
 
-#### SQLite の実行方式（非同期 worker）
+#### reldb.tx
 
-better-sqlite3 は同期ドライバーなので、クエリは Node のメインイベントループをブロックします。WAL は DB ロックの並行性を改善しますが、同期呼び出しによるブロックは解消しません。専用 worker スレッドで SQLite を実行して処理を移せます（単一接続、任意設定、既定は `sync`）：
+原子的な書込。begin は query/get/execute/batch/queryPage/commit/rollback を持つハンドル、wrap はコールバックの結果を返す。失敗 HaiResult は明示的にロールバックする。
 
-```ts
-await reldb.init({
-  type: 'sqlite',
-  database: './data.db',
-  sqlite: {
-    executor: 'worker', // 'sync'（默认）| 'worker'
-    walMode: true, // 默认 true
-    workerConnectTimeoutMs: 10000, // worker 打开连接超时，默认 10000
-  },
-})
-```
+| 入口             | 入力引数 | 成功結果              | 呼出し例                                                                                                                                                            |
+| ---------------- | -------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `reldb.tx.begin` | 引数なし | `DmlWithTxOperations` | `await reldb.tx.begin()`                                                                                                                                            |
+| `reldb.tx.wrap`  | fn       | `T`                   | `await reldb.tx.wrap(async tx => { const found = await tx.get('SELECT 1 AS value'); if (!found.success) throw new Error(found.error.message); return found.data })` |
 
-worker モードではクエリ、書き込み、トランザクションを worker スレッドで順番に実行します。公開 API と戻り値は同期モードと同じです。
+#### reldb.crud
 
-#### 操作ログ
+業務エンティティのテーブル・フィールド対応から CRUD とページ処理のリポジトリを直接作成。DB 接続は露出しない。
 
-DB 設定の `operationLog` で SQL 操作ログを有効にできます。ログは reldb provider-base の DML 層で出力され、`reldb-main.ts` や各 raw provider で重複してラップしません。
+| 入口               | 入力引数 | 成功結果                     | 呼出し例                                  |
+| ------------------ | -------- | ---------------------------- | ----------------------------------------- |
+| `reldb.crud.table` | config   | `ReldbCrudRepository<TItem>` | `reldb.crud.table(orderRepositoryConfig)` |
 
-```yaml
-# config/_db.yml
-type: sqlite
-database: ./data/app.db
-operationLog:
-  read: false # query / get / queryPage
-  write: false # DDL, execute / batch, tx.begin / tx.commit / tx.rollback
-  maxLength: 1000 # 安全な件数サマリーの最大長。0は省略。SQL本文と値は記録しない
-  level: debug # info | debug | trace，默认 debug
-```
+#### reldb.json
 
-`core.config.load('db', ...)` で読み込む場合、`HAI_DB_TYPE`、
-`HAI_DB_DATABASE`、`HAI_DB_OPERATIONLOG_LEVEL` などの規約に沿う変数が YAML より優先されます。
+方言共通の JSON 式。信頼する列名、JSON パス、値/patch から SQL 式と束縛値を直接作成し、ここでは実行しない。
 
-```ts
-await reldb.init({
-  type: 'sqlite',
-  database: './data.db',
-  operationLog: {
-    read: true,
-    write: true,
-    maxLength: 500,
-    level: 'debug',
-  },
-})
-```
+| 入口                 | 入力引数            | 成功結果      | 呼出し例                                            |
+| -------------------- | ------------------- | ------------- | --------------------------------------------------- |
+| `reldb.json.extract` | column, path        | `JsonSqlExpr` | `reldb.json.extract('payload', '$.status')`         |
+| `reldb.json.set`     | column, path, value | `JsonSqlExpr` | `reldb.json.set('payload', '$.status', 'paid')`     |
+| `reldb.json.insert`  | column, path, value | `JsonSqlExpr` | `reldb.json.insert('payload', '$.note', 'checked')` |
+| `reldb.json.remove`  | column, path        | `JsonSqlExpr` | `reldb.json.remove('payload', '$.note')`            |
+| `reldb.json.merge`   | column, patch       | `JsonSqlExpr` | `reldb.json.merge('payload', { status: 'paid' })`   |
 
-操作ログには固定の操作名、SQL 長、パラメーター数、バッチ件数を記録します。失敗時は、エラーコード、traceId、許可リストに含まれるマスキング済みのドライバーメッセージとスタックも保持します。SQL 全文、バインド値、接続設定をそのまま記録することはありません。
+- 共通 API で SQLite・PostgreSQL・MySQL に接続。
+- パラメーター付き SQL、テーブル・索引管理、ページ取得。
+- トランザクション、CRUD、Repository による業務の読み書き。
 
 ### トランザクション
 
+トランザクションの終了処理を所有できるのは一つの操作だけです。commit または rollback の開始後、新規クエリ、重複 commit、並行 rollback は直ちに TRANSACTION_FAILED を返し、接続は一度だけ返却します。復旧目的で並行終了を試みず、最初の終了結果を待ってください。
+
 3 種類の使用方法：
 
 #### wrap（自動コミット/ロールバック）
@@ -272,8 +223,14 @@ if (!rolledBack.success)
 ```ts
 await reldb.tx.wrap(async (tx) => {
   const inserted = await tx.batch([
-    { sql: 'INSERT INTO users (name) VALUES (?)', params: ['Alice'] },
-    { sql: 'INSERT INTO users (name) VALUES (?)', params: ['Bob'] },
+    {
+      sql: 'INSERT INTO users (name) VALUES (?)',
+      params: ['Alice']
+    },
+    {
+      sql: 'INSERT INTO users (name) VALUES (?)',
+      params: ['Bob']
+    },
   ])
   if (!inserted.success)
     throw new Error(inserted.error.message, { cause: inserted.error })
@@ -376,10 +333,16 @@ await userCrud.deleteById(1)
 #### count / exists / existsById
 
 ```ts
-const total = await userCrud.count({ where: 'name LIKE ?', params: ['%张%'] })
+const total = await userCrud.count({
+  where: 'name LIKE ?',
+  params: ['%张%']
+})
 // total.data → 5
 
-const has = await userCrud.exists({ where: 'email = ?', params: ['test@example.com'] })
+const has = await userCrud.exists({
+  where: 'email = ?',
+  params: ['test@example.com']
+})
 // has.data → true
 
 const found = await userCrud.existsById(1)
@@ -426,11 +389,46 @@ interface UserRow {
 }
 
 const USER_FIELDS: ReldbCrudFieldDefinition[] = [
-  { fieldName: 'id', columnName: 'id', def: { type: 'INTEGER', primaryKey: true, autoIncrement: true }, select: true, create: false, update: false },
-  { fieldName: 'name', columnName: 'name', def: { type: 'TEXT', notNull: true }, select: true, create: true, update: true },
-  { fieldName: 'email', columnName: 'email', def: { type: 'TEXT', notNull: true }, select: true, create: true, update: true },
-  { fieldName: 'createdAt', columnName: 'created_at', def: { type: 'TIMESTAMP', notNull: true }, select: true, create: true, update: false },
-  { fieldName: 'updatedAt', columnName: 'updated_at', def: { type: 'TIMESTAMP', notNull: true }, select: true, create: true, update: false },
+  {
+    fieldName: 'id',
+    columnName: 'id',
+    def: { type: 'INTEGER', primaryKey: true, autoIncrement: true },
+    select: true,
+    create: false,
+    update: false
+  },
+  {
+    fieldName: 'name',
+    columnName: 'name',
+    def: { type: 'TEXT', notNull: true },
+    select: true,
+    create: true,
+    update: true
+  },
+  {
+    fieldName: 'email',
+    columnName: 'email',
+    def: { type: 'TEXT', notNull: true },
+    select: true,
+    create: true,
+    update: true
+  },
+  {
+    fieldName: 'createdAt',
+    columnName: 'created_at',
+    def: { type: 'TIMESTAMP', notNull: true },
+    select: true,
+    create: true,
+    update: false
+  },
+  {
+    fieldName: 'updatedAt',
+    columnName: 'updated_at',
+    def: { type: 'TIMESTAMP', notNull: true },
+    select: true,
+    create: true,
+    update: false
+  },
 ]
 
 class UserRepository extends BaseReldbCrudRepository<UserRow> {
@@ -440,7 +438,11 @@ class UserRepository extends BaseReldbCrudRepository<UserRow> {
 
   /** 自定义查询方法 */
   async findByEmail(email: string) {
-    return this.findAll({ where: 'email = ?', params: [email], limit: 1 })
+    return this.findAll({
+      where: 'email = ?',
+      params: [email],
+      limit: 1
+    })
   }
 
   /** 自定义方法中使用 this.sql(tx) 自动路由到事务 */
@@ -554,7 +556,7 @@ await reldb.sql.execute(
 )
 ```
 
-`json.merge(column, patch)` は三つのバックエンドで RFC 7396 のオブジェクトパッチを実装します。未変更の入れ子キーを保持し、null が指定したキーを削除し、配列を全体置換します。PostgreSQL はパラメーター化した再帰 CTE を単一 SQL 内で適用し、関数の事前インストールやアプリ側の読み取り後の書き戻しを必要としません。パッチのルートは JSON シリアライズ可能なオブジェクトに限ります。列式は開発者の静的 SQL で、パスと値はパラメーターです。[RFC 7396](https://www.rfc-editor.org/rfc/rfc7396)・[PostgreSQL JSON 演算](https://www.postgresql.org/docs/16/functions-json.html)。
+`json.merge(column, patch)` は三つのバックエンドで RFC 7396 のオブジェクトパッチを実装します。未変更の入れ子キーを保持し、null が指定したキーを削除し、配列を全体置換します。PostgreSQL はパラメーター化した再帰 CTE を単一 SQL 内で適用し、関数の事前インストールやアプリ側の読み取り後の書き戻しを必要としません。パッチのルートは JSON シリアライズ可能なオブジェクトに限ります。列式は開発者の静的 SQL で、パスと値はパラメーターです。[RFC 7396](https://www.rfc-editor.org/rfc/rfc7396)・[PostgreSQL JSON 演算](https://www.postgresql.org/docs/16/functions-json.html).
 
 #### 完全な使用例
 
@@ -568,7 +570,13 @@ await reldb.ddl.createTable('products', {
 // 插入初始 JSON
 await reldb.sql.execute(
   `INSERT INTO products (meta) VALUES (?)`,
-  [JSON.stringify({ status: 'draft', tags: ['new'], version: 1 })],
+  [
+    JSON.stringify({
+      status: 'draft',
+      tags: ['new'],
+      version: 1
+    })
+  ],
 )
 
 // 设置字段
@@ -591,7 +599,159 @@ const { sql: rmSql, params: rmParams } = reldb.json.remove('meta', '$.reviewer')
 await reldb.sql.execute(`UPDATE products SET meta = ${rmSql} WHERE id = ?`, [...rmParams, 1])
 ```
 
-### エラー処理
+### 本番の共有状態
+
+本番は PostgreSQL/MySQL が必須です。ファイルを含む SQLite は開発・明示的テスト用であり、ホスト間の共有状態を保証しません。 NODE_ENV または HAI_CORE_ENV が production の場合、初期化成功前に検証します。明示的な HAI_E2E=1/HAI_E2E_MOCK=1 テストのみ除外します。 [状態・並行制御・復旧範囲（中国語）](../../.agents/instructions/distributed-state.md).
+
+### モジュールのスキーマ移行
+
+`reldb.schemaColumns(table, sql?)` は実際の列を読み取ります。`reldb.migrateSchema(module, steps, { dryRun: true })` は台帳を作成しません。各モジュールが手順を所有し、`hai_schema_migrations` に版を記録します。SQLite/PostgreSQL はトランザクション、MySQL の暗黙 DDL コミットには再入可能な手順が必要です。失敗時は版を進めず、実構造を再確認して再試行します。新しい台帳へのダウングレードは拒否します。旧書込を停止し DB/セッションキャッシュをバックアップしてください。復旧は互換 DB とバイナリを一緒に戻します。[更新ガイド](../../docs/usage/README.ja.md)を参照。
+
+## 設定
+
+ライフサイクル。init にバックエンド/業務設定を渡し成功後に使用します。借用依存先の解放前に close の完了を待ち、正確な戻り値は例と公開署名に従います。
+
+`@h-ai/reldb/schemas` は同じ設定 Schema と型を Zod のみで公開し、DB インスタンスやドライバーを読み込みません。CLI やブラウザーで設定検証に利用できます。MySQL TLS は `false` または厳密なオブジェクトのみで、`{}` は証明書チェーンと DNS ID を検証します。PostgreSQL の真偽値・文字列モード・オブジェクト契約は維持します。
+
+```ts
+import { ReldbConfigSchema } from '@h-ai/reldb/schemas'
+
+const checked = ReldbConfigSchema.safeParse({ type: 'mysql', database: 'shop', ssl: {} })
+if (!checked.success)
+  throw new Error('Invalid database configuration')
+// checked.data.ssl: { rejectUnauthorized: true, verifyIdentity: true }
+```
+
+接続文字列（`url`）または個別フィールド（`host/port/database/user/password`）を指定できます。
+
+```ts
+// SQLite
+await reldb.init({ type: 'sqlite', database: './data.db' })
+
+// PostgreSQL
+await reldb.init({ type: 'postgresql', url: 'postgres://user:pass@localhost:5432/mydb', database: 'mydb' })
+
+// MySQL
+await reldb.init({
+  type: 'mysql',
+  host: 'localhost',
+  port: 3306,
+  database: 'mydb',
+  user: 'admin',
+  password: 'secret',
+  mysql: { charset: 'utf8mb4' },
+  pool: { max: 10, acquireTimeout: 5000, queueLimit: 100 },
+})
+```
+
+### 接続プールと MySQL URL
+
+MySQL の `pool` は `max`、`acquireTimeout`、`queueLimit` のみを受け付け、省略時もそれぞれ 10、10000 ミリ秒、1000 を使用します。`min`、`idleTimeout` などの未対応フィールドと未実装の `mysql.timezone` は設定検証で拒否します。アイドル接続は mysql2/サーバーによる切断または `close()` で解放し、最小保持数や設定可能なアイドル回収期限は保証しません。[mysql2 3.24.5 の設定](https://github.com/sidorares/node-mysql2/blob/v3.24.5/typings/mysql/lib/Pool.d.ts)は PostgreSQL と異なります。
+
+| フィールド       | PostgreSQL（`pool` 指定時の既定値） | MySQL                                  |
+| ---------------- | ----------------------------------- | -------------------------------------- |
+| `max`            | 10                                  | 10、借用中と接続確立中の合計上限       |
+| `min`            | 1、既存接続の保持下限。事前作成なし | 未対応、拒否                           |
+| `idleTimeout`    | 30000 ミリ秒、0 は無効化            | 未対応、拒否                           |
+| `acquireTimeout` | 10000 ミリ秒、0 は無効化            | 10000 ミリ秒、1–2147483647 の整数      |
+| `queueLimit`     | 未対応                              | 1000、待機リクエスト数の上限、正の整数 |
+
+PostgreSQL で `pool` を省略した場合は pg の既定値を使用します。保持と回収の仕様は [pg.Pool](https://node-postgres.com/apis/pool) を参照してください。MySQL の SQL、DDL、CRUD、バッチ、トランザクションは共通の有限 FIFO 待機キューを使います。待機と接続確立に一つの期限を適用し、超過時は `TIMEOUT`、満杯時は `POOL_EXHAUSTED` を返します。期限切れ項目は削除し、遅れて取得した接続は SQL を実行せず解放します。確立処理が完了するまで容量枠を保持します。受領時と処理開始前にも期限を確認しますが、開始済み SQL/トランザクションの実行時間は制限しません。
+
+MySQL の `close()` は新規・待機リクエストを直ちに拒否し、借用接続、トランザクション、接続確立の完了後にプールを閉じます。`connectTimeout` にも同じ値を使うため、その期限や既存処理を待つ場合があります。アプリはトランザクションを終了してください。環境変数は `HAI_DB_POOL_*` です。`MIN` / `IDLETIMEOUT` は PostgreSQL 専用で、MySQL の `QUEUELIMIT` は待機総数を制限します。
+
+MySQL は `mysql://` の `url` だけでも接続でき、URL がなければ `database` が必須です。URL の host/port/database/user/password を優先し、競合する個別フィールドは接続に使用しません。`pool`、`mysql.charset`、`ssl`、`operationLog` は独立して適用します。query/fragment は拒否し、URL 内の隠れた設定で TLS やプールを変更できません。接続ログの URL は機密情報を伏せます。以下は `HAI_DB_URL` の設定を前提とします：
+
+```ts
+const initialized = await reldb.init({
+  type: 'mysql',
+  url: process.env.HAI_DB_URL,
+  pool: { max: 10, acquireTimeout: 5000, queueLimit: 100 }
+})
+if (!initialized.success)
+  throw new Error(initialized.error.message)
+```
+
+MySQL の空 `url`（空の環境変数を含む）は host/port/database/user/password を使用します。空でない URL は厳密に検証します。
+
+#### MySQL TLS
+
+`ssl` を省略するか `false` にすると TLS を使用しません。有効化には厳密なオブジェクトを指定し、空オブジェクトの既定値は `{ rejectUnauthorized: true, verifyIdentity: true }` です。`ca` は信頼する CA の PEM 内容で、省略時は Node の信頼ストアを使います。任意のクライアント `cert` / `key` も PEM 内容で、必ず対で指定します。未知の TLS フィールド、`true`、PostgreSQL の文字列モードは拒否し、任意の設定やコールバックは透過しません。
+
+[mysql2 3.24.5 の主機名検証](https://github.com/sidorares/node-mysql2/blob/v3.24.5/lib/base/connection.js)は DNS servername に依存します。証明書と名前の両方を検証する場合、IP 接続先は `CONFIG_ERROR` とし、証明書の DNS SAN に一致するホスト名を使います。明示的な `verifyIdentity: false` は証明書チェーンのみを検証します。`rejectUnauthorized: false` はサーバー認証を放棄し、暗号化だけでは相手の身元を確認できません。どちらかの検証を無効にすると固定のリスク警告を記録し、安全な構成とは扱いません。
+
+```ts
+// trustedCaPem は配置時の信頼設定から供給し、任意の接続先証明書をそのまま信頼しません。
+const initialized = await reldb.init({
+  type: 'mysql',
+  host: 'db.example.com',
+  database: 'app',
+  ssl: { ca: trustedCaPem }
+})
+if (!initialized.success)
+  throw new Error(initialized.error.message)
+```
+
+TLS テストには OpenSSL（Windows は Git 同梱版も可）とローカルのコンテナー転送が必要です。各実行で CA/秘密鍵を生成・削除し、信頼済み DNS、誤った CA/主機名の拒否、`REQUIRE X509` 認証、実際の `Ssl_cipher` を検証します。検証無効の接続を認証済み TLS の証拠にはしません。
+
+#### SQLite の実行方式（非同期 worker）
+
+better-sqlite3 は同期ドライバーなので、クエリは Node のメインイベントループをブロックします。WAL は DB ロックの並行性を改善しますが、同期呼び出しによるブロックは解消しません。専用 worker スレッドで SQLite を実行して処理を移せます（単一接続、任意設定、既定は `sync`）：
+
+```ts
+await reldb.init({
+  type: 'sqlite',
+  database: './data.db',
+  sqlite: {
+    executor: 'worker', // 'sync'（默认）| 'worker'
+    walMode: true, // 默认 true
+    workerConnectTimeoutMs: 10000, // worker 打开连接超时，默认 10000
+  },
+})
+```
+
+worker モードではクエリ、書き込み、トランザクションを worker スレッドで順番に実行します。公開 API と戻り値は同期モードと同じです。
+
+#### 操作ログ
+
+DB 設定の `operationLog` で SQL 操作ログを有効にできます。ログは reldb provider-base の DML 層で出力され、`reldb-main.ts` や各 raw provider で重複してラップしません。
+
+```yaml
+# config/_db.yml
+type: sqlite
+database: ./data/app.db
+operationLog:
+  read: false # query / get / queryPage
+  write: false # DDL, execute / batch, tx.begin / tx.commit / tx.rollback
+  maxLength: 1000 # 安全な件数サマリーの最大長。0は省略。SQL本文と値は記録しない
+  level: debug # info | debug | trace，默认 debug
+```
+
+`core.config.load('db', ...)` で読み込む場合、`HAI_DB_TYPE`、
+`HAI_DB_DATABASE`、`HAI_DB_OPERATIONLOG_LEVEL` などの規約に沿う変数が YAML より優先されます。
+
+```ts
+await reldb.init({
+  type: 'sqlite',
+  database: './data.db',
+  operationLog: {
+    read: true,
+    write: true,
+    maxLength: 500,
+    level: 'debug',
+  },
+})
+```
+
+操作ログには固定の操作名、SQL 長、パラメーター数、バッチ件数を記録します。失敗時は、エラーコード、traceId、許可リストに含まれるマスキング済みのドライバーメッセージとスタックも保持します。SQL 全文、バインド値、接続設定をそのまま記録することはありません。
+
+設定はホストが読込・検証してから渡します。秘密はサーバーの非公開環境に保存し、利用場面に応じてバックエンド・容量・期限・ログを選びます。変更後は再初期化の結果を確認してください。
+
+[項目別の用途・適用場面・例](../../docs/usage/configuration/data.md).
+
+## エラー処理
+
+領域操作は result.success を確認し、失敗時はモジュールのエラー定義と安全な説明を使います。コード・関連 ID・秘匿した原因をサーバーログに残します。同期ツール・ファクトリー・ストリーム反復・ライフサイクルは各署名に従い、Promise 完了だけで成功と判断しません。回復条件は各機能を参照してください。
 
 すべての操作は `HaiResult<T>` を返し、`result.success` で成功・失敗を判定します。
 
@@ -630,15 +790,7 @@ if (!result.success) {
 
 `BaseReldbCrudRepository` の派生クラスで独自 SQL を実行する前に `await this.ensureReady()` を確認します。構築時に建表を開始するだけなので、サービス init は候補の準備完了後に公開します。PostgreSQL の自動コミットによる単一の `CREATE TABLE/INDEX IF NOT EXISTS` は、`23505/pg_class_relname_nsp_index`（建表は `pg_type_typname_nsp_index` も対象）の競合、または建表時にサーバー routine が `heap_create_with_catalog` / `TypeCreate` である `42710` の行型競合に限り、DDL/SQL の両入口で一度だけ再実行します。再試行も失敗した場合はエラーを返します。トランザクション、業務の一意制約、その他の失敗は再試行しません。初期接続確認の一時 DNS エラー `EAI_AGAIN` は 250/500 ms 間隔で最大三回試行し、業務 SQL は再送しません。
 
-## 本番の共有状態
-
-本番は PostgreSQL/MySQL が必須です。ファイルを含む SQLite は開発・明示的テスト用であり、ホスト間の共有状態を保証しません。 NODE_ENV または HAI_CORE_ENV が production の場合、初期化成功前に検証します。明示的な HAI_E2E=1/HAI_E2E_MOCK=1 テストのみ除外します。 [状態・並行制御・復旧範囲（中国語）](../../.agents/instructions/distributed-state.md)。
-
-## モジュールのスキーマ移行
-
-`schemaColumns(reldb, table, sql?)` は実際の列を読み取ります。`migrateSchema(reldb, module, steps, { dryRun: true })` は台帳を作成しません。各モジュールが手順を所有し、`hai_schema_migrations` に版を記録します。SQLite/PostgreSQL はトランザクション、MySQL の暗黙 DDL コミットには再入可能な手順が必要です。失敗時は版を進めず、実構造を再確認して再試行します。新しい台帳へのダウングレードは拒否します。旧書込を停止し DB/セッションキャッシュをバックアップしてください。復旧は互換 DB とバイナリを一緒に戻します。[更新ガイド](../../docs/usage/README.ja.md)を参照。
-
-## エラー表示とログの関連付け
+### エラー表示とログの関連付け
 
 一意制約違反は `HaiReldbError.DUPLICATE_ENTRY`（409）に統一し、タイムアウトや待機列満杯など既存のコードは保持します。翻訳済みメッセージやドライバー文字列ではなくコードで分岐してください。ログには code/schema/routine/constraint とスタック行番号を残し、数値のバインド値でこれらの診断識別子を隠しません。