a2db

🗄️ a2db

Agent-to-Database

为 AI Agent 提供安全的数据库只读访问权限。一键调用，运行多个查询，结果清晰易读。

5 种数据库 · 批量查询 · 预配置连接 · SQLGlot 只读

快速开始 · MCP 工具 · 安全性 · 对比 · 设置

---

Agent: "Show me active users and their recent orders"
  ↓
a2db execute → 2 queries, 1 call, structured results
  ↓
Agent: "Got it — 847 active users, avg order $42.50"

为什么选择 a2db？

大多数数据库 MCP 服务要求你一次运行一个查询、每次调用都重复填写连接信息，并将结果双重编码在 JSON 字符串中。a2db 解决了这些问题：

• 预配置连接 — 使用 --register 在 .mcp.json 中定义数据库，Agent 即可立即查询
• 批量查询 — 一次工具调用中运行多个命名查询
• 默认连接 — 设置一次连接，即可在批次中的所有查询里使用
• 清晰的输出 — 结构化 JSON 封装，包含紧凑的 TSV 数据和每个查询的耗时（参见为什么使用 TSV？）
• 强制只读 — SQLGlot AST 解析会阻止所有写操作
• 内置所有驱动 — 执行 pip install a2db 即可完成
• 密钥保存在环境变量中 — 在 DSN 中使用 ${DB_PASSWORD}，仅在连接时展开

支持的数据库

数据库	驱动	异步
PostgreSQL	asyncpg	原生
SQLite	aiosqlite	原生
MySQL / MariaDB	mysql-connector-python	封装
Oracle	oracledb	封装
SQL Server	pymssql	封装

快速开始

pip install a2db

作为 MCP 服务（推荐）

Claude Code（使用预配置连接）：

claude mcp add -s user a2db -- a2db-mcp \
  --register myapp/prod/main 'postgresql://user:${DB_PASSWORD}@host/mydb'

Claude Code（精简配置 — Agent 按需调用 login）：

claude mcp add -s user a2db -- a2db-mcp

Claude Desktop / Cursor / 任意 MCP 客户端（.mcp.json）：

{
  "mcpServers": {
    "a2db": {
      "command": "uvx",
      "args": [
        "a2db-mcp",
        "--register", "myapp/prod/main", "postgresql://user:${DB_PASSWORD}@host/mydb"
      ],
      "env": {
        "DB_PASSWORD": "your-password-here"
      }
    }
  }
}

多个数据库：

{
  "args": [
    "a2db-mcp",
    "--register", "myapp/prod/main", "postgresql://user:${DB_PASSWORD}@host/maindb",
    "--register", "myapp/prod/analytics", "postgresql://user:${DB_PASSWORD}@host/analytics"
  ]
}

--register 会在服务启动时预先注册连接 — Agent 可以立即查询。密码使用 ${ENV_VAR} 语法，并在连接时展开，绝不会以明文形式存储。

作为命令行工具

# Save a connection (validates immediately)
a2db login -p myapp -e prod -d main 'postgresql://user:${DB_PASSWORD}@localhost/mydb'

# Query
a2db query -p myapp -e prod -d main "SELECT * FROM users LIMIT 10"

# JSON output
a2db query -p myapp -e prod -d main -f json "SELECT * FROM users LIMIT 10"

# Explore schema
a2db schema -p myapp -e prod -d main tables
a2db schema -p myapp -e prod -d main columns -t users

# List / remove connections
a2db connections
a2db logout -p myapp -e prod -d main

MCP 工具

工具	说明
login	保存连接 — 会先尝试连接以验证
logout	移除已保存的连接
list_connections	列出连接（不会暴露密钥）
execute	运行带分页的命名批量查询
search_objects	探索架构 — 表、列，并可指定详细程度

execute — 核心工具

使用带默认连接的命名字典（推荐）：

{
  "connection": {"project": "myapp", "env": "prod", "db": "main"},
  "queries": {
    "active_users": {"sql": "SELECT id, name FROM users WHERE active = true"},
    "recent_orders": {"sql": "SELECT id, total FROM orders ORDER BY created_at DESC LIMIT 5"}
  }
}

列表格式（自动命名为 q1、q2……）：

{
  "connection": {"project": "myapp", "env": "prod", "db": "main"},
  "queries": [
    {"sql": "SELECT COUNT(*) AS cnt FROM users"},
    {"sql": "SELECT AVG(total) AS avg_order FROM orders"}
  ]
}

响应（TSV 格式 — 默认）：

{
  "active_users": {
    "data": "id\tname\n1\tAlice\n2\tBob\n3\tCharlie",
    "rows": 3,
    "truncated": false,
    "time_ms": 12
  },
  "recent_orders": {
    "data": "id\ttotal\n501\t129.00\n500\t49.99",
    "rows": 2,
    "truncated": false,
    "time_ms": 8
  }
}

无需使用 ::text 转换 — 整数、浮点数、时间戳、数组、NULL 均可原生处理。

错误上下文

当查询因列错误而失败时，a2db 会补充错误信息：

column "nme" does not exist
Did you mean: name?
Available columns: id (integer), name (text), email (text), active (integer)

为什么选择 TSV？

大模型上下文窗口的成本很高。JSON 行数据很冗长——每行都会重复所有列名，还会添加大括号、逗号和引号。TSV 是一个扁平网格：一行表头，之后只有用制表符分隔的值。

对于包含 100 行、5 列的结果集，TSV 通常比 JSON 行格式少用 40-60% 的令牌。结构化的 JSON 封装仍会提供元数据（行数、截断状态）——只有行数据负载采用 TSV 格式。

如果需要每行都包含列名的完整结构化输出，请设置 format="json"。

安全

只读强制措施

每条查询在执行前都会由 SQLGlot 解析：

• 禁止： INSERT、UPDATE、DELETE、DROP、TRUNCATE、ALTER、CREATE、GRANT、REVOKE
• 难以绕过： 多语句攻击和由注释包裹的写入操作会在 AST 层面被拦截，而不只是匹配关键字
• 允许： SELECT、UNION、EXPLAIN、SHOW、DESCRIBE、PRAGMA

这是纵深防御措施——你也应使用只读数据库用户，但即使该用户拥有写入权限，a2db 也不会允许写入操作通过。

写入支持已在核心中实现，但尚未通过 MCP 暴露。计划支持：按连接设置写入权限，并由人类操作员（而非 Agent）明确启用。请参阅 TODO.md。

凭据存储

连接以 TOML 文件形式保存在 ~/.config/a2db/connections/ 中。

• ${DB_PASSWORD} 语法——环境变量引用会以字面形式存储，仅在连接时展开。密钥保留在环境中，不会写入磁盘。
• 列表输出不含密钥——list_connections 会显示项目／环境／数据库和数据库类型，但绝不会显示 DSN 或密码
• 连接文件保存在你的本地计算机上，不属于任何代码仓库

部署范围

a2db 当前以本地 stdio MCP 服务运行。它会继承启动它的进程（你的 shell、Claude Code、Docker）的环境变量。这是本地 MCP 服务采用的标准模式，DBHub、Google Toolbox 等也使用相同方式。

计划中： 按照 MCP 规范支持带 OAuth 2.1 的远程 HTTP 传输。目前，如果在 Docker 中运行，请在容器运行时通过环境变量注入密钥。

对比

功能	a2db	DBHub	Google Toolbox	PGMCP	Supabase MCP
数据库	5 种（PG、SQLite、MySQL、Oracle、MSSQL）	5 种（PG、MySQL、MSSQL、MariaDB、SQLite）	40+ 种（云服务 + OSS）	仅 PG	PG（Supabase）
批量查询	命名字典 + 列表	用分号分隔	不支持	不支持	不支持
默认连接	设置一次，供所有操作使用	每条查询单独设置	不适用	单个数据库	单个项目
只读	SQLGlot AST（强制执行）	关键字检查（配置项）	提示／注释	只读事务 + 正则表达式	配置标记
写入支持	计划中（按连接设置）	配置标记	通过工具定义	不支持	配置标记
输出	JSON + TSV 数据	结构化文本	MCP 协议	表格 / JSON / CSV	JSON
架构发现	3 个详细级别	专用工具	预构建工具	通过自然语言转 SQL	专用工具
预配置	在 MCP 配置中使用 --register	配置文件	YAML 配置	环境变量	云端管理
凭据	DSN 中的 ${ENV_VAR}	DSN 字符串	环境变量 + GCP IAM	环境变量	OAuth 2.1
捆绑驱动程序	全部包含	全部包含	因情况而异	内置	托管
命令行	支持	不支持	支持	支持	不支持
错误上下文	列建议 + 类型	无	无	无	无
许可证	Apache 2.0	MIT	Apache 2.0	Apache 2.0	Apache 2.0

如何选择：

• a2db — 适合需要简洁输出的多数据库批量查询，采用 Agent 优先设计，设置快速
• DBHub — 适合通过 TOML 配置自定义工具，并使用 Web 工作台界面
• Google Toolbox — 适合 GCP 生态系统、IAM 集成和 40+ 个数据源
• PGMCP — 适用于 PostgreSQL 的自然语言转 SQL（需要 OpenAI 密钥）
• Supabase MCP — 适用于完整的 Supabase 平台管理（边缘函数、分支、存储）

按环境设置

本地（macOS / Linux）

pip install a2db

# CLI
a2db login -p myapp -e dev -d main 'postgresql://user:pass@localhost/mydb'

# Or add as MCP server (see Quick Start)

Docker

FROM python:3.12-slim
RUN pip install a2db
CMD ["a2db-mcp", "--register", "myapp/prod/main", "postgresql://user:${DB_PASSWORD}@host/mydb"]

docker run -e DB_PASSWORD=secret -i my-a2db-image

密钥会在运行时作为环境变量注入，绝不会写入镜像。

CI / 自动化

pip install a2db

# Pre-configured — no login needed
a2db-mcp --register myapp/ci/main "postgresql://ci_user:${CI_DB_PASSWORD}@db-host/mydb"

# Or use CLI directly
a2db login -p myapp -e ci -d main "postgresql://ci_user:${CI_DB_PASSWORD}@db-host/mydb"
a2db query -p myapp -e ci -d main "SELECT COUNT(*) FROM migrations"

开发

make bootstrap   # Install deps + hooks
make check       # Lint + test + security (full gate)
make test        # Tests with coverage (90% minimum)
make lint        # Lint only (never modifies files)
make fix         # Auto-fix + lint

许可证

Apache 2.0

---

_{🗄️ 自 2025 年起，以 Agent 为先的数据库访问。}

_{由 Denis Tomilin 构建}