Agent 拿到的是批准查询的菜单,而不是 SQL 储藏室的钥匙。
1. 动机
自由生成 SQL 会让执行难以审查。 Database 扩展让应用把批准的 snippet 与可搜索 predicate 持久化为类型化行,再公开狭窄的 MCP 表面。 请先完成数据连接,使ws、database_id 与 warehouse.db 存在于同一个 Python 进程。
2. 注册只读 Snippet
db-database 行标识外部数据源。
3. 通过附属 API 运行
suggest_sql 搜索批准的 snippet 与 predicate。
它不会要求 LLM 在引擎内部发明 SQL。
除非显式启用 heavenbase.database.allow_write,写入 snippet 仍会被拒绝。
默认值是 false。
4. 添加可搜索 Predicate
suggest_sql 不会执行它们。
5. 公开 Database Profile
database Profile 限定普通读取/查询工具以及 suggest_sql 与 run_snippet。
准备好向外部 Agent 注册并服务 Toolkit 时,请使用 MCP Toolkit 参考。
6. 保持诚实边界
- Schema 摄取不会复制源数据行。
- 搜索提出批准的 snippet,但不会执行它们。
- Snippet 执行会重新连接外部数据库。
- 只读是默认值,而写访问是一项刻意的配置变更。
- HeavenBase 不声称与源数据库形成分布式事务。
总结
- 把批准的 SQL 持久化为
db-snippet行。 - 应用直接调用时使用
ws.database。 - 使用
databaseMCP Profile 提供小型 Agent 表面。 - 把连接凭据留在执行环境中。

