@nsyan/db 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (30) hide show
  1. package/README.md +128 -0
  2. package/index.ts +929 -0
  3. package/package.json +57 -0
  4. package/src/config.ts +220 -0
  5. package/src/core/export.ts +14 -0
  6. package/src/core/index.ts +7 -0
  7. package/src/core/policy.ts +11 -0
  8. package/src/core/scan/candidates.ts +286 -0
  9. package/src/core/scan/parsers.ts +149 -0
  10. package/src/core/scan/placeholders.ts +24 -0
  11. package/src/core/scan/scoring.ts +25 -0
  12. package/src/core/scan/spring.ts +73 -0
  13. package/src/core/scan/walker.ts +47 -0
  14. package/src/core/sql-text.ts +72 -0
  15. package/src/core/types.ts +88 -0
  16. package/src/core/whitelist.ts +4 -0
  17. package/src/dialects/bigdata-dialect.ts +197 -0
  18. package/src/dialects/dialect.ts +38 -0
  19. package/src/dialects/dm.ts +159 -0
  20. package/src/dialects/elasticsearch.ts +219 -0
  21. package/src/dialects/hive.ts +124 -0
  22. package/src/dialects/index.ts +12 -0
  23. package/src/dialects/kv-dialect.ts +127 -0
  24. package/src/dialects/mysql.ts +158 -0
  25. package/src/dialects/oracle.ts +177 -0
  26. package/src/dialects/postgresql.ts +168 -0
  27. package/src/dialects/redis.ts +190 -0
  28. package/src/dialects/relational-dialect.ts +76 -0
  29. package/src/dialects/search-dialect.ts +128 -0
  30. package/src/dialects/spark.ts +120 -0
package/README.md ADDED
@@ -0,0 +1,128 @@
1
+ <div align="center">
2
+
3
+ # db
4
+
5
+ **AI 接入数据库插件 —— 方言化架构，原生 Node.js 实现，无需 Python**
6
+
7
+ 支持关系型 / KV / 搜索 / 大数据四大家族，共 8 种数据库的查询、表结构浏览与项目配置扫描建连。
8
+
9
+ ![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)
10
+
11
+ </div>
12
+
13
+ ## ✨ 特性
14
+
15
+ - **方言化架构**：`core/` + `dialects/` 零 pi 运行时依赖，为 MCP server 复用铺路
16
+ - **8 种数据库**：PostgreSQL · MySQL · Oracle · 达梦 DM8 · Redis · Elasticsearch · Hive · Spark（Thrift Server）
17
+ - **四大家族**：关系型 / KV / 搜索 / 大数据，各有一套共享基类
18
+ - **安全强化**：
19
+ - 多语句**逐条**检查，`SELECT 1; DROP TABLE x` 无法绕过
20
+ - 注释剥离后再匹配，`/* c */ DELETE` 无法绕过
21
+ - CTE-DML / `FOR UPDATE` 识别为写操作
22
+ - Redis 命令白名单（只读模式放行读命令，`FLUSHALL/CONFIG/SHUTDOWN` 恒拒）
23
+ - ES 端点白名单（只读模式放行读端点，`DELETE index` 恒拒）
24
+ - **代码扫描建连** `/db scan`：从 Spring 配置 / docker-compose / .env 自动抽取连接候选
25
+ - **P0 体验**：一键连接串（自动识别家族）、默认连接（`database` 参数可选）、`list_tables` pattern 过滤、超 50 行结果自动导出 CSV/JSON
26
+
27
+ ## 📦 安装
28
+
29
+ ```bash
30
+ pi install ./packages/db
31
+ ```
32
+
33
+ > 依赖 `pg` / `mysql2` / `oracledb` / `dmdb` / `ioredis` / `@elastic/elasticsearch` / `es7` / `hive-driver` / `typebox`，`pi install` 自动安装。
34
+
35
+ ## 🚀 快速开始
36
+
37
+ ```bash
38
+ /db add # 新增连接（一键粘贴连接串，或按家族逐步填写）
39
+ /db ls # 列出所有连接
40
+ /db scan # 扫描项目源码自动建连
41
+ /db config # 查看/修改全局设置
42
+ ```
43
+
44
+ AI 侧接入后，直接用 `query_database` / `list_tables` / `describe_table` / `scan_project_configs` 四个工具即可。
45
+
46
+ ## 🗄️ 支持的数据库
47
+
48
+ | 数据库 | 家族 | 驱动 | 支持版本 | 备注 |
49
+ |--------|------|------|---------|------|
50
+ | PostgreSQL | 关系型 | `pg` | 9.6 ~ 17 全系 | `statement_timeout` 全版本可用 |
51
+ | MySQL | 关系型 | `mysql2` v3 | 5.7 / 8.0 / 8.4 | `max_execution_time` 需 ≥5.7.8，低版本自动忽略（客户端超时仍生效） |
52
+ | Oracle | 关系型 | `oracledb`（Thin，零依赖） | ≥12.1 | Thin 模式硬性要求 DB ≥12.1，11g 及以下不支持（会给出版本原因指引）；Thick 模式列入后续迭代 |
53
+ | 达梦 DM | 关系型 | `dmdb` | DM8 全系；DM9 未验证 | 纯 JS 依赖，macOS/Linux/Windows 可用 |
54
+ | Redis | KV | `ioredis` | 2.8 ~ 8.x | `SCAN` 需 ≥2.8；`MEMORY USAGE` 需 ≥4.0，低版本自动跳过；生产库一律 SCAN，禁 `KEYS` |
55
+ | Elasticsearch | 搜索 | `@elastic/elasticsearch` v8 + v7（npm 别名 `es7`） | 7.x / 8.x / 更新大版本 | 连接时探测大版本分发对应客户端；未知大版本用最新客户端尝试并给出版本警告 |
56
+ | Hive | 大数据 | `hive-driver` | 目标 2.x；4.x 未实测 | HS2 Thrift 协议；无 4.x 环境前声明仅支持 2/3 |
57
+ | Spark（Thrift Server） | 大数据 | `hive-driver`（复用） | 2.x ~ 4.x | 与 Hive 同协议栈；Spark Connect（DataFrame/gRPC）不支持 |
58
+
59
+ > 版本兼容采用**端点抽测**：每个支持项只实测「最老支持版 + 最新版」两个端点，中间版本声明兼容不实测。
60
+
61
+ ## ⚙️ 新增连接
62
+
63
+ `/db add` 首问选择「粘贴连接串（一键）」或「逐步填写」。连接串自动识别家族：
64
+
65
+ ```
66
+ postgresql://user:pass@host:5432/db → PostgreSQL
67
+ jdbc:mysql://host:3306/db → MySQL
68
+ jdbc:oracle:thin:@//host:1521/svc → Oracle（也支持 SID 形式）
69
+ jdbc:dm://host:5236/schema → 达梦
70
+ redis://:pass@host:6379/0 → Redis（含 rediss:// TLS）
71
+ http://host:9200 → Elasticsearch
72
+ jdbc:hive2://host:10000/db → Hive / Spark
73
+ ```
74
+
75
+ 逐步填写按家族分支：Redis 无账号要求、需库号（dbIndex）；ES 账号/密码；其余 URL + 账号 + 密码。
76
+
77
+ ## 🔎 代码扫描建连 `/db scan`
78
+
79
+ 从项目源码自动抽取连接信息（Spring `application*.yml/properties`、`docker-compose.yml`、`.env`、通用 URL 正则）：
80
+
81
+ ```bash
82
+ /db scan # 扫描当前工作目录
83
+ /db scan ./backend # 扫描指定子目录（越界拒绝）
84
+ ```
85
+
86
+ 扫描结果按状态分组：✅ 可直接建 / ✏️ 待补字段 / 🔒 jasypt 加密（只标注不建）/ ⏭️ 同名已存在。逐个确认后才写入配置——**绝不静默建连、绝不静默覆盖**。占位符 `${KEY:default}` 取 default，`${KEY}` 依次查同目录 `.env` → 进程环境变量，缺省在终端追问。
87
+
88
+ AI 侧说「连一下这个项目的数据库」等，会调用 `scan_project_configs` 展示**掩码后**的候选（不写盘），建连仍需你在终端确认，密码不进模型上下文。
89
+
90
+ ## ⭐ 默认连接
91
+
92
+ `/db` → 打开连接 → `⭐ 设为默认`。AI 调用工具时 `database` 参数可省略，缺省走默认连接；未设默认时给出指引。
93
+
94
+ ## 💾 查询结果导出
95
+
96
+ 查询结果超过 50 行时，完整结果自动导出到 `/tmp`（CSV + JSON 双格式），只返回文件路径。结果达到 `max_rows` 上限截断时有明确标注。
97
+
98
+ ## 🔐 安全控制
99
+
100
+ - **执行策略同步**：系统提示动态注入当前 AI 只读模式与执行确认设置
101
+ - **逐语句检查**：多语句 SQL 逐条检查，注释剥离后再匹配
102
+ - **硬限制**：DROP TABLE/DATABASE（关系型/大数据）、`FLUSHALL/FLUSHDB/CONFIG/SHUTDOWN`（Redis）、`DELETE <index>`（ES）
103
+ - **只读白名单**：Redis 读命令白名单、ES 读端点白名单
104
+ - **确认策略**：不确认 / 写操作确认 / 每次确认；无 UI 环境自动取消
105
+ - **手工查询一致**：`/db` 菜单手工执行与 AI 工具使用相同的策略裁决
106
+
107
+ ## ⚙️ 设置
108
+
109
+ 通过 `/db config` 修改，每轮注入系统提示：
110
+
111
+ | 设置项 | 默认值 | 说明 |
112
+ |--------|--------|------|
113
+ | AI 只读模式 | 是 | 开启时 AI 只能执行查询；关闭时允许写操作 |
114
+ | 执行确认 | 写操作确认 | 不确认 / 写操作确认 / 每次都确认 |
115
+ | 最大行数 | 100 | 查询返回的最大行数 |
116
+ | 查询超时 | 30s | 单条语句超时（服务端设置失败时客户端兜底） |
117
+
118
+ ## 📁 开发
119
+
120
+ ```bash
121
+ pnpm install
122
+ cd packages/db
123
+ NODE_ENV=development pnpm test # 运行全部单测（tsx + node:test）
124
+ ```
125
+
126
+ ## 📄 许可
127
+
128
+ [MIT](./LICENSE)