@fett/sql-translator 0.0.1-beta

package/README.md

@@ -0,0 +1,191 @@
+# @fett/sql-translator
+
+以 SQL 为统一查询语言的数据库兼容层。支持 **MySQL 5.7 / 8.x / PostgreSQL / SQLite / MongoDB**（MongoDB 为 SQL→Query 翻译），双运行时 **Node ≥ 22.5 / Bun ≥ 1.1**，内置连接池、任务队列（多线程）、结构 JSON 检出。
+
+> 状态：**全部完成**（双运行时 Node ≥ 22.5 / Bun ≥ 1.1 全部 202 用例通过）：SQLite / MySQL 5.7/8 / **MariaDB** / PostgreSQL / MongoDB（含**副本集事务**）驱动 + 连接池 + 任务队列（多线程）+ 事务 + **查询结果缓存** + **selectOnly 只读模式** + **耗时返回** + 结构 JSON 检出 + 静态数据源 + CI。
+
+## 快速开始
+
+```ts
+import { createClient } from '@fett/sql-translator';
+
+// 唯一入参：连接配置
+const db = createClient({ type: 'sqlite', database: ':memory:' });
+
+await db.testConnection();          // { success, message }
+await db.execute(
+  'CREATE TABLE users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER)',
+);
+await db.execute('INSERT INTO users (name, age) VALUES (?, ?)', ['alice', 30]);
+
+const result = await db.query('SELECT * FROM users WHERE age > ?', [18]);
+// { rows: [...], fields: [...], total: 1, offset: 0, limit: 100, duration: 3.42 }
+// duration：执行耗时（ms），client.run / query / execute / 函数式 runSql 均返回
+
+const schema = await db.getTableSchema('users');  // 结构 JSON
+const json = await db.exportSchemaAsJson();       // 全库结构 → JSON 字符串
+
+await db.destroy();  // 释放引用（共享池引用归零后回收）
+```
+
+## MySQL（5.7 / 8.x 双版本）
+
+```ts
+const db = createClient({
+  type: 'mysql',
+  host: '127.0.0.1', port: 3306,
+  user: 'root', password: '...', database: 'test',
+  version: 'auto',          // '5' | '8' | 'auto'（auto = SELECT VERSION() 探测）
+  dml: { requireWhereForUpdateDelete: true },
+});
+
+await db.query('SELECT * FROM users WHERE age > ?', [18]);   // 自动分页包装
+await db.execute('UPDATE users SET age = ? WHERE id = ?', [31, 1]);
+const schema = await db.getTableSchema('users');             // 结构 JSON
+```
+
+- 分页包装按版本能力矩阵自动选择：MySQL 8 用 CTE，5.7 用派生表
+- 无 WHERE 的 UPDATE/DELETE 默认拦截（DML_BLOCKED）
+
+## MongoDB（SQL → Query / DML 翻译）
+
+```ts
+const db = createClient({ type: 'mongodb', uri: 'mongodb://127.0.0.1:27017', database: 'test' });
+
+// SQL → find / aggregate（@synatic/noql）
+const res = await db.query('SELECT * FROM users WHERE age > ?', [18]);
+await db.query('SELECT status, COUNT(*) AS n FROM orders GROUP BY status');
+
+// SQL → insert/update/delete（node-sql-parser + noql WHERE 翻译）
+await db.execute("INSERT INTO users (name, age) VALUES ('dave', 40)");
+await db.execute("UPDATE users SET age = age + 1 WHERE name = 'dave'");
+await db.execute("DELETE FROM users WHERE name = 'dave'");
+
+// 结构检出：采样（嵌套对象/数组/ObjectId），长任务可取消
+const schema = await db.getTableSchema('users');
+```
+
+- WHERE 条件翻译与 SELECT 路径一致（=, >, <, LIKE, IN, BETWEEN, AND/OR, IS NULL）
+- SET 支持 `$set` 与算术自增 `$inc`；无 WHERE 的 UPDATE/DELETE 默认拦截
+- 结构检出为长任务（分批采样 + 进度 + 取消 + TTL 缓存）
+
+## 本地测试数据库（docker compose）
+
+```bash
+pnpm db:up      # 启动 mysql5(33061) / mysql8(33062) / postgres(54321) / mongodb(27017)
+pnpm db:init    # 初始化种子数据（MySQL 走 utf8mb4 脚本，Mongo 注入）
+
+# 跑全部集成测试（含 4 种数据库）
+SQLENGINE_TEST_MYSQL5_HOST=127.0.0.1 SQLENGINE_TEST_MYSQL5_PORT=33061 \
+SQLENGINE_TEST_MYSQL5_USER=root SQLENGINE_TEST_MYSQL5_PASSWORD=root \
+SQLENGINE_TEST_MYSQL8_HOST=127.0.0.1 SQLENGINE_TEST_MYSQL8_PORT=33062 \
+SQLENGINE_TEST_MYSQL8_USER=root SQLENGINE_TEST_MYSQL8_PASSWORD=root \
+SQLENGINE_TEST_PG_HOST=127.0.0.1 SQLENGINE_TEST_PG_PORT=54321 \
+SQLENGINE_TEST_MONGO_URI=mongodb://127.0.0.1:27017 \
+pnpm test
+```
+
+> 国内网络镜像慢时：`MYSQL5_IMAGE=docker.m.daocloud.io/library/mysql:5.7 MYSQL8_IMAGE=docker.m.daocloud.io/library/mysql:8.0 MONGO_IMAGE=docker.m.daocloud.io/library/mongo:7 pnpm db:up`
+> 说明：bson@7.3.2 已打补丁（Bun 下 node:v8 兼容），见 `patches/` + package.json `pnpm.patchedDependencies`
+
+## 多数据源平台
+
+```ts
+import { createClientManager } from '@fett/sql-translator';
+
+const manager = createClientManager({ maxClients: 200, lru: { maxIdlePools: 50 } });
+
+async function handleSql(dsConfig, sql, params) {
+  const db = manager.getClient(dsConfig);   // 命中共享池，零成本
+  return db.query(sql, params);
+}
+
+await manager.invalidate(dsId);   // 数据源配置更新：销毁旧池
+await manager.release(dsId);      // 数据源删除：释放引用
+await manager.destroyAll();       // 应用退出
+```
+
+## 函数式 API
+
+```ts
+import { runSql, getTableSchema, exportSchemaAsJson } from '@fett/sql-translator';
+
+const result = await runSql(dsConfig, { sql, offset: 0, limit: 10 });
+const schema = await exportSchemaAsJson(dsConfig);
+```
+
+## 任务队列（多线程）
+
+```ts
+const db = createClient(config);
+
+// 进程内异步并发（I/O 密集）
+await db.tasks.enqueue(() => fetch('...'));
+
+// CPU 密集任务 offload 到 worker 线程（需可序列化规格）
+await db.tasks.enqueue({ module: '/abs/path/to/fn.mjs', fn: 'heavyCompute', args: [1e7] }, { worker: true });
+
+// 长任务：进度 + 取消
+const task = db.getAllTableSchemas({ onProgress: (p) => console.log(p) });
+await task.promise;
+```
+
+## 事务
+
+```ts
+await db.withTransaction(async (tx) => {
+  await tx.execute('UPDATE accounts SET balance = balance - 100 WHERE id = 1');
+  await tx.execute('UPDATE accounts SET balance = balance + 100 WHERE id = 2');
+  // fn 抛错自动回滚；也可手动 tx.commit() / tx.rollback()
+});
+```
+SQLite/PG/MySQL/MariaDB 真事务；MongoDB 走 session（**需副本集**——docker compose 提供单节点副本集 `mongo-rs`(27018)，`node scripts/init-mongo-rs.mjs` 初始化）。
+
+## 查询结果缓存
+
+```ts
+const db = createClient({ type: 'sqlite', database: ':memory:', cache: { enabled: true, ttlMs: 60000, maxEntries: 1000 } });
+// 幂等 SELECT 结果缓存（TTL + LRU）；DML/DDL 后自动失效
+```
+仅缓存 SELECT；写操作后本 client 缓存整库失效。
+
+## selectOnly 只读模式
+
+```ts
+const db = createClient({ type: 'sqlite', database: ':memory:', selectOnly: true });
+await db.query('SELECT * FROM t');          // ✅
+await db.execute('UPDATE t SET v = 1');     // ❌ READ_ONLY
+await db.withTransaction(async (tx) => {}); // ❌ READ_ONLY
+```
+只读模式下仅允许 SELECT，DML/DDL/事务一律拒绝（错误码 `READ_ONLY`）。
+
+## MariaDB
+
+```ts
+const db = createClient({ type: 'mariadb', host, port: 3306, user, password, database, version: 'auto' });
+// MySQL 协议兼容；能力矩阵独立（10.2+ CTE → 分页走 CTE 包装；慢查询兜底用 max_statement_time）
+```
+
+## 静态数据源（JSON/CSV/Excel → SQLite）
+
+```ts
+import { createStaticSqlitePool, importDataToSqlite, runStaticSql } from '@fett/sql-engine';
+
+const pool = await createStaticSqlitePool({ type: 'sqlite', database: ':memory:' });
+await importDataToSqlite(pool, 'json_data_1_1', [{ id: 1, name: 'alice' }]);
+
+// 用户 SQL 用逻辑表名，自动映射为 SQLite 物理表名
+const res = await runStaticSql(
+  pool,
+  { sql: 'SELECT * FROM 用户表 WHERE price > ?', params: [5] },
+  [{ name: '用户表', datasourceName: '数据源A', sqliteTableName: 'json_data_1_1' }],
+);
+```
+
+## CI
+
+GitHub Actions（.github/workflows/test.yml）：Node + Bun 双运行时，docker 起 4 种数据库跑全量集成测试。
+
+## 文档
+
+架构设计见 [.docs/architecture.md](.docs/architecture.md)。

package/lib/client/client.d.ts

@@ -0,0 +1,59 @@
+import type { ConnectionConfig, SchemaOptions } from '../types/config.js';
+import { type ExecResult, type Field, type QueryResult, type RunSqlRequest, type TestResult, type WriteResult } from '../types/result.js';
+import type { TableSchema } from '../types/schema.js';
+import type { IntrospectTask } from '../types/task.js';
+import type { TaskQueue } from '../types/queue.js';
+import type { TransactionHandle } from '../types/transaction.js';
+import type { PoolRegistry } from './registry.js';
+export declare class DbClient {
+    readonly config: ConnectionConfig;
+    readonly fingerprint: string;
+    /** 任务队列（多线程） */
+    readonly tasks: TaskQueue;
+    private registry;
+    private driverCache;
+    private handlePromise;
+    private destroyed;
+    private queryCache;
+    constructor(registry: PoolRegistry, config: ConnectionConfig);
+    private get driver();
+    private getHandle;
+    /** 连接测试（一次性连接，不入池） */
+    testConnection(): Promise<TestResult>;
+    /** 池内探活：失败触发池重建 */
+    ping(): Promise<void>;
+    /** 释放引用（引用归零且空闲超限时池被回收）；不是「立即销毁共享池」 */
+    destroy(): Promise<void>;
+    /** 完整执行入口（SELECT → QueryResult，DML → WriteResult）
+     * dml 选项按本 client 配置注入（池共享时 handle 配置不可靠）
+     * 查询结果缓存：仅幂等 SELECT；写操作（DML/DDL）后整库失效
+     * selectOnly 只读模式：拒绝一切非 SELECT 语句
+     * 返回结果统一携带 duration（执行耗时 ms，含缓存命中） */
+    run(request: RunSqlRequest): Promise<ExecResult>;
+    /** selectOnly 只读模式护栏：拒绝非 SELECT 语句 */
+    private assertWritable;
+    private getQueryCache;
+    /** SELECT 查询 */
+    query<T = any>(sql: string, params?: unknown[]): Promise<QueryResult>;
+    /** 写操作：DML（INSERT/UPDATE/DELETE）+ DDL（CREATE/ALTER/DROP 透传） */
+    execute(sql: string, params?: unknown[]): Promise<WriteResult>;
+    /** 透传原始驱动结果（不包装）——M2 提供方言原生透传 */
+    raw(sql: string, params?: unknown[]): Promise<unknown>;
+    getTables(): Promise<string[]>;
+    getTableDDL(table: string): Promise<string>;
+    getColumns(table: string): Promise<Field[]>;
+    getRowsCount(table: string, whereClause?: string, params?: unknown[]): Promise<number>;
+    getPreviewRows(table: string, offset?: number, limit?: number, whereClause?: string): Promise<any[]>;
+    /** 单表结构 JSON 检出 */
+    getTableSchema(table: string, opts?: SchemaOptions): Promise<TableSchema>;
+    /** 全库批量结构导出（长任务：进度/取消）
+     * 引用语义：client 持有池引用直到 destroy()，任务期间不额外计 ref */
+    getAllTableSchemas(opts?: SchemaOptions): IntrospectTask<TableSchema[]>;
+    /** 全库结构 → JSON 字符串 */
+    exportSchemaAsJson(opts?: SchemaOptions): Promise<string>;
+    /** 事务：fn 内所有查询在同一事务/连接内执行；fn 抛错自动回滚 */
+    withTransaction<T>(fn: (tx: TransactionHandle) => Promise<T>): Promise<T>;
+}
+/** 判断 SQL 是否为写操作（供上层语义判断） */
+export declare function isWriteSql(sql: string): boolean;
+//# sourceMappingURL=client.d.ts.map

package/lib/client/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client/client.ts"],"names":[],"mappings":"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"}

package/lib/client/client.js

@@ -0,0 +1,201 @@
+/**
+ * DbClient：绑定 config 的极简 API
+ * 外部唯一入口：createClient(config)
+ */
+import { SqlEngineError } from '../errors.js';
+import { configKey } from '../core/config.js';
+import { TtlCache, queryCacheKey } from '../core/cache.js';
+import { getDriver } from '../driver/registry.js';
+import { roundDuration, } from '../types/result.js';
+import { wrapTask } from '../types/task.js';
+import { TaskQueueImpl } from '../core/task-queue.js';
+import { detectStatementType } from '../core/sql/statement.js';
+import { normalizeSql } from '../core/sql/normalize.js';
+export class DbClient {
+    config;
+    fingerprint;
+    /** 任务队列（多线程） */
+    tasks;
+    registry;
+    driverCache = null;
+    handlePromise = null;
+    destroyed = false;
+    queryCache = null;
+    constructor(registry, config) {
+        this.registry = registry;
+        this.config = config;
+        this.fingerprint = configKey(config);
+        // driver 懒加载：createClient 不抛 UNSUPPORTED_DIALECT，首次操作才校验
+        this.tasks = new TaskQueueImpl(config.queue ?? {});
+    }
+    get driver() {
+        this.driverCache ??= getDriver(this.config.type);
+        return this.driverCache;
+    }
+    // ==================== 连接生命周期 ====================
+    getHandle() {
+        if (this.destroyed) {
+            return Promise.reject(new SqlEngineError('CONNECTION_FAILED', 'client 已销毁（destroy 后不可再使用）'));
+        }
+        this.handlePromise ??= this.registry.getPool(this.config);
+        return this.handlePromise;
+    }
+    /** 连接测试（一次性连接，不入池） */
+    testConnection() {
+        return this.driver.testConnection(this.config);
+    }
+    /** 池内探活：失败触发池重建 */
+    async ping() {
+        const handle = await this.getHandle();
+        try {
+            await handle.ping();
+        }
+        catch (err) {
+            // 探活失败 → 销毁并重建池
+            await this.registry.invalidate(this.fingerprint).catch(() => undefined);
+            this.handlePromise = null;
+            throw err;
+        }
+    }
+    /** 释放引用（引用归零且空闲超限时池被回收）；不是「立即销毁共享池」 */
+    async destroy() {
+        if (this.destroyed)
+            return;
+        this.destroyed = true;
+        this.registry.release(this.fingerprint);
+        if (this.tasks && typeof this.tasks.close === 'function') {
+            await this.tasks.close();
+        }
+    }
+    // ==================== SQL 执行 ====================
+    /** 完整执行入口（SELECT → QueryResult，DML → WriteResult）
+     * dml 选项按本 client 配置注入（池共享时 handle 配置不可靠）
+     * 查询结果缓存：仅幂等 SELECT；写操作（DML/DDL）后整库失效
+     * selectOnly 只读模式：拒绝一切非 SELECT 语句
+     * 返回结果统一携带 duration（执行耗时 ms，含缓存命中） */
+    async run(request) {
+        const start = performance.now();
+        const finish = (result) => {
+            if (result && typeof result === 'object') {
+                result.duration = roundDuration(performance.now() - start);
+            }
+            return result;
+        };
+        const type = detectStatementType(request.sql);
+        this.assertWritable(type);
+        const handle = await this.getHandle();
+        const req = request.dml ? request : { ...request, dml: this.config.dml };
+        const cacheOpts = this.config.cache;
+        const cache = cacheOpts?.enabled ? this.getQueryCache() : null;
+        if (cache && type === 'SELECT') {
+            const key = queryCacheKey(this.fingerprint, request.sql, request);
+            const hit = cache.get(key);
+            if (hit !== undefined)
+                return finish(hit);
+            const result = await this.driver.runSql(handle, req);
+            cache.set(key, structuredClone(result));
+            return finish(result);
+        }
+        const result = await this.driver.runSql(handle, req);
+        // 写操作后失效（粗粒度：本 client 缓存全清；精确按表失效留后续）
+        if (cache && type !== 'SELECT')
+            cache.clear();
+        return finish(result);
+    }
+    /** selectOnly 只读模式护栏：拒绝非 SELECT 语句 */
+    assertWritable(type) {
+        if (this.config.selectOnly && type !== 'SELECT') {
+            throw new SqlEngineError('READ_ONLY', `只读模式（selectOnly: true）禁止 ${type} 语句，仅允许 SELECT`);
+        }
+    }
+    getQueryCache() {
+        const opts = this.config.cache;
+        this.queryCache ??= new TtlCache(opts?.ttlMs ?? 60000, opts?.maxEntries ?? 1000);
+        return this.queryCache;
+    }
+    /** SELECT 查询 */
+    async query(sql, params) {
+        const type = detectStatementType(sql);
+        if (type !== 'SELECT') {
+            throw new SqlEngineError('QUERY_FAILED', `query() 仅支持 SELECT，收到 ${type}（写操作请用 execute()）`);
+        }
+        const result = await this.run({ sql, params });
+        return result;
+    }
+    /** 写操作：DML（INSERT/UPDATE/DELETE）+ DDL（CREATE/ALTER/DROP 透传） */
+    async execute(sql, params) {
+        const type = detectStatementType(sql);
+        if (type !== 'INSERT' && type !== 'UPDATE' && type !== 'DELETE' && type !== 'DDL') {
+            throw new SqlEngineError('QUERY_FAILED', `execute() 仅支持写操作（INSERT/UPDATE/DELETE/DDL），收到 ${type}（查询请用 query()）`);
+        }
+        const result = await this.run({ sql, params });
+        return result;
+    }
+    /** 透传原始驱动结果（不包装）——M2 提供方言原生透传 */
+    async raw(sql, params) {
+        void sql;
+        void params;
+        throw new SqlEngineError('QUERY_FAILED', 'raw() 暂未在驱动层暴露（M2 提供方言原生透传）');
+    }
+    // ==================== 元信息检出 ====================
+    async getTables() {
+        const handle = await this.getHandle();
+        return this.driver.getTableList(handle);
+    }
+    async getTableDDL(table) {
+        const handle = await this.getHandle();
+        if (!this.driver.getTableDDL) {
+            throw new SqlEngineError('QUERY_FAILED', `方言 ${this.driver.dialect} 不支持 getTableDDL`);
+        }
+        return this.driver.getTableDDL(handle, table);
+    }
+    async getColumns(table) {
+        const handle = await this.getHandle();
+        return this.driver.getColumns(handle, table);
+    }
+    async getRowsCount(table, whereClause, params) {
+        void params;
+        const handle = await this.getHandle();
+        return this.driver.getRowsCount(handle, table, whereClause);
+    }
+    async getPreviewRows(table, offset = 0, limit = 100, whereClause) {
+        const handle = await this.getHandle();
+        return this.driver.getPreviewRows(handle, table, offset, limit, whereClause);
+    }
+    /** 单表结构 JSON 检出 */
+    getTableSchema(table, opts) {
+        return this.getHandle().then((handle) => this.driver.getTableSchema(handle, table, opts));
+    }
+    /** 全库批量结构导出（长任务：进度/取消）
+     * 引用语义：client 持有池引用直到 destroy()，任务期间不额外计 ref */
+    getAllTableSchemas(opts) {
+        return wrapTask(() => this.getHandle().then((handle) => {
+            if (!this.driver.getAllTableSchemas) {
+                throw new SqlEngineError('QUERY_FAILED', `方言 ${this.driver.dialect} 不支持 getAllTableSchemas`);
+            }
+            return this.driver.getAllTableSchemas(handle, opts);
+        }));
+    }
+    /** 全库结构 → JSON 字符串 */
+    async exportSchemaAsJson(opts) {
+        const task = this.getAllTableSchemas(opts);
+        const schemas = await task.promise;
+        return JSON.stringify(schemas, null, 2);
+    }
+    /** 事务：fn 内所有查询在同一事务/连接内执行；fn 抛错自动回滚 */
+    async withTransaction(fn) {
+        if (this.config.selectOnly) {
+            throw new SqlEngineError('READ_ONLY', '只读模式（selectOnly: true）禁止事务');
+        }
+        if (!this.driver.withTransaction) {
+            throw new SqlEngineError('QUERY_FAILED', `方言 ${this.driver.dialect} 不支持事务`);
+        }
+        const handle = await this.getHandle();
+        return this.driver.withTransaction(handle, fn);
+    }
+}
+/** 判断 SQL 是否为写操作（供上层语义判断） */
+export function isWriteSql(sql) {
+    return detectStatementType(normalizeSql(sql)) !== 'SELECT';
+}
+//# sourceMappingURL=client.js.map

package/lib/client/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client/client.ts"],"names":[],"mappings":"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"}

package/lib/client/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 极简客户端入口：createClient(config)
+ * 零成本轻量操作（不建连接）；底层连接池全局共享（defaultRegistry）
+ */
+import type { ConnectionConfig } from '../types/config.js';
+import { DbClient } from './client.js';
+import { ClientManager } from './manager.js';
+/** 创建绑定 config 的 client（懒建池：首次真实调用才建立连接） */
+export declare function createClient(config: ConnectionConfig): DbClient;
+/** 创建多数据源管理器 */
+export declare function createClientManager(options?: ConstructorParameters<typeof ClientManager>[0]): ClientManager;
+export { DbClient } from './client.js';
+export { ClientManager } from './manager.js';
+export { PoolRegistry, defaultRegistry } from './registry.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,4CAA4C;AAC5C,wBAAgB,YAAY,CAAC,MAAM,EAAE,gBAAgB,GAAG,QAAQ,CAE/D;AAED,gBAAgB;AAChB,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE,qBAAqB,CAAC,OAAO,aAAa,CAAC,CAAC,CAAC,CAAC,GAAG,aAAa,CAE3G;AAED,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}

package/lib/client/index.js

@@ -0,0 +1,15 @@
+import { DbClient } from './client.js';
+import { defaultRegistry } from './registry.js';
+import { ClientManager } from './manager.js';
+/** 创建绑定 config 的 client（懒建池：首次真实调用才建立连接） */
+export function createClient(config) {
+    return new DbClient(defaultRegistry, config);
+}
+/** 创建多数据源管理器 */
+export function createClientManager(options) {
+    return new ClientManager(options);
+}
+export { DbClient } from './client.js';
+export { ClientManager } from './manager.js';
+export { PoolRegistry, defaultRegistry } from './registry.js';
+//# sourceMappingURL=index.js.map

package/lib/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,4CAA4C;AAC5C,MAAM,UAAU,YAAY,CAAC,MAAwB;IACnD,OAAO,IAAI,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;AAC/C,CAAC;AAED,gBAAgB;AAChB,MAAM,UAAU,mBAAmB,CAAC,OAAwD;IAC1F,OAAO,IAAI,aAAa,CAAC,OAAO,CAAC,CAAC;AACpC,CAAC;AAED,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}

package/lib/client/manager.d.ts

@@ -0,0 +1,27 @@
+import type { ConnectionConfig } from '../types/config.js';
+import type { ClientManagerOptions, PoolMetrics } from '../types/manager.js';
+import { DbClient } from './client.js';
+export declare class ClientManager {
+    private registry;
+    private byId;
+    private maxClients;
+    constructor(options?: ClientManagerOptions);
+    /**
+     * 获取/创建绑定 config 的 client（首次懒建池，之后命中共享池）
+     * 创建本身零成本：不建立连接，首次调用才真实建连
+     */
+    getClient(config: ConnectionConfig): DbClient;
+    /** 注册业务 ID → client（避免每次从库读 config 后重复计算指纹） */
+    register(dsId: string, config: ConnectionConfig): Promise<DbClient>;
+    getClientById(dsId: string): DbClient | undefined;
+    getConfigById(dsId: string): ConnectionConfig | undefined;
+    /** 释放 client 引用（数据源删除：引用归零即回收池） */
+    release(dsId: string): Promise<void>;
+    /** 强制销毁池（数据源配置更新：下次按新 config 重建） */
+    invalidate(target: string | ConnectionConfig): Promise<void>;
+    /** 应用退出清理 */
+    destroyAll(): Promise<void>;
+    /** 池指标 */
+    metrics(): PoolMetrics;
+}
+//# sourceMappingURL=manager.d.ts.map

package/lib/client/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/client/manager.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAC7E,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAQvC,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAe;IAC/B,OAAO,CAAC,IAAI,CAAuC;IACnD,OAAO,CAAC,UAAU,CAAS;gBAEf,OAAO,GAAE,oBAAyB;IAK9C;;;OAGG;IACH,SAAS,CAAC,MAAM,EAAE,gBAAgB,GAAG,QAAQ;IAM7C,+CAA+C;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAczE,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS;IAIjD,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAIzD,mCAAmC;IAC7B,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ1C,oCAAoC;IAC9B,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAYlE,aAAa;IACP,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAKjC,UAAU;IACV,OAAO,IAAI,WAAW;CAGvB"}

package/lib/client/manager.js

@@ -0,0 +1,73 @@
+/**
+ * ClientManager：多数据源注册表
+ * 核心：连接池按 config 指纹全局共享，client 是廉价句柄；每请求 getClient 命中缓存，不建新池
+ */
+import { SqlEngineError } from '../errors.js';
+import { configKey } from '../core/config.js';
+import { DbClient } from './client.js';
+import { PoolRegistry } from './registry.js';
+export class ClientManager {
+    registry;
+    byId = new Map();
+    maxClients;
+    constructor(options = {}) {
+        this.registry = new PoolRegistry(options);
+        this.maxClients = options.maxClients ?? 500;
+    }
+    /**
+     * 获取/创建绑定 config 的 client（首次懒建池，之后命中共享池）
+     * 创建本身零成本：不建立连接，首次调用才真实建连
+     */
+    getClient(config) {
+        // 立即抛错校验方言（避免把错误延迟到首次调用）
+        void configKey(config);
+        return new DbClient(this.registry, config);
+    }
+    /** 注册业务 ID → client（避免每次从库读 config 后重复计算指纹） */
+    async register(dsId, config) {
+        if (this.byId.size >= this.maxClients) {
+            throw new SqlEngineError('CLIENT_LIMIT_EXCEEDED', `已注册 client 数达到上限 ${this.maxClients}（ClientManagerOptions.maxClients 可调）`);
+        }
+        const client = this.getClient(config);
+        // 预热：立即建池并探活，让后续请求零延迟命中
+        await client.ping();
+        this.byId.set(dsId, { config, client });
+        return client;
+    }
+    getClientById(dsId) {
+        return this.byId.get(dsId)?.client;
+    }
+    getConfigById(dsId) {
+        return this.byId.get(dsId)?.config;
+    }
+    /** 释放 client 引用（数据源删除：引用归零即回收池） */
+    async release(dsId) {
+        const rec = this.byId.get(dsId);
+        this.byId.delete(dsId);
+        if (rec) {
+            await rec.client.destroy();
+        }
+    }
+    /** 强制销毁池（数据源配置更新：下次按新 config 重建） */
+    async invalidate(target) {
+        if (typeof target === 'string') {
+            const rec = this.byId.get(target);
+            if (rec) {
+                await this.registry.invalidate(configKey(rec.config));
+                this.byId.delete(target);
+            }
+            return;
+        }
+        await this.registry.invalidate(configKey(target));
+    }
+    /** 应用退出清理 */
+    async destroyAll() {
+        await this.registry.destroyAll();
+        this.byId.clear();
+    }
+    /** 池指标 */
+    metrics() {
+        return this.registry.metrics();
+    }
+}
+//# sourceMappingURL=manager.js.map

package/lib/client/manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.js","sourceRoot":"","sources":["../../src/client/manager.ts"],"names":[],"mappings":"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"}

package/lib/client/registry.d.ts

@@ -0,0 +1,31 @@
+import type { PoolHandle } from '../driver/interface.js';
+import type { ConnectionConfig } from '../types/config.js';
+import type { ClientManagerOptions, PoolMetrics } from '../types/manager.js';
+export declare class PoolRegistry {
+    private pools;
+    private totalRefs;
+    private maxClients;
+    private lruEnabled;
+    private maxIdlePools;
+    constructor(options?: ClientManagerOptions);
+    /**
+     * 获取/创建连接池并 +1 引用
+     * 首次遇到某指纹时懒创建池；之后复用（不按请求建池）
+     */
+    getPool(config: ConnectionConfig): Promise<PoolHandle>;
+    /** -1 引用；归零的池进入空闲集合（LRU 超限时回收） */
+    release(fingerprint: string): void;
+    /** 强制销毁池（数据源 update/remove 时调用） */
+    invalidate(fingerprint: string): Promise<void>;
+    /** 全局清理（应用退出） */
+    destroyAll(): Promise<void>;
+    /** 池指标（监控/容量规划） */
+    metrics(): PoolMetrics;
+    /** 空闲池 LRU 淘汰：引用归零的池超过 maxIdlePools 时，回收最久未用者 */
+    private maybeCollectIdle;
+    /** 测试辅助：清空注册表 */
+    reset(): Promise<void>;
+}
+/** 模块级默认注册表（所有入口共享） */
+export declare const defaultRegistry: PoolRegistry;
+//# sourceMappingURL=registry.d.ts.map