使用说明
🗄️ a2db
Agent-to-Database
Give AI agents safe, read-only access to your databases. One call, multiple queries, clean results.
5 databases · batch queries · pre-configured connections · SQLGlot read-only
Quick Start · MCP Tools · Security · Comparison · Setup
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"
为什么是2db？
大多数数据库MCP服务器使您一次运行一个查询，在每次调用时重复连接详细信息，并在JSON字符串中返回双重编码的结果。a2db修复了所有这些问题：
- 预配置连接 --在中定义数据库
.mcp.json随着--register，代理立即查询 - 批量查询 --在单个工具调用中运行多个命名查询
- 默认连接 --设置一次连接，在批处理中的所有查询中使用它
- 清洁输出 --结构化JSON信封，包含紧凑的TSV数据和每个查询的时间（请参阅 为什么是TSV？)
- 强制只读 --SQLGlot AST解析阻止所有写入操作
- 所有驱动程序捆绑 —
pip install a2db你完了 - 秘密留在环境中 —
${DB_PASSWORD}在DSN中，仅在连接时扩展
支持的数据库
| 数据库 | 驱动程序 | 异步 |
|---|---|---|
| PostgreSQL | 异步pg | 本机 |
| SQLite | aiosqlite | 原生 |
| MySQL/MariaDB | MySQL连接器python | 封装 |
| Oracle | oracledb | 已包装 |
| SQL Server | pymssql | 已包装 |
快速开始
pip install a2db
作为MCP服务器（推荐）
克劳德代码 （具有预配置的连接）：
claude mcp add -s user a2db -- a2db-mcp \
--register myapp/prod/main 'postgresql://user:${DB_PASSWORD}@host/mydb'
克劳德代码 （最少——代理调用 login 按需）：
claude mcp add -s user a2db -- a2db-mcp
克劳德桌面/光标/任何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 在服务器启动时预注册连接——代理可以立即查询。密码使用 ${ENV_VAR} 语法，在连接时扩展，从不以明文存储。
作为CLI
# 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？
LLM上下文窗口很昂贵。JSON行数据很冗长——每一行都重复每个列名，添加大括号、逗号和引号。TSV是一个平面网格：一个标题行，然后是由制表符分隔的值。
对于100行、5列的结果集，TSV通常使用 代币数量减少40-60% JSON行格式。结构化的JSON信封仍然为您提供元数据（行数、截断状态）——只有行有效载荷是TSV。
集 format="json" 如果您需要每行都有列名的完整结构化输出。
安全
只读执行
每个查询都由解析 SQLGlot 执行前：
- 此 路 不通： 插入、更新、删除、删除、截断、更改、创建、授予、撤销
- 旁路阻力： 多语句攻击和注释包装写入是在AST级别捕获的，而不仅仅是关键字匹配
- 允许： 选择、结合、解释、展示、描述、语用
这是深度防御——你也应该使用只读数据库用户，但a2db不会让写通过，即使用户有写权限。
撰写支持 在核心中实现，但尚未通过MCP暴露。计划：每个连接的写入权限，由人工操作员明确启用，而不是代理。看 TODO.md.
凭据存储
连接保存在 ~/.config/a2db/connections/ 作为TOML文件。
${DB_PASSWORD}语法 --环境变量引用按字面意思存储，仅在连接时扩展。秘密留在你的环境中，而不是磁盘上。- 列表输出中没有秘密 —
list_connections显示项目/env/db和数据库类型，从不显示DSN或密码 - 连接文件位于您的计算机本地，不在任何存储库中
部署范围
a2db当前作为 本地stdio MCP服务器它继承了启动它的进程（你的shell、Claude Code、Docker）的环境变量。这是本地MCP服务器的标准模型，与DBHub、Google Toolbox和其他服务器使用的方法相同。
计划： 根据MCP规范，使用OAuth 2.1进行远程HTTP传输。目前，如果在Docker中运行，请在容器运行时通过环境变量注入secrets。
比较
| 功能 | a2db | DBHub | 谷歌工具箱 | PGMCP | Supabase MCP |
|---|---|---|---|---|---|
| 数据库 | 5（PG、SQLite、MySQL、Oracle、MSSQL） | 5（PG，MySQL，MSSQL，MariaDB，SQLite） | 40+（云+OSS） | 仅限PG | PG（Supabase） |
| 批量查询 | 命名字典+列表 | 分号分隔 | 否 | 否 | 无 |
| 默认连接 | 设置一次，全部使用 | 每次查询 | N/A | 单个数据库 | 单个项目 |
| 只读 | SQLGlot AST（强制） | 关键字检查（配置） | 提示/注释 | 只读tx+正则表达式 | 配置标志 |
| 撰写支持 | 计划（每个连接） | 配置标志 | 通过工具定义 | 否 | 配置标志 |
| 输出 | JSON+TSV数据 | 结构化文本 | MCP协议 | 表/JSON/CSV | JSON |
| 架构发现 | 3个细节级别 | 专用工具 | 预构建工具 | 通过NL到SQL | 专用工具 |
| 预配置 | --register 在MCP配置 |
配置文件 | YAML配置 | 环境变量 | 云管理 |
| 凭证 | ${ENV_VAR} 在DSN |
DSN字符串 | 环境变量+GCP IAM | 环境变量 | OAuth 2.1中 |
| 捆绑驱动程序 | 全部包含 | 全部包含 | 各不相同 | 内置 | 管理 |
| 命令行界面 | 是 | 否 | 是 | 是 | 否 |
| 错误上下文 | 列建议+类型 | 否 | 否 | 无 | 否 |
| 许可证 | Apache 2.0 | 麻省理工学院 | Apache 2.0 | Apache 2.0 |
何时使用什么：
- a2db --多数据库批量查询，输出清晰，代理优先设计，快速设置
- DBHub --通过TOML配置、web工作台UI定制工具
- 谷歌工具箱 --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)
码头工人
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
🗄️ Agent-first database access since 2025.
Built by Denis Tomilin
