Quarry

The database workbench built for the AI era — one kernel, many faces (CLI / GUI / MCP / agent skill).

中文文档 → · Website →

Every database tool you know — DBeaver, TablePlus, pgAdmin — assumes a human at the keyboard. But increasingly, the entity running your queries is an AI agent, and agents need different guarantees:

• Results a machine can parse, not a screen a human can read
• Safety rails that live in the kernel, so no client can forget them
• Deterministic error contracts (stable exit codes), not stack traces to scrape
• Configuration as files, not clicks — so it can be versioned, diffed, and shared with agents

Quarry inverts the traditional design: it is a query kernel with an agent-safe contract first, and the human faces (CLI, GUI) are thin shells grown from the same kernel. Whether a query comes from a person in the browser, a script in CI, or Claude running a skill, it passes through the exact same safety rails and returns the exact same structured result.

Philosophy

1. One core, many faces. Connection management, query execution, schema introspection, and safety rails live in an importable kernel (quarry.core). The CLI (qy), the GUI, the MCP server, and agent skills are thin shells. Fix a bug once, every face gets it.

2. Read-only by default; escalation is explicit and graduated. Writes and DDL are blocked (exit code 8) unless you pass --write. Production connections require an additional confirmation on top of --write. Every query gets an automatic LIMIT 500 unless you opt out. Because the rails are in the kernel, an agent cannot bypass them by picking a different entry point.

3. A contract machines can trust. Every query returns {columns, rows, rowCount, truncated, elapsedMs, engine, sql}. Exit codes are stable API: 0 ok, 2 connection error, 3 SQL error, 8 safety block. An agent can branch on outcomes without parsing prose.

4. Workspace as code. A workspace is just a directory: connections.toml + queries/**/*.sql (named queries with -- @meta headers). It lives in your repo, versioned by git, shared between teammates and agents alike. The kernel itself carries zero business logic and zero secrets.

5. Nearly zero dependencies. Pure stdlib. PostgreSQL goes through your system psql, Redis through redis-cli, SSH tunnels through system ssh. MySQL is one optional pymysql. No Electron, no daemon, no cloud.

Install

pipx install quarry-db        # or: pip install quarry-db
qy --help

PostgreSQL uses the system psql binary; MySQL needs pip install "quarry-db[mysql]".

Quickstart

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                       # list connections
qy exec shop --sql "select * from customers"
qy schema shop customers             # table structure (\d+)
qy gui                               # browser data grid

Workspace

A workspace directory is the source of connections + queries:

my-workspace/
├── connections.toml      # [key] url / engine / env / group / notes
└── queries/<db>/*.sql    # named queries (with -- @meta headers)

Resolution order: `--workspa

... View full README on GitHub