@raft-hlc-sync-protocol/raft-sync-lib 1.0.1 → 1.0.3

package/README.md

@@ -33,74 +33,73 @@ cp -r sync-lib/ your-project/sync-lib/
 
 ### Step 1: Implement DatabaseAdapter
 
-The adapter translates sync-lib's generic calls into your database's dialect. Here's the SQLite version:
+The adapter provides basic query methods. Dialect-specific SQL (transactions, upsert, schema, triggers) is handled automatically via the `dialect` parameter.
+
+**SQLite:**
 
 ```js
 import Database from 'better-sqlite3';
-import { getInfraSchemaSQL } from 'sync-lib';
 
 const rawDb = new Database(':memory:');
 rawDb.pragma('journal_mode = WAL');
 
 const db = {
-    // --- Query (required) ---
     run(sql, params = [])  { return rawDb.prepare(sql).run(...params); },
     get(sql, params = [])  { return rawDb.prepare(sql).get(...params) || null; },
     all(sql, params = [])  { return rawDb.prepare(sql).all(...params); },
     exec(sql)              { rawDb.exec(sql); },
+};
+```
 
-    // --- Transaction control (required) ---
-    beginTransaction()     { rawDb.exec('BEGIN IMMEDIATE'); },
-    commit()               { rawDb.exec('COMMIT'); },
-    rollback()             { rawDb.exec('ROLLBACK'); },
+**PostgreSQL:**
 
-    // --- Upsert SQL builder (required) ---
-    upsertSQL(table, columns, keyColumns) {
-        const cols = columns.join(', ');
-        const ph = columns.map(() => '?').join(', ');
-        return `INSERT OR REPLACE INTO ${table} (${cols}) VALUES (${ph})`;
-    },
+```js
+import pg from 'pg';
+const pool = new pg.Pool({ connectionString: '...' });
 
-    // --- Schema DDL (optional, falls back to built-in SQLite DDL) ---
-    infraSchemaSQL() { return getInfraSchemaSQL(); },
+function pgConvert(sql) {
+    let i = 0;
+    return sql.replace(/\?/g, () => '$' + (++i));
+}
+
+const db = {
+    async run(sql, p = [])  { const r = await pool.query(pgConvert(sql), p); return { changes: r.rowCount }; },
+    async get(sql, p = [])  { const r = await pool.query(pgConvert(sql), p); return r.rows[0] || null; },
+    async all(sql, p = [])  { const r = await pool.query(pgConvert(sql), p); return r.rows; },
+    async exec(sql)         { await pool.query(sql); },
 };
 ```
 
-> See [PostgreSQL adapter](#databaseadapter-for-postgresql) and [MySQL adapter](#databaseadapter-for-mysql) below.
-
-#### Why `upsertSQL`?
+**MySQL:**
 
-sync-lib syncs data by "insert if not exists, update if exists". Every database has different syntax:
+```js
+import mysql from 'mysql2/promise';
+const pool = await mysql.createPool({ host: '...', user: '...', password: '...', database: '...' });
 
-| Database | `upsertSQL('users', ['id','name','_hlc'], ['id'])` returns |
-|----------|-----------------------------------------------------------|
-| SQLite | `INSERT OR REPLACE INTO users (id, name, _hlc) VALUES (?, ?, ?)` |
-| PostgreSQL | `INSERT INTO users (id, name, _hlc) VALUES ($1, $2, $3) ON CONFLICT (id) DO UPDATE SET name = EXCLUDED.name, _hlc = EXCLUDED._hlc` |
-| MySQL | `INSERT INTO users (id, name, _hlc) VALUES (?, ?, ?) ON DUPLICATE KEY UPDATE name = VALUES(name), _hlc = VALUES(_hlc)` |
+const db = {
+    async run(sql, p = [])  { const [r] = await pool.execute(sql, p); return { changes: r.affectedRows }; },
+    async get(sql, p = [])  { const [rows] = await pool.execute(sql, p); return rows[0] || null; },
+    async all(sql, p = [])  { const [rows] = await pool.execute(sql, p); return rows; },
+    async exec(sql)         { await pool.query(sql); },
+};
+```
 
-**Parameters**:
-- `table` — target table name
-- `columns` — all columns to insert (including keys)
-- `keyColumns` — primary key columns, used for conflict detection. On conflict, all non-key columns are updated.
+That's it — just 4 methods. The `dialect` parameter (see Step 2) fills in everything else automatically.
 
-sync-lib calls `upsertSQL` internally in 3 places:
-1. Syncing remote data into business tables
-2. Writing/updating tombstones (`_tombstones` table)
-3. Updating peer sync positions (`_sync_peers` table)
+> For custom databases, see [Full DatabaseAdapter Interface](#databaseadapter-interface) and [Custom Adapter Examples](#custom-adapter-examples) below.
 
-#### Why `infraSchemaSQL`?
+#### Built-in dialect support
 
-sync-lib needs 3 internal tables (`_sync_log`, `_sync_peers`, `_tombstones`). When you call `engine.initSchema()`, it calls `db.infraSchemaSQL()` to get the CREATE TABLE DDL.
+sync-lib has built-in support for **SQLite**, **PostgreSQL**, and **MySQL**. When you specify `dialect: 'sqlite'` (or `'postgresql'` / `'mysql'`), all dialect-specific methods are auto-filled on your adapter:
 
-Different databases need different DDL:
+- `beginTransaction()` / `commit()` / `rollback()` — transaction control
+- `upsertSQL(table, columns, keyColumns)` — conflict-aware insert/update SQL
+- `infraSchemaSQL()` — DDL for internal tables (`_sync_log`, `_sync_peers`, `_tombstones`)
+- `triggersSQL(tableName, def)` / `dropTriggersSQL(tableName)` — auto-logging triggers
 
-| | SQLite | PostgreSQL | MySQL |
-|--|--------|------------|-------|
-| Auto-increment | `AUTOINCREMENT` | `BIGSERIAL` | `AUTO_INCREMENT` |
-| Timestamp default | `datetime('now')` | `NOW()` | `CURRENT_TIMESTAMP` |
-| String type | `TEXT` | `TEXT` | `VARCHAR(255)` |
+**If you don't specify a dialect (or specify an unsupported one), you must implement ALL of these methods yourself.** Missing methods will throw an error at construction time.
 
-If you don't implement `infraSchemaSQL()`, sync-lib falls back to built-in SQLite DDL. **SQLite users can skip this method. PostgreSQL/MySQL users must implement it.**
+You can override any auto-filled method by defining it on your `db` adapter — your explicit implementation always takes priority over the built-in dialect.
 
 ### Step 2: Create engine and register tables
 
@@ -110,6 +109,7 @@ import { SyncEngine } from 'sync-lib';
 const engine = new SyncEngine({
     nodeId: 'node-1',
     db,
+    dialect: 'sqlite',   // or 'postgresql' or 'mysql'
 
     // Required callbacks
     onSendToPeer:    (peerId, msg) => yourTransport.send(peerId, msg),
@@ -130,8 +130,7 @@ engine.registerTable('users', {
 });
 
 engine.initSchema();     // Creates _sync_log, _sync_peers, _tombstones
-engine.initTriggers();   // SQLite only — creates auto-logging triggers
-                         // Skip for PostgreSQL/MySQL, use logChange() instead
+engine.initTriggers();   // Creates auto-logging triggers (dialect-aware)
 engine.start();          // Starts leader election
 ```
 
@@ -162,7 +161,7 @@ setInterval(() => engine.tickCleanup(), 3600_000);   // Cleanup old logs every 1
 
 ### Step 5: Write data
 
-**SQLite** (triggers auto-log changes):
+With `dialect` set and `initTriggers()` called, all databases work the same way — triggers automatically log changes:
 
 ```js
 const ts = engine.hlc.tick();
@@ -171,7 +170,7 @@ db.run('INSERT INTO users (user_id, name, _hlc) VALUES (?, ?, ?)',
 engine.notifyLocalWrite();  // pushes to peers
 ```
 
-**PostgreSQL / MySQL** (manual logChange):
+**Without triggers** (manual logChange fallback):
 
 ```js
 import { logChange } from 'sync-lib';
@@ -232,7 +231,11 @@ The leader executes the request via the `onExecuteProxyRequest` callback.
 
 ---
 
-## DatabaseAdapter for PostgreSQL
+## Custom Adapter Examples
+
+When using a built-in dialect (`sqlite`, `postgresql`, `mysql`), you only need `run/get/all/exec` on your adapter — everything else is auto-filled. The examples below show what the built-in dialect provides, and are useful as reference if you need to customize or use an unsupported database.
+
+### PostgreSQL (full manual adapter)
 
 ```js
 import pg from 'pg';
@@ -291,12 +294,40 @@ const db = {
                 _hlc TEXT NOT NULL, PRIMARY KEY (table_name, row_key))`,
         ];
     },
+
+    // Optional: inject PG triggers so initTriggers() works
+    triggersSQL(tableName, def) {
+        const keyExpr = def.keyColumns.map(c => `'${c}', NEW.${c}`).join(', ');
+        const dataExpr = def.dataColumns.map(c => `'${c}', NEW.${c}`).join(', ');
+        return [
+            `CREATE OR REPLACE FUNCTION _sync_trg_${tableName}_fn() RETURNS TRIGGER AS $$
+             BEGIN
+                 INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
+                 VALUES ('${tableName}', TG_OP,
+                         json_build_object(${keyExpr})::text,
+                         CASE WHEN TG_OP = 'DELETE' THEN NULL
+                              ELSE json_build_object(${dataExpr})::text END,
+                         COALESCE(NEW._hlc, OLD._hlc));
+                 RETURN COALESCE(NEW, OLD);
+             END; $$ LANGUAGE plpgsql`,
+            `DROP TRIGGER IF EXISTS _sync_trg_${tableName} ON ${tableName}`,
+            `CREATE TRIGGER _sync_trg_${tableName}
+             AFTER INSERT OR UPDATE OR DELETE ON ${tableName}
+             FOR EACH ROW EXECUTE FUNCTION _sync_trg_${tableName}_fn()`,
+        ];
+    },
+    dropTriggersSQL(tableName) {
+        return [
+            `DROP TRIGGER IF EXISTS _sync_trg_${tableName} ON ${tableName}`,
+            `DROP FUNCTION IF EXISTS _sync_trg_${tableName}_fn`,
+        ];
+    },
 };
 ```
 
 ---
 
-## DatabaseAdapter for MySQL
+### MySQL (full manual adapter)
 
 ```js
 import mysql from 'mysql2/promise';
@@ -347,6 +378,34 @@ const db = {
                 _hlc VARCHAR(64) NOT NULL, PRIMARY KEY (table_name, row_key(255)))`,
         ];
     },
+
+    // Optional: inject MySQL triggers so initTriggers() works
+    triggersSQL(tableName, def) {
+        const keyExpr = def.keyColumns.map(c => `'${c}', NEW.${c}`).join(', ');
+        const dataExpr = def.dataColumns.map(c => `'${c}', NEW.${c}`).join(', ');
+        const delKeyExpr = def.keyColumns.map(c => `'${c}', OLD.${c}`).join(', ');
+        return [
+            `CREATE TRIGGER _sync_trg_${tableName}_insert
+             AFTER INSERT ON ${tableName} FOR EACH ROW
+             INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
+             VALUES ('${tableName}', 'INSERT', JSON_OBJECT(${keyExpr}), JSON_OBJECT(${dataExpr}), NEW._hlc)`,
+            `CREATE TRIGGER _sync_trg_${tableName}_update
+             AFTER UPDATE ON ${tableName} FOR EACH ROW
+             INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
+             VALUES ('${tableName}', 'UPDATE', JSON_OBJECT(${keyExpr}), JSON_OBJECT(${dataExpr}), NEW._hlc)`,
+            `CREATE TRIGGER _sync_trg_${tableName}_delete
+             AFTER DELETE ON ${tableName} FOR EACH ROW
+             INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
+             VALUES ('${tableName}', 'DELETE', JSON_OBJECT(${delKeyExpr}), NULL, OLD._hlc)`,
+        ];
+    },
+    dropTriggersSQL(tableName) {
+        return [
+            `DROP TRIGGER IF EXISTS _sync_trg_${tableName}_insert`,
+            `DROP TRIGGER IF EXISTS _sync_trg_${tableName}_update`,
+            `DROP TRIGGER IF EXISTS _sync_trg_${tableName}_delete`,
+        ];
+    },
 };
 ```
 
@@ -385,14 +444,17 @@ const db = {
 ### Standalone utilities
 
 ```js
-import { HLC, logChange, getInfraSchemaSQL, getTriggersSQL } from 'sync-lib';
+import { HLC, DIALECTS, applyDialect, logChange, getInfraSchemaSQL, getTriggersSQL } from 'sync-lib';
 ```
 
 | Export | Description |
 |--------|-------------|
 | `HLC` | Hybrid Logical Clock class |
 | `LeaderElection` | Leader election state machine |
-| `logChange(db, table, op, key, data, hlc)` | Manually log a change (for non-SQLite DBs) |
+| `DIALECTS` | Built-in dialect definitions (sqlite, postgresql, mysql) |
+| `applyDialect(db, name)` | Apply a dialect's methods to a db adapter |
+| `validateDialectMethods(db)` | Validate all required dialect methods exist |
+| `logChange(db, table, op, key, data, hlc)` | Manually log a change (alternative to triggers) |
 | `getInfraSchemaSQL()` | Built-in SQLite DDL for infrastructure tables |
 | `getTriggersSQL(table, def)` | Generate SQLite sync triggers |
 | `applyEntries(db, entries, hlc, registry)` | Apply remote entries idempotently |
@@ -401,26 +463,31 @@ import { HLC, logChange, getInfraSchemaSQL, getTriggersSQL } from 'sync-lib';
 
 ## DatabaseAdapter Interface
 
-Every adapter must implement these methods:
-
 ```
 ┌───────────────────────────────────────────────────────────────┐
+│  Always required (you must implement):                         │
+│                                                               │
 │  db.run(sql, params)           → { changes: number }          │
 │  db.get(sql, params)           → Object | null                │
 │  db.all(sql, params)           → Object[]                     │
 │  db.exec(sql)                  → void                         │
 │                                                               │
+├───────────────────────────────────────────────────────────────┤
+│  Auto-filled by dialect (or manually required):               │
+│                                                               │
 │  db.beginTransaction()         → void                         │
 │  db.commit()                   → void                         │
 │  db.rollback()                 → void                         │
-│                                                               │
 │  db.upsertSQL(table, cols, keyColumns) → string               │
-│                                                               │
-│  db.infraSchemaSQL()           → string[]    (optional)       │
+│  db.infraSchemaSQL()           → string[]                     │
+│  db.triggersSQL(table, def)    → string[]                     │
+│  db.dropTriggersSQL(table)     → string[]                     │
 └───────────────────────────────────────────────────────────────┘
 ```
 
-SQL uses `?` placeholders. If your database uses `$1/$2` (e.g. PostgreSQL), convert inside the adapter.
+With `dialect: 'sqlite' | 'postgresql' | 'mysql'`, the bottom 7 methods are auto-filled. Without a dialect, you must implement all of them yourself.
+
+SQL uses `?` placeholders. If your database uses `$1/$2` (e.g. PostgreSQL), convert inside `run/get/all`.
 
 ---
 
@@ -446,7 +513,8 @@ sync-lib/
 ├── hlc.js                ← Hybrid Logical Clock (pure algorithm)
 ├── leader-election.js    ← Raft-simplified election state machine
 ├── sync-protocol.js      ← Message codec + idempotent data apply
-└── sync-engine.js        ← Main engine (composes all above)
+├── sync-engine.js        ← Main engine (composes all above)
+└── dialects.js           ← Built-in SQL dialects (SQLite/PG/MySQL)
 ```
 
 **Design principles**:

package/README.zh-CN.md

@@ -33,74 +33,73 @@ cp -r sync-lib/ your-project/sync-lib/
 
 ### 第 1 步：实现 DatabaseAdapter
 
-适配器将 sync-lib 的通用调用翻译为你的数据库方言。以下是 SQLite 版本：
+适配器只需提供基础查询方法。方言相关的 SQL（事务、upsert、schema、触发器）由 `dialect` 参数自动处理。
+
+**SQLite：**
 
 ```js
 import Database from 'better-sqlite3';
-import { getInfraSchemaSQL } from 'sync-lib';
 
 const rawDb = new Database(':memory:');
 rawDb.pragma('journal_mode = WAL');
 
 const db = {
-    // --- 查询（必需）---
     run(sql, params = [])  { return rawDb.prepare(sql).run(...params); },
     get(sql, params = [])  { return rawDb.prepare(sql).get(...params) || null; },
     all(sql, params = [])  { return rawDb.prepare(sql).all(...params); },
     exec(sql)              { rawDb.exec(sql); },
+};
+```
 
-    // --- 事务控制（必需）---
-    beginTransaction()     { rawDb.exec('BEGIN IMMEDIATE'); },
-    commit()               { rawDb.exec('COMMIT'); },
-    rollback()             { rawDb.exec('ROLLBACK'); },
+**PostgreSQL：**
 
-    // --- Upsert SQL 生成器（必需）---
-    upsertSQL(table, columns, keyColumns) {
-        const cols = columns.join(', ');
-        const ph = columns.map(() => '?').join(', ');
-        return `INSERT OR REPLACE INTO ${table} (${cols}) VALUES (${ph})`;
-    },
+```js
+import pg from 'pg';
+const pool = new pg.Pool({ connectionString: '...' });
 
-    // --- Schema DDL（可选，默认使用内置 SQLite DDL）---
-    infraSchemaSQL() { return getInfraSchemaSQL(); },
+function pgConvert(sql) {
+    let i = 0;
+    return sql.replace(/\?/g, () => '$' + (++i));
+}
+
+const db = {
+    async run(sql, p = [])  { const r = await pool.query(pgConvert(sql), p); return { changes: r.rowCount }; },
+    async get(sql, p = [])  { const r = await pool.query(pgConvert(sql), p); return r.rows[0] || null; },
+    async all(sql, p = [])  { const r = await pool.query(pgConvert(sql), p); return r.rows; },
+    async exec(sql)         { await pool.query(sql); },
 };
 ```
 
-> 参见下方 [PostgreSQL 适配器](#postgresql-适配器) 和 [MySQL 适配器](#mysql-适配器)。
-
-#### 为什么需要 `upsertSQL`？
+**MySQL：**
 
-sync-lib 通过"不存在则插入，存在则更新"来同步数据。不同数据库语法各异：
+```js
+import mysql from 'mysql2/promise';
+const pool = await mysql.createPool({ host: '...', user: '...', password: '...', database: '...' });
 
-| 数据库 | `upsertSQL('users', ['id','name','_hlc'], ['id'])` 返回值 |
-|--------|-----------------------------------------------------------|
-| SQLite | `INSERT OR REPLACE INTO users (id, name, _hlc) VALUES (?, ?, ?)` |
-| PostgreSQL | `INSERT INTO users (id, name, _hlc) VALUES ($1, $2, $3) ON CONFLICT (id) DO UPDATE SET name = EXCLUDED.name, _hlc = EXCLUDED._hlc` |
-| MySQL | `INSERT INTO users (id, name, _hlc) VALUES (?, ?, ?) ON DUPLICATE KEY UPDATE name = VALUES(name), _hlc = VALUES(_hlc)` |
+const db = {
+    async run(sql, p = [])  { const [r] = await pool.execute(sql, p); return { changes: r.affectedRows }; },
+    async get(sql, p = [])  { const [rows] = await pool.execute(sql, p); return rows[0] || null; },
+    async all(sql, p = [])  { const [rows] = await pool.execute(sql, p); return rows; },
+    async exec(sql)         { await pool.query(sql); },
+};
+```
 
-**参数说明**：
-- `table` — 目标表名
-- `columns` — 要插入的所有列（包括主键列）
-- `keyColumns` — 主键列，用于冲突检测。冲突时更新所有非主键列。
+只需 4 个方法。`dialect` 参数（见第 2 步）会自动填充其余所有方言方法。
 
-sync-lib 内部在 3 个地方调用 `upsertSQL`：
-1. 将远程数据同步到业务表
-2. 写入/更新墓碑记录（`_tombstones` 表）
-3. 更新对等节点同步位置（`_sync_peers` 表）
+> 自定义数据库请参见下方 [DatabaseAdapter 接口](#databaseadapter-接口) 和 [自定义适配器示例](#自定义适配器示例)。
 
-#### 为什么需要 `infraSchemaSQL`？
+#### 内置方言支持
 
-sync-lib 需要 3 张内部表（`_sync_log`、`_sync_peers`、`_tombstones`）。调用 `engine.initSchema()` 时，它会调用 `db.infraSchemaSQL()` 获取 CREATE TABLE DDL。
+sync-lib 内置 **SQLite**、**PostgreSQL** 和 **MySQL** 三种方言。指定 `dialect: 'sqlite'`（或 `'postgresql'` / `'mysql'`）后，以下方法会自动填充到你的适配器上：
 
-不同数据库的 DDL 语法差异：
+- `beginTransaction()` / `commit()` / `rollback()` — 事务控制
+- `upsertSQL(table, columns, keyColumns)` — 冲突感知的 insert/update SQL
+- `infraSchemaSQL()` — 内部表（`_sync_log`、`_sync_peers`、`_tombstones`）的 DDL
+- `triggersSQL(tableName, def)` / `dropTriggersSQL(tableName)` — 自动记录变更的触发器
 
-| | SQLite | PostgreSQL | MySQL |
-|--|--------|------------|-------|
-| 自增 | `AUTOINCREMENT` | `BIGSERIAL` | `AUTO_INCREMENT` |
-| 时间戳默认值 | `datetime('now')` | `NOW()` | `CURRENT_TIMESTAMP` |
-| 字符串类型 | `TEXT` | `TEXT` | `VARCHAR(255)` |
+**如果不指定 dialect（或指定不支持的值），必须自行实现以上所有方法。** 缺失方法会在构造时报错。
 
-如果不实现 `infraSchemaSQL()`，sync-lib 会回退到内置的 SQLite DDL。**SQLite 用户可跳过此方法。PostgreSQL/MySQL 用户必须实现。**
+你也可以在 `db` 适配器上显式定义任何方法来覆盖内置实现 — 你的显式实现始终优先于内置方言。
 
 ### 第 2 步：创建引擎并注册表
 
@@ -110,6 +109,7 @@ import { SyncEngine } from 'sync-lib';
 const engine = new SyncEngine({
     nodeId: 'node-1',
     db,
+    dialect: 'sqlite',   // 或 'postgresql' 或 'mysql'
 
     // 必需回调
     onSendToPeer:    (peerId, msg) => yourTransport.send(peerId, msg),
@@ -130,8 +130,7 @@ engine.registerTable('users', {
 });
 
 engine.initSchema();     // 创建 _sync_log、_sync_peers、_tombstones
-engine.initTriggers();   // 仅 SQLite — 创建自动日志触发器
-                         // PostgreSQL/MySQL 跳过此步，改用 logChange()
+engine.initTriggers();   // 创建同步触发器（方言感知）
 engine.start();          // 启动 Leader 选举
 ```
 
@@ -162,7 +161,7 @@ setInterval(() => engine.tickCleanup(), 3600_000);   // 每 1 小时清理旧日
 
 ### 第 5 步：写入数据
 
-**SQLite**（触发器自动记录变更）：
+指定了 `dialect` 并调用 `initTriggers()` 后，所有数据库的写入方式完全一致 — 触发器自动记录变更：
 
 ```js
 const ts = engine.hlc.tick();
@@ -171,7 +170,7 @@ db.run('INSERT INTO users (user_id, name, _hlc) VALUES (?, ?, ?)',
 engine.notifyLocalWrite();  // 推送到对等节点
 ```
 
-**PostgreSQL / MySQL**（手动调用 logChange）：
+**不使用触发器时**（手动 logChange 备选方案）：
 
 ```js
 import { logChange } from 'sync-lib';
@@ -232,7 +231,11 @@ Leader 通过 `onExecuteProxyRequest` 回调执行请求。
 
 ---
 
-## PostgreSQL 适配器
+## 自定义适配器示例
+
+使用内置方言（`sqlite`、`postgresql`、`mysql`）时，适配器只需 `run/get/all/exec` 四个方法。以下完整示例供参考，适用于需要自定义或使用不支持的数据库的场景。
+
+### PostgreSQL（完整手动适配器）
 
 ```js
 import pg from 'pg';
@@ -291,12 +294,40 @@ const db = {
                 _hlc TEXT NOT NULL, PRIMARY KEY (table_name, row_key))`,
         ];
     },
+
+    // 可选：注入 PG 触发器，使 initTriggers() 自动创建
+    triggersSQL(tableName, def) {
+        const keyExpr = def.keyColumns.map(c => `'${c}', NEW.${c}`).join(', ');
+        const dataExpr = def.dataColumns.map(c => `'${c}', NEW.${c}`).join(', ');
+        return [
+            `CREATE OR REPLACE FUNCTION _sync_trg_${tableName}_fn() RETURNS TRIGGER AS $$
+             BEGIN
+                 INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
+                 VALUES ('${tableName}', TG_OP,
+                         json_build_object(${keyExpr})::text,
+                         CASE WHEN TG_OP = 'DELETE' THEN NULL
+                              ELSE json_build_object(${dataExpr})::text END,
+                         COALESCE(NEW._hlc, OLD._hlc));
+                 RETURN COALESCE(NEW, OLD);
+             END; $$ LANGUAGE plpgsql`,
+            `DROP TRIGGER IF EXISTS _sync_trg_${tableName} ON ${tableName}`,
+            `CREATE TRIGGER _sync_trg_${tableName}
+             AFTER INSERT OR UPDATE OR DELETE ON ${tableName}
+             FOR EACH ROW EXECUTE FUNCTION _sync_trg_${tableName}_fn()`,
+        ];
+    },
+    dropTriggersSQL(tableName) {
+        return [
+            `DROP TRIGGER IF EXISTS _sync_trg_${tableName} ON ${tableName}`,
+            `DROP FUNCTION IF EXISTS _sync_trg_${tableName}_fn`,
+        ];
+    },
 };
 ```
 
 ---
 
-## MySQL 适配器
+### MySQL（完整手动适配器）
 
 ```js
 import mysql from 'mysql2/promise';
@@ -347,6 +378,34 @@ const db = {
                 _hlc VARCHAR(64) NOT NULL, PRIMARY KEY (table_name, row_key(255)))`,
         ];
     },
+
+    // 可选：注入 MySQL 触发器，使 initTriggers() 自动创建
+    triggersSQL(tableName, def) {
+        const keyExpr = def.keyColumns.map(c => `'${c}', NEW.${c}`).join(', ');
+        const dataExpr = def.dataColumns.map(c => `'${c}', NEW.${c}`).join(', ');
+        const delKeyExpr = def.keyColumns.map(c => `'${c}', OLD.${c}`).join(', ');
+        return [
+            `CREATE TRIGGER _sync_trg_${tableName}_insert
+             AFTER INSERT ON ${tableName} FOR EACH ROW
+             INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
+             VALUES ('${tableName}', 'INSERT', JSON_OBJECT(${keyExpr}), JSON_OBJECT(${dataExpr}), NEW._hlc)`,
+            `CREATE TRIGGER _sync_trg_${tableName}_update
+             AFTER UPDATE ON ${tableName} FOR EACH ROW
+             INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
+             VALUES ('${tableName}', 'UPDATE', JSON_OBJECT(${keyExpr}), JSON_OBJECT(${dataExpr}), NEW._hlc)`,
+            `CREATE TRIGGER _sync_trg_${tableName}_delete
+             AFTER DELETE ON ${tableName} FOR EACH ROW
+             INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
+             VALUES ('${tableName}', 'DELETE', JSON_OBJECT(${delKeyExpr}), NULL, OLD._hlc)`,
+        ];
+    },
+    dropTriggersSQL(tableName) {
+        return [
+            `DROP TRIGGER IF EXISTS _sync_trg_${tableName}_insert`,
+            `DROP TRIGGER IF EXISTS _sync_trg_${tableName}_update`,
+            `DROP TRIGGER IF EXISTS _sync_trg_${tableName}_delete`,
+        ];
+    },
 };
 ```
 
@@ -385,14 +444,17 @@ const db = {
 ### 独立工具函数
 
 ```js
-import { HLC, logChange, getInfraSchemaSQL, getTriggersSQL } from 'sync-lib';
+import { HLC, DIALECTS, applyDialect, logChange, getInfraSchemaSQL, getTriggersSQL } from 'sync-lib';
 ```
 
 | 导出 | 说明 |
 |------|------|
 | `HLC` | 混合逻辑时钟类 |
 | `LeaderElection` | Leader 选举状态机 |
-| `logChange(db, table, op, key, data, hlc)` | 手动记录变更（用于非 SQLite 数据库） |
+| `DIALECTS` | 内置方言定义（sqlite、postgresql、mysql） |
+| `applyDialect(db, name)` | 将方言方法应用到 db 适配器 |
+| `validateDialectMethods(db)` | 校验 db 是否具备所有必需的方言方法 |
+| `logChange(db, table, op, key, data, hlc)` | 手动记录变更（触发器的替代方案） |
 | `getInfraSchemaSQL()` | 内置 SQLite DDL（基础设施表） |
 | `getTriggersSQL(table, def)` | 生成 SQLite 同步触发器 |
 | `applyEntries(db, entries, hlc, registry)` | 幂等地应用远程条目 |
@@ -401,26 +463,31 @@ import { HLC, logChange, getInfraSchemaSQL, getTriggersSQL } from 'sync-lib';
 
 ## DatabaseAdapter 接口
 
-每个适配器必须实现以下方法：
-
 ```
 ┌───────────────────────────────────────────────────────────────┐
+│  始终必须实现：                                                │
+│                                                               │
 │  db.run(sql, params)           → { changes: number }          │
 │  db.get(sql, params)           → Object | null                │
 │  db.all(sql, params)           → Object[]                     │
 │  db.exec(sql)                  → void                         │
 │                                                               │
+├───────────────────────────────────────────────────────────────┤
+│  由 dialect 自动填充（或手动实现）：                            │
+│                                                               │
 │  db.beginTransaction()         → void                         │
 │  db.commit()                   → void                         │
 │  db.rollback()                 → void                         │
-│                                                               │
 │  db.upsertSQL(table, cols, keyColumns) → string               │
-│                                                               │
-│  db.infraSchemaSQL()           → string[]    （可选）          │
+│  db.infraSchemaSQL()           → string[]                     │
+│  db.triggersSQL(table, def)    → string[]                     │
+│  db.dropTriggersSQL(table)     → string[]                     │
 └───────────────────────────────────────────────────────────────┘
 ```
 
-SQL 使用 `?` 占位符。如果你的数据库使用 `$1/$2`（如 PostgreSQL），请在适配器内部转换。
+指定 `dialect: 'sqlite' | 'postgresql' | 'mysql'` 后，下面 7 个方法自动填充。不指定 dialect 则必须全部自行实现。
+
+SQL 使用 `?` 占位符。如果你的数据库使用 `$1/$2`（如 PostgreSQL），请在 `run/get/all` 内部转换。
 
 ---
 
@@ -446,7 +513,8 @@ sync-lib/
 ├── hlc.js                ← 混合逻辑时钟（纯算法）
 ├── leader-election.js    ← Raft 简化版选举状态机
 ├── sync-protocol.js      ← 消息编解码 + 幂等数据应用
-└── sync-engine.js        ← 主引擎（组合以上模块）
+├── sync-engine.js        ← 主引擎（组合以上模块）
+└── dialects.js           ← 内置 SQL 方言（SQLite/PG/MySQL）
 ```
 
 **设计原则**：

package/dialects.js

@@ -0,0 +1,286 @@
+/**
+ * 内置 SQL 方言定义
+ *
+ * 支持 sqlite、postgresql、mysql 三种方言。
+ * 每种方言提供以下 DatabaseAdapter 方法的默认实现：
+ *   - beginTransaction / commit / rollback（通过 SQL 字符串 + db.exec）
+ *   - upsertSQL
+ *   - infraSchemaSQL
+ *   - triggersSQL / dropTriggersSQL
+ *
+ * 使用方式：
+ *   new SyncEngine({ dialect: 'sqlite', db: { run, get, all, exec }, ... })
+ *
+ * 指定 dialect 后，db 上缺失的方言方法由内置实现自动填充。
+ * db 上已有的方法优先级更高（不会被覆盖）。
+ *
+ * 若不指定 dialect 或指定不认识的值，所有方言方法必须由 db 自行实现，否则报错。
+ */
+
+import { getInfraSchemaSQL, getTriggersSQL, dropTriggersSQL } from './sync-protocol.js';
+
+// ═══════════════════════════════════════════════════
+//  SQLite
+// ═══════════════════════════════════════════════════
+
+const SQLITE = {
+    beginTransactionSQL: 'BEGIN IMMEDIATE',
+    commitSQL: 'COMMIT',
+    rollbackSQL: 'ROLLBACK',
+
+    upsertSQL(table, columns, _keyColumns) {
+        const cols = columns.join(', ');
+        const ph = columns.map(() => '?').join(', ');
+        return `INSERT OR REPLACE INTO ${table} (${cols}) VALUES (${ph})`;
+    },
+
+    infraSchemaSQL: getInfraSchemaSQL,
+    triggersSQL: getTriggersSQL,
+    dropTriggersSQL,
+};
+
+// ═══════════════════════════════════════════════════
+//  PostgreSQL
+// ═══════════════════════════════════════════════════
+
+const POSTGRESQL = {
+    beginTransactionSQL: 'BEGIN',
+    commitSQL: 'COMMIT',
+    rollbackSQL: 'ROLLBACK',
+
+    upsertSQL(table, columns, keyColumns) {
+        const cols = columns.join(', ');
+        const ph = columns.map(() => '?').join(', ');
+        const keys = keyColumns.join(', ');
+        const updates = columns
+            .filter(c => !keyColumns.includes(c))
+            .map(c => `${c} = EXCLUDED.${c}`);
+        return updates.length === 0
+            ? `INSERT INTO ${table} (${cols}) VALUES (${ph}) ON CONFLICT (${keys}) DO NOTHING`
+            : `INSERT INTO ${table} (${cols}) VALUES (${ph}) ON CONFLICT (${keys}) DO UPDATE SET ${updates.join(', ')}`;
+    },
+
+    infraSchemaSQL() {
+        return [
+            `CREATE TABLE IF NOT EXISTS _sync_log (
+                id BIGSERIAL PRIMARY KEY,
+                table_name TEXT NOT NULL,
+                operation TEXT NOT NULL,
+                row_key TEXT NOT NULL,
+                row_data TEXT,
+                _hlc TEXT NOT NULL,
+                created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+            )`,
+            `CREATE INDEX IF NOT EXISTS idx_sync_log_id ON _sync_log (id)`,
+            `CREATE TABLE IF NOT EXISTS _sync_peers (
+                peer_key TEXT PRIMARY KEY,
+                last_sync_id BIGINT DEFAULT 0,
+                last_sync_at TIMESTAMPTZ
+            )`,
+            `CREATE TABLE IF NOT EXISTS _tombstones (
+                table_name TEXT NOT NULL,
+                row_key TEXT NOT NULL,
+                _hlc TEXT NOT NULL,
+                PRIMARY KEY (table_name, row_key)
+            )`,
+        ];
+    },
+
+    triggersSQL(tableName, def) {
+        const blobSet = new Set(def.blobColumns || []);
+
+        const keyExprNew = def.keyColumns.map(c => `'${c}', NEW.${c}`).join(', ');
+        const keyExprOld = def.keyColumns.map(c => `'${c}', OLD.${c}`).join(', ');
+
+        const dataExpr = def.dataColumns.map(c => {
+            if (blobSet.has(c)) return `'${c}', encode(NEW.${c}, 'hex')`;
+            return `'${c}', NEW.${c}`;
+        }).join(', ');
+
+        return [
+            `CREATE OR REPLACE FUNCTION _sync_trg_${tableName}_fn() RETURNS TRIGGER AS $$
+BEGIN
+    IF TG_OP = 'DELETE' THEN
+        INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
+        VALUES ('${tableName}', 'DELETE', json_build_object(${keyExprOld})::text, NULL, OLD._hlc);
+        RETURN OLD;
+    ELSE
+        INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
+        VALUES ('${tableName}', TG_OP, json_build_object(${keyExprNew})::text, json_build_object(${dataExpr})::text, NEW._hlc);
+        RETURN NEW;
+    END IF;
+END; $$ LANGUAGE plpgsql`,
+            `DROP TRIGGER IF EXISTS _sync_trg_${tableName} ON ${tableName}`,
+            `CREATE TRIGGER _sync_trg_${tableName}
+AFTER INSERT OR UPDATE OR DELETE ON ${tableName}
+FOR EACH ROW EXECUTE FUNCTION _sync_trg_${tableName}_fn()`,
+        ];
+    },
+
+    dropTriggersSQL(tableName) {
+        return [
+            `DROP TRIGGER IF EXISTS _sync_trg_${tableName} ON ${tableName}`,
+            `DROP FUNCTION IF EXISTS _sync_trg_${tableName}_fn`,
+        ];
+    },
+};
+
+// ═══════════════════════════════════════════════════
+//  MySQL
+// ═══════════════════════════════════════════════════
+
+const MYSQL = {
+    beginTransactionSQL: 'START TRANSACTION',
+    commitSQL: 'COMMIT',
+    rollbackSQL: 'ROLLBACK',
+
+    upsertSQL(table, columns, keyColumns) {
+        const cols = columns.join(', ');
+        const ph = columns.map(() => '?').join(', ');
+        const updates = columns
+            .filter(c => !keyColumns.includes(c))
+            .map(c => `${c} = VALUES(${c})`);
+        return updates.length === 0
+            ? `INSERT IGNORE INTO ${table} (${cols}) VALUES (${ph})`
+            : `INSERT INTO ${table} (${cols}) VALUES (${ph}) ON DUPLICATE KEY UPDATE ${updates.join(', ')}`;
+    },
+
+    infraSchemaSQL() {
+        return [
+            `CREATE TABLE IF NOT EXISTS _sync_log (
+                id BIGINT AUTO_INCREMENT PRIMARY KEY,
+                table_name VARCHAR(255) NOT NULL,
+                operation VARCHAR(10) NOT NULL,
+                row_key TEXT NOT NULL,
+                row_data LONGTEXT,
+                _hlc VARCHAR(64) NOT NULL,
+                created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
+            )`,
+            `CREATE TABLE IF NOT EXISTS _sync_peers (
+                peer_key VARCHAR(255) PRIMARY KEY,
+                last_sync_id BIGINT DEFAULT 0,
+                last_sync_at DATETIME
+            )`,
+            `CREATE TABLE IF NOT EXISTS _tombstones (
+                table_name VARCHAR(255) NOT NULL,
+                row_key VARCHAR(1024) NOT NULL,
+                _hlc VARCHAR(64) NOT NULL,
+                PRIMARY KEY (table_name, row_key(255))
+            )`,
+        ];
+    },
+
+    triggersSQL(tableName, def) {
+        const blobSet = new Set(def.blobColumns || []);
+
+        const keyExpr = (ref) => def.keyColumns.map(c => `'${c}', ${ref}.${c}`).join(', ');
+        const dataExpr = (ref) => def.dataColumns.map(c => {
+            if (blobSet.has(c)) return `'${c}', HEX(${ref}.${c})`;
+            return `'${c}', ${ref}.${c}`;
+        }).join(', ');
+
+        return [
+            `CREATE TRIGGER _sync_trg_${tableName}_insert
+AFTER INSERT ON ${tableName} FOR EACH ROW
+INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
+VALUES ('${tableName}', 'INSERT', JSON_OBJECT(${keyExpr('NEW')}), JSON_OBJECT(${dataExpr('NEW')}), NEW._hlc)`,
+            `CREATE TRIGGER _sync_trg_${tableName}_update
+AFTER UPDATE ON ${tableName} FOR EACH ROW
+INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
+VALUES ('${tableName}', 'UPDATE', JSON_OBJECT(${keyExpr('NEW')}), JSON_OBJECT(${dataExpr('NEW')}), NEW._hlc)`,
+            `CREATE TRIGGER _sync_trg_${tableName}_delete
+AFTER DELETE ON ${tableName} FOR EACH ROW
+INSERT INTO _sync_log (table_name, operation, row_key, row_data, _hlc)
+VALUES ('${tableName}', 'DELETE', JSON_OBJECT(${keyExpr('OLD')}), NULL, OLD._hlc)`,
+        ];
+    },
+
+    dropTriggersSQL(tableName) {
+        return [
+            `DROP TRIGGER IF EXISTS _sync_trg_${tableName}_insert`,
+            `DROP TRIGGER IF EXISTS _sync_trg_${tableName}_update`,
+            `DROP TRIGGER IF EXISTS _sync_trg_${tableName}_delete`,
+        ];
+    },
+};
+
+// ═══════════════════════════════════════════════════
+//  公共接口
+// ═══════════════════════════════════════════════════
+
+/** 所有内置方言 */
+export const DIALECTS = {
+    sqlite: SQLITE,
+    postgresql: POSTGRESQL,
+    postgres: POSTGRESQL,   // 别名
+    pg: POSTGRESQL,         // 别名
+    mysql: MYSQL,
+};
+
+/** 需要方言提供的全部方法名 */
+const DIALECT_METHODS = [
+    'beginTransaction', 'commit', 'rollback',
+    'upsertSQL', 'infraSchemaSQL',
+    'triggersSQL', 'dropTriggersSQL',
+];
+
+/**
+ * 将内置方言应用到 db 适配器。
+ *
+ * - 已有的方法不覆盖（用户显式注入的优先级最高）。
+ * - beginTransaction / commit / rollback 通过 db.exec(sql) 桥接。
+ *
+ * @param {object} db - DatabaseAdapter 实例
+ * @param {string} dialectName - 方言名称
+ */
+export function applyDialect(db, dialectName) {
+    const dialect = DIALECTS[dialectName];
+    if (!dialect) {
+        const supported = Object.keys(DIALECTS).filter(k => !['postgres', 'pg'].includes(k)).join(', ');
+        throw new Error(
+            `Unknown dialect "${dialectName}". Supported: ${supported}. ` +
+            `Or omit dialect and implement all adapter methods manually.`
+        );
+    }
+
+    // 事务控制：通过 SQL 字符串 + db.exec() 桥接
+    if (typeof db.beginTransaction !== 'function') {
+        db.beginTransaction = () => db.exec(dialect.beginTransactionSQL);
+    }
+    if (typeof db.commit !== 'function') {
+        db.commit = () => db.exec(dialect.commitSQL);
+    }
+    if (typeof db.rollback !== 'function') {
+        db.rollback = () => db.exec(dialect.rollbackSQL);
+    }
+
+    // 函数方法：直接挂载
+    if (typeof db.upsertSQL !== 'function') {
+        db.upsertSQL = dialect.upsertSQL;
+    }
+    if (typeof db.infraSchemaSQL !== 'function') {
+        db.infraSchemaSQL = dialect.infraSchemaSQL;
+    }
+    if (typeof db.triggersSQL !== 'function') {
+        db.triggersSQL = dialect.triggersSQL;
+    }
+    if (typeof db.dropTriggersSQL !== 'function') {
+        db.dropTriggersSQL = dialect.dropTriggersSQL;
+    }
+}
+
+/**
+ * 校验 db 适配器是否具备所有必需的方言方法。
+ * 如果缺失任何方法，抛出包含缺失列表的错误。
+ *
+ * @param {object} db - DatabaseAdapter 实例
+ */
+export function validateDialectMethods(db) {
+    const missing = DIALECT_METHODS.filter(m => typeof db[m] !== 'function');
+    if (missing.length > 0) {
+        throw new Error(
+            `DatabaseAdapter missing required methods: ${missing.join(', ')}. ` +
+            `Either specify a dialect (e.g. dialect: 'sqlite') or implement these methods on your db adapter.`
+        );
+    }
+}

package/index.js

@@ -55,7 +55,7 @@
  *
  *  // 4. 初始化 Schema & 触发器
  *  engine.initSchema();     // 创建 _sync_log, _sync_peers, _tombstones
- *  engine.initTriggers();   // 创建 SQLite 触发器（PostgreSQL 等请跳过，改用 logChange()）
+ *  engine.initTriggers();   // 创建同步触发器（由 dialect 自动选择对应方言）
  *  engine.start();
  *
  *  // 5. 外部传输层对接
@@ -72,7 +72,7 @@
  *  db.run('INSERT INTO users ...');
  *  engine.notifyLocalWrite();
  *
- *  // 8. 非 SQLite 数据库：手动记录变更（替代触发器）
+ *  // 8. 未使用触发器时的备选方案：手动记录变更
  *  db.run('INSERT INTO users ...');
  *  engine.logChange('users', 'INSERT', { user_id: 'u1' }, { user_id: 'u1', name: 'Alice', ... });
  *  engine.notifyLocalWrite();
@@ -116,6 +116,9 @@ export { SyncEngine } from './sync-engine.js';
 export { HLC } from './hlc.js';
 export { LeaderElection } from './leader-election.js';
 
+// 内置方言
+export { DIALECTS, applyDialect, validateDialectMethods } from './dialects.js';
+
 // 协议层工具（高级用途：自定义消息处理）
 export {
     // 消息构造

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raft-hlc-sync-protocol/raft-sync-lib",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "pure javascript raft and hlc sync protocol",
   "keywords": [
     "raft",
@@ -13,7 +13,7 @@
   ],
   "license": "MIT",
   "author": "xnet",
-  "type": "commonjs",
+  "type": "module",
   "main": "index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"

package/sync-engine.js

@@ -91,7 +91,7 @@
  *
  *  // 3. 初始化
  *  engine.initSchema();    // 创建 _sync_log 等基础设施表
- *  engine.initTriggers();  // 创建 SQLite 触发器（可选，也可用 logChange()）
+ *  engine.initTriggers();  // 创建同步触发器（由 dialect 决定方言）
  *  engine.start();         // 启动 Leader Election
  *
  *  // 4. 外部传输层事件
@@ -113,6 +113,7 @@
 
 import { HLC } from './hlc.js';
 import { LeaderElection } from './leader-election.js';
+import { applyDialect, validateDialectMethods } from './dialects.js';
 import {
     makeHandshake,
     makeSync,
@@ -183,6 +184,11 @@ export class SyncEngine {
      * @param {function(string, Error): void} [options.onError] - 错误通知
      * @param {function(object): Promise<object>} [options.onExecuteProxyRequest] - 代理请求执行
      *
+     * ── 方言 ──
+     * @param {string} [options.dialect] - 数据库方言：'sqlite' | 'postgresql' | 'mysql'
+     *   指定后自动填充 db 上缺失的方言方法（beginTransaction/commit/rollback/upsertSQL/infraSchemaSQL/triggersSQL/dropTriggersSQL）。
+     *   不指定时所有方言方法必须由 db 自行实现，否则报错。
+     *
      * ── 可选配置 ──
      * @param {number}   [options.numShards=16]            - 虚拟分片数
      * @param {number}   [options.syncBatchSize=500]       - 每批同步最大条目数
@@ -200,6 +206,12 @@ export class SyncEngine {
         this.db = options.db;
         this.hlc = new HLC(options.nodeId);
 
+        // ===== 方言处理 =====
+        if (options.dialect) {
+            applyDialect(this.db, options.dialect);
+        }
+        validateDialectMethods(this.db);
+
         // ===== 必须回调 =====
         this._onSendToPeer = options.onSendToPeer;
         this._onClosePeer = options.onClosePeer;
@@ -294,18 +306,18 @@ export class SyncEngine {
 
     /** 创建同步基础设施表（_sync_log, _sync_peers, _tombstones） */
     initSchema() {
-        const sqls = typeof this.db.infraSchemaSQL === 'function'
-            ? this.db.infraSchemaSQL()
-            : getInfraSchemaSQL();
-        for (const sql of sqls) {
+        for (const sql of this.db.infraSchemaSQL()) {
             this.db.exec(sql);
         }
     }
 
-    /** 为所有已注册表创建 SQLite 同步触发器（非 SQLite 请跳过，改用 logChange()） */
+    /**
+     * 为所有已注册表创建同步触发器。
+     * 触发器 SQL 由 db.triggersSQL(tableName, def) 提供（内置方言或外部注入）。
+     */
     initTriggers() {
         for (const [tableName, def] of this._tableRegistry) {
-            for (const sql of getTriggersSQL(tableName, def)) {
+            for (const sql of this.db.triggersSQL(tableName, def)) {
                 this.db.exec(sql);
             }
         }
@@ -314,7 +326,7 @@ export class SyncEngine {
     /** 删除所有已注册表的同步触发器 */
     dropTriggers() {
         for (const tableName of this._tableRegistry.keys()) {
-            for (const sql of dropTriggersSQL(tableName)) {
+            for (const sql of this.db.dropTriggersSQL(tableName)) {
                 this.db.exec(sql);
             }
         }

package/sync-protocol.js

@@ -44,6 +44,18 @@
  *     返回同步基础设施表的 DDL 语句数组。
  *     不实现则由 sync-lib 提供内置 SQLite DDL 作为降级。
  *
+ *  ── 触发器（可选注入）──
+ *
+ *   db.triggersSQL?(tableName, def)  → string[]
+ *     返回指定表的同步触发器 DDL 语句数组。
+ *     不实现则由 sync-lib 提供内置 SQLite 触发器。
+ *     PG / MySQL 用户可注入各自方言的触发器，
+ *     从而使用 initTriggers() 自动记录变更，无需手动调用 logChange()。
+ *
+ *   db.dropTriggersSQL?(tableName)   → string[]
+ *     返回删除指定表同步触发器的 SQL 语句数组。
+ *     不实现则由 sync-lib 提供内置 SQLite 版本。
+ *
  * ═══════════════════════════════════════════════════════
  *  表定义 TableDef（通过 SyncEngine.registerTable 注册）：
  * ═══════════════════════════════════════════════════════