npm - dbgraph - Versions diffs - 0.1.1 → 0.1.3 - Mend

dbgraph 0.1.1 → 0.1.3

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 (3) hide show

package/README.ZH-cn.md CHANGED Viewed

@@ -1,64 +1,153 @@
+<div align="center">
 # DBGraph
+### 数据库知识图谱 — 将数据库 schema 提取为知识图谱，通过 MCP 供 AI 代理使用
+**零猜测 SQL 生成 · 亚毫秒级 schema 查询 · 100% 本地运行**
 [![npm version](https://img.shields.io/npm/v/dbgraph)](https://www.npmjs.com/package/dbgraph)
-[![License](https://img.shields.io/npm/l/dbgraph)](LICENSE)
-[![Node](https://img.shields.io/node/v/dbgraph)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/Node.js-%3E%3D22.5-brightgreen)](https://nodejs.org/)
-数据库知识图谱 —— 将数据库 schema 提取为本地知识图谱，通过 MCP 供 LLM 理解库表结构，从而减少 SQL 生成错误。
+[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-支持-blue)](#支持引擎)
+[![MySQL](https://img.shields.io/badge/MySQL-支持-blue)](#支持引擎)
+[![SQLite](https://img.shields.io/badge/SQLite-支持-blue)](#支持引擎)
-## 原理
+</div>
-LLM 写 SQL 犯错的最大原因是**不知道你的库有什么**——表名靠猜、列名靠蒙、JOIN 条件靠碰运气。DBGraph 把数据库的 schema 信息（表、列、类型、外键、约束、索引）全部提取成一个**可搜索的知识图谱**存在 `.dbgraph/` 目录下，LLM 通过 MCP 工具直接查询，不直接连数据库。
+## 快速开始
+```bash
+# 零安装（推荐）
+npx dbgraph
+# 或全局安装
+npm i -g dbgraph
 ```
-传统流程:
-  LLM → 猜表名列名 → 写 SQL → 执行 → 报错 → 再猜 → 循环
-DBGraph 流程:
-  LLM → dbgraph_context("orders") → 拿到精确 schema
-       → 写 SQL → dbgraph_execute → 成功
+### 初始化项目
+```bash
+cd your-project
+npx dbgraph init -i       # 一步完成初始化 + 索引
 ```
-## 快速安装
+<sub>`dbgraph init` 创建 `.dbgraph/` 目录和默认 `dbgraph-db.json` 配置。加上 `-i`（`--index`）会立即内省数据库。编辑 `dbgraph-db.json` 配置数据库连接。</sub>
+### 启动 MCP 服务器
 ```bash
-# 全局安装
-npm install -g dbgraph
+npx dbgraph serve
+```
+AI 代理连接 MCP 后自动发现 `dbgraph_*` 工具，用于 schema 感知的 SQL 生成。
-# 或直接用 npx（无需安装）
-npx dbgraph --help
+## MCP 配置
+在 AI 代理的配置文件中添加 DBGraph 作为 MCP 服务器：
+**opencode**（`~/.config/opencode/opencode.json`）：
+```json
+{
+  "mcp": {
+    "dbgraph": {
+      "type": "local",
+      "command": ["npx", "dbgraph", "serve", "--auto-refresh"],
+      "enabled": true
+    }
+  }
+}
 ```
-## 前置要求
+**Cursor** → 设置 → MCP Servers → 添加：
+```json
+{
+  "mcpServers": {
+    "dbgraph": {
+      "command": "npx",
+      "args": ["dbgraph", "serve", "--auto-refresh"]
+    }
+  }
+}
+```
-- **Node.js >= 22.5.0**（需要内置 `node:sqlite` 支持 FTS5 + WAL）
+**Claude Code**（`~/.claude/settings.json`）：
+```json
+{
+  "mcpServers": {
+    "dbgraph": {
+      "command": "npx",
+      "args": ["dbgraph", "serve", "--auto-refresh"]
+    }
+  }
+}
+```
-## 快速开始
+**Codex CLI**（`~/.codexclirc.json`）：
+```json
+{
+  "mcpServers": {
+    "dbgraph": {
+      "type": "local",
+      "command": ["npx", "dbgraph", "serve", "--auto-refresh"]
+    }
+  }
+}
+```
-> 安装后直接使用 `dbgraph` 命令。如需本地开发，可用 `npm run cli -- <命令>` 替代（自动先构建）。
+## 为什么用 DBGraph？
-### 1. 初始化项目
+LLM 写 SQL 出错的最大原因是**不知道库表结构**——表名靠猜、列名靠蒙、JOIN 条件靠碰运气。DBGraph 把数据库 schema（表、列、类型、外键、约束、索引）提取为**可搜索的知识图谱**存在 `.dbgraph/` 中。AI 代理通过 MCP 工具直接查询，无需数据库直连。
-所有命令默认使用当前目录，也可指定目录路径。
+```
+传统流程:
+  LLM → 猜名列名 → 写 SQL → 报错 → 再猜 → 循环
-```bash
-# 初始化当前目录
-dbgraph init
+DBGraph 流程:
+  LLM → dbgraph_context("orders") → 拿到精确 schema
+       → 写 SQL → 成功
+```
+## CLI 命令
+| 命令 | 说明 |
+|---------|-------------|
+| `init` | 初始化 `.dbgraph` 项目（`-i` 立即索引）|
+| `index` | 运行数据库内省 |
+| `serve` | 启动 MCP 服务器（`--auto-refresh` 自动检测 schema 变更）|
+| `query` | 搜索表、列、视图、索引 |
+| `context` | 查看完整表结构（写 SQL 前必调）|
+| `trace` | 追踪外键关联路径 |
+| `explore` | 批量查看多张表 schema |
+| `sources` | 列出已配置的数据库源 |
+| `status` | 知识图谱统计 |
+| `test` | 测试数据库连接 |
+| `config` | 查看或创建配置 |
-# 初始化并立即索引（一步完成）
-dbgraph init -i
+所有命令默认使用当前目录，也可指定目录：
-# 初始化指定目录
-dbgraph init ./demo-project
+```bash
+npx dbgraph status                  # 当前目录
+npx dbgraph status ./other-project  # 其他项目
 ```
-这会创建：
-- `.dbgraph/` —— 知识图谱数据目录
-- `dbgraph-db.json` —— 数据库连接配置（默认模板）
+## MCP 工具
+启动 `dbgraph serve` 后，AI 代理可调用：
+| 工具 | 用途 |
+|------|---------|
+| `dbgraph_search` | 按名称搜索 schema 对象 |
+| `dbgraph_context` | **完整表结构** — 列、类型、主键、外键、索引 |
+| `dbgraph_trace` | 追踪外键关联路径（orders → users）|
+| `dbgraph_explore` | 批量查看多张表 |
+| `dbgraph_sources` | 列出所有数据库源 |
+| `dbgraph_status` | 图谱健康状态与统计 |
-### 2. 配置数据库连接
+## 配置说明
-编辑 `demo-project/dbgraph-db.json`，填入你的数据库信息：
+编辑项目根目录的 `dbgraph-db.json`：
 ```json
 {
@@ -81,277 +170,43 @@ dbgraph init ./demo-project
 }
 ```
-### 3. 提取 Schema
-```bash
-dbgraph index
-```
-把数据库 schema 提取到知识图谱中。首次运行会连接所有配置的数据库，提取表/列/外键/索引/视图等信息。
-### 4. 查询知识图谱
-```bash
-# 搜索表/列
-dbgraph query orders
-dbgraph query users --kind table
-# 查看完整表结构
-dbgraph context public.orders
-# 查看状态
-dbgraph status
-# 列出数据源
-dbgraph sources
-```
-## 配置说明
-### `dbgraph-db.json`
 | 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `alias` | string | 是 | 数据库别名，在知识图谱中用 `db://@alias` 标识 |
-| `engine` | string | 是 | 数据库引擎：`postgresql` / `mysql` / `mariadb` / `sqlite` |
-| `host` | string | 否 | 主机地址（SQLite 不需要）|
+|-------|------|----------|-------------|
+| `alias` | string | 是 | 数据库别名（图谱中以 `db://@alias` 标识）|
+| `engine` | string | 是 | `postgresql` / `mysql` / `mariadb` / `sqlite` |
+| `host` | string | 否 | 主机地址 |
 | `port` | number | 否 | 端口（默认根据引擎判断）|
-| `database` | string | 是(非SQLite) | 数据库名 |
+| `database` | string | 视情况 | PostgreSQL/MySQL 必填 |
 | `schemas` | string[] | 否 | 要提取的 schema 列表（默认全部）|
-| `path` | string | 是(SQLite) | SQLite 文件路径 |
-| `auth` | string | 否 | 认证方式，如 `env:DB_PASSWORD`（环境变量）、`~/.pgpass` |
-| `ssl` | boolean | 否 | 是否启用 SSL 连接 |
-## CLI 命令参考
-所有命令格式：`dbgraph <命令> [选项] [目录]`
-不填目录时默认为当前目录。
-| 命令 | 说明 |
-|------|------|
-| `init` | 初始化 .dbgraph 项目 + 配置 |
-| `index` | 运行数据库内省，提取 schema |
-| `serve` | 启动 MCP 服务器（供 AI Agent 使用）|
-| `query` | 搜索表/列/视图 |
-| `context` | 查看完整表结构 |
-| `status` | 知识图谱状态统计 |
-| `sources` | 列出数据源 |
-| `test` | 测试数据库连接 |
-| `config` | 查看/创建配置 |
-### `init`
-```bash
-# 初始化当前目录
-dbgraph init
-# 初始化并立即索引
-dbgraph init -i
-# 初始化指定目录
-dbgraph init ./my-project
-# 指定配置文件路径
-dbgraph init ./my-project -c ./my-project/custom-config.json
-```
-### `index`
-```bash
-# 索引当前目录配置的数据库
-dbgraph index
-# 指定配置文件
-dbgraph index ./my-project -c ./my-project/custom-config.json
-```
-### `serve`（MCP 模式）
-```bash
-# 启动 MCP stdio 服务器（当前目录）
-dbgraph serve
-# 指定项目目录
-dbgraph serve ./my-project
-```
-AI Agent 连接到 MCP 后自动发现 `dbgraph_*` 工具。
-### `query`
-```bash
-# 搜索
-dbgraph query orders
-# 按类型过滤
-dbgraph query orders --kind table
-dbgraph query amount --kind column
-# JSON 格式输出
-dbgraph query orders --json
-```
-### `context`
-```bash
-# 查看表结构
-dbgraph context orders
-dbgraph context public.orders
-```
-输出示例：
-```
-## Table: public.orders
-Database: prod (postgresql)
-| Column       | Type         | Nullable | Default  | PK | FK        |
-|-------------|-------------|----------|----------|----|-----------|
-| id          | bigint       | NO       |          | PK |           |
-| user_id     | integer      | NO       |          |    | users.id  |
-| status      | varchar(20)  | NO       | pending  |    |           |
-| total_amount| numeric(10,2)| YES      | 0.00     |    |           |
-| created_at  | timestamp    | NO       | now()    |    |           |
-Indexes:
-  - idx_orders_status on (status)
-  - pk_orders PRIMARY KEY using btree (id)
-Foreign Keys:
-  - fk_orders_user → users(id) ON DELETE CASCADE
-```
-## MCP 工具
-启动 `dbgraph serve` 后，AI Agent 可以调用以下工具：
-| 工具 | 用途 | 推荐时机 |
-|------|------|---------|
-| `dbgraph_search` | 搜索表/列/视图/索引 | 不确定名字时 |
-| `dbgraph_context` | **主要入口** —— 返回完整表结构 + 列 + FK + 索引 | 写 SQL 前 |
-| `dbgraph_trace` | 追踪 FK 关联路径（orders→users） | 需要写 JOIN 时 |
-| `dbgraph_explore` | 一次性探索多张相关表 | 复杂查询涉及多表时 |
-| `dbgraph_sources` | 列出所有已配置的数据库源 | 了解有哪些库可用 |
-| `dbgraph_status` | 知识图谱统计 | 检查是否已索引 |
-### 推荐工具调用策略
-```
-写 SQL 前的标准流程:
-1. dbgraph_search("order")        → 找到 order 相关表
-2. dbgraph_context("public.orders") → 获取完整 schema
-3. dbgraph_context("public.users")   → 获取关联表 schema
-4. dbgraph_trace("orders", "users")  → 验证 FK 关联
-5. LLM 写出精确 SQL
-```
+| `path` | string | 视情况 | SQLite 必填 |
+| `auth` | string | 否 | `env:VAR_NAME` 或 `~/.pgpass` |
+| `ssl` | boolean | 否 | 启用 SSL |
 ## 支持引擎
-| 引擎 | 状态 | 说明 |
-|------|------|------|
-| PostgreSQL | ✅ 完整支持 | `information_schema` + `pg_catalog` |
-| MySQL / MariaDB | ✅ 完整支持 | `information_schema` |
-| SQLite | ✅ 完整支持 | `pragma table_info` / `foreign_key_list` |
-| SQL Server | 🔜 计划中 | |
-| Oracle | 🔜 计划中 | |
-| MongoDB | 🔜 计划中 | |
-## 项目结构
-```
-dbgraph/
-├── src/
-│   ├── index.ts                        # DBGraph 主类
-│   ├── types.ts                        # 所有类型 (Node, Edge, TableSchema...)
-│   ├── config.ts                       # dbgraph-db.json 配置管理
-│   ├── directory.ts                    # .dbgraph 目录管理
-│   ├── errors.ts                       # 错误类型
-│   ├── utils.ts                        # 工具函数
-│   │
-│   ├── db/                             # SQLite 存储层
-│   │   ├── schema.sql                  # 表结构 (nodes/edges FTS5)
-│   │   ├── sqlite-adapter.ts           # node:sqlite 适配
-│   │   ├── migrations.ts               # 版本迁移
-│   │   ├── queries.ts                  # CRUD + FTS5 搜索 + 评分 (LRU缓存)
-│   │   └── index.ts                    # 连接管理
-│   │
-│   ├── graph/
-│   │   └── traversal.ts                # BFS/DFS/寻路/影响半径
-│   │
-│   ├── context/
-│   │   ├── index.ts                    # 表结构组装
-│   │   └── formatter.ts                # Markdown 输出
-│   │
-│   ├── introspect/                     # 数据库内省
-│   │   ├── base.ts                     # 基类 + Node/Edge 工厂
-│   │   ├── index.ts                    # 工厂方法
-│   │   ├── connection.ts               # 连接管理
-│   │   ├── postgres.ts                 # PostgreSQL
-│   │   ├── mysql.ts                    # MySQL
-│   │   └── sqlite.ts                   # SQLite
-│   │
-│   ├── mcp/                            # MCP 服务器
-│   │   ├── transport.ts                # JSON-RPC 传输
-│   │   ├── session.ts                  # 会话管理
-│   │   ├── engine.ts                   # 引擎 + 生命周期
-│   │   ├── tools.ts                    # 6 个 dbgraph_* 工具
-│   │   ├── server-instructions.ts      # LLM 指引
-│   │   └── index.ts                    # MCPServer
-│   │
-│   └── bin/
-│       └── dbgraph.ts                  # CLI
-```
+| 引擎 | 状态 |
+|--------|------|
+| PostgreSQL | ✅ 完整支持 |
+| MySQL / MariaDB | ✅ 完整支持 |
+| SQLite | ✅ 完整支持 |
+| SQL Server | 🔜 计划中 |
+| Oracle | 🔜 计划中 |
 ## 开发
 ```bash
-# 安装依赖
+git clone https://github.com/ZhangYaoSong/dbgraph.git
+cd dbgraph
 npm install
-# 构建
 npm run build
-# 开发模式（watch）
-npm run dev
-# 运行帮助
-npm run cli -- --help
+npm run cli -- init -i   # 初始化当前目录 + 索引
+npm run cli -- serve      # 从源码启动 MCP 服务器
 ```
-### 添加新数据库引擎
-在 `src/introspect/` 下创建新文件（如 `mssql.ts`），实现 `BaseIntrospector` 抽象类：
-```typescript
-import { BaseIntrospector } from './base';
-export class MSSQLIntrospector extends BaseIntrospector {
-  async extractAll(): Promise<IntrospectResult> {
-    // 1. 连接数据库
-    // 2. 查询 information_schema
-    // 3. 调用 this.makeNode() / this.makeEdge()
-    // 4. 返回 IntrospectResult
-  }
-}
-```
-然后在 `src/introspect/index.ts` 中注册：
-```typescript
-case 'mssql':
-  return new MSSQLIntrospector(config);
-```
-## 参考
-- **[AGENTS.md](AGENTS.md)** — OpenCode AI Agent 的项目指引，包含开发命令速查、架构要点和 CodeGraph 使用说明。
-- **CodeGraph** — 本项目已初始化 CodeGraph 索引（`.codegraph/`），Agent 可优先使用 `codegraph_*` 工具进行结构查询，速度远超 grep。
 ## 鸣谢
-DBGraph 的架构和 MCP 设计受到了 [CodeGraph](https://github.com/colbymchenry/codegraph) 的启发。CodeGraph 是一个优秀的代码知识图谱工具，将代码库结构提取为可查询的知识图谱，本项目借鉴了其思路并将其应用于数据库 schema 领域。
+受 [CodeGraph](https://github.com/colbymchenry/codegraph) 启发——一个优秀的代码知识图谱工具，本项目将其思路应用于数据库 schema 领域。
-## License
+## 许可证
 MIT

package/README.md CHANGED Viewed

@@ -1,353 +1,212 @@
-# DBGraph
+<div align="center">
-[![npm version](https://img.shields.io/npm/v/dbgraph)](https://www.npmjs.com/package/dbgraph)
-[![License](https://img.shields.io/npm/l/dbgraph)](LICENSE)
-[![Node](https://img.shields.io/node/v/dbgraph)](https://nodejs.org)
+# DBGraph
-Database knowledge graph — Introspect database schemas into a local-first knowledge graph, exposed over MCP for LLM-powered SQL generation.
+### Database Knowledge Graph — Introspect schemas into a searchable graph, expose over MCP for AI agents
-## The Problem
+**Zero-guess SQL generation · Sub-millisecond schema lookups · 100% local**
-LLMs make SQL mistakes 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/`. LLMs query it via MCP tools directly — no live database connection needed.
+[![npm version](https://img.shields.io/npm/v/dbgraph)](https://www.npmjs.com/package/dbgraph)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/Node.js-%3E%3D22.5-brightgreen)](https://nodejs.org/)
-```
-Without DBGraph:
-  LLM → guess names → write SQL → run → error → guess again → loop
+[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-supported-blue)](#supported-engines)
+[![MySQL](https://img.shields.io/badge/MySQL-supported-blue)](#supported-engines)
+[![SQLite](https://img.shields.io/badge/SQLite-supported-blue)](#supported-engines)
-With DBGraph:
-  LLM → dbgraph_context("orders") → get exact schema
-       → write SQL → dbgraph_execute → success
-```
+</div>
-## Quick Install
+## Get Started
 ```bash
-# Global install
-npm install -g dbgraph
+# Zero-install (recommended)
+npx dbgraph
-# Or use directly with npx
-npx dbgraph --help
+# Or install globally
+npm i -g dbgraph
 ```
-## Requirements
-- **Node.js >= 22.5.0** (requires built-in `node:sqlite` for FTS5 + WAL)
-## Quick Start
-All commands default to the current directory. Pass a directory path to target another project.
-### 1. Initialize a project
-```bash
-# Initialize current directory
-dbgraph init
-# Or initialize + index in one step
-dbgraph init -i
-# Or target a specific directory
-dbgraph init ./demo-project
-```
-This creates:
-- `.dbgraph/` — knowledge graph data directory
-- `dbgraph-db.json` — database connection config (default template)
-### 2. Configure database connections
-Edit `dbgraph-db.json` with your database info:
-```json
-{
-  "databases": [
-    {
-      "alias": "prod",
-      "engine": "postgresql",
-      "host": "localhost",
-      "port": 5432,
-      "database": "ecommerce",
-      "schemas": ["public"],
-      "auth": "env:DB_PASSWORD"
-    },
-    {
-      "alias": "local",
-      "engine": "sqlite",
-      "path": "./dev.db"
-    }
-  ]
-}
-```
-### 3. Extract schema
-```bash
-dbgraph index
-```
-Introspects all configured databases and stores tables, columns, foreign keys, indexes, and views into the knowledge graph.
-### 4. Query the knowledge graph
-```bash
-# Search tables/columns
-dbgraph query orders
-dbgraph query users --kind table
-# View full table structure
-dbgraph context public.orders
-# Check status
-dbgraph status
-# List data sources
-dbgraph sources
+### Initialize a project
+```bash
+cd your-project
+npx dbgraph init -i       # init + index in one step
 ```
-## Configuration
+<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>
-### `dbgraph-db.json`
+### Start the MCP server
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `alias` | string | yes | Database alias, identified as `db://@alias` in the graph |
-| `engine` | string | yes | Database engine: `postgresql` / `mysql` / `mariadb` / `sqlite` |
-| `host` | string | no | Host address (not needed for SQLite) |
-| `port` | number | no | Port (default depends on engine) |
-| `database` | string | yes (non-SQLite) | Database name |
-| `schemas` | string[] | no | Schemas to introspect (default: all) |
-| `path` | string | yes (SQLite) | SQLite file path |
-| `auth` | string | no | Authentication, e.g. `env:DB_PASSWORD` or `~/.pgpass` |
-| `ssl` | boolean | no | Enable SSL connection |
+```bash
+npx dbgraph serve
+```
-## CLI Reference
+AI agents connected to MCP automatically discover `dbgraph_*` tools for schema-aware SQL generation.
-All commands follow: `dbgraph <command> [options] [directory]`
+## MCP Configuration
-| Command | Description |
-|---------|-------------|
-| `init` | Initialize .dbgraph project + config |
-| `index` | Run database introspection |
-| `serve` | Start MCP server (for AI agents) |
-| `query` | Search tables/columns/views |
-| `context` | View full table structure |
-| `status` | Knowledge graph statistics |
-| `sources` | List data sources |
-| `test` | Test database connections |
-| `config` | View/create configuration |
-### `init`
-```bash
-# Initialize current directory
-dbgraph init
-# Init and index immediately
-dbgraph init -i
-# Initialize a specific directory
-dbgraph init ./my-project
-# Specify config file path
-dbgraph init ./my-project -c ./my-project/custom-config.json
-```
-### `index`
-```bash
-# Index configured databases (current dir)
-dbgraph index
-# Use a specific config file
-dbgraph index ./my-project -c ./my-project/custom-config.json
-```
-### `serve` (MCP mode)
-```bash
-# Start MCP stdio server (current dir)
-dbgraph serve
-# Start for a specific project directory
-dbgraph serve ./my-project
-```
-AI agents automatically discover `dbgraph_*` tools upon connecting to MCP.
+Add DBGraph as an MCP server in your agent's config:
-### `query`
+**opencode** (`~/.config/opencode/opencode.json`):
+```json
+{
+  "mcp": {
+    "dbgraph": {
+      "type": "local",
+      "command": ["npx", "dbgraph", "serve", "--auto-refresh"],
+      "enabled": true
+    }
+  }
+}
+```
-```bash
-# Search
-dbgraph query orders ./my-project
+**Cursor** → Settings → MCP Servers → Add:
+```json
+{
+  "mcpServers": {
+    "dbgraph": {
+      "command": "npx",
+      "args": ["dbgraph", "serve", "--auto-refresh"]
+    }
+  }
+}
+```
-# Filter by kind
-dbgraph query orders --kind table ./my-project
-dbgraph query amount --kind column ./my-project
+**Claude Code** (`~/.claude/settings.json`):
+```json
+{
+  "mcpServers": {
+    "dbgraph": {
+      "command": "npx",
+      "args": ["dbgraph", "serve", "--auto-refresh"]
+    }
+  }
+}
+```
-# JSON output
-dbgraph query orders --json ./my-project
+**Codex CLI** (`~/.codexclirc.json`):
+```json
+{
+  "mcpServers": {
+    "dbgraph": {
+      "type": "local",
+      "command": ["npx", "dbgraph", "serve", "--auto-refresh"]
+    }
+  }
+}
 ```
-### `context`
+## Why DBGraph?
+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.
-```bash
-# View table structure
-dbgraph context orders ./my-project
-dbgraph context public.orders ./my-project
 ```
+Without DBGraph:
+  LLM → guess names → write SQL → run → error → guess again → loop
-Example output:
+With DBGraph:
+  LLM → dbgraph_context("orders") → get exact schema
+       → write SQL → success
 ```
-## Table: public.orders
-Database: prod (postgresql)
+## CLI Reference
-| Column       | Type         | Nullable | Default  | PK | FK        |
-|-------------|-------------|----------|----------|----|-----------|
-| id          | bigint       | NO       |          | PK |           |
-| user_id     | integer      | NO       |          |    | users.id  |
-| status      | varchar(20)  | NO       | pending  |    |           |
-| total_amount| numeric(10,2)| YES      | 0.00     |    |           |
-| created_at  | timestamp    | NO       | now()    |    |           |
+| Command | Description |
+|---------|-------------|
+| `init` | Initialize `.dbgraph` project (`-i` to index immediately) |
+| `index` | Run database introspection |
+| `serve` | Start MCP server (use `--auto-refresh` to watch for schema changes) |
+| `query` | Search tables, columns, views, indexes |
+| `context` | View full table schema (call before writing SQL) |
+| `trace` | Trace foreign key join paths between tables |
+| `explore` | Explore multiple related tables at once |
+| `sources` | List configured database sources |
+| `status` | Knowledge graph statistics |
+| `test` | Test database connections |
+| `config` | View or create configuration |
-Indexes:
-  - idx_orders_status on (status)
-  - pk_orders PRIMARY KEY using btree (id)
+All commands default to the current directory. Pass a directory path to target another project:
-Foreign Keys:
-  - fk_orders_user → users(id) ON DELETE CASCADE
+```bash
+npx dbgraph status                  # current directory
+npx dbgraph status ./other-project  # another project
 ```
 ## MCP Tools
-After starting `dbgraph serve`, AI agents can call these tools:
+After starting `dbgraph serve`, AI agents can call:
-| Tool | Purpose | When to use |
-|------|---------|-------------|
-| `dbgraph_search` | Search tables/columns/views/indexes | When unsure about names |
-| `dbgraph_context` | **Primary entry** — full table schema + columns + FKs + indexes | Before writing SQL |
-| `dbgraph_trace` | Trace FK join paths (orders→users) | Before writing JOINs |
-| `dbgraph_explore` | Explore multiple related tables at once | Complex multi-table queries |
-| `dbgraph_sources` | List all configured database sources | Learn what databases are available |
-| `dbgraph_status` | Knowledge graph statistics | Verify the graph is healthy |
+| Tool | Purpose |
+|------|---------|
+| `dbgraph_search` | Search schema objects by name |
+| `dbgraph_context` | **Full table schema** — columns, types, PKs, FKs, indexes |
+| `dbgraph_trace` | Trace FK join paths (orders → users) |
+| `dbgraph_explore` | Batch schema for multiple tables |
+| `dbgraph_sources` | List all database sources |
+| `dbgraph_status` | Graph health and statistics |
-### Recommended workflow
+## Configuration
-```
-Standard pre-SQL flow:
-1. dbgraph_search("order")        → find relevant tables
-2. dbgraph_context("public.orders") → get full schema
-3. dbgraph_context("public.users")   → get related table schema
-4. dbgraph_trace("orders", "users")  → verify FK paths
-5. LLM writes precise SQL
+Edit `dbgraph-db.json` in your project root:
+```json
+{
+  "databases": [
+    {
+      "alias": "prod",
+      "engine": "postgresql",
+      "host": "localhost",
+      "port": 5432,
+      "database": "ecommerce",
+      "schemas": ["public"],
+      "auth": "env:DB_PASSWORD"
+    },
+    {
+      "alias": "local",
+      "engine": "sqlite",
+      "path": "./dev.db"
+    }
+  ]
+}
 ```
-## Supported Engines
-| Engine | Status | Details |
-|--------|--------|---------|
-| PostgreSQL | ✅ Full | `information_schema` + `pg_catalog` |
-| MySQL / MariaDB | ✅ Full | `information_schema` |
-| SQLite | ✅ Full | `pragma table_info` / `foreign_key_list` |
-| SQL Server | 🔜 Planned | |
-| Oracle | 🔜 Planned | |
-| MongoDB | 🔜 Planned | |
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `alias` | string | yes | Database alias (`db://@alias` in graph) |
+| `engine` | string | yes | `postgresql` / `mysql` / `mariadb` / `sqlite` |
+| `host` | string | no | Host address |
+| `port` | number | no | Port (default depends on engine) |
+| `database` | string | depends | Required for PostgreSQL/MySQL |
+| `schemas` | string[] | no | Schemas to introspect (default: all) |
+| `path` | string | depends | Required for SQLite |
+| `auth` | string | no | `env:VAR_NAME` or `~/.pgpass` |
+| `ssl` | boolean | no | Enable SSL |
-## Project Structure
+## Supported Engines
-```
-dbgraph/
-├── src/
-│   ├── index.ts                        # DBGraph main class
-│   ├── types.ts                        # All types (Node, Edge, TableSchema...)
-│   ├── config.ts                       # dbgraph-db.json config management
-│   ├── directory.ts                    # .dbgraph directory management
-│   ├── errors.ts                       # Error types
-│   ├── utils.ts                        # Utility functions
-│   │
-│   ├── db/                             # SQLite storage layer
-│   │   ├── schema.sql                  # Table schema (nodes/edges FTS5)
-│   │   ├── sqlite-adapter.ts           # node:sqlite adapter
-│   │   ├── migrations.ts               # Version migrations
-│   │   ├── queries.ts                  # CRUD + FTS5 search + scoring (LRU cache)
-│   │   └── index.ts                    # Connection management
-│   │
-│   ├── graph/
-│   │   └── traversal.ts                # BFS/DFS/pathfinding/impact radius
-│   │
-│   ├── context/
-│   │   ├── index.ts                    # Table context assembly
-│   │   └── formatter.ts                # Markdown output
-│   │
-│   ├── introspect/                     # Database introspection
-│   │   ├── base.ts                     # Base class + Node/Edge factory
-│   │   ├── index.ts                    # Factory method
-│   │   ├── connection.ts               # Connection management
-│   │   ├── postgres.ts                 # PostgreSQL
-│   │   ├── mysql.ts                    # MySQL
-│   │   └── sqlite.ts                   # SQLite
-│   │
-│   ├── mcp/                            # MCP server
-│   │   ├── transport.ts                # JSON-RPC transport
-│   │   ├── session.ts                  # Session management
-│   │   ├── engine.ts                   # Engine + lifecycle
-│   │   ├── tools.ts                    # 6 dbgraph_* tools
-│   │   ├── server-instructions.ts      # LLM instructions
-│   │   └── index.ts                    # MCPServer
-│   │
-│   └── bin/
-│       └── dbgraph.ts                  # CLI
-```
+| Engine | Status |
+|--------|--------|
+| PostgreSQL | ✅ Full support |
+| MySQL / MariaDB | ✅ Full support |
+| SQLite | ✅ Full support |
+| SQL Server | 🔜 Planned |
+| Oracle | 🔜 Planned |
 ## Development
 ```bash
-# Install dependencies
+git clone https://github.com/ZhangYaoSong/dbgraph.git
+cd dbgraph
 npm install
-# Build
 npm run build
-# Development mode (watch)
-npm run dev
-# Quick build + run
-npm run cli -- status ./my-project
+npm run cli -- init -i   # init current dir + index
+npm run cli -- serve      # start MCP server from source
 ```
-### Adding a new database engine
-Create a new file in `src/introspect/` (e.g. `mssql.ts`) implementing `BaseIntrospector`:
-```typescript
-import { BaseIntrospector } from './base';
-export class MSSQLIntrospector extends BaseIntrospector {
-  async extractAll(): Promise<IntrospectResult> {
-    // 1. Connect to database
-    // 2. Query information_schema
-    // 3. Call this.makeNode() / this.makeEdge()
-    // 4. Return IntrospectResult
-  }
-}
-```
-Then register it in `src/introspect/index.ts`:
-```typescript
-case 'mssql':
-  return new MSSQLIntrospector(config);
-```
-## References
-- **[AGENTS.md](AGENTS.md)** — OpenCode AI Agent project guide with dev commands and architecture overview
-- **CodeGraph** — This project uses CodeGraph indexing (`.codegraph/`) for fast structural queries
 ## Acknowledgments
-DBGraph\'s architecture and MCP design were inspired by [CodeGraph](https://github.com/colbymchenry/codegraph), an excellent code knowledge graph tool that extracts codebase structure into a queryable graph. This project adapts those ideas to the database schema domain.
+Inspired by [CodeGraph](https://github.com/colbymchenry/codegraph) — an excellent code knowledge graph tool that this project adapts to the database schema domain.
 ## License
-MIT
+MIT

package/package.json CHANGED Viewed

@@ -1,11 +1,11 @@
 {
   "name": "dbgraph",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Database knowledge graph for LLM-powered SQL generation. Introspect database schemas into a local-first knowledge graph, exposed over MCP.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
-    "dbgraph": "./dist/bin/dbgraph.js"
+    "dbgraph": "dist/bin/dbgraph.js"
   },
   "files": [
     "dist",