🚀 DBChat - 用人工智能与你的数据库对话

DBChat 能将你的数据库转变为一个智能的对话伙伴。你可以用自然语言提问，即刻获取答案，并创建精美的可视化图表，这一切都能通过 Claude Desktop 实现。

🚀 快速开始

步骤 1：下载

从 GitHub Releases 下载最新版本：

• dbchat-2.0.4.jar - 基础版本（支持 PostgreSQL、SQLite、H2、HSQLDB、CSV）
• dbchat-2.0.4.jar - 标准版本（新增 MySQL、MariaDB、ClickHouse）
• dbchat-2.0.4.jar - 企业版本（新增 Oracle、SQL Server、DB2）
• dbchat-2.0.4.jar - 包含所有数据库支持（400MB+）

注意：你也可以仅构建包含所需驱动的自定义 JAR 文件。详情请参阅 INSTALL.md。

重要提示：请确保你拥有使用所安装的任何 JDBC 驱动的合法许可。DBChat 许可不涵盖任何第三方代码或二进制文件。

步骤 2：安装 Claude Desktop（或其他 MCP 客户端）

1. 下载 Claude Desktop（免费）
2. 使用你的 Claude 账户登录
3. 重要：Claude 网站不支持 MCP。若要使用 Anthropic 模型的 MCP 功能，你需要使用 Claude Desktop。

步骤 3：设置数据库连接

创建一个配置文件 dbchat.conf：

# 基本数据库连接
DB_URL=jdbc:mysql://localhost:3306/your_database
DB_USER=your_username
DB_PASSWORD=your_password
DB_DRIVER=com.mysql.cj.jdbc.Driver

# 可选：启用 Web 界面
HTTP_MODE=false
HTTP_PORT=8080

常见数据库示例： MySQL：

DB_URL=jdbc:mysql://localhost:3306/your_database
DB_USER=your_username
DB_PASSWORD=your_password
DB_DRIVER=com.mysql.cj.jdbc.Driver

PostgreSQL：

DB_URL=jdbc:postgresql://localhost:5432/your_database
DB_USER=your_username
DB_PASSWORD=your_password
DB_DRIVER=org.postgresql.Driver

SQLite：

DB_URL=jdbc:sqlite:/path/to/your/database.db
DB_USER=
DB_PASSWORD=
DB_DRIVER=org.sqlite.JDBC

使用 H2 进行测试（无需设置）：

DB_URL=jdbc:h2:mem:testdb
DB_USER=sa
DB_PASSWORD=
DB_DRIVER=org.h2.Driver

步骤 4：配置 Claude Desktop

1. 打开 Claude Desktop
2. 转到 设置 → 开发者 → 编辑配置
3. 添加你的数据库服务器：

{
  "mcpServers": {
    "database": {
      "command": "java",
      "args": [
        "-jar", 
        "/absolute/path/to/dbchat-2.0.4.jar",
        "--config_file=/absolute/path/to/dbchat.conf"
      ]
    }
  }
}

不使用配置文件的替代方法：

{
  "mcpServers": {
    "database": {
      "command": "java",
      "args": ["-jar", "/absolute/path/to/dbchat-2.0.4.jar"],
      "env": {
        "DB_URL": "jdbc:mysql://localhost:3306/your_database",
        "DB_USER": "your_username", 
        "DB_PASSWORD": "your_password",
        "DB_DRIVER": "com.mysql.cj.jdbc.Driver"
      }
    }
  }
}

Windows 示例：

{
  "mcpServers": {
    "database": {
      "command": "java",
      "args": [
        "-jar", 
        "C:/Users/YourName/Downloads/dbchat-2.0.4.jar",
        "--config_file=C:/Users/YourName/dbchat.conf"
      ]
    }
  }
}

注意：如果 Java 不在你的系统路径中，请在命令中使用 Java（JDK 17+）的完整路径。

步骤 5：连接多个数据库

你可以同时使用多个数据库！

{
  "mcpServers": {
    "production-db": {
      "command": "java",
      "args": ["-jar", "/path/to/dbchat-2.0.4.jar"],
      "env": {
        "DB_URL": "jdbc:mysql://prod-server:3306/production",
        "DB_USER": "readonly_user",
        "DB_PASSWORD": "secure_password",
        "DB_DRIVER": "com.mysql.cj.jdbc.Driver",
        "SELECT_ONLY": "true"
      }
    },
    "analytics-db": {
      "command": "java", 
      "args": ["-jar", "/path/to/dbchat-2.0.4.jar"],
      "env": {
        "DB_URL": "jdbc:postgresql://analytics:5432/warehouse",
        "DB_USER": "analyst",
        "DB_PASSWORD": "password",
        "DB_DRIVER": "org.postgresql.Driver"
      }
    }
  }
}

步骤 6：重启 Claude Desktop

关闭并重新打开 Claude Desktop。你应该会在聊天输入框中看到数据库连接指示器。

✨ 主要特性

🗣️ 自然语言数据库查询

• 用自然语言提问：例如 "上个月有多少客户注册？"
• 获得对话式回应：Claude 会解释数据并提供见解
• 无需 SQL 知识：非常适合业务用户和分析师

📊 即时数据可视化

• 自动创建图表：Claude 可以根据你的数据生成精美的图表
• 多种图表类型：支持折线图、柱状图、饼图、散点图等
• 交互式洞察：可以通过后续问题深入挖掘数据

🔍 智能数据探索

• 数据库发现：例如 "我们有哪些表？" "显示客户表的结构"
• 关系理解：Claude 会解释表之间的关联
• 数据质量洞察：可以发现重复数据、缺失数据和异常值

💼 轻松实现商业智能

• 高管仪表盘：例如 "为我们的董事会会议创建一份销售摘要"
• 趋势分析：例如 "显示过去 6 个月的用户增长情况"
• 绩效指标：例如 "哪些产品表现不佳？"

📦 安装指南

DBChat 几乎可以与任何数据库配合使用（只要该数据库有 JDBC 驱动）。

常见数据库

• MySQL / MariaDB - 适用于 Web 应用和电子商务
• Oracle - 适用于企业应用
• PostgreSQL - 适用于高级应用和分析
• SQL Server - 适用于微软环境
• H2 - 用于测试和开发
• SQLite - 适用于本地应用和原型开发
• HSQLDB - 用于测试和开发

分析与云数据库

• Snowflake - 云数据平台
• Databricks - 云数据平台
• Amazon Redshift - AWS 数据仓库
• Google BigQuery - 谷歌分析
• ClickHouse - 实时分析

基于平面文件的数据

• CSV 文件 - 电子表格数据和导出数据
• Excel 文件 - 可以导出为 CSV 格式并进行查询

完整列表和构建选项请参阅 INSTALL.md。

💻 使用示例

基础用法

"数据库中有哪些表？"
"显示客户表的结构"
"每个表中有多少条记录？"

高级用法

"计算每个客户细分市场的客户终身价值"
"识别我们销售数据中的季节性趋势"
"找出客户年龄与购买行为之间的相关性"

📚 详细文档

更多实际示例

电子商务分析

"显示从访客到购买的转化漏斗"
"哪些产品的退货率最高？"
"创建一个显示每日销售业绩的仪表盘"

客户成功

"找出有流失风险的客户"
"显示客户满意度趋势"
"确定我们最有价值的客户细分市场"

财务报告

"生成本季度的损益表摘要"
"显示过去 12 个月的现金流趋势"
"按部门创建费用明细"

运营管理

"监控所有仓库的库存水平"
"显示各承运商的运输绩效"
"找出我们订单履行流程中的瓶颈"

数据可视化示例

DBChat 使 Claude 能够直接从你的数据库创建令人惊叹的可视化图表：

销售仪表盘

• 月收入趋势：折线图展示随时间的增长情况
• 畅销产品：柱状图显示畅销产品
• 区域绩效：热力图展示各地区的销售情况
• 客户细分：饼图展示收入分布

分析报告

• 用户增长：面积图展示用户获取趋势
• 绩效指标：多轴图表结合不同的关键绩效指标
• 比较分析：并排可视化展示不同时期的数据

运营仪表盘

• 库存水平：实时库存可视化
• 系统性能：时间序列图表展示关键指标
• 质量指标：统计图表展示趋势和异常值

🔧 技术细节

安全特性

只读模式

通过只读访问保护你的数据：

SELECT_ONLY=true

查询限制

控制资源使用：

MAX_ROWS_LIMIT=1000
QUERY_TIMEOUT_SECONDS=30
MAX_SQL_LENGTH=10000

本地处理

• 所有数据都保留在你的本地机器上
• 无需外部 API 调用
• 环境变量经过加密
• 本地通信安全可靠

网页界面（可选）

启用 HTTP 模式以实现基于 Web 的访问：

# 开启 HTTP 监听器
HTTP_MODE=true
# 监听端口 8080
HTTP_PORT=8080
# 绑定到所有接口（允许外部访问）
BIND_ADDRESS=0.0.0.0
# 注意：如果未指定绑定地址，默认绑定到本地主机（最安全）

然后通过 http://localhost:8080/ 进行访问。例如，尝试 http://localhost:8080/health 来检查健康状态。

若要通过 CLI 参数进行类似配置，请使用：

# 仅绑定到本地主机（默认，最安全）
java -jar dbchat-2.0.4.jar --http_mode=true --http_port=8080

# 绑定到所有接口（允许外部访问）
java -jar dbchat-2.0.4.jar --http_mode=true --bind_address=0.0.0.0 --http_port=8080

# 绑定到特定接口
java -jar dbchat-2.0.4.jar --http_mode=true --bind_address=192.168.1.100 --http_port=8080

配置方法和优先级

为了实现最大的灵活性，DBChat 支持多种配置方法，如 CLI 参数、配置文件、环境变量、系统属性和内置默认值。了解优先级顺序对于故障排除和高级设置至关重要。

配置优先级顺序（从高到低）

1. 命令行参数（最高优先级）
2. 配置文件
3. 环境变量
4. 系统属性
5. 内置默认值（最低优先级）

这意味着命令行参数将始终覆盖配置文件，配置文件将覆盖环境变量，依此类推。

方法 1：命令行参数

格式：--parameter_name=value 使用场景：快速覆盖、测试、一次性配置

java -jar dbchat-2.0.4.jar \
  --db_url="jdbc:mysql://localhost:3306/mydb" \
  --db_user="username" \
  --db_password="password" \
  --db_driver="com.mysql.cj.jdbc.Driver" \
  --http_mode=true \
  --http_port=8080 \
  --select_only=true

可用参数：

• --config_file=/path/to/config.conf
• --db_url="jdbc:..."
• --db_user="username"
• --db_password="password"
• --db_driver="com.mysql.cj.jdbc.Driver"
• --http_mode=true
• --http_port=8080
• --max_connections=20
• --connection_timeout_ms=30000
• --query_timeout_seconds=60
• --select_only=true
• --max_sql_length=50000
• --max_rows_limit=10000

方法 2：配置文件

格式：KEY=VALUE（每行一个） 使用场景：生产环境、复杂配置、版本控制

创建一个文件（例如 dbchat.conf）：

# 数据库连接
DB_URL=jdbc:postgresql://localhost:5432/myapp
DB_USER=dbuser
DB_PASSWORD=my secure password with spaces
DB_DRIVER=org.postgresql.Driver

# 连接池设置
MAX_CONNECTIONS=20
CONNECTION_TIMEOUT_MS=60000
IDLE_TIMEOUT_MS=300000
MAX_LIFETIME_MS=1800000
LEAK_DETECTION_THRESHOLD_MS=60000

# 查询设置
QUERY_TIMEOUT_SECONDS=45
SELECT_ONLY=false
MAX_SQL_LENGTH=50000
MAX_ROWS_LIMIT=50000

# 服务器设置
HTTP_MODE=true
HTTP_PORT=8080

使用方法：

java -jar dbchat-2.0.4.jar --config_file=dbchat.conf

配置文件特性：

• 注释以 # 开头
• 空行将被忽略
• 值可以加引号：DB_PASSWORD="password with spaces"
• 键不区分大小写
• 支持与命令行相同的所有参数

方法 3：环境变量

格式：UPPERCASE_WITH_UNDERSCORES 使用场景：Docker、云部署、CI/CD、安全凭证管理

export DB_URL="jdbc:mysql://localhost:3306/mydb"
export DB_USER="username"
export DB_PASSWORD="password"
export DB_DRIVER="com.mysql.cj.jdbc.Driver"
export HTTP_MODE="true"
export HTTP_PORT="8080"
export SELECT_ONLY="true"

java -jar dbchat-2.0.4.jar

所有环境变量：

• CONFIG_FILE - 配置文件的路径
• DB_URL - 数据库连接 URL
• DB_USER - 数据库用户名
• DB_PASSWORD - 数据库密码
• DB_DRIVER - JDBC 驱动类
• HTTP_MODE - 启用 HTTP 模式（true/false）
• HTTP_PORT - HTTP 服务器端口
• MAX_CONNECTIONS - 连接池大小
• CONNECTION_TIMEOUT_MS - 连接超时时间
• QUERY_TIMEOUT_SECONDS - 查询超时时间
• SELECT_ONLY - 只读模式（true/false）
• MAX_SQL_LENGTH - 最大查询长度
• MAX_ROWS_LIMIT - 最大结果行数
• IDLE_TIMEOUT_MS - 连接空闲超时时间
• MAX_LIFETIME_MS - 连接最大生命周期
• LEAK_DETECTION_THRESHOLD_MS - 泄漏检测阈值

方法 4：系统属性

格式：-Dparameter.name=value（下划线变为点） 使用场景：JVM 特定配置、IDE 运行配置

java -Ddb.url="jdbc:mysql://localhost:3306/mydb" \
     -Ddb.user="username" \
     -Ddb.password="password" \
     -Ddb.driver="com.mysql.cj.jdbc.Driver" \
     -Dhttp.mode="true" \
     -Dhttp.port="8080" \
     -jar dbchat-2.0.4.jar

属性命名：环境变量 DB_URL 对应的系统属性为 db.url

方法 5：内置默认值

适用情况：未提供配置时 值：为开发提供安全的默认值

DB_URL=jdbc:h2:mem:testdb
DB_USER=sa
DB_PASSWORD=
DB_DRIVER=org.h2.Driver
HTTP_MODE=false
HTTP_PORT=8080
MAX_CONNECTIONS=10
CONNECTION_TIMEOUT_MS=30000
QUERY_TIMEOUT_SECONDS=30
SELECT_ONLY=true
MAX_SQL_LENGTH=10000
MAX_ROWS_LIMIT=10000

配置示例

示例 1：优先级覆盖

# 配置文件中设置 HTTP_PORT=8080
echo "HTTP_PORT=8080" > config.conf

# 环境变量设置不同的端口
export HTTP_PORT=9090

# 命令行参数覆盖两者
java -jar dbchat-2.0.4.jar --config_file=config.conf --http_port=7070

# 结果：使用端口 7070（命令行参数优先级最高）

示例 2：混合配置

# 使用配置文件设置数据库相关设置
echo "DB_URL=jdbc:mysql://localhost:3306/mydb" > prod.conf
echo "DB_USER=produser" >> prod.conf
echo "SELECT_ONLY=true" >> prod.conf

# 通过环境变量覆盖密码（更安全）
export DB_PASSWORD="secure_password"

# 通过命令行参数覆盖端口（仅本次运行有效）
java -jar dbchat-2.0.4.jar --config_file=prod.conf --http_port=9090

示例 3：Claude Desktop 配置

{
  "mcpServers": {
    "database": {
      "command": "java",
      "args": [
        "-jar", "/path/to/dbchat-2.0.4.jar",
        "--config_file=/path/to/production.conf",
        "--select_only=true"
      ],
      "env": {
        "DB_PASSWORD": "secure_password_from_env"
      }
    }
  }
}

配置参数参考

数据库连接

• DB_URL - JDBC 连接字符串（必需）
• DB_USER - 数据库用户名
• DB_PASSWORD - 数据库密码
• DB_DRIVER - JDBC 驱动类（必需）

连接池

• MAX_CONNECTIONS=10 - 最大并发连接数
• CONNECTION_TIMEOUT_MS=30000 - 连接获取超时时间
• IDLE_TIMEOUT_MS=600000 - 连接空闲超时时间（10 分钟）
• MAX_LIFETIME_MS=1800000 - 连接最大生命周期（30 分钟）
• LEAK_DETECTION_THRESHOLD_MS=60000 - 连接泄漏检测（1 分钟）

查询设置

• QUERY_TIMEOUT_SECONDS=30 - SQL 查询执行超时时间
• SELECT_ONLY=true - 只读模式（阻止 INSERT/UPDATE/DELETE 操作）
• MAX_SQL_LENGTH=10000 - SQL 查询的最大字符数
• MAX_ROWS_LIMIT=10000 - 每个查询返回的最大行数

服务器设置

• HTTP_MODE=false - 启用 HTTP Web 界面
• HTTP_PORT=8080 - HTTP 服务器端口

安全最佳实践

凭证管理

# 推荐：使用环境变量存储密码
export DB_PASSWORD="secure_password"
java -jar dbchat-2.0.4.jar --config_file=app.conf

# 推荐：使用具有受限权限的配置文件
chmod 600 secure.conf
java -jar dbchat-2.0.4.jar --config_file=secure.conf

# 避免：在命令行中明文显示密码（会在进程列表中可见）
java -jar dbchat-2.0.4.jar --db_password="visible_password"

配置文件安全

# 创建安全的配置文件
umask 077
cat > secure.conf << EOF
DB_PASSWORD=secure_password
EOF

# 验证权限
ls -la secure.conf
# 应该显示：-rw-------（仅所有者可读写）

配置故障排除

检查有效配置

启用调试日志以查看实际使用的值：

java -Dlogging.level.root=DEBUG -jar dbchat-2.0.4.jar --config_file=myconfig.conf

常见问题

1. 找不到配置文件：使用绝对路径
2. 权限被拒绝：检查文件权限
3. 使用了错误的值：检查优先级顺序
4. 环境变量未设置：使用 env | grep DB_ 进行验证

验证命令

# 使用当前配置测试数据库连接
java -jar dbchat-2.0.4.jar --help

# 验证配置文件语法
grep -v "^#" myconfig.conf | grep -v "^$"

# 检查环境变量
env | grep -E "(DB_|HTTP_|MAX_|SELECT_)"

🚫 故障排除

Claude Desktop 无法连接

1. 检查路径：在配置中使用绝对路径
2. Java 版本：确保安装了 Java 17 或更高版本
3. 文件权限：验证 JAR 文件是否可读
4. 重启 Claude：关闭并重新打开 Claude Desktop

数据库连接问题

1. 测试连接：验证数据库是否正在运行
2. 检查凭证：确保用户名和密码正确
3. 网络访问：确认数据库允许连接
4. 驱动支持：使用适合你数据库的正确 JAR 版本

性能问题

1. 限制结果：使用 MAX_ROWS_LIMIT=1000
2. 查询超时：设置 QUERY_TIMEOUT_SECONDS=30
3. 连接池：调整 MAX_CONNECTIONS=10

常见错误消息

"ClassNotFoundException"

• 下载适合你数据库的正确 JAR 版本
• 检查数据库驱动是否已包含

"Connection refused"

• 验证数据库服务器是否正在运行
• 检查连接 URL、用户名和密码
• 确保数据库允许从你的机器进行连接

"Server not responding"

• 检查 Claude Desktop 的配置语法
• 验证 Java 是否在系统路径中可用
• 查看 Claude Desktop 的日志

🎯 最佳实践

入门建议

1. 从只读模式开始：最初使用 SELECT_ONLY=true
2. 使用示例数据进行测试：可以先尝试使用 H2 数据库
3. 从简单问题开始：从基本的表探索开始
4. 逐步增加复杂度：随着时间推移，逐渐转向高级分析

安全方面

1. 使用专用数据库用户：为 DBChat 创建只读用户
2. 限制访问权限：仅授予必要的表权限
3. 监控使用情况：定期审查查询日志
4. 备份数据：始终维护数据库备份

性能方面

1. 设置合理的限制：使用 MAX_ROWS_LIMIT 和超时设置
2. 对重要列创建索引：确保查询能够高效运行
3. 监控资源使用：关注 CPU 和内存使用情况
4. 优化查询：让 Claude 建议查询优化方案

📚 了解更多

• 模型上下文协议：modelcontextprotocol.io
• Claude Desktop：claude.ai/download
• 开发者指南：有关技术细节，请参阅 INSTALL.md
• GitHub 仓库：github.com/skanga/dbchat

🚀 准备好改变你的数据体验了吗？

1. 下载 适合你数据库的 JAR 文件
2. 安装 Claude Desktop（免费）
3. 配置 你的数据库连接
4. 添加 DBChat 到 Claude Desktop 设置中
5. 开始 询问关于你数据的问题！

改变你与数据的交互方式。无需再编写复杂的 SQL 查询，无需再等待报告。只需通过自然语言与你的数据库对话，借助 Claude 的智能和 DBChat 的无缝集成。

立即开始，发现你的数据想要告诉你的信息。