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
• Shared query safety policies, with explicit authorization by entry point
• 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 uses shared query policies. CLI formats render rows; the GUI, MCP and Python API expose a structured QueryResult. See the interface and support contract for the exact boundaries.

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. CLI writes require --write; prod additionally needs confirmation or --yes. MCP requires server and per-call authorization, plus confirm_prod for prod. GUI queries are read-only; Python callers obtain authorization before passing allow_write=True. Read queries without an outer LIMIT default to a 500-row cap; --max-rows 0 explicitly disables it. PostgreSQL/MySQL query execution also uses database read-only transactions unless writes are authorized.

3. A contract machines can trust. GUI/MCP/Python queries return {columns, rows, rowCount, truncated, elapsedMs, engine, sql, downloadBytes, sizeIsEstimated}. CLI JSON remains an array of rows; diagnostics and truncation notices go to stderr. Exit codes are stable API: 0 ok, 2 connection error, 3 SQL error, 8 safety block. CLI argument syntax errors also use 2; other commands have their own codes (for example ping returns 1 on failure). GUI/MCP/Python report structured errors.

4. Workspace as code. A workspace is just a directory: connections.toml + queries/**/*.sql (named queries with -- @meta headers). Share query files and credential-free templates through your repo; keep actual connection credentials local.

5. Nearly zero dependencies. The base package and GUI use Python 3.11+ stdlib. PostgreSQL uses system psql, Redis needs redis-cli 6+, SSH uses system ssh, and MySQL uses the optional quarry-db[mysql] dependencies. No Electron or cloud service; the optional qy up keeper runs in the background.

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: --workspace PATH → ~/.config/quarry/config.toml → current directory.

See COMPATIBILITY.md for lossless number/string representations, write support by entry point, stable interfaces and tested environment boundaries.

CLI reference

MCP (the agent-native face)

qy mcp speaks the Model Context Protocol over stdio — pure stdlib, no SDK dependency. Agents get six tools (list_connections, list_tables, describe_table, exec_sql, list_saved_queries, run_saved_query) with the exact same kernel rails: read-only unless the server was started with --write and the call passes write: true; a prod env additionally requires confirm_prod: true.

# Claude Code
claude mcp add quarry -- qy mcp --workspace ~/my-workspace

{ "mcpServers": { "quarry": { "command": "qy", "args": ["mcp", "--workspace", "/path/to/workspace"] } } }

Published in the MCP Registry as mcp-name: io.github.Wangggym/quarry.

Safety rails (the AI-native moat)

• CLI read-only default: writes/DDL blocked with exit code 8; --write to allow
• Automatic row cap: read queries without an outer LIMIT default to 500 rows; raise with --max-rows N, disable with --max-rows 0 (utility/locking queries are not rewritten; Redis caps after receipt)
• CLI prod protection: all envs default read-only → dev needs --write → prod needs --write plus an interactive confirmation (--yes for automation)
• Query exit codes: 0 success (rows optional), 1 usage, 2 connection or CLI argument syntax, 3 execution, 8 safety block; other commands have their own documented codes

Timeouts

Query execution and connection establishment (including SSH tunnel setup) are capped independently, so an unreachable host fails fast instead of eating the whole query budget:

• Connect timeout: 15s, fixed — bounds tunnel/dial only.
• Execute timeout: 300s default for the CLI/GUI, 120s for MCP (agents should converge faster).

The effective execute timeout is resolved in priority order:

1. --timeout N (CLI, on qy exec/qy run)
2. QUARRY_TIMEOUT env var
3. the connection's timeout field in connections.toml (set via qy connections add/set --timeout N)
4. the default above

[shop_prod]
url     = "postgresql://…prod…/shop"
timeout = 600   # this connection alone gets 10 minutes

On PostgreSQL, qy also sets a server-side statement_timeout (~90% of the execute timeout) before running the query; on MySQL/MariaDB it sets the equivalent session variable (MAX_EXECUTION_TIME / max_statement_time, whichever the server supports) best-effort. PostgreSQL enforces its statement timeout server-side. MySQL support is best-effort and its MAX_EXECUTION_TIME applies to SELECTs; a client timeout is not proof that a write was cancelled. A timeout error always tells you how to raise it (--timeout, QUARRY_TIMEOUT, or the connection's timeout setting). --timeout and the timeout field must be a positive number of seconds.

As a library (what the GUI and agents use)

from quarry import configure_workspace, get_connection, run_query

configure_workspace("~/my-workspace")
res = run_query(get_connection("shop"), "select * from customers")
print(res.to_dict())   # {columns, rows, rowCount, truncated, elapsedMs, engine, sql}

SSH tunnels

For databases only reachable via a bastion, add ssh_* fields and qy opens the tunnel automatically (system ssh, zero dependencies):

[internal_db]
url      = "postgresql://user:pass@127.0.0.1:5432/appdb"
engine   = "postgres"
ssh_host = "bastion.example.com"
ssh_user = "ubuntu"
ssh_key  = "~/.ssh/id_ed25519"

Neptune participates in the same tunnel path now: if a Neptune connection has ssh_host (plus optional ssh_user/ssh_key/ssh_port), it joins tunnel pooling/keep-alive the same way as Postgres/MySQL/Redis.

Workspace keep-alive (qy up/down/status)

If you query the same SSH-backed connections repeatedly (CLI + GUI + MCP), run the workspace keeper once and reuse warm forwards across processes:

qy up                    # enable keep-alive; default reconnect on unless explicitly disabled
qy status                # text status: keeper + per-connection tunnel state
qy status --format json  # per-tunnel state (up/reconnecting/down/blocked)
qy down                  # stop keeper