dbgraph 0.1.0 → 0.1.2
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.
- package/README.ZH-cn.md +159 -0
- package/README.md +98 -286
- package/package.json +2 -2
package/README.ZH-cn.md
ADDED
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# DBGraph
|
|
4
|
+
|
|
5
|
+
### 数据库知识图谱 — 将数据库 schema 提取为知识图谱，通过 MCP 供 AI 代理使用
|
|
6
|
+
|
|
7
|
+
**零猜测 SQL 生成 · 亚毫秒级 schema 查询 · 100% 本地运行**
|
|
8
|
+
|
|
9
|
+
[](https://www.npmjs.com/package/dbgraph)
|
|
10
|
+
[](LICENSE)
|
|
11
|
+
[](https://nodejs.org/)
|
|
12
|
+
|
|
13
|
+
[](#支持引擎)
|
|
14
|
+
[](#支持引擎)
|
|
15
|
+
[](#支持引擎)
|
|
16
|
+
|
|
17
|
+
</div>
|
|
18
|
+
|
|
19
|
+
## 快速开始
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
# 零安装（推荐）
|
|
23
|
+
npx dbgraph
|
|
24
|
+
|
|
25
|
+
# 或全局安装
|
|
26
|
+
npm i -g dbgraph
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
### 初始化项目
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
cd your-project
|
|
33
|
+
npx dbgraph init -i # 一步完成初始化 + 索引
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
<sub>`dbgraph init` 创建 `.dbgraph/` 目录和默认 `dbgraph-db.json` 配置。加上 `-i`（`--index`）会立即内省数据库。编辑 `dbgraph-db.json` 配置数据库连接。</sub>
|
|
37
|
+
|
|
38
|
+
### 启动 MCP 服务器
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
npx dbgraph serve
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
AI 代理连接 MCP 后自动发现 `dbgraph_*` 工具，用于 schema 感知的 SQL 生成。
|
|
45
|
+
|
|
46
|
+
## 为什么用 DBGraph？
|
|
47
|
+
|
|
48
|
+
LLM 写 SQL 出错的最大原因是**不知道库表结构**——表名靠猜、列名靠蒙、JOIN 条件靠碰运气。DBGraph 把数据库 schema（表、列、类型、外键、约束、索引）提取为**可搜索的知识图谱**存在 `.dbgraph/` 中。AI 代理通过 MCP 工具直接查询，无需数据库直连。
|
|
49
|
+
|
|
50
|
+
```
|
|
51
|
+
传统流程:
|
|
52
|
+
LLM → 猜名列名 → 写 SQL → 报错 → 再猜 → 循环
|
|
53
|
+
|
|
54
|
+
DBGraph 流程:
|
|
55
|
+
LLM → dbgraph_context("orders") → 拿到精确 schema
|
|
56
|
+
→ 写 SQL → 成功
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## CLI 命令
|
|
60
|
+
|
|
61
|
+
| 命令 | 说明 |
|
|
62
|
+
|---------|-------------|
|
|
63
|
+
| `init` | 初始化 `.dbgraph` 项目（`-i` 立即索引）|
|
|
64
|
+
| `index` | 运行数据库内省 |
|
|
65
|
+
| `serve` | 启动 MCP 服务器（`--auto-refresh` 自动检测 schema 变更）|
|
|
66
|
+
| `query` | 搜索表、列、视图、索引 |
|
|
67
|
+
| `context` | 查看完整表结构（写 SQL 前必调）|
|
|
68
|
+
| `trace` | 追踪外键关联路径 |
|
|
69
|
+
| `explore` | 批量查看多张表 schema |
|
|
70
|
+
| `sources` | 列出已配置的数据库源 |
|
|
71
|
+
| `status` | 知识图谱统计 |
|
|
72
|
+
| `test` | 测试数据库连接 |
|
|
73
|
+
| `config` | 查看或创建配置 |
|
|
74
|
+
|
|
75
|
+
所有命令默认使用当前目录，也可指定目录：
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
npx dbgraph status # 当前目录
|
|
79
|
+
npx dbgraph status ./other-project # 其他项目
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
## MCP 工具
|
|
83
|
+
|
|
84
|
+
启动 `dbgraph serve` 后，AI 代理可调用：
|
|
85
|
+
|
|
86
|
+
| 工具 | 用途 |
|
|
87
|
+
|------|---------|
|
|
88
|
+
| `dbgraph_search` | 按名称搜索 schema 对象 |
|
|
89
|
+
| `dbgraph_context` | **完整表结构** — 列、类型、主键、外键、索引 |
|
|
90
|
+
| `dbgraph_trace` | 追踪外键关联路径（orders → users）|
|
|
91
|
+
| `dbgraph_explore` | 批量查看多张表 |
|
|
92
|
+
| `dbgraph_sources` | 列出所有数据库源 |
|
|
93
|
+
| `dbgraph_status` | 图谱健康状态与统计 |
|
|
94
|
+
|
|
95
|
+
## 配置说明
|
|
96
|
+
|
|
97
|
+
编辑项目根目录的 `dbgraph-db.json`：
|
|
98
|
+
|
|
99
|
+
```json
|
|
100
|
+
{
|
|
101
|
+
"databases": [
|
|
102
|
+
{
|
|
103
|
+
"alias": "prod",
|
|
104
|
+
"engine": "postgresql",
|
|
105
|
+
"host": "localhost",
|
|
106
|
+
"port": 5432,
|
|
107
|
+
"database": "ecommerce",
|
|
108
|
+
"schemas": ["public"],
|
|
109
|
+
"auth": "env:DB_PASSWORD"
|
|
110
|
+
},
|
|
111
|
+
{
|
|
112
|
+
"alias": "local",
|
|
113
|
+
"engine": "sqlite",
|
|
114
|
+
"path": "./dev.db"
|
|
115
|
+
}
|
|
116
|
+
]
|
|
117
|
+
}
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
| 字段 | 类型 | 必填 | 说明 |
|
|
121
|
+
|-------|------|----------|-------------|
|
|
122
|
+
| `alias` | string | 是 | 数据库别名（图谱中以 `db://@alias` 标识）|
|
|
123
|
+
| `engine` | string | 是 | `postgresql` / `mysql` / `mariadb` / `sqlite` |
|
|
124
|
+
| `host` | string | 否 | 主机地址 |
|
|
125
|
+
| `port` | number | 否 | 端口（默认根据引擎判断）|
|
|
126
|
+
| `database` | string | 视情况 | PostgreSQL/MySQL 必填 |
|
|
127
|
+
| `schemas` | string[] | 否 | 要提取的 schema 列表（默认全部）|
|
|
128
|
+
| `path` | string | 视情况 | SQLite 必填 |
|
|
129
|
+
| `auth` | string | 否 | `env:VAR_NAME` 或 `~/.pgpass` |
|
|
130
|
+
| `ssl` | boolean | 否 | 启用 SSL |
|
|
131
|
+
|
|
132
|
+
## 支持引擎
|
|
133
|
+
|
|
134
|
+
| 引擎 | 状态 |
|
|
135
|
+
|--------|------|
|
|
136
|
+
| PostgreSQL | ✅ 完整支持 |
|
|
137
|
+
| MySQL / MariaDB | ✅ 完整支持 |
|
|
138
|
+
| SQLite | ✅ 完整支持 |
|
|
139
|
+
| SQL Server | 🔜 计划中 |
|
|
140
|
+
| Oracle | 🔜 计划中 |
|
|
141
|
+
|
|
142
|
+
## 开发
|
|
143
|
+
|
|
144
|
+
```bash
|
|
145
|
+
git clone https://github.com/ZhangYaoSong/dbgraph.git
|
|
146
|
+
cd dbgraph
|
|
147
|
+
npm install
|
|
148
|
+
npm run build
|
|
149
|
+
npm run cli -- init -i # 初始化当前目录 + 索引
|
|
150
|
+
npm run cli -- serve # 从源码启动 MCP 服务器
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
## 鸣谢
|
|
154
|
+
|
|
155
|
+
受 [CodeGraph](https://github.com/colbymchenry/codegraph) 启发——一个优秀的代码知识图谱工具，本项目将其思路应用于数据库 schema 领域。
|
|
156
|
+
|
|
157
|
+
## 许可证
|
|
158
|
+
|
|
159
|
+
MIT
|
package/README.md
CHANGED
|
@@ -1,56 +1,100 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
1
3
|
# DBGraph
|
|
2
4
|
|
|
5
|
+
### Database Knowledge Graph — Introspect schemas into a searchable graph, expose over MCP for AI agents
|
|
6
|
+
|
|
7
|
+
**Zero-guess SQL generation · Sub-millisecond schema lookups · 100% local**
|
|
8
|
+
|
|
3
9
|
[](https://www.npmjs.com/package/dbgraph)
|
|
4
|
-
[](LICENSE)
|
|
11
|
+
[](https://nodejs.org/)
|
|
6
12
|
|
|
7
|
-
|
|
13
|
+
[](#supported-engines)
|
|
14
|
+
[](#supported-engines)
|
|
15
|
+
[](#supported-engines)
|
|
8
16
|
|
|
9
|
-
|
|
17
|
+
</div>
|
|
10
18
|
|
|
11
|
-
|
|
19
|
+
## Get Started
|
|
12
20
|
|
|
13
|
-
```
|
|
14
|
-
|
|
15
|
-
|
|
21
|
+
```bash
|
|
22
|
+
# Zero-install (recommended)
|
|
23
|
+
npx dbgraph
|
|
16
24
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
→ 写 SQL → dbgraph_execute → 成功
|
|
25
|
+
# Or install globally
|
|
26
|
+
npm i -g dbgraph
|
|
20
27
|
```
|
|
21
28
|
|
|
22
|
-
|
|
29
|
+
### Initialize a project
|
|
23
30
|
|
|
24
31
|
```bash
|
|
25
|
-
|
|
26
|
-
|
|
32
|
+
cd your-project
|
|
33
|
+
npx dbgraph init -i # init + index in one step
|
|
34
|
+
```
|
|
27
35
|
|
|
28
|
-
|
|
29
|
-
|
|
36
|
+
<sub>`dbgraph init` creates `.dbgraph/` and a default `dbgraph-db.json` config. Adding `-i` (`--index`) also introspects your databases immediately. Edit `dbgraph-db.json` first to configure your connections.</sub>
|
|
37
|
+
|
|
38
|
+
### Start the MCP server
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
npx dbgraph serve
|
|
30
42
|
```
|
|
31
43
|
|
|
32
|
-
|
|
44
|
+
AI agents connected to MCP automatically discover `dbgraph_*` tools for schema-aware SQL generation.
|
|
45
|
+
|
|
46
|
+
## Why DBGraph?
|
|
47
|
+
|
|
48
|
+
LLMs write wrong SQL because they **don't know your schema** — guessing table names, column names, and JOIN conditions. DBGraph extracts your complete database schema (tables, columns, types, foreign keys, constraints, indexes) into a **searchable knowledge graph** stored in `.dbgraph/`. AI agents query it via MCP tools directly — no live database connection needed.
|
|
49
|
+
|
|
50
|
+
```
|
|
51
|
+
Without DBGraph:
|
|
52
|
+
LLM → guess names → write SQL → run → error → guess again → loop
|
|
33
53
|
|
|
34
|
-
|
|
54
|
+
With DBGraph:
|
|
55
|
+
LLM → dbgraph_context("orders") → get exact schema
|
|
56
|
+
→ write SQL → success
|
|
57
|
+
```
|
|
35
58
|
|
|
36
|
-
##
|
|
59
|
+
## CLI Reference
|
|
37
60
|
|
|
38
|
-
|
|
61
|
+
| Command | Description |
|
|
62
|
+
|---------|-------------|
|
|
63
|
+
| `init` | Initialize `.dbgraph` project (`-i` to index immediately) |
|
|
64
|
+
| `index` | Run database introspection |
|
|
65
|
+
| `serve` | Start MCP server (use `--auto-refresh` to watch for schema changes) |
|
|
66
|
+
| `query` | Search tables, columns, views, indexes |
|
|
67
|
+
| `context` | View full table schema (call before writing SQL) |
|
|
68
|
+
| `trace` | Trace foreign key join paths between tables |
|
|
69
|
+
| `explore` | Explore multiple related tables at once |
|
|
70
|
+
| `sources` | List configured database sources |
|
|
71
|
+
| `status` | Knowledge graph statistics |
|
|
72
|
+
| `test` | Test database connections |
|
|
73
|
+
| `config` | View or create configuration |
|
|
39
74
|
|
|
40
|
-
|
|
75
|
+
All commands default to the current directory. Pass a directory path to target another project:
|
|
41
76
|
|
|
42
77
|
```bash
|
|
43
|
-
#
|
|
44
|
-
dbgraph
|
|
78
|
+
npx dbgraph status # current directory
|
|
79
|
+
npx dbgraph status ./other-project # another project
|
|
45
80
|
```
|
|
46
81
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
82
|
+
## MCP Tools
|
|
83
|
+
|
|
84
|
+
After starting `dbgraph serve`, AI agents can call:
|
|
50
85
|
|
|
51
|
-
|
|
86
|
+
| Tool | Purpose |
|
|
87
|
+
|------|---------|
|
|
88
|
+
| `dbgraph_search` | Search schema objects by name |
|
|
89
|
+
| `dbgraph_context` | **Full table schema** — columns, types, PKs, FKs, indexes |
|
|
90
|
+
| `dbgraph_trace` | Trace FK join paths (orders → users) |
|
|
91
|
+
| `dbgraph_explore` | Batch schema for multiple tables |
|
|
92
|
+
| `dbgraph_sources` | List all database sources |
|
|
93
|
+
| `dbgraph_status` | Graph health and statistics |
|
|
52
94
|
|
|
53
|
-
|
|
95
|
+
## Configuration
|
|
96
|
+
|
|
97
|
+
Edit `dbgraph-db.json` in your project root:
|
|
54
98
|
|
|
55
99
|
```json
|
|
56
100
|
{
|
|
@@ -73,274 +117,42 @@ dbgraph init ./demo-project
|
|
|
73
117
|
}
|
|
74
118
|
```
|
|
75
119
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
# 搜索表/列
|
|
88
|
-
node dist/bin/dbgraph.js query orders ./demo-project
|
|
89
|
-
node dist/bin/dbgraph.js query users --kind table ./demo-project
|
|
90
|
-
|
|
91
|
-
# 查看完整表结构
|
|
92
|
-
node dist/bin/dbgraph.js context public.orders ./demo-project
|
|
93
|
-
|
|
94
|
-
# 查看状态
|
|
95
|
-
node dist/bin/dbgraph.js status ./demo-project
|
|
96
|
-
|
|
97
|
-
# 列出数据源
|
|
98
|
-
node dist/bin/dbgraph.js sources ./demo-project
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
## 配置说明
|
|
102
|
-
|
|
103
|
-
### `dbgraph-db.json`
|
|
104
|
-
|
|
105
|
-
| 字段 | 类型 | 必填 | 说明 |
|
|
106
|
-
|------|------|------|------|
|
|
107
|
-
| `alias` | string | 是 | 数据库别名，在知识图谱中用 `db://@alias` 标识 |
|
|
108
|
-
| `engine` | string | 是 | 数据库引擎：`postgresql` / `mysql` / `mariadb` / `sqlite` |
|
|
109
|
-
| `host` | string | 否 | 主机地址（SQLite 不需要）|
|
|
110
|
-
| `port` | number | 否 | 端口（默认根据引擎判断）|
|
|
111
|
-
| `database` | string | 是(非SQLite) | 数据库名 |
|
|
112
|
-
| `schemas` | string[] | 否 | 要提取的 schema 列表（默认全部）|
|
|
113
|
-
| `path` | string | 是(SQLite) | SQLite 文件路径 |
|
|
114
|
-
| `auth` | string | 否 | 认证方式，如 `env:DB_PASSWORD`（环境变量）、`~/.pgpass` |
|
|
115
|
-
| `ssl` | boolean | 否 | 是否启用 SSL 连接 |
|
|
116
|
-
|
|
117
|
-
## CLI 命令参考
|
|
118
|
-
|
|
119
|
-
所有命令格式：
|
|
120
|
-
```
|
|
121
|
-
node dist/bin/dbgraph.js <命令> [选项] [目录参数]
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
| 命令 | 说明 |
|
|
125
|
-
|------|------|
|
|
126
|
-
| `init` | 初始化 .dbgraph 项目 + 配置 |
|
|
127
|
-
| `index` | 运行数据库内省，提取 schema |
|
|
128
|
-
| `serve` | 启动 MCP 服务器（供 AI Agent 使用）|
|
|
129
|
-
| `query` | 搜索表/列/视图 |
|
|
130
|
-
| `context` | 查看完整表结构 |
|
|
131
|
-
| `status` | 知识图谱状态统计 |
|
|
132
|
-
| `sources` | 列出数据源 |
|
|
133
|
-
| `test` | 测试数据库连接 |
|
|
134
|
-
| `config` | 查看/创建配置 |
|
|
135
|
-
|
|
136
|
-
### `init`
|
|
137
|
-
|
|
138
|
-
```bash
|
|
139
|
-
# 初始化项目
|
|
140
|
-
node dist/bin/dbgraph.js init ./my-project
|
|
141
|
-
|
|
142
|
-
# 初始化后立即索引
|
|
143
|
-
node dist/bin/dbgraph.js init ./my-project --index
|
|
144
|
-
|
|
145
|
-
# 指定配置文件路径
|
|
146
|
-
node dist/bin/dbgraph.js init ./my-project -c ./my-project/custom-config.json
|
|
147
|
-
```
|
|
148
|
-
|
|
149
|
-
### `index`
|
|
150
|
-
|
|
151
|
-
```bash
|
|
152
|
-
# 索引指定项目配置的数据库
|
|
153
|
-
node dist/bin/dbgraph.js index ./my-project
|
|
154
|
-
|
|
155
|
-
# 指定配置文件
|
|
156
|
-
node dist/bin/dbgraph.js index ./my-project -c ./my-project/custom-config.json
|
|
157
|
-
```
|
|
158
|
-
|
|
159
|
-
### `serve`（MCP 模式）
|
|
120
|
+
| Field | Type | Required | Description |
|
|
121
|
+
|-------|------|----------|-------------|
|
|
122
|
+
| `alias` | string | yes | Database alias (`db://@alias` in graph) |
|
|
123
|
+
| `engine` | string | yes | `postgresql` / `mysql` / `mariadb` / `sqlite` |
|
|
124
|
+
| `host` | string | no | Host address |
|
|
125
|
+
| `port` | number | no | Port (default depends on engine) |
|
|
126
|
+
| `database` | string | depends | Required for PostgreSQL/MySQL |
|
|
127
|
+
| `schemas` | string[] | no | Schemas to introspect (default: all) |
|
|
128
|
+
| `path` | string | depends | Required for SQLite |
|
|
129
|
+
| `auth` | string | no | `env:VAR_NAME` or `~/.pgpass` |
|
|
130
|
+
| `ssl` | boolean | no | Enable SSL |
|
|
160
131
|
|
|
161
|
-
|
|
162
|
-
# 启动 MCP stdio 服务器
|
|
163
|
-
node dist/bin/dbgraph.js serve ./my-project
|
|
164
|
-
```
|
|
165
|
-
|
|
166
|
-
AI Agent 连接到 MCP 后自动发现 `dbgraph_*` 工具。
|
|
167
|
-
|
|
168
|
-
### `query`
|
|
169
|
-
|
|
170
|
-
```bash
|
|
171
|
-
# 搜索
|
|
172
|
-
node dist/bin/dbgraph.js query orders ./my-project
|
|
132
|
+
## Supported Engines
|
|
173
133
|
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
134
|
+
| Engine | Status |
|
|
135
|
+
|--------|--------|
|
|
136
|
+
| PostgreSQL | ✅ Full support |
|
|
137
|
+
| MySQL / MariaDB | ✅ Full support |
|
|
138
|
+
| SQLite | ✅ Full support |
|
|
139
|
+
| SQL Server | 🔜 Planned |
|
|
140
|
+
| Oracle | 🔜 Planned |
|
|
177
141
|
|
|
178
|
-
|
|
179
|
-
node dist/bin/dbgraph.js query orders --json ./my-project
|
|
180
|
-
```
|
|
181
|
-
|
|
182
|
-
### `context`
|
|
142
|
+
## Development
|
|
183
143
|
|
|
184
144
|
```bash
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
node dist/bin/dbgraph.js context public.orders ./my-project
|
|
188
|
-
```
|
|
189
|
-
|
|
190
|
-
输出示例：
|
|
191
|
-
```
|
|
192
|
-
## Table: public.orders
|
|
193
|
-
|
|
194
|
-
Database: prod (postgresql)
|
|
195
|
-
|
|
196
|
-
| Column | Type | Nullable | Default | PK | FK |
|
|
197
|
-
|-------------|-------------|----------|----------|----|-----------|
|
|
198
|
-
| id | bigint | NO | | PK | |
|
|
199
|
-
| user_id | integer | NO | | | users.id |
|
|
200
|
-
| status | varchar(20) | NO | pending | | |
|
|
201
|
-
| total_amount| numeric(10,2)| YES | 0.00 | | |
|
|
202
|
-
| created_at | timestamp | NO | now() | | |
|
|
203
|
-
|
|
204
|
-
Indexes:
|
|
205
|
-
- idx_orders_status on (status)
|
|
206
|
-
- pk_orders PRIMARY KEY using btree (id)
|
|
207
|
-
|
|
208
|
-
Foreign Keys:
|
|
209
|
-
- fk_orders_user → users(id) ON DELETE CASCADE
|
|
210
|
-
```
|
|
211
|
-
|
|
212
|
-
## MCP 工具
|
|
213
|
-
|
|
214
|
-
启动 `dbgraph serve` 后，AI Agent 可以调用以下工具：
|
|
215
|
-
|
|
216
|
-
| 工具 | 用途 | 推荐时机 |
|
|
217
|
-
|------|------|---------|
|
|
218
|
-
| `dbgraph_search` | 搜索表/列/视图/索引 | 不确定名字时 |
|
|
219
|
-
| `dbgraph_context` | **主要入口** —— 返回完整表结构 + 列 + FK + 索引 | 写 SQL 前 |
|
|
220
|
-
| `dbgraph_trace` | 追踪 FK 关联路径（orders→users） | 需要写 JOIN 时 |
|
|
221
|
-
| `dbgraph_explore` | 一次性探索多张相关表 | 复杂查询涉及多表时 |
|
|
222
|
-
| `dbgraph_sources` | 列出所有已配置的数据库源 | 了解有哪些库可用 |
|
|
223
|
-
| `dbgraph_status` | 知识图谱统计 | 检查是否已索引 |
|
|
224
|
-
|
|
225
|
-
### 推荐工具调用策略
|
|
226
|
-
|
|
227
|
-
```
|
|
228
|
-
写 SQL 前的标准流程:
|
|
229
|
-
1. dbgraph_search("order") → 找到 order 相关表
|
|
230
|
-
2. dbgraph_context("public.orders") → 获取完整 schema
|
|
231
|
-
3. dbgraph_context("public.users") → 获取关联表 schema
|
|
232
|
-
4. dbgraph_trace("orders", "users") → 验证 FK 关联
|
|
233
|
-
5. LLM 写出精确 SQL
|
|
234
|
-
```
|
|
235
|
-
|
|
236
|
-
## 支持引擎
|
|
237
|
-
|
|
238
|
-
| 引擎 | 状态 | 说明 |
|
|
239
|
-
|------|------|------|
|
|
240
|
-
| PostgreSQL | ✅ 完整支持 | `information_schema` + `pg_catalog` |
|
|
241
|
-
| MySQL / MariaDB | ✅ 完整支持 | `information_schema` |
|
|
242
|
-
| SQLite | ✅ 完整支持 | `pragma table_info` / `foreign_key_list` |
|
|
243
|
-
| SQL Server | 🔜 计划中 | |
|
|
244
|
-
| Oracle | 🔜 计划中 | |
|
|
245
|
-
| MongoDB | 🔜 计划中 | |
|
|
246
|
-
|
|
247
|
-
## 项目结构
|
|
248
|
-
|
|
249
|
-
```
|
|
250
|
-
dbgraph/
|
|
251
|
-
├── src/
|
|
252
|
-
│ ├── index.ts # DBGraph 主类
|
|
253
|
-
│ ├── types.ts # 所有类型 (Node, Edge, TableSchema...)
|
|
254
|
-
│ ├── config.ts # dbgraph-db.json 配置管理
|
|
255
|
-
│ ├── directory.ts # .dbgraph 目录管理
|
|
256
|
-
│ ├── errors.ts # 错误类型
|
|
257
|
-
│ ├── utils.ts # 工具函数
|
|
258
|
-
│ │
|
|
259
|
-
│ ├── db/ # SQLite 存储层
|
|
260
|
-
│ │ ├── schema.sql # 表结构 (nodes/edges FTS5)
|
|
261
|
-
│ │ ├── sqlite-adapter.ts # node:sqlite 适配
|
|
262
|
-
│ │ ├── migrations.ts # 版本迁移
|
|
263
|
-
│ │ ├── queries.ts # CRUD + FTS5 搜索 + 评分 (LRU缓存)
|
|
264
|
-
│ │ └── index.ts # 连接管理
|
|
265
|
-
│ │
|
|
266
|
-
│ ├── graph/
|
|
267
|
-
│ │ └── traversal.ts # BFS/DFS/寻路/影响半径
|
|
268
|
-
│ │
|
|
269
|
-
│ ├── context/
|
|
270
|
-
│ │ ├── index.ts # 表结构组装
|
|
271
|
-
│ │ └── formatter.ts # Markdown 输出
|
|
272
|
-
│ │
|
|
273
|
-
│ ├── introspect/ # 数据库内省
|
|
274
|
-
│ │ ├── base.ts # 基类 + Node/Edge 工厂
|
|
275
|
-
│ │ ├── index.ts # 工厂方法
|
|
276
|
-
│ │ ├── connection.ts # 连接管理
|
|
277
|
-
│ │ ├── postgres.ts # PostgreSQL
|
|
278
|
-
│ │ ├── mysql.ts # MySQL
|
|
279
|
-
│ │ └── sqlite.ts # SQLite
|
|
280
|
-
│ │
|
|
281
|
-
│ ├── mcp/ # MCP 服务器
|
|
282
|
-
│ │ ├── transport.ts # JSON-RPC 传输
|
|
283
|
-
│ │ ├── session.ts # 会话管理
|
|
284
|
-
│ │ ├── engine.ts # 引擎 + 生命周期
|
|
285
|
-
│ │ ├── tools.ts # 6 个 dbgraph_* 工具
|
|
286
|
-
│ │ ├── server-instructions.ts # LLM 指引
|
|
287
|
-
│ │ └── index.ts # MCPServer
|
|
288
|
-
│ │
|
|
289
|
-
│ └── bin/
|
|
290
|
-
│ └── dbgraph.ts # CLI
|
|
291
|
-
```
|
|
292
|
-
|
|
293
|
-
## 开发
|
|
294
|
-
|
|
295
|
-
```bash
|
|
296
|
-
# 安装依赖
|
|
145
|
+
git clone https://github.com/ZhangYaoSong/dbgraph.git
|
|
146
|
+
cd dbgraph
|
|
297
147
|
npm install
|
|
298
|
-
|
|
299
|
-
# 构建
|
|
300
148
|
npm run build
|
|
301
|
-
|
|
302
|
-
#
|
|
303
|
-
npm run dev
|
|
304
|
-
|
|
305
|
-
# 运行帮助
|
|
306
|
-
node dist/bin/dbgraph.js --help
|
|
307
|
-
|
|
308
|
-
# 快速构建 + 运行（等价于 build 后执行 node dist/bin/dbgraph.js）
|
|
309
|
-
npm run cli -- status ./my-project
|
|
149
|
+
npm run cli -- init -i # init current dir + index
|
|
150
|
+
npm run cli -- serve # start MCP server from source
|
|
310
151
|
```
|
|
311
152
|
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
在 `src/introspect/` 下创建新文件（如 `mssql.ts`），实现 `BaseIntrospector` 抽象类：
|
|
315
|
-
|
|
316
|
-
```typescript
|
|
317
|
-
import { BaseIntrospector } from './base';
|
|
318
|
-
|
|
319
|
-
export class MSSQLIntrospector extends BaseIntrospector {
|
|
320
|
-
async extractAll(): Promise<IntrospectResult> {
|
|
321
|
-
// 1. 连接数据库
|
|
322
|
-
// 2. 查询 information_schema
|
|
323
|
-
// 3. 调用 this.makeNode() / this.makeEdge()
|
|
324
|
-
// 4. 返回 IntrospectResult
|
|
325
|
-
}
|
|
326
|
-
}
|
|
327
|
-
```
|
|
328
|
-
|
|
329
|
-
然后在 `src/introspect/index.ts` 中注册：
|
|
330
|
-
|
|
331
|
-
```typescript
|
|
332
|
-
case 'mssql':
|
|
333
|
-
return new MSSQLIntrospector(config);
|
|
334
|
-
```
|
|
335
|
-
|
|
336
|
-
## 参考
|
|
337
|
-
|
|
338
|
-
- **[AGENTS.md](AGENTS.md)** — OpenCode AI Agent 的项目指引，包含开发命令速查、架构要点和 CodeGraph 使用说明。
|
|
339
|
-
- **CodeGraph** — 本项目已初始化 CodeGraph 索引（`.codegraph/`），Agent 可优先使用 `codegraph_*` 工具进行结构查询，速度远超 grep。
|
|
340
|
-
|
|
341
|
-
## 鸣谢
|
|
153
|
+
## Acknowledgments
|
|
342
154
|
|
|
343
|
-
|
|
155
|
+
Inspired by [CodeGraph](https://github.com/colbymchenry/codegraph) — an excellent code knowledge graph tool that this project adapts to the database schema domain.
|
|
344
156
|
|
|
345
157
|
## License
|
|
346
158
|
|
package/package.json
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dbgraph",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.2",
|
|
4
4
|
"description": "Database knowledge graph for LLM-powered SQL generation. Introspect database schemas into a local-first knowledge graph, exposed over MCP.",
|
|
5
5
|
"main": "dist/index.js",
|
|
6
6
|
"types": "dist/index.d.ts",
|
|
7
7
|
"bin": {
|
|
8
|
-
"dbgraph": "
|
|
8
|
+
"dbgraph": "dist/bin/dbgraph.js"
|
|
9
9
|
},
|
|
10
10
|
"files": [
|
|
11
11
|
"dist",
|