@h-ai/reldb 0.1.0-alpha.56 → 0.1.0-alpha.57

package/README.en.md

@@ -0,0 +1,520 @@
+# @h-ai/reldb
+
+[简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
+
+[Framework home](../../README.en.md) · Related modules: [@h-ai/core](../core/README.en.md)
+
+A relational database module with a unified `reldb` object for SQLite, PostgreSQL, and MySQL.
+
+## Supported databases
+
+- SQLite
+- PostgreSQL
+- MySQL
+
+## Quick start
+
+```ts
+import { HaiReldbError, reldb } from '@h-ai/reldb'
+
+// 初始化
+await reldb.init({ type: 'sqlite', database: ':memory:' })
+
+// DDL
+await reldb.ddl.createTable('users', {
+  id: { type: 'INTEGER', primaryKey: true, autoIncrement: true },
+  name: { type: 'TEXT', notNull: true },
+  email: { type: 'TEXT', unique: true },
+})
+
+// SQL
+await reldb.sql.execute('INSERT INTO users (name, email) VALUES (?, ?)', ['张三', 'test@example.com'])
+const users = await reldb.sql.query<{ id: number, name: string }>('SELECT * FROM users')
+
+// 分页查询
+const page = await reldb.sql.queryPage<{ id: number, name: string }>({
+  sql: 'SELECT id, name FROM users ORDER BY id',
+  pagination: { page: 1, pageSize: 20 },
+})
+
+// CRUD
+const userCrud = reldb.crud.table({
+  table: 'users',
+  idColumn: 'id',
+  select: ['id', 'name', 'email'],
+  createColumns: ['name', 'email'],
+  updateColumns: ['name', 'email'],
+  dbType: 'sqlite',
+})
+await userCrud.create({ name: '李四', email: 'li@test.com' })
+const user = await userCrud.findById(1)
+
+// 关闭
+await reldb.close()
+```
+
+`reldb.config` returns a **redacted configuration snapshot**. Database `password` and credentials embedded in URLs are hidden automatically. Use it to inspect state, not to replay original connection details.
+
+## Configuration
+
+Use either a connection string (`url`) or separate fields (`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' })
+
+// MySQL
+await reldb.init({
+  type: 'mysql',
+  host: 'localhost',
+  port: 3306,
+  database: 'mydb',
+  user: 'admin',
+  password: 'secret',
+  mysql: { charset: 'utf8mb4' },
+})
+```
+
+### SQLite execution (asynchronous worker)
+
+better-sqlite3 is synchronous, so queries block Node's main event loop. WAL improves database lock concurrency but cannot remove this blocking. To offload it, opt in to a dedicated SQLite worker thread (single connection; defaults to `sync`):
+
+```ts
+await reldb.init({
+  type: 'sqlite',
+  database: './data.db',
+  sqlite: {
+    executor: 'worker', // 'sync'（默认）| 'worker'
+    walMode: true, // 默认 true
+    workerConnectTimeoutMs: 10000, // worker 打开连接超时，默认 10000
+  },
+})
+```
+
+In worker mode, queries, writes, and transactions run serially on the worker thread. Public APIs and return values remain identical to synchronous mode.
+
+### Operation logging
+
+Enable SQL operation logs with `operationLog` in the database configuration. Logs are emitted at the DML layer of reldb provider-base, without duplicate wrappers in `reldb-main.ts` or raw providers.
+
+```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 # 参数序列化后的最大输出长度，超出会截断
+  level: debug # info | debug | trace，默认 debug
+```
+
+When loading through `core.config.load('db', ...)`, convention-based variables such as `HAI_DB_TYPE`,
+`HAI_DB_DATABASE`, and `HAI_DB_OPERATIONLOG_LEVEL` override YAML values.
+
+```ts
+await reldb.init({
+  type: 'sqlite',
+  database: './data.db',
+  operationLog: {
+    read: true,
+    write: true,
+    maxLength: 500,
+    level: 'debug',
+  },
+})
+```
+
+## Transactions
+
+Three approaches:
+
+### wrap (automatic commit/rollback)
+
+```ts
+const result = await reldb.tx.wrap(async (tx) => {
+  await tx.execute('INSERT INTO users (name) VALUES (?)', ['用户1'])
+  await tx.execute('INSERT INTO users (name) VALUES (?)', ['用户2'])
+  return 'ok'
+})
+// 回调正常返回 → 自动提交；抛异常 → 自动回滚
+```
+
+### begin + commit (explicit commit)
+
+```ts
+const txResult = await reldb.tx.begin()
+if (!txResult.success) { /* 处理错误 */ }
+const tx = txResult.data
+
+await tx.execute('INSERT INTO users (name) VALUES (?)', ['用户1'])
+await tx.execute('INSERT INTO users (name) VALUES (?)', ['用户2'])
+await tx.commit()
+```
+
+### begin + rollback (explicit rollback)
+
+```ts
+const txResult = await reldb.tx.begin()
+if (!txResult.success) { /* 处理错误 */ }
+const tx = txResult.data
+
+await tx.execute('INSERT INTO users (name) VALUES (?)', ['用户1'])
+// 业务检查失败，手动回滚
+await tx.rollback()
+```
+
+### batch / queryPage inside transactions
+
+```ts
+await reldb.tx.wrap(async (tx) => {
+  await tx.batch([
+    { sql: 'INSERT INTO users (name) VALUES (?)', params: ['用户1'] },
+    { sql: 'INSERT INTO users (name) VALUES (?)', params: ['用户2'] },
+  ])
+
+  const page = await tx.queryPage<{ id: number, name: string }>({
+    sql: 'SELECT id, name FROM users ORDER BY id',
+    pagination: { page: 1, pageSize: 10 },
+  })
+})
+```
+
+## Crud
+
+Create a single-table CRUD repository with `reldb.crud.table()`, without writing SQL:
+
+```ts
+const userCrud = reldb.crud.table<{ id: number, name: string, email: string }>({
+  table: 'users',
+  idColumn: 'id', // 主键列，默认 'id'
+  select: ['id', 'name', 'email'], // 查询列，默认 '*'
+  createColumns: ['name', 'email'], // 允许插入的列
+  updateColumns: ['name', 'email'], // 允许更新的列
+  dbType: 'sqlite', // 数据库类型
+})
+```
+
+### create / createMany
+
+```ts
+// 单条插入
+const result = await userCrud.create({ name: '张三', email: 'test@example.com' })
+// result.data → { changes: 1, lastInsertRowid: 1 }
+
+// 批量插入
+await userCrud.createMany([
+  { name: '用户A', email: 'a@test.com' },
+  { name: '用户B', email: 'b@test.com' },
+])
+```
+
+### createOrUpdate
+
+Update when the primary key exists; otherwise create (upsert):
+
+```ts
+const userCrud = reldb.crud.table<{ id: number, name: string, email: string }>({
+  table: 'users',
+  idColumn: 'id',
+  createColumns: ['id', 'name', 'email'],
+  updateColumns: ['name', 'email'],
+  dbType: 'sqlite',
+})
+
+await userCrud.createOrUpdate({ id: 1, name: '张三', email: 'test@example.com' })
+// 不存在 → 插入；已存在 → 更新 name、email
+```
+
+`BaseReldbCrudRepository` obtains `dbType` automatically; no manual argument is needed.
+
+### findById / getById / findAll / findPage
+
+```ts
+// 主键查找（不存在时返回 null）
+const user = await userCrud.findById(1)
+// user.data → { id: 1, name: '张三', email: 'test@example.com' } | null
+
+// 主键获取（不存在时返回 RECORD_NOT_FOUND 错误）
+const user2 = await userCrud.getById(1)
+// user2.data → { id: 1, name: '张三', email: 'test@example.com' }
+
+// 条件查询（where + params 占位符）
+const actives = await userCrud.findAll({
+  where: 'name LIKE ?',
+  params: ['%张%'],
+  orderBy: 'id DESC',
+  limit: 10,
+  offset: 0,
+})
+
+// 分页查询
+const page = await userCrud.findPage({
+  where: 'name LIKE ?',
+  params: ['%张%'],
+  orderBy: 'id DESC',
+  pagination: { page: 1, pageSize: 20 },
+})
+// page.data → { items: [...], total: 100, page: 1, pageSize: 20 }
+```
+
+### updateById / deleteById
+
+```ts
+await userCrud.updateById(1, { name: '李四' })
+await userCrud.deleteById(1)
+```
+
+### count / exists / existsById
+
+```ts
+const total = await userCrud.count({ where: 'name LIKE ?', params: ['%张%'] })
+// total.data → 5
+
+const has = await userCrud.exists({ where: 'email = ?', params: ['test@example.com'] })
+// has.data → true
+
+const found = await userCrud.existsById(1)
+// found.data → true
+```
+
+### Crud inside transactions
+
+All methods accept `tx` and automatically route operations to that transaction context:
+
+```ts
+await reldb.tx.wrap(async (tx) => {
+  await userCrud.create({ name: '用户A', email: 'a@test.com' }, tx)
+  await userCrud.updateById(1, { name: '新名字' }, tx)
+  const user = await userCrud.findById(1, tx)
+})
+```
+
+## BaseReldbCrudRepository
+
+Business repositories extend `BaseReldbCrudRepository` and define field mappings with `fields` for automatic table creation and type conversion:
+
+```ts
+import type { DmlWithTxOperations, ReldbCrudFieldDefinition } from '@h-ai/reldb'
+import { BaseReldbCrudRepository, reldb } from '@h-ai/reldb'
+
+interface UserRow {
+  id: number
+  name: string
+  email: string
+  createdAt: Date
+  updatedAt: Date
+}
+
+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 },
+]
+
+class UserRepository extends BaseReldbCrudRepository<UserRow> {
+  constructor() {
+    super(reldb, { table: 'users', idColumn: 'id', fields: USER_FIELDS })
+  }
+
+  /** 自定义查询方法 */
+  async findByEmail(email: string) {
+    return this.findAll({ where: 'email = ?', params: [email], limit: 1 })
+  }
+
+  /** 自定义方法中使用 this.sql(tx) 自动路由到事务 */
+  async insertRaw(data: { name: string, email: string }, tx?: DmlWithTxOperations) {
+    // 自定义原始写操作应先确保表已就绪（避免刚建库/建表较慢时的竞态）
+    const ready = await this.ensureReady()
+    if (!ready.success)
+      return ready
+    const now = Date.now()
+    return this.sql(tx).execute(
+      'INSERT INTO users (name, email, created_at, updated_at) VALUES (?, ?, ?, ?)',
+      [data.name, data.email, now, now],
+    )
+  }
+}
+
+// 使用
+const repo = new UserRepository()
+await repo.create({ name: '张三', email: 'test@example.com' })
+const user = await repo.findById(1)
+
+// 创建或更新（upsert）
+await repo.createOrUpdate({ id: 1, name: '李四', email: 'test@example.com' })
+// id=1 已存在 → 更新 name；不存在 → 插入新记录
+
+// 跨仓库事务
+const txResult = await reldb.tx.begin()
+if (txResult.success) {
+  const tx = txResult.data
+  await repo.create({ name: '用户A', email: 'a@test.com' }, tx)
+  await repo.create({ name: '用户B', email: 'b@test.com' }, tx)
+  await tx.commit()
+}
+```
+
+## JSON path operations
+
+Use `reldb.json` to build SQL expressions for consistent JSON path operations across databases.
+
+Paths follow SQL/JSON Path (`$.key` / `$.key.subkey` / `$[0]`); each backend maps them to its own functions or operators.
+
+| Operation | SQLite         | PostgreSQL     | MySQL              |
+| --------- | -------------- | -------------- | ------------------ |
+| `extract` | `json_extract` | `#>` (text[])  | `JSON_EXTRACT`     |
+| `set`     | `json_set`     | `jsonb_set`    | `JSON_SET`         |
+| `insert`  | `json_insert`  | `jsonb_insert` | `JSON_INSERT`      |
+| `remove`  | `json_remove`  | `#-` (text[])  | `JSON_REMOVE`      |
+| `merge`   | `json_patch`   | `\|\| ::jsonb` | `JSON_MERGE_PATCH` |
+
+All methods return `{ sql, params }` fragments that can be embedded in `reldb.sql.query` / `reldb.sql.execute`.
+
+### extract — read a JSON field value
+
+```ts
+// 用于 WHERE 条件
+const { sql, params } = reldb.json.extract('settings', '$.theme')
+const rows = await reldb.sql.query(
+  `SELECT * FROM users WHERE ${sql} = ?`,
+  [...params, '"dark"'],
+)
+
+// 用于 SELECT 列
+const { sql, params } = reldb.json.extract('profile', '$.name')
+const result = await reldb.sql.query(
+  `SELECT id, ${sql} as display_name FROM users`,
+  params,
+)
+```
+
+### set — set a JSON path (create or replace)
+
+```ts
+const { sql, params } = reldb.json.set('settings', '$.theme', 'dark')
+await reldb.sql.execute(
+  `UPDATE users SET settings = ${sql} WHERE id = ?`,
+  [...params, userId],
+)
+```
+
+### insert — insert at a JSON path (only when absent)
+
+```ts
+const { sql, params } = reldb.json.insert('data', '$.firstSeen', new Date().toISOString())
+await reldb.sql.execute(
+  `UPDATE events SET data = ${sql} WHERE id = ?`,
+  [...params, eventId],
+)
+```
+
+### remove — remove a JSON path
+
+```ts
+const { sql, params } = reldb.json.remove('settings', '$.deprecated')
+await reldb.sql.execute(
+  `UPDATE users SET settings = ${sql} WHERE id = ?`,
+  [...params, userId],
+)
+```
+
+### merge — merge JSON objects (RFC 7396 Merge Patch)
+
+```ts
+// 覆盖已有键、保留未提及键、将 null 键删除
+const { sql, params } = reldb.json.merge('profile', {
+  bio: '新简介',
+  avatar: null, // 传入 null 表示删除该键
+})
+await reldb.sql.execute(
+  `UPDATE users SET profile = ${sql} WHERE id = ?`,
+  [...params, userId],
+)
+```
+
+### Complete example
+
+```ts
+// 建表（含 JSON 列）
+await reldb.ddl.createTable('products', {
+  id: { type: 'INTEGER', primaryKey: true, autoIncrement: true },
+  meta: { type: 'JSON' },
+})
+
+// 插入初始 JSON
+await reldb.sql.execute(
+  `INSERT INTO products (meta) VALUES (?)`,
+  [JSON.stringify({ status: 'draft', tags: ['new'], version: 1 })],
+)
+
+// 设置字段
+const { sql: setSql, params: setParams } = reldb.json.set('meta', '$.status', 'published')
+await reldb.sql.execute(`UPDATE products SET meta = ${setSql} WHERE id = ?`, [...setParams, 1])
+
+// 提取字段（用于过滤）
+const { sql: exSql, params: exParams } = reldb.json.extract('meta', '$.status')
+const published = await reldb.sql.query(
+  `SELECT * FROM products WHERE ${exSql} = ?`,
+  [...exParams, '"published"'],
+)
+
+// 合并更新
+const { sql: mSql, params: mParams } = reldb.json.merge('meta', { version: 2, reviewer: 'admin' })
+await reldb.sql.execute(`UPDATE products SET meta = ${mSql} WHERE id = ?`, [...mParams, 1])
+
+// 删除字段
+const { sql: rmSql, params: rmParams } = reldb.json.remove('meta', '$.reviewer')
+await reldb.sql.execute(`UPDATE products SET meta = ${rmSql} WHERE id = ?`, [...rmParams, 1])
+```
+
+## Error handling
+
+All operations return `HaiResult<T>`; check `result.success` for success or failure.
+
+```ts
+import { HaiReldbError, reldb } from '@h-ai/reldb'
+
+const result = await reldb.sql.query('SELECT * FROM users')
+if (!result.success) {
+  switch (result.error.code) {
+    case HaiReldbError.NOT_INITIALIZED.code:
+      // 请先调用 reldb.init()
+      break
+    case HaiReldbError.QUERY_FAILED.code:
+      // SQL 执行错误
+      break
+    case HaiReldbError.CONSTRAINT_VIOLATION.code:
+      // 约束违反（如唯一约束、外键等）
+      break
+  }
+}
+```
+
+Common error codes:
+
+| Error code                           | code            | Description           |
+| ------------------------------------ | --------------- | --------------------- |
+| `HaiReldbError.NOT_INITIALIZED`      | `hai:reldb:010` | Not initialized       |
+| `HaiReldbError.CONNECTION_FAILED`    | `hai:reldb:001` | Connection failed     |
+| `HaiReldbError.QUERY_FAILED`         | `hai:reldb:002` | Query failed          |
+| `HaiReldbError.CONSTRAINT_VIOLATION` | `hai:reldb:003` | Constraint violation  |
+| `HaiReldbError.TRANSACTION_FAILED`   | `hai:reldb:004` | Transaction failed    |
+| `HaiReldbError.DDL_FAILED`           | `hai:reldb:020` | DDL operation failed  |
+| `HaiReldbError.CONFIG_ERROR`         | `hai:reldb:013` | Invalid configuration |
+
+## Tests
+
+```bash
+pnpm --filter @h-ai/reldb test
+```
+
+> MySQL/PostgreSQL tests require Docker.
+
+## License
+
+Apache-2.0

package/README.ja.md

@@ -0,0 +1,520 @@
+# @h-ai/reldb
+
+[简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
+
+[フレームワークのホーム](../../README.ja.md) · 関連モジュール：[@h-ai/core](../core/README.ja.md)
+
+共通の `reldb` オブジェクトで SQLite、PostgreSQL、MySQL を操作するリレーショナルデータベースモジュールです。
+
+## 対応データベース
+
+- SQLite
+- PostgreSQL
+- MySQL
+
+## クイックスタート
+
+```ts
+import { HaiReldbError, reldb } from '@h-ai/reldb'
+
+// 初始化
+await reldb.init({ type: 'sqlite', database: ':memory:' })
+
+// DDL
+await reldb.ddl.createTable('users', {
+  id: { type: 'INTEGER', primaryKey: true, autoIncrement: true },
+  name: { type: 'TEXT', notNull: true },
+  email: { type: 'TEXT', unique: true },
+})
+
+// SQL
+await reldb.sql.execute('INSERT INTO users (name, email) VALUES (?, ?)', ['张三', 'test@example.com'])
+const users = await reldb.sql.query<{ id: number, name: string }>('SELECT * FROM users')
+
+// 分页查询
+const page = await reldb.sql.queryPage<{ id: number, name: string }>({
+  sql: 'SELECT id, name FROM users ORDER BY id',
+  pagination: { page: 1, pageSize: 20 },
+})
+
+// CRUD
+const userCrud = reldb.crud.table({
+  table: 'users',
+  idColumn: 'id',
+  select: ['id', 'name', 'email'],
+  createColumns: ['name', 'email'],
+  updateColumns: ['name', 'email'],
+  dbType: 'sqlite',
+})
+await userCrud.create({ name: '李四', email: 'li@test.com' })
+const user = await userCrud.findById(1)
+
+// 关闭
+await reldb.close()
+```
+
+`reldb.config` は**機密情報をマスクした設定スナップショット**を返します。DB の `password` と URL 内の認証情報は自動的に非表示になります。状態確認用であり、元の接続情報の再利用には使わないでください。
+
+## 設定
+
+接続文字列（`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' })
+
+// MySQL
+await reldb.init({
+  type: 'mysql',
+  host: 'localhost',
+  port: 3306,
+  database: 'mydb',
+  user: 'admin',
+  password: 'secret',
+  mysql: { charset: 'utf8mb4' },
+})
+```
+
+### 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 # 参数序列化后的最大输出长度，超出会截断
+  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',
+  },
+})
+```
+
+## トランザクション
+
+3 種類の使用方法：
+
+### wrap（自動コミット/ロールバック）
+
+```ts
+const result = await reldb.tx.wrap(async (tx) => {
+  await tx.execute('INSERT INTO users (name) VALUES (?)', ['用户1'])
+  await tx.execute('INSERT INTO users (name) VALUES (?)', ['用户2'])
+  return 'ok'
+})
+// 回调正常返回 → 自动提交；抛异常 → 自动回滚
+```
+
+### begin + commit（手動コミット）
+
+```ts
+const txResult = await reldb.tx.begin()
+if (!txResult.success) { /* 处理错误 */ }
+const tx = txResult.data
+
+await tx.execute('INSERT INTO users (name) VALUES (?)', ['用户1'])
+await tx.execute('INSERT INTO users (name) VALUES (?)', ['用户2'])
+await tx.commit()
+```
+
+### begin + rollback（手動ロールバック）
+
+```ts
+const txResult = await reldb.tx.begin()
+if (!txResult.success) { /* 处理错误 */ }
+const tx = txResult.data
+
+await tx.execute('INSERT INTO users (name) VALUES (?)', ['用户1'])
+// 业务检查失败，手动回滚
+await tx.rollback()
+```
+
+### トランザクション内での batch / queryPage
+
+```ts
+await reldb.tx.wrap(async (tx) => {
+  await tx.batch([
+    { sql: 'INSERT INTO users (name) VALUES (?)', params: ['用户1'] },
+    { sql: 'INSERT INTO users (name) VALUES (?)', params: ['用户2'] },
+  ])
+
+  const page = await tx.queryPage<{ id: number, name: string }>({
+    sql: 'SELECT id, name FROM users ORDER BY id',
+    pagination: { page: 1, pageSize: 10 },
+  })
+})
+```
+
+## Crud
+
+`reldb.crud.table()` で単一テーブルの CRUD リポジトリーを作成できます。SQL の記述は不要です：
+
+```ts
+const userCrud = reldb.crud.table<{ id: number, name: string, email: string }>({
+  table: 'users',
+  idColumn: 'id', // 主键列，默认 'id'
+  select: ['id', 'name', 'email'], // 查询列，默认 '*'
+  createColumns: ['name', 'email'], // 允许插入的列
+  updateColumns: ['name', 'email'], // 允许更新的列
+  dbType: 'sqlite', // 数据库类型
+})
+```
+
+### create / createMany
+
+```ts
+// 单条插入
+const result = await userCrud.create({ name: '张三', email: 'test@example.com' })
+// result.data → { changes: 1, lastInsertRowid: 1 }
+
+// 批量插入
+await userCrud.createMany([
+  { name: '用户A', email: 'a@test.com' },
+  { name: '用户B', email: 'b@test.com' },
+])
+```
+
+### createOrUpdate
+
+主キーが存在すれば更新し、存在しなければ作成します（upsert）：
+
+```ts
+const userCrud = reldb.crud.table<{ id: number, name: string, email: string }>({
+  table: 'users',
+  idColumn: 'id',
+  createColumns: ['id', 'name', 'email'],
+  updateColumns: ['name', 'email'],
+  dbType: 'sqlite',
+})
+
+await userCrud.createOrUpdate({ id: 1, name: '张三', email: 'test@example.com' })
+// 不存在 → 插入；已存在 → 更新 name、email
+```
+
+`BaseReldbCrudRepository` は `dbType` を自動取得するため、手動指定は不要です。
+
+### findById / getById / findAll / findPage
+
+```ts
+// 主键查找（不存在时返回 null）
+const user = await userCrud.findById(1)
+// user.data → { id: 1, name: '张三', email: 'test@example.com' } | null
+
+// 主键获取（不存在时返回 RECORD_NOT_FOUND 错误）
+const user2 = await userCrud.getById(1)
+// user2.data → { id: 1, name: '张三', email: 'test@example.com' }
+
+// 条件查询（where + params 占位符）
+const actives = await userCrud.findAll({
+  where: 'name LIKE ?',
+  params: ['%张%'],
+  orderBy: 'id DESC',
+  limit: 10,
+  offset: 0,
+})
+
+// 分页查询
+const page = await userCrud.findPage({
+  where: 'name LIKE ?',
+  params: ['%张%'],
+  orderBy: 'id DESC',
+  pagination: { page: 1, pageSize: 20 },
+})
+// page.data → { items: [...], total: 100, page: 1, pageSize: 20 }
+```
+
+### updateById / deleteById
+
+```ts
+await userCrud.updateById(1, { name: '李四' })
+await userCrud.deleteById(1)
+```
+
+### count / exists / existsById
+
+```ts
+const total = await userCrud.count({ where: 'name LIKE ?', params: ['%张%'] })
+// total.data → 5
+
+const has = await userCrud.exists({ where: 'email = ?', params: ['test@example.com'] })
+// has.data → true
+
+const found = await userCrud.existsById(1)
+// found.data → true
+```
+
+### トランザクション内での Crud
+
+すべてのメソッドに `tx` を渡すことができ、対応するトランザクションのコンテキストへ自動的に切り替わります：
+
+```ts
+await reldb.tx.wrap(async (tx) => {
+  await userCrud.create({ name: '用户A', email: 'a@test.com' }, tx)
+  await userCrud.updateById(1, { name: '新名字' }, tx)
+  const user = await userCrud.findById(1, tx)
+})
+```
+
+## BaseReldbCrudRepository
+
+業務リポジトリーは `BaseReldbCrudRepository` を継承し、`fields` でフィールドの対応を定義します。テーブル作成と型変換は自動です：
+
+```ts
+import type { DmlWithTxOperations, ReldbCrudFieldDefinition } from '@h-ai/reldb'
+import { BaseReldbCrudRepository, reldb } from '@h-ai/reldb'
+
+interface UserRow {
+  id: number
+  name: string
+  email: string
+  createdAt: Date
+  updatedAt: Date
+}
+
+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 },
+]
+
+class UserRepository extends BaseReldbCrudRepository<UserRow> {
+  constructor() {
+    super(reldb, { table: 'users', idColumn: 'id', fields: USER_FIELDS })
+  }
+
+  /** 自定义查询方法 */
+  async findByEmail(email: string) {
+    return this.findAll({ where: 'email = ?', params: [email], limit: 1 })
+  }
+
+  /** 自定义方法中使用 this.sql(tx) 自动路由到事务 */
+  async insertRaw(data: { name: string, email: string }, tx?: DmlWithTxOperations) {
+    // 自定义原始写操作应先确保表已就绪（避免刚建库/建表较慢时的竞态）
+    const ready = await this.ensureReady()
+    if (!ready.success)
+      return ready
+    const now = Date.now()
+    return this.sql(tx).execute(
+      'INSERT INTO users (name, email, created_at, updated_at) VALUES (?, ?, ?, ?)',
+      [data.name, data.email, now, now],
+    )
+  }
+}
+
+// 使用
+const repo = new UserRepository()
+await repo.create({ name: '张三', email: 'test@example.com' })
+const user = await repo.findById(1)
+
+// 创建或更新（upsert）
+await repo.createOrUpdate({ id: 1, name: '李四', email: 'test@example.com' })
+// id=1 已存在 → 更新 name；不存在 → 插入新记录
+
+// 跨仓库事务
+const txResult = await reldb.tx.begin()
+if (txResult.success) {
+  const tx = txResult.data
+  await repo.create({ name: '用户A', email: 'a@test.com' }, tx)
+  await repo.create({ name: '用户B', email: 'b@test.com' }, tx)
+  await tx.commit()
+}
+```
+
+## JSON パス操作
+
+`reldb.json` で、複数のデータベースに共通する JSON パス操作の SQL 式を作成します。
+
+パスは SQL/JSON Path（`$.key` / `$.key.subkey` / `$[0]`）に従い、各 DB の関数・演算子に自動変換されます。
+
+| 操作      | SQLite         | PostgreSQL     | MySQL              |
+| --------- | -------------- | -------------- | ------------------ |
+| `extract` | `json_extract` | `#>` (text[])  | `JSON_EXTRACT`     |
+| `set`     | `json_set`     | `jsonb_set`    | `JSON_SET`         |
+| `insert`  | `json_insert`  | `jsonb_insert` | `JSON_INSERT`      |
+| `remove`  | `json_remove`  | `#-` (text[])  | `JSON_REMOVE`      |
+| `merge`   | `json_patch`   | `\|\| ::jsonb` | `JSON_MERGE_PATCH` |
+
+すべてのメソッドは `{ sql, params }` の断片を返し、`reldb.sql.query` / `reldb.sql.execute` に直接組み込めます。
+
+### extract — JSON フィールド値の取得
+
+```ts
+// 用于 WHERE 条件
+const { sql, params } = reldb.json.extract('settings', '$.theme')
+const rows = await reldb.sql.query(
+  `SELECT * FROM users WHERE ${sql} = ?`,
+  [...params, '"dark"'],
+)
+
+// 用于 SELECT 列
+const { sql, params } = reldb.json.extract('profile', '$.name')
+const result = await reldb.sql.query(
+  `SELECT id, ${sql} as display_name FROM users`,
+  params,
+)
+```
+
+### set — JSON パスの設定（作成または置換）
+
+```ts
+const { sql, params } = reldb.json.set('settings', '$.theme', 'dark')
+await reldb.sql.execute(
+  `UPDATE users SET settings = ${sql} WHERE id = ?`,
+  [...params, userId],
+)
+```
+
+### insert — JSON パスへの挿入（未存在の場合のみ）
+
+```ts
+const { sql, params } = reldb.json.insert('data', '$.firstSeen', new Date().toISOString())
+await reldb.sql.execute(
+  `UPDATE events SET data = ${sql} WHERE id = ?`,
+  [...params, eventId],
+)
+```
+
+### remove — JSON パスの削除
+
+```ts
+const { sql, params } = reldb.json.remove('settings', '$.deprecated')
+await reldb.sql.execute(
+  `UPDATE users SET settings = ${sql} WHERE id = ?`,
+  [...params, userId],
+)
+```
+
+### merge — JSON オブジェクトのマージ（RFC 7396 Merge Patch）
+
+```ts
+// 覆盖已有键、保留未提及键、将 null 键删除
+const { sql, params } = reldb.json.merge('profile', {
+  bio: '新简介',
+  avatar: null, // 传入 null 表示删除该键
+})
+await reldb.sql.execute(
+  `UPDATE users SET profile = ${sql} WHERE id = ?`,
+  [...params, userId],
+)
+```
+
+### 完全な使用例
+
+```ts
+// 建表（含 JSON 列）
+await reldb.ddl.createTable('products', {
+  id: { type: 'INTEGER', primaryKey: true, autoIncrement: true },
+  meta: { type: 'JSON' },
+})
+
+// 插入初始 JSON
+await reldb.sql.execute(
+  `INSERT INTO products (meta) VALUES (?)`,
+  [JSON.stringify({ status: 'draft', tags: ['new'], version: 1 })],
+)
+
+// 设置字段
+const { sql: setSql, params: setParams } = reldb.json.set('meta', '$.status', 'published')
+await reldb.sql.execute(`UPDATE products SET meta = ${setSql} WHERE id = ?`, [...setParams, 1])
+
+// 提取字段（用于过滤）
+const { sql: exSql, params: exParams } = reldb.json.extract('meta', '$.status')
+const published = await reldb.sql.query(
+  `SELECT * FROM products WHERE ${exSql} = ?`,
+  [...exParams, '"published"'],
+)
+
+// 合并更新
+const { sql: mSql, params: mParams } = reldb.json.merge('meta', { version: 2, reviewer: 'admin' })
+await reldb.sql.execute(`UPDATE products SET meta = ${mSql} WHERE id = ?`, [...mParams, 1])
+
+// 删除字段
+const { sql: rmSql, params: rmParams } = reldb.json.remove('meta', '$.reviewer')
+await reldb.sql.execute(`UPDATE products SET meta = ${rmSql} WHERE id = ?`, [...rmParams, 1])
+```
+
+## エラー処理
+
+すべての操作は `HaiResult<T>` を返し、`result.success` で成功・失敗を判定します。
+
+```ts
+import { HaiReldbError, reldb } from '@h-ai/reldb'
+
+const result = await reldb.sql.query('SELECT * FROM users')
+if (!result.success) {
+  switch (result.error.code) {
+    case HaiReldbError.NOT_INITIALIZED.code:
+      // 请先调用 reldb.init()
+      break
+    case HaiReldbError.QUERY_FAILED.code:
+      // SQL 执行错误
+      break
+    case HaiReldbError.CONSTRAINT_VIOLATION.code:
+      // 约束违反（如唯一约束、外键等）
+      break
+  }
+}
+```
+
+主なエラーコード：
+
+| エラーコード                         | code            | 説明                   |
+| ------------------------------------ | --------------- | ---------------------- |
+| `HaiReldbError.NOT_INITIALIZED`      | `hai:reldb:010` | 未初期化               |
+| `HaiReldbError.CONNECTION_FAILED`    | `hai:reldb:001` | 接続に失敗             |
+| `HaiReldbError.QUERY_FAILED`         | `hai:reldb:002` | 検索に失敗             |
+| `HaiReldbError.CONSTRAINT_VIOLATION` | `hai:reldb:003` | 制約違反               |
+| `HaiReldbError.TRANSACTION_FAILED`   | `hai:reldb:004` | トランザクションに失敗 |
+| `HaiReldbError.DDL_FAILED`           | `hai:reldb:020` | DDL 操作に失敗         |
+| `HaiReldbError.CONFIG_ERROR`         | `hai:reldb:013` | 設定エラー             |
+
+## テスト
+
+```bash
+pnpm --filter @h-ai/reldb test
+```
+
+> MySQL/PostgreSQL のテストには Docker が必要です。
+
+## License
+
+Apache-2.0

package/README.md

@@ -1,5 +1,9 @@
 # @h-ai/reldb
 
+[简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
+
+[框架首页](../../README.md) · 相关模块：[@h-ai/core](../core/README.md)
+
 关系型数据库访问模块，通过统一的 `reldb` 对象访问 SQLite、PostgreSQL、MySQL。
 
 ## 支持的数据库

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/reldb",
   "type": "module",
-  "version": "0.1.0-alpha.56",
+  "version": "0.1.0-alpha.57",
   "description": "Hai Framework relational database module for SQLite, PostgreSQL, and MySQL.",
   "license": "Apache-2.0",
   "exports": {
@@ -25,7 +25,7 @@
   "dependencies": {
     "better-sqlite3": "^12.6.2",
     "zod": "^4.4.3",
-    "@h-ai/core": "0.1.0-alpha.56"
+    "@h-ai/core": "0.1.0-alpha.57"
   },
   "optionalDependencies": {
     "mysql2": "^3.11.5",