@harneon-ai/db 0.0.1

package/dist/config/types.d.ts

@@ -0,0 +1,358 @@
+/**
+ * 配置类型定义
+ *
+ * 使用 Zod 定义配置文件的 schema，兼容 ShardingSphere YAML 格式。
+ * 所有 Zod schema 同时导出对应的 TypeScript 类型，供其他模块使用。
+ *
+ * 配置文件结构层次:
+ * - dataSources: 数据源连接信息（多个 PostgreSQL 实例）
+ * - rules[].!SHARDING: 分片规则
+ *   - tables: 逻辑表 → 分片配置映射
+ *   - shardingAlgorithms: 分片算法定义
+ *   - defaultDatabaseStrategy/defaultTableStrategy: 默认分片策略
+ * - props: 额外属性（如 sql-show 等）
+ *
+ * 关键设计说明:
+ * - none 策略字段使用 z.union([z.null(), z.object({})]) 是因为 YAML 中 `none:` 解析为 null 而非 {}
+ * - DataSourceConfig 同时支持 jdbcUrl 和 url 字段，兼容不同版本的 ShardingSphere 配置
+ */
+import { z } from 'zod';
+/**
+ * 单个数据源的连接配置
+ * 对应 YAML 中 dataSources.ds_X 节点
+ * jdbcUrl 格式: jdbc:postgresql://host:port/database
+ */
+export declare const DataSourceConfigSchema: z.ZodObject<{
+    dataSourceClassName: z.ZodOptional<z.ZodString>;
+    driverClassName: z.ZodOptional<z.ZodString>;
+    jdbcUrl: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+    username: z.ZodString;
+    password: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    username: string;
+    password: string;
+    dataSourceClassName?: string | undefined;
+    driverClassName?: string | undefined;
+    jdbcUrl?: string | undefined;
+    url?: string | undefined;
+}, {
+    username: string;
+    password: string;
+    dataSourceClassName?: string | undefined;
+    driverClassName?: string | undefined;
+    jdbcUrl?: string | undefined;
+    url?: string | undefined;
+}>;
+/**
+ * 单个逻辑表的分片配置
+ * actualDataNodes 使用 ShardingSphere 表达式语法，如: ds_$->{0..1}.tbl_order_$->{0..1}
+ * 表达式由 parser.ts 中的 expandDataNodes() 展开为具体节点列表
+ */
+export declare const ShardingTableConfigSchema: z.ZodObject<{
+    actualDataNodes: z.ZodString;
+    tableStrategy: z.ZodOptional<z.ZodObject<{
+        none: z.ZodOptional<z.ZodUnion<[z.ZodNull, z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>]>>;
+        standard: z.ZodOptional<z.ZodObject<{
+            shardingColumn: z.ZodString;
+            shardingAlgorithmName: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            shardingColumn: string;
+            shardingAlgorithmName: string;
+        }, {
+            shardingColumn: string;
+            shardingAlgorithmName: string;
+        }>>;
+        complex: z.ZodOptional<z.ZodObject<{
+            shardingColumns: z.ZodString;
+            shardingAlgorithmName: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            shardingAlgorithmName: string;
+            shardingColumns: string;
+        }, {
+            shardingAlgorithmName: string;
+            shardingColumns: string;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        none?: {} | null | undefined;
+        standard?: {
+            shardingColumn: string;
+            shardingAlgorithmName: string;
+        } | undefined;
+        complex?: {
+            shardingAlgorithmName: string;
+            shardingColumns: string;
+        } | undefined;
+    }, {
+        none?: {} | null | undefined;
+        standard?: {
+            shardingColumn: string;
+            shardingAlgorithmName: string;
+        } | undefined;
+        complex?: {
+            shardingAlgorithmName: string;
+            shardingColumns: string;
+        } | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    actualDataNodes: string;
+    tableStrategy?: {
+        none?: {} | null | undefined;
+        standard?: {
+            shardingColumn: string;
+            shardingAlgorithmName: string;
+        } | undefined;
+        complex?: {
+            shardingAlgorithmName: string;
+            shardingColumns: string;
+        } | undefined;
+    } | undefined;
+}, {
+    actualDataNodes: string;
+    tableStrategy?: {
+        none?: {} | null | undefined;
+        standard?: {
+            shardingColumn: string;
+            shardingAlgorithmName: string;
+        } | undefined;
+        complex?: {
+            shardingAlgorithmName: string;
+            shardingColumns: string;
+        } | undefined;
+    } | undefined;
+}>;
+/**
+ * 分片算法配置
+ * type 常见值: INLINE, MOD, HASH_MOD 等
+ * props 中 algorithm-expression 定义分片表达式，如: tbl_order_$->{order_id % 2}
+ */
+export declare const ShardingAlgorithmConfigSchema: z.ZodObject<{
+    type: z.ZodString;
+    props: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber]>>>;
+}, "strip", z.ZodTypeAny, {
+    type: string;
+    props?: Record<string, string | number> | undefined;
+}, {
+    type: string;
+    props?: Record<string, string | number> | undefined;
+}>;
+/**
+ * 完整的分片规则配置
+ * 包含所有逻辑表定义、默认策略和算法定义
+ */
+export declare const ShardingRuleConfigSchema: z.ZodObject<{
+    tables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        actualDataNodes: z.ZodString;
+        tableStrategy: z.ZodOptional<z.ZodObject<{
+            none: z.ZodOptional<z.ZodUnion<[z.ZodNull, z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>]>>;
+            standard: z.ZodOptional<z.ZodObject<{
+                shardingColumn: z.ZodString;
+                shardingAlgorithmName: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                shardingColumn: string;
+                shardingAlgorithmName: string;
+            }, {
+                shardingColumn: string;
+                shardingAlgorithmName: string;
+            }>>;
+            complex: z.ZodOptional<z.ZodObject<{
+                shardingColumns: z.ZodString;
+                shardingAlgorithmName: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                shardingAlgorithmName: string;
+                shardingColumns: string;
+            }, {
+                shardingAlgorithmName: string;
+                shardingColumns: string;
+            }>>;
+        }, "strip", z.ZodTypeAny, {
+            none?: {} | null | undefined;
+            standard?: {
+                shardingColumn: string;
+                shardingAlgorithmName: string;
+            } | undefined;
+            complex?: {
+                shardingAlgorithmName: string;
+                shardingColumns: string;
+            } | undefined;
+        }, {
+            none?: {} | null | undefined;
+            standard?: {
+                shardingColumn: string;
+                shardingAlgorithmName: string;
+            } | undefined;
+            complex?: {
+                shardingAlgorithmName: string;
+                shardingColumns: string;
+            } | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        actualDataNodes: string;
+        tableStrategy?: {
+            none?: {} | null | undefined;
+            standard?: {
+                shardingColumn: string;
+                shardingAlgorithmName: string;
+            } | undefined;
+            complex?: {
+                shardingAlgorithmName: string;
+                shardingColumns: string;
+            } | undefined;
+        } | undefined;
+    }, {
+        actualDataNodes: string;
+        tableStrategy?: {
+            none?: {} | null | undefined;
+            standard?: {
+                shardingColumn: string;
+                shardingAlgorithmName: string;
+            } | undefined;
+            complex?: {
+                shardingAlgorithmName: string;
+                shardingColumns: string;
+            } | undefined;
+        } | undefined;
+    }>>>;
+    defaultShardingColumn: z.ZodOptional<z.ZodString>;
+    defaultDatabaseStrategy: z.ZodOptional<z.ZodObject<{
+        standard: z.ZodOptional<z.ZodObject<{
+            shardingColumn: z.ZodString;
+            shardingAlgorithmName: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            shardingColumn: string;
+            shardingAlgorithmName: string;
+        }, {
+            shardingColumn: string;
+            shardingAlgorithmName: string;
+        }>>;
+        none: z.ZodOptional<z.ZodUnion<[z.ZodNull, z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>]>>;
+    }, "strip", z.ZodTypeAny, {
+        none?: {} | null | undefined;
+        standard?: {
+            shardingColumn: string;
+            shardingAlgorithmName: string;
+        } | undefined;
+    }, {
+        none?: {} | null | undefined;
+        standard?: {
+            shardingColumn: string;
+            shardingAlgorithmName: string;
+        } | undefined;
+    }>>;
+    defaultTableStrategy: z.ZodOptional<z.ZodObject<{
+        standard: z.ZodOptional<z.ZodObject<{
+            shardingColumn: z.ZodString;
+            shardingAlgorithmName: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            shardingColumn: string;
+            shardingAlgorithmName: string;
+        }, {
+            shardingColumn: string;
+            shardingAlgorithmName: string;
+        }>>;
+        none: z.ZodOptional<z.ZodUnion<[z.ZodNull, z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>]>>;
+    }, "strip", z.ZodTypeAny, {
+        none?: {} | null | undefined;
+        standard?: {
+            shardingColumn: string;
+            shardingAlgorithmName: string;
+        } | undefined;
+    }, {
+        none?: {} | null | undefined;
+        standard?: {
+            shardingColumn: string;
+            shardingAlgorithmName: string;
+        } | undefined;
+    }>>;
+    shardingAlgorithms: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodString;
+        props: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber]>>>;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        props?: Record<string, string | number> | undefined;
+    }, {
+        type: string;
+        props?: Record<string, string | number> | undefined;
+    }>>>;
+}, "strip", z.ZodTypeAny, {
+    tables?: Record<string, {
+        actualDataNodes: string;
+        tableStrategy?: {
+            none?: {} | null | undefined;
+            standard?: {
+                shardingColumn: string;
+                shardingAlgorithmName: string;
+            } | undefined;
+            complex?: {
+                shardingAlgorithmName: string;
+                shardingColumns: string;
+            } | undefined;
+        } | undefined;
+    }> | undefined;
+    defaultShardingColumn?: string | undefined;
+    defaultDatabaseStrategy?: {
+        none?: {} | null | undefined;
+        standard?: {
+            shardingColumn: string;
+            shardingAlgorithmName: string;
+        } | undefined;
+    } | undefined;
+    defaultTableStrategy?: {
+        none?: {} | null | undefined;
+        standard?: {
+            shardingColumn: string;
+            shardingAlgorithmName: string;
+        } | undefined;
+    } | undefined;
+    shardingAlgorithms?: Record<string, {
+        type: string;
+        props?: Record<string, string | number> | undefined;
+    }> | undefined;
+}, {
+    tables?: Record<string, {
+        actualDataNodes: string;
+        tableStrategy?: {
+            none?: {} | null | undefined;
+            standard?: {
+                shardingColumn: string;
+                shardingAlgorithmName: string;
+            } | undefined;
+            complex?: {
+                shardingAlgorithmName: string;
+                shardingColumns: string;
+            } | undefined;
+        } | undefined;
+    }> | undefined;
+    defaultShardingColumn?: string | undefined;
+    defaultDatabaseStrategy?: {
+        none?: {} | null | undefined;
+        standard?: {
+            shardingColumn: string;
+            shardingAlgorithmName: string;
+        } | undefined;
+    } | undefined;
+    defaultTableStrategy?: {
+        none?: {} | null | undefined;
+        standard?: {
+            shardingColumn: string;
+            shardingAlgorithmName: string;
+        } | undefined;
+    } | undefined;
+    shardingAlgorithms?: Record<string, {
+        type: string;
+        props?: Record<string, string | number> | undefined;
+    }> | undefined;
+}>;
+export type DataSourceConfig = z.infer<typeof DataSourceConfigSchema>;
+export type ShardingTableConfig = z.infer<typeof ShardingTableConfigSchema>;
+export type ShardingAlgorithmConfig = z.infer<typeof ShardingAlgorithmConfigSchema>;
+export type ShardingRuleConfig = z.infer<typeof ShardingRuleConfigSchema>;
+/**
+ * 解析后的配置（应用内部使用的最终结构）
+ * 与原始 YAML 的区别: shardingRule 从 rules 数组中提取为单独字段
+ */
+export interface ParsedConfig {
+    dataSources: Record<string, DataSourceConfig>;
+    shardingRule?: ShardingRuleConfig;
+    props?: Record<string, unknown>;
+}

package/dist/config/types.js

@@ -0,0 +1,86 @@
+/**
+ * 配置类型定义
+ *
+ * 使用 Zod 定义配置文件的 schema，兼容 ShardingSphere YAML 格式。
+ * 所有 Zod schema 同时导出对应的 TypeScript 类型，供其他模块使用。
+ *
+ * 配置文件结构层次:
+ * - dataSources: 数据源连接信息（多个 PostgreSQL 实例）
+ * - rules[].!SHARDING: 分片规则
+ *   - tables: 逻辑表 → 分片配置映射
+ *   - shardingAlgorithms: 分片算法定义
+ *   - defaultDatabaseStrategy/defaultTableStrategy: 默认分片策略
+ * - props: 额外属性（如 sql-show 等）
+ *
+ * 关键设计说明:
+ * - none 策略字段使用 z.union([z.null(), z.object({})]) 是因为 YAML 中 `none:` 解析为 null 而非 {}
+ * - DataSourceConfig 同时支持 jdbcUrl 和 url 字段，兼容不同版本的 ShardingSphere 配置
+ */
+import { z } from 'zod';
+/**
+ * 单个数据源的连接配置
+ * 对应 YAML 中 dataSources.ds_X 节点
+ * jdbcUrl 格式: jdbc:postgresql://host:port/database
+ */
+export const DataSourceConfigSchema = z.object({
+    dataSourceClassName: z.string().optional(), // 如 com.zaxxer.hikari.HikariDataSource
+    driverClassName: z.string().optional(), // 如 org.postgresql.Driver
+    jdbcUrl: z.string().optional(), // JDBC 连接 URL（优先使用）
+    url: z.string().optional(), // 备选 URL 字段（部分配置使用 url 而非 jdbcUrl）
+    username: z.string(),
+    password: z.string(),
+});
+/**
+ * 单个逻辑表的分片配置
+ * actualDataNodes 使用 ShardingSphere 表达式语法，如: ds_$->{0..1}.tbl_order_$->{0..1}
+ * 表达式由 parser.ts 中的 expandDataNodes() 展开为具体节点列表
+ */
+export const ShardingTableConfigSchema = z.object({
+    actualDataNodes: z.string(),
+    tableStrategy: z.object({
+        // none 表示不分表（使用默认策略）；YAML 中 `none:` 解析为 null，故需兼容 null
+        none: z.union([z.null(), z.object({})]).optional(),
+        // standard 策略: 单分片键
+        standard: z.object({
+            shardingColumn: z.string(),
+            shardingAlgorithmName: z.string(), // 引用 shardingAlgorithms 中的算法名称
+        }).optional(),
+        // complex 策略: 多分片键（逗号分隔）
+        complex: z.object({
+            shardingColumns: z.string(), // 多个分片列，逗号分隔
+            shardingAlgorithmName: z.string(),
+        }).optional(),
+    }).optional(),
+});
+/**
+ * 分片算法配置
+ * type 常见值: INLINE, MOD, HASH_MOD 等
+ * props 中 algorithm-expression 定义分片表达式，如: tbl_order_$->{order_id % 2}
+ */
+export const ShardingAlgorithmConfigSchema = z.object({
+    type: z.string(),
+    props: z.record(z.string(), z.union([z.string(), z.number()])).optional(),
+});
+/**
+ * 完整的分片规则配置
+ * 包含所有逻辑表定义、默认策略和算法定义
+ */
+export const ShardingRuleConfigSchema = z.object({
+    tables: z.record(z.string(), ShardingTableConfigSchema).optional(),
+    defaultShardingColumn: z.string().optional(), // 全局默认分片列
+    defaultDatabaseStrategy: z.object({
+        standard: z.object({
+            shardingColumn: z.string(),
+            shardingAlgorithmName: z.string(),
+        }).optional(),
+        none: z.union([z.null(), z.object({})]).optional(),
+    }).optional(),
+    defaultTableStrategy: z.object({
+        standard: z.object({
+            shardingColumn: z.string(),
+            shardingAlgorithmName: z.string(),
+        }).optional(),
+        none: z.union([z.null(), z.object({})]).optional(),
+    }).optional(),
+    shardingAlgorithms: z.record(z.string(), ShardingAlgorithmConfigSchema).optional(),
+});

package/dist/config/writer.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 配置序列化与合并
+ *
+ * 负责将 ParsedConfig 对象序列化为 ShardingSphere 兼容的 YAML 格式，
+ * 以及将新配置合并到现有配置中。
+ *
+ * 核心难点:
+ * 1. ShardingSphere 要求分片规则使用 `!SHARDING` 自定义 YAML 标签
+ *    解决: 使用 yaml 库的 Document API 构建 AST，手动为分片规则节点设置 tag
+ * 2. 合并策略需要按 key 合并而非简单覆盖，避免丢失已有配置
+ */
+import type { ParsedConfig } from './types.js';
+/**
+ * 将 ParsedConfig 序列化为 ShardingSphere 兼容的 YAML 字符串
+ *
+ * 序列化策略:
+ * - dataSources / props: 直接使用 yaml Document 的 createNode 转换
+ * - shardingRule: 需要包裹在 rules 数组中，并为节点添加 `!SHARDING` 标签
+ * - none 策略: ShardingSphere 中 `none:` 后无值，序列化时需保持为 null
+ *
+ * @param config 解析后的配置对象
+ * @returns ShardingSphere 兼容的 YAML 字符串
+ */
+export declare function serializeConfig(config: ParsedConfig): string;
+/**
+ * 合并新配置到现有配置中
+ *
+ * 合并策略:
+ * - dataSources: 按 key 合并，同名数据源会被覆盖
+ * - shardingRule.tables: 按逻辑表名合并
+ * - shardingRule.shardingAlgorithms: 按算法名合并
+ * - shardingRule 其他字段（defaultDatabaseStrategy 等）: 新值覆盖旧值
+ * - props: 浅合并
+ *
+ * @param existing 现有配置
+ * @param incoming 待合并的新配置（部分字段）
+ * @returns 合并后的完整配置
+ */
+export declare function mergeConfigs(existing: ParsedConfig, incoming: Partial<ParsedConfig>): ParsedConfig;
+/**
+ * 将配置写入 YAML 文件
+ *
+ * 写入前会将原文件备份为 .bak 后缀，防止写入中断导致配置丢失。
+ * 如果原文件不存在则直接写入（首次创建场景）。
+ *
+ * @param filePath 配置文件路径
+ * @param config 要写入的配置对象
+ */
+export declare function writeConfigFile(filePath: string, config: ParsedConfig): void;

package/dist/config/writer.js

@@ -0,0 +1,129 @@
+/**
+ * 配置序列化与合并
+ *
+ * 负责将 ParsedConfig 对象序列化为 ShardingSphere 兼容的 YAML 格式，
+ * 以及将新配置合并到现有配置中。
+ *
+ * 核心难点:
+ * 1. ShardingSphere 要求分片规则使用 `!SHARDING` 自定义 YAML 标签
+ *    解决: 使用 yaml 库的 Document API 构建 AST，手动为分片规则节点设置 tag
+ * 2. 合并策略需要按 key 合并而非简单覆盖，避免丢失已有配置
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { Document, YAMLMap, YAMLSeq, Pair, Scalar } from 'yaml';
+/**
+ * 将 ParsedConfig 序列化为 ShardingSphere 兼容的 YAML 字符串
+ *
+ * 序列化策略:
+ * - dataSources / props: 直接使用 yaml Document 的 createNode 转换
+ * - shardingRule: 需要包裹在 rules 数组中，并为节点添加 `!SHARDING` 标签
+ * - none 策略: ShardingSphere 中 `none:` 后无值，序列化时需保持为 null
+ *
+ * @param config 解析后的配置对象
+ * @returns ShardingSphere 兼容的 YAML 字符串
+ */
+export function serializeConfig(config) {
+    const doc = new Document();
+    const root = new YAMLMap();
+    // dataSources 节点
+    root.add(new Pair(new Scalar('dataSources'), doc.createNode(config.dataSources)));
+    // rules 节点: 将 shardingRule 包裹在数组中，添加 !SHARDING 标签
+    if (config.shardingRule) {
+        const rulesSeq = new YAMLSeq();
+        const shardingNode = doc.createNode(config.shardingRule);
+        shardingNode.tag = '!SHARDING';
+        rulesSeq.add(shardingNode);
+        root.add(new Pair(new Scalar('rules'), rulesSeq));
+    }
+    // props 节点
+    if (config.props && Object.keys(config.props).length > 0) {
+        root.add(new Pair(new Scalar('props'), doc.createNode(config.props)));
+    }
+    doc.contents = root;
+    return doc.toString({ lineWidth: 0 });
+}
+/**
+ * 合并新配置到现有配置中
+ *
+ * 合并策略:
+ * - dataSources: 按 key 合并，同名数据源会被覆盖
+ * - shardingRule.tables: 按逻辑表名合并
+ * - shardingRule.shardingAlgorithms: 按算法名合并
+ * - shardingRule 其他字段（defaultDatabaseStrategy 等）: 新值覆盖旧值
+ * - props: 浅合并
+ *
+ * @param existing 现有配置
+ * @param incoming 待合并的新配置（部分字段）
+ * @returns 合并后的完整配置
+ */
+export function mergeConfigs(existing, incoming) {
+    const merged = {
+        dataSources: { ...existing.dataSources },
+        shardingRule: existing.shardingRule ? structuredClone(existing.shardingRule) : undefined,
+        props: existing.props ? { ...existing.props } : undefined,
+    };
+    // 合并数据源: 按 key 合并，同名覆盖
+    if (incoming.dataSources) {
+        for (const [name, ds] of Object.entries(incoming.dataSources)) {
+            merged.dataSources[name] = ds;
+        }
+    }
+    // 合并分片规则
+    if (incoming.shardingRule) {
+        if (!merged.shardingRule) {
+            merged.shardingRule = structuredClone(incoming.shardingRule);
+        }
+        else {
+            mergeShardingRule(merged.shardingRule, incoming.shardingRule);
+        }
+    }
+    // 合并 props: 浅合并
+    if (incoming.props) {
+        merged.props = { ...(merged.props || {}), ...incoming.props };
+    }
+    return merged;
+}
+/**
+ * 合并分片规则（原地修改 target）
+ * tables 和 shardingAlgorithms 按 key 合并，其他字段新值覆盖旧值
+ */
+function mergeShardingRule(target, source) {
+    if (source.tables) {
+        target.tables = { ...(target.tables || {}), ...source.tables };
+    }
+    if (source.shardingAlgorithms) {
+        target.shardingAlgorithms = { ...(target.shardingAlgorithms || {}), ...source.shardingAlgorithms };
+    }
+    if (source.defaultDatabaseStrategy !== undefined) {
+        target.defaultDatabaseStrategy = source.defaultDatabaseStrategy;
+    }
+    if (source.defaultTableStrategy !== undefined) {
+        target.defaultTableStrategy = source.defaultTableStrategy;
+    }
+    if (source.defaultShardingColumn !== undefined) {
+        target.defaultShardingColumn = source.defaultShardingColumn;
+    }
+}
+/**
+ * 将配置写入 YAML 文件
+ *
+ * 写入前会将原文件备份为 .bak 后缀，防止写入中断导致配置丢失。
+ * 如果原文件不存在则直接写入（首次创建场景）。
+ *
+ * @param filePath 配置文件路径
+ * @param config 要写入的配置对象
+ */
+export function writeConfigFile(filePath, config) {
+    // 确保配置文件所在目录存在（全局安装时 ~/.harneon-ai/db/ 可能尚未创建）
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    // 备份原文件（如果存在）
+    if (fs.existsSync(filePath)) {
+        fs.copyFileSync(filePath, `${filePath}.bak`);
+    }
+    const yamlContent = serializeConfig(config);
+    fs.writeFileSync(filePath, yamlContent, 'utf-8');
+}

package/dist/db/connection-manager.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 数据库连接池管理器
+ *
+ * 管理多个 PostgreSQL 数据源的连接池，采用懒初始化策略:
+ * - 构造时不创建任何连接，首次调用 getPool() 时才创建对应数据源的连接池
+ * - 使用 Promise Map 避免并发调用时重复创建连接池（竞态安全）
+ * - 所有连接池强制设置 default_transaction_read_only=on（数据库层面只读保护）
+ *
+ * 连接池参数:
+ * - max=3: 元数据查询不需要大连接池，3 个连接足够
+ * - idleTimeoutMillis=30000: 空闲 30 秒后释放连接
+ */
+import pg from 'pg';
+import { type ParsedConfig } from '../config/types.js';
+export declare class ConnectionManager {
+    /**
+     * 使用 Promise<pg.Pool> 而非 pg.Pool 存储，确保并发调用 getPool() 时
+     * 多个调用者 await 同一个 Promise，避免重复创建连接池导致资源泄漏
+     */
+    private poolPromises;
+    private config;
+    constructor(config: ParsedConfig);
+    /**
+     * 获取指定数据源的连接池（懒初始化，并发安全）
+     * @param dsName 数据源名称，对应 YAML 配置中 dataSources 下的 key（如 ds_0, ds_1）
+     * @throws 数据源不存在或 JDBC URL 解析失败时抛出错误
+     */
+    getPool(dsName: string): Promise<pg.Pool>;
+    private createPool;
+    /** 返回所有已配置的数据源名称列表 */
+    getAllDataSourceNames(): string[];
+    /**
+     * 重新加载配置: 关闭所有已创建的连接池并清空缓存
+     *
+     * 调用前应先原地修改 config 对象（因为所有 tool 闭包引用同一对象）。
+     * 调用后，下次 getPool() 会基于更新后的 config 懒初始化新连接池。
+     */
+    reloadConfig(): Promise<void>;
+    /** 关闭所有已创建的连接池，用于进程退出时的资源清理 */
+    shutdown(): Promise<void>;
+}