Skip to main content
Glama
README.md
# Quarry 2

A native database workbench: one reusable Rust kernel, CLI, browser GUI and MCP.
PostgreSQL, MySQL, SQLite, Redis and experimental Neptune; explicit query/write
policies, SSH tunnels, saved queries, local Docker services and a SQL assistant.

## Install

Quarry 2.x ships as a native Rust executable.

```sh
curl -fsSL https://yiminspace.github.io/quarry/install.sh | sh
qy --version
qy gui
```

Or download a native archive and SHA256SUMS from [GitHub Releases](https://github.com/yiminspace/quarry/releases).
The native executable needs neither Python nor a Rust toolchain. Supported:
macOS/Linux arm64/x86_64; Linux glibc 2.28+. See [install and upgrade](docs/install.md).

Installer-managed copies can download new stable versions in the background.
The next launch activates the verified update. Run `qy update` to update now.

## Use

Run `qy gui stop` from another terminal to shut down the local standalone GUI.
Use the same `--config`, `--workspace`, `--host`, and `--port` overrides as at
launch. If you started with `--port 0`, use the port in the printed GUI URL.

```sh
qy --workspace /path/to/workspace connections
qy --workspace /path/to/workspace exec shop --env dev --sql 'SELECT 1'
qy --workspace /path/to/workspace mcp
```

Workspaces contain `connections.toml` and reusable SQL query files. Actual
credentials remain local. GUI queries stay read-only; CLI writes require
`--write` and production confirmation. MCP writes require both server and
request authorization. SQLite opens existing files; it never invents a database
when a connection path is wrong. Assistant proposals never execute themselves.

Ordinary queries use native database drivers. SSH needs system ssh; Local
services need Docker, and PostgreSQL schema sync needs pg_dump/psql.

## Rust and Python

Rust owns main and all 2.x distribution. `quarry-core`, `quarry-runtime`,
`quarry-local`, `quarry-assistant` and `quarry-service` can be embedded directly
in host applications. [Architecture](docs/rust-migration.md).

For a hosted workbench, the official Docker image serves the GUI, authentication,
read-only API and execution from one configuration file. Use a built-in
administrator or configure an existing platform's IAM. Standalone `qy` runs
locally with its own workspaces.
See the [hosting guide](docs/hosting.md) for deployment, access grants and offline
behavior. The Rust SDK remains available for advanced embedding.

Python 1.11.0 is preserved at its tag and the protected `archive/python-1.x`
branch. Python import APIs do not ship in 2.x. The Python source retained in this
checkout is a development/test baseline, not a runtime dependency or published
Python implementation. Existing configuration, saved queries and histories are
read by Rust. See upgrade instructions before changing installer ownership.

## Build and verify

For frontend development, start the Rust workbench and Vite in separate terminals.

```sh
qy gui --no-browser
```

```sh
cd web
npm ci
npm run dev
```

Open the Vite URL ending in `/quarry/`. Vite reloads frontend changes and forwards
`/api` to the local Rust workbench on port 8765. If `qy gui` uses a different
port, start Vite with `QUARRY_DEV_API_PORT=<port> npm run dev`.

For a native build and the existing test workflow:

```sh
cd web && npm ci && npm run build && cd ..
cargo build --release --locked -p quarry-cli
cargo test --workspace --all-targets --locked
```

[GUI feature matrix](TESTING.md) · [Compatibility](COMPATIBILITY.md) ·
[Verification boundaries](docs/rust-verification.md) · [中文](README.zh-CN.md)