所有数据库工具都默认键盘前坐着一个人。Quarry 默认操作者是 agent —— 给它一个带安全栏的查询内核,长出多张脸:CLI、GUI、agent skill、MCP。
$ qy exec shop --sql "select …" --format json ✓ exit 0 — auto LIMIT applied $ qy exec shop --sql "delete from orders" ✗ exit 8 — blocked without --write
DBeaver、TablePlus、pgAdmin —— 都是好工具,但都是为"人在点击"设计的。而越来越多的查询由 AI agent 在 skill、脚本、CI 里执行。agent 不会"自己小心",工具必须替它小心。
GUI/MCP/Python 返回 {columns, rows, rowCount, truncated, elapsedMs, engine, sql};CLI JSON 输出行数组 —— 稳定的结构化契约。不用爬屏幕,不用解析文字。
查询入口共享默认只读和行数限制。写入需显式授权:CLI/MCP 对 prod 额外确认,Python 由调用方取得授权;GUI 查询保持只读。
CLI 查询退出码区分成功、连接/执行失败和安全拦截;参数及其他命令的错误含义另有约定。GUI/MCP/Python 提供结构化错误,详见下方接口契约。
我们没有往数据库 GUI 上钉一个聊天机器人。
你的 agent 本来就是 —— Quarry 给它一个通往数据的安全插座。
qy gui 在同一个内核上起一个本地零构建 web 工作台:分组连接树 + 环境切换器(prod 变红)、多标签 SQL 编辑器(补全)、一键 EXPLAIN、类型着色网格(键盘导航 + 可折叠 JSON 查看器)、可搜索历史 —— 亮暗双主题、中英双语,浏览器存储可用时保留草稿和有大小限制的结果快照;大结果仅保留在当前会话。Redis key 已支持可折叠命名空间树。
连接管理、查询执行、schema 内省、安全栏都在一个可 import 的内核里,其余全是薄壳。共享修复惠及各查询入口;授权方式和错误呈现由各入口明确约定。
连接 · 执行 · 内省 · 安全栏 · 结果契约
CLI 写入需 --write,prod 还需确认或 --yes;MCP 需服务端和调用同时授权,prod 额外要求 confirm_prod。Python 由调用方通过 allow_write=True 授权;GUI 查询只读。无外层 LIMIT 的读查询默认 500 行,--max-rows 0 可取消;工具/锁定查询不改写,Redis 在取回后截断。环境默认 dev。
一个 workspace 就是一个目录:connections.toml 加上带元信息头的 .sql 命名查询。查询文件和不含凭据的配置模板可放进你的仓库共享;真实连接凭据留在本机。Quarry 能把多个 workspace 聚合到同一个视图。
[shop_dev] url = "postgresql://user:password@dev.example.com:5432/shop" db = "shop" env = "dev" [shop_prod] url = "postgresql://user:password@prod.example.com:5432/shop" db = "shop" env = "prod" [internal_db] url = "postgresql://user:password@127.0.0.1:5432/appdb" ssh_host = "bastion.example.com" # auto tunnel
-- @name: recent_orders -- @db: shop -- @desc: Latest orders with customer names -- @param: days (int, default=7) SELECT o.id, c.name, o.amount, o.status FROM orders o JOIN customers c ON c.id = o.customer_id WHERE o.created_at > now() - make_interval(days => :days) ORDER BY o.created_at DESC;
同一个逻辑库的 dev / staging / prod 折叠成一个 env-set —— 一份命名查询跑任意环境:qy run recent_orders --env prod。
基础包与 GUI 使用 Python 3.11+ 标准库。PostgreSQL、Redis、SSH 使用系统客户端;MySQL 使用可选 Python 驱动。可选 keeper 在后台运行,无需 Electron 或 Quarry 托管服务。
Neptune 属于实验性支持:已提供 openCypher 端点接入,真实 AWS/IAM 行为尚未完成发布验收。本地空端点不执行或存储图数据。已验证环境、持久化限制和错误码详见支持与接口契约。
from quarry import run_query —— CLI、GUI、MCP server 用的同一个内核,三行代码进你自己的工具,共享查询策略并返回 QueryResult;CLI JSON 输出行数组。
Quarry 不向 Quarry 服务上传连接凭据、查询或结果;查询发送到你配置的目标数据库。GUI 默认绑定 localhost 并检查本地来源。PyPI 更新检查可用 QUARRY_UPDATE_CHECK=0 关闭。