内容
# Quarry
> **为 AI 时代打造的数据库工作台** — 一个内核，多张面孔（命令行 / 图形界面 /代理技能）。
[
[](https://pypi.org/project/quarry-db/)
[](LICENSE)
[中文文档 →](README.zh-CN · [官网 →](https://quarry.yiminlab.site)
你所知道的数据库工具——DBeaverPlus、pgAdmin——都假设键盘前坐着的是**人类**。但越来越多的情况是，运行查询的是**AI ，而代理需要不同的保证：
- **机器可解析的结果**，而不是人类可读的屏幕
- **内核中的**，以便任何客户端都无法忘记它们
- **确定性的错误合约**（稳定的退出代码），而不是堆栈跟踪
- **配置文件**，而不是点击操作——这样可以进行版本控制、差异比较和与代理共享arry 颠覆了传统设计：它是一个**具有代理的查询内核**，而人类界面（命令行、图形界面）只是从同一内核中衍壳。无论查询来自浏览器中的人员、CI 中的运行技能的 Claude，它都经过相同的防护栏并返回相同的结构化结果。
## 哲学
1. **一核多面。** 连接管理、查询执行、模式 introspection 和安全防护栏都位于可导入的内核（`quarry.core`）命令行（`qy`）、图形界面、MCP 服务器和代理技能都是薄壳。修复一个 bug，一切面孔都将受益。
2. **默认只读；提升权限是显式且分级的。** 在未传递 `--write` 的情况下，写入和 DDL 操作被阻止（退出代码 `8`）。生产环境连接需要在 `--write` 的基础上进行额外的确认。每条查询都自动获得 `LIMIT 500`，除非你选择退出。因为防护栏位于内核中，所以代理无法通过选择不同的入口点来绕过它们。
3. **机器可信的合约。** 每个查询都返回 `{columns, rows, rowCount, truncated, elapsedMs, engine, sql}`。退出代码是稳定的 API：`0` 确认、`2` 连接错误、`3` SQL 错误、`8` 安全阻止。代理可以根据结果分支，而无需解析文本。
4. **工作区即代码 工作区只是一个目录：` + `queries/**/*.sql`（带有 `-- @ 头的命名查询）。**你的**仓库中，由版本控制，并可以在团队成员和代理之间共享。内核包含任何业务逻辑和。
5. **几乎。** 纯标准库。PostgreSQL 通过系统 `` 访问，Redis 通过-cli` 访问，SSH通过系统 `ssh`MySQL 只需要一个 `pymysql`。没有 Electron，没有守护进程，没有云。
## 安装
```bash
pipx install quarry-db # 或：pip install quarry-db
qy --help
```
PostgreSQL 使用系统 `psql` 二进制文件；MySQLpip install "quarryysql]"`。
##入门
```bash
mkdir my-workspace && cd my-workspace
cat > connections.toml <<'EOF'
[shop]
url = "postgresql://user:pass@localhost:5432/shop"
engine = "postgres"
env = "dev"
EOF
qy connections # 列出连接
qy exec shop --sql "select customers"
qy schema shop # 表结构 (\d+)
qy gui # 浏览器数据网格
```
## 工作工作区目录是连接和查询的源：
```
my/
├── connections.toml # [key] url / engine / env / group / notes
└── queries/<db>/*.sql # 命名查询（带有 -- @meta 头）
```
解析顺序：`--workspace PATH` → `~/.config/quarry/config.toml` → 当前目录。
## 命令行参考
| 命令 | 目的 |
|---------|---------|
| `qy connections [list\|add\|set\|remove\|test]` | 管理连接 |
| `qy exec <db> --sql "..." [--format json\|ndjson\|csv\|table]` | 运行临时 SQL |
| `qy schema <db> <table>` | 实时表结构 |
| `qy run <name> [k=v ...]` | 运行已保存的命名查询 |
| `qy save <name> --db X --sql "..."` | 保存命名查询 |
| `qy list / describe / validate / fingerprint / audit` | 管理命名查询 |
| `qy workspace list/add/remove` | 管理聚合工作区 |
| `qy gui` | 启动本地图形界面 |
| `qy mcp [--write]` | 通过 stdio 提供 MCP 接口（适用于 AI 代理） |
## MCP（适用于代理的原生接口）
mcp` 通过 提供模型上下文协议——纯标准库，无需 SDK 依赖。代理获得六种工具（`list_connections`、`list_tables`、`describe_table`、`exec_sql`、`list_saved_queries`、`run_saved_query`），具有相同的内核防护栏：除非服务器启动时write` *和* 调用传递 `write: true`，否则只读；生产环境还需要 `confirm_prod: true`。
```bash
# Claude 代码
claude mcp add quarry -- qy mcp --workspace ~/my-workspace
```
```json
// 或任何 MCP 客户端（.mcp.json）
{ "mcpServers": { "quarry": { "command": "qy", "args": ["mcp", "--workspace", "/path/to/workspace"] } } }
```
已在 [MCP 注册表](https://registry.modelcontextprotocol.io/) 上发布，名称为 `mcp-name: io.github.Wangggym/quarry`。
## 安全防护栏（AI 原生护城河）
- **默认只读**：写入/DDL 操作被阻止，退出代码为 `8`；使用 `--write` 允许
- **自动行限制**：`run_query()` 注入 `LIMIT 500`；使用 `--max-rows N` 提升限制
- **分级生产保护**默认为只读 → 开发环境需要 `--write` → 生产环境需要 `--write`* 交互式确认（`--yes` 用于自动化）
- **稳定退出代码合约**：`0` 确认 / `2` 连接错误3` SQL 错误 / `8` 安全阻止
## 作为库（图形界面和代理使用）
```python
arry import configure_workspace,, run_query
configure_workspace("~/my-workspace")
res = run_query(get_connection("shop"), "select * from customers")
print(res.to_dict()) # {columns, rows, row truncated, elapsedMs, sql}
```
## SSH 隧道
对于只能通过堡垒机访问的数据库，请添加 `ssh_*` 字段` 将自动打开隧道（系统 `ssh`依赖）：
```toml
[internal_db]
url = "postgresql://user:pass.0.5432/appdb"
engine = "postgres"
ssh_host = "bastion.example.com"
ssh_user = "ubuntu"
ssh_key = "~/.ssh/id_ed25519"
```
## Redis
`engine = "redis"`（使用系统 `redis-cli`）。查询是 Redis 命令：
```bash
qy exec cache --sql "SCAN 0 COUNT 100"
qy exec cache --sql "ALL user:只读防护栏同样适用：`GET/SCAN/TTL/HGETALL` 通过；`SET/DEL/FLUSHALL` 在没有 `--write` 的情况下。在图形界面中，Redis 键是可点击的，并具有 TYPE 感知值显示。
## 分组和环境集
连接可以组织成**项目文件夹**（`group`）和**环境集**（相同的 `db`，不同的 `env`，共享模式）：
```toml
[shop_dev]
url = "postgresql://…dev…/shop"; group = "shop"; db = "shop"; env = "dev"
[shop_prod]
url = "postgresql://…prod…/shop"; group = "shop"; db = "shop"; env = "prod"
```
- 具有相同 `db`会折叠成一个环境集——一个已保存的查询可以针对任何环境运行：`qy exec shop --env prod`
- 未指定的环境默认为 `dev`（最安全）
- 图形界面显示环境切换器（生产环境变为红色）
## 多个
`qy` 聚合了 `~/.config/quarry/config.toml` 中列出的所有工作区——一个图形界面/命令行适用于所有项目：
```bash
qy workspace add ~/projects/acme/db-workspace
qy workspace add ~/projects/side-project/db
qy connections # 两个项目，qy gui # 侧边栏显示并排
```
` a:b`（以 `os.pathsep` 分隔）作为临时覆盖；第一个目录。
## 图形界面
gui` — 一个本地的、零构建的 Web 图形界面（Slate & Copper 主题，浅色/深色）：
- 分组侧边栏树，带有环境切换器（生产环境显示为红色），连接健康状态点
- **多标签编辑器** —标签页都记住其 SQL + 连接，重启后仍保持不变
- SQL 高亮 + 本地自动补全（关键字 / 表 / 列）
- **EXPLAIN 按钮** — 一键查询计划
- 类型感知数据网格：排序、列宽调整、**键盘（箭头 + Enter检查，带有 **可折叠的 JSON 树**
- CSV/JSON 导出、**可搜索的查询历史记录**（带有连接 + 时间）
- 类型感知 Redis 键浏览
## 路线图
- 所有引擎的结果合约中的列类型
- SQLite 和 DuckDB 引擎（零设置本地演示）
- Redis 键命名空间树
- 跨环境模式/数据差异
- 写入审计日志（谁运行了什么，在哪里，什么时候）
- 单二进制分发
## 开发
```bash
pip install -e ".[dev]"
createdb quarry_test && psql quarry_test -f tests/seed.sql
python3 -m pytest -q
```
数据库测试在 PostgreSQL 无法访问时自动跳过；单元测试。参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
Quarry 在 macOS 和 Linux 上开发和测试。Windows 目前未测试（`psql` / `ssh` 集成和端口占用是 Unix 特有的）——欢迎提交 PR。
## 许可证
](LICENSE)
