Dbecho

dbecho

通过 AI 与 PostgreSQL 数据库对话。无需仪表板，无需 BI 工具，只需提问并获取答案。

dbecho 是一个 MCP 服务，可让 AI Agent（Claude Code、Cursor、Windsurf 或任何 MCP 客户端）直接以只读方式访问 PostgreSQL 数据库。连接数据库后，用日常语言提问，即可立即获得分析结果。

You: What are my most popular blog posts and why?
Claude: [runs schema → query → analyze → trend across 29 tables]
       Here's what the data shows...

它能做什么？

14 个工具，覆盖完整的分析工作流：

工具	用途
list_databases	显示所有已连接的数据库
health	检查连接状态、PostgreSQL 版本和数据库大小
schema	完整架构：表、列、类型、主键、行数、大小
describe	深入查看单个表：列、主键、索引、大小 — 比 schema 更省资源
find	按名称子串查找表和列，一次搜索所有数据库
query	执行只读 SQL（SELECT、WITH、EXPLAIN、SHOW），支持偏移分页和 JSON 输出
explain	查看查询计划及估算成本/行数 — 执行前评估查询
analyze	分析表：空值、基数、分布、常见值
compare	在多个数据库上运行同一查询，并排比较结果
summary	概览：表数量、总行数、最大表
trend	时间序列：按日/周/月/年分组统计数量/平均值，并以 JSON 输出
anomalies	数据质量检查：大量空值、异常值、重复项、未来日期
sample	预览任意表中的行
erd	实体关系图：主键和外键

此外还有 3 个 MCP 资源（每个数据库的架构/摘要）和 3 个 MCP 提示词（引导式探索、跨数据库比较、数据质量审计）。

分区表会显示为父表，而不是一堆子表： schema、find、summary 和 erd 会隐藏分区子表，并将父表标记为 [partitioned]，行数估算值和大小会汇总整个分区树（父表本身不存储数据，因此直接读取系统目录会显示数据库中最大的表为空）。查询父表并让 PostgreSQL 执行分区裁剪； 如果明确指定分区，describe <child> 仍然有效。

为什么选择 dbecho？

问题： 你在多个项目中使用 PostgreSQL 数据库。要获取答案，就得切换到 psql、pgAdmin 或 BI 工具，编写 SQL、整理结果，再把见解带回当前对话。

解决方案： dbecho 融入 AI Agent 的工作流。Agent 可以探索架构、编写 SQL、交叉查询表并开展分析，你无需离开当前对话。只需一个配置文件，完全无需切换上下文。

它与直接给 Agent 一个连接字符串的做法有何不同：

• 支持多数据库。 可连接 1 个或 20 个数据库。通过一次工具调用即可进行跨库比较。
• 默认安全。 只读连接、查询超时、行数限制和 SQL 注入防护。不会意外执行 DROP TABLE。
• 针对 Agent 优化的输出。 架构、统计数据和查询结果经过格式化，便于大模型高效解析，而非原样输出 psql 转储内容。
• 零基础设施。 无需容器、Web UI 或后台进程。这是一个通过 stdio 使用 MCP 协议通信的 Python 包。

示例会话

You: Show me what's in the database

Claude: [calls list_databases → schema → summary]

       Database: ecommerce (12 tables, 847 MB)
       Largest: orders (2.1M rows), products (45K rows), users (128K rows)

You: How are sales trending this quarter?

Claude: [calls trend on orders table, grouped by week]

       Week        | orders | total_revenue
       2026-01-06  | 3,241  | $482,100
       2026-01-13  | 3,892  | $571,340
       2026-01-20  | 2,107  | $298,500  ← 46% drop
       ...
       Significant drop in week of Jan 20. Let me check what happened.

       [calls query to investigate, then anomalies on orders table]

       Found: 89% of orders that week have status='cancelled'.
       The cancellation spike correlates with a payment gateway outage
       (payments table shows 0 successful transactions Jan 19-21).

You: Any data quality issues I should worry about?

Claude: [calls anomalies on each table]

       Found 4 issues:
       - users.email: 342 possible duplicates
       - orders.shipped_at: 127 dates in the future
       - products.price: 23 outliers (IQR: $5..$89, found items at $0 and $9,999)
       - events.user_id: 94.2% NULL (missing user attribution)

一次对话，无需切换上下文。Agent 会自动选择合适的工具。

快速开始

1. 安装

pip install dbecho

也可以从源码安装：

git clone https://github.com/ginkida/dbecho.git
cd dbecho
pip install .

需要 Python 3.10+ 和 PostgreSQL 12 或更高版本。

2. 配置

在项目目录中创建 dbecho.toml：

[databases.myapp]
url = "postgres://user:pass@localhost:5432/myapp"
description = "Main application"

[databases.analytics]
url = "postgres://user:pass@localhost:5432/analytics"
description = "Analytics warehouse"

[settings]
row_limit = 500           # max rows returned per query (default: 500)
query_timeout = 30        # seconds before query is killed (default: 30)
max_profile_rows = 5000000  # refuse analyze/anomalies above this row count
redact_sensitive = true   # redact password/token/secret-like columns in output

环境变量可使用 ${VAR} 语法：

[databases.production]
url = "${DATABASE_URL}"
description = "Production (read replica)"

如果应用将表存储在 public 之外，请设置 schema（默认为 "public"，小写标识符）。所有元数据工具（schema、describe、analyze 等）都会以此为目标，并将其置于 search_path 首位，以便原始查询使用未限定的表名：

[databases.events]
url = "${EVENTS_DATABASE_URL}"
schema = "analytics"

在配置 MCP 客户端之前，请验证配置和连通性：

dbecho --check     # validate config + ping every database
dbecho --version   # print "dbecho <version>"
dbecho --help      # usage and flags

--check 会为每个数据库打印一行 [OK]/[FAIL] <name>: …，并且仅当每个数据库都能响应时才以 0 退出（否则返回非零值），因此可直接用于 CI 或健康检查脚本。

退出代码：0 表示成功，1 表示配置或启动失败（--check 失败时也会返回此代码），2 表示用法错误。无法识别的参数会被拒绝，而不是忽略，因此像 --verison 这样的拼写错误不会导致服务启动后悄无声息地什么也不做。

3. 连接到 MCP 客户端

Claude Code（项目级，推荐）：

在项目根目录中创建 .mcp.json：

{
  "mcpServers": {
    "dbecho": {
      "command": "dbecho",
      "args": ["--config", "/path/to/dbecho.toml"]
    }
  }
}

Claude Code（全局）：

添加到 ~/.claude.json：

{
  "mcpServers": {
    "dbecho": {
      "command": "dbecho"
    }
  }
}

如果没有传入 --config，dbecho 会按以下顺序查找配置：

1. ./dbecho.toml（当前目录）
2. ~/.config/dbecho/config.toml
3. ~/.dbecho.toml

其他 MCP 客户端（Cursor、Windsurf 等）：在客户端的 MCP 服务配置中使用相同的命令和参数。

4. 提问

Show me a summary of all my databases
How many users signed up each month this year?
Compare order counts between staging and production
Find data quality issues in the events table
What's the relationship between users, orders, and products?
Which columns have the most nulls?
Show me the trend of daily revenue for the last 90 days

Agent 会自动选择合适的工具。你不需要知道工具名称。

安全性

dbecho 的设计目标是可以安全地连接到任何数据库，包括生产环境数据库：

• 只读连接。 每个连接都会在 PostgreSQL 层设置 default_transaction_read_only=on。即使有人构造恶意 SQL，数据库也会拒绝写入操作。
• 查询白名单。 仅允许 SELECT、WITH、EXPLAIN 和 SHOW 语句——验证器还会独立拒绝修改数据的 CTE（WITH x AS (DELETE ...) SELECT ...）、SELECT INTO，以及针对写入语句的 EXPLAIN ANALYZE，因此并非只依赖只读连接。
• 屏蔽函数。 即使事务为只读，也会拒绝文件系统、大对象、dblink 和 set_config 函数——它们可能被用于数据外泄或逃逸。
• 防止 SQL 注入。 所有表和列标识符都使用 psycopg.sql.Identifier() 参数化。用户输入会根据 ^[a-zA-Z_][a-zA-Z0-9_]*\Z 验证（使用 \Z 而非 $，这样末尾换行符就无法蒙混过关）。唯一一个未放入 Identifier()、但形式上类似标识符的值，是每个数据库的 schema 配置选项——它会嵌入连接的 search_path 中，并在加载配置时、创建任何连接之前，按照相同格式（仅小写）进行验证。
• 查询超时。 默认 30 秒，通过 statement_timeout 为多查询工具设置共享的总时间预算，并在每个连接上设置会话级超时作为后备保障。
• 行数限制。 每个查询默认最多返回 500 行，防止 Agent 将整张表读入上下文。全表分析（analyze/anomalies）还会拒绝处理行数超过 max_profile_rows 的表——无法以低成本计算超过 5000 万行的精确统计数据，因此会直接拒绝，并在消息中指出用于提高上限的设置项。
• 列数上限。 analyze/anomalies 最多探查 80 列（每列都需要单独执行查询）。列数更多的表会进行部分分析，而不是直接拒绝；结果始终会说明跳过了多少列，并列出这些列名——看起来完整、实则不完整的分析结果比报错更糟。
• 敏感列脱敏。 对于看起来包含机密信息的列（password、token、api_key、secret 等），其值会在 query/sample/analyze 输出中替换为 <redacted>（默认开启；设置 redact_sensitive = false 可关闭）。基于列名的处理只是降低风险，并非完备的安全控制——按设计，query 是开放的读取通道。
• 清理错误信息。 连接失败会以粗略的类别报告给 Agent（authentication failed、connection refused 等）；完整详情只会写入服务日志，因此主机名和用户名不会泄露到对话中。
• 仅限本地。 不进行网络调用，不收集遥测数据，也不使用云服务。数据始终保留在你的机器上。

对于生产环境数据库，最稳妥的设置仍然是采用最小权限角色：创建一个仅对你希望开放访问的表和视图拥有 SELECT 权限的 PostgreSQL 用户。dbecho 的多层保护可以防止意外操作和被提示词注入的 Agent；最终决定权仍在数据库自身的授权设置中。

架构

src/dbecho/
  config.py   TOML config loading, env var expansion, validation
  db.py       DatabaseManager: connections, SQL validation, schema, queries, stats, trends, anomalies
  server.py   FastMCP server: 14 tools, 3 resources, 3 prompts

总计约 2700 行 Python 代码。除 mcp 和 psycopg 外，不依赖任何框架。

开发

git clone https://github.com/ginkida/dbecho.git
cd dbecho
pip install -e ".[dev]"
pytest -v

测试完全使用模拟，不需要 PostgreSQL 实例。CI 在 Python 3.10-3.13 上运行。

coverage run --branch -m pytest -q
coverage report --show-missing --include='src/*'

由于测试套件从不连接服务端，目录级 SQL（分区树、 pg_stat_user_tables 联接、索引内省）应在合并前对照临时实例手动检查——例如： docker run --rm -d -e POSTGRES_HOST_AUTH_METHOD=trust -p 55434:5432 postgres:16， 然后让临时的 dbecho.toml 指向它。模拟测试可以验证连接流程；只有真实服务端才能告诉你查询是否正确。

许可证

MIT