quarry

Quarry

AI 時代のために構築されたデータベースワークベンチ — 1 つのカーネルで、さまざまな形態に対応します（CLI / GUI / MCP / エージェントスキル）。

中国語ドキュメント → · ウェブサイト →

DBeaver、TablePlus、pgAdmin など、よく知られているデータベースツールはすべて、キーボードの前にいるのは 人間 であることを前提としています。しかし、クエリを実行する存在はますます AI エージェント になりつつあり、エージェントには異なる保証が必要です。

• 人間が読む画面ではなく、機械が解析できる結果
• エントリーポイントごとに明示的な認可を行う、共有クエリ安全ポリシー
• スクレイピングが必要なスタックトレースではなく、決定論的なエラー契約（安定した終了コード）
• クリック操作ではなく、ファイルによる設定 — そのため、バージョン管理、差分確認、エージェントとの共有が可能です

Quarry は従来の設計を逆転させます。まず エージェントに安全な契約を備えたクエリカーネル として設計され、人間向けのインターフェース（CLI、GUI）は同じカーネルから派生した薄いシェルです。クエリがブラウザー上のユーザー、CI のスクリプト、スキルを実行する Claude のいずれから来ても、共有クエリポリシーが適用されます。CLI は行をフォーマットして表示し、GUI、MCP、Python API は構造化された QueryResult を公開します。正確な境界については、インターフェースとサポート契約をご覧ください。

設計思想

1. 1 つのコアで、さまざまな形態に対応します。 接続管理、クエリ実行、スキーマイントロスペクション、安全機構は、インポート可能なカーネル（quarry.core）に集約されています。CLI（qy）、GUI、MCP サーバー、エージェントスキルは薄いシェルです。バグを一度修正すれば、すべてのインターフェースに反映されます。

2. デフォルトは読み取り専用。権限の引き上げは明示的かつ段階的です。 CLI で書き込みを行うには --write が必要です。本番環境ではさらに確認、または --yes が必要です。MCP ではサーバーと呼び出しごとの認可に加え、本番環境では confirm_prod が必要です。GUI のクエリは読み取り専用です。Python の呼び出し元は allow_write=True を渡す前に認可を取得します。外側の LIMIT を指定していない読み取りクエリには、デフォルトで 500 行の上限が適用されます。--max-rows 0 を指定すると、この上限は明示的に無効になります。PostgreSQL と MySQL のクエリ実行でも、書き込みが認可されていない限りデータベースの読み取り専用トランザクションを使用します。SQLite は既存のファイルを読み取り専用モードで開きます。

3. 機械が信頼できる契約。 GUI／MCP／Python のクエリは {columns, rows, rowCount, truncated, elapsedMs, engine, sql, downloadBytes, sizeIsEstimated} を返します。CLI の JSON は引き続き行の配列で、診断情報と結果の切り捨て通知は stderr に出力されます。終了コードは安定した API です。0 は成功、2 は接続エラー、3 は SQL エラー、8 は安全機構によるブロックです。CLI の引数構文エラーにも 2 を使用します。それ以外のコマンドには独自のコードがあります（たとえば、ping は失敗時に 1 を返します）。GUI／MCP／Python は構造化されたエラーを報告します。

4. コードとしてのワークスペース。 ワークスペースは単なるディレクトリです。connections.toml と queries/**/*.sql（-- @meta ヘッダーを持つ名前付きクエリ）で構成されます。クエリファイルと認証情報を含まないテンプレートは あなたの リポジトリで共有し、実際の接続認証情報はローカルに保管してください。

5. 依存関係はほぼゼロ。 ベースパッケージと GUI は、SQLite 用の sqlite3 を含め、Python 3.11 以降の標準ライブラリを使用します。PostgreSQL にはシステムの psql が必要です。Redis には redis-cli 6 以降、SSH にはシステムの ssh、MySQL にはオプションの quarry-db[mysql] 依存関係が必要です。Electron やクラウドサービスは不要です。オプションの qy up キーパーはバックグラウンドで動作します。

インストール

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

SQLite では Python 組み込みの sqlite3 を使用するため、サーバー、Docker コンテナ、sqlite3 CLI は不要です。PostgreSQL ではシステムの psql バイナリを使用します。MySQL には pip install "quarry-db[mysql]" が必要です。

クイックスタート

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

SQLite ファイル

qy を実行しているマシン上の既存の SQLite ファイルを接続先に指定します。

[notes_local]
engine = "sqlite"
url = "sqlite:///data/notes-local.db"
db = "notes"
env = "local"

[notes_prod]
engine = "sqlite"
url = "sqlite:////srv/notes/notes.db"
db = "notes"
env = "prod"
production = true

sqlite:///data/notes-local.db は、その接続を含むワークスペースを基準とした相対パスとして解決されます。sqlite:////srv/notes/notes.db は絶対パスです。engine = "sqlite" を明示すれば、通常のファイルパスも使用できます。ファイルが存在しない場合は、書き込みが許可されている場合も含めてエラーになります。Quarry は接続パスの入力ミスによって空のデータベースが作成されることがないよう、空のデータベースを作成しません。

qy connections test notes --env local
qy exec notes --env local --sql "SELECT * FROM notes ORDER BY id"
qy schema notes notes --env local
qy gui

CLI、GUI、MCP、Python API では、テーブル／ビューの閲覧、スキーマの調査、パラメーター、クエリ制限、エクスポートを共通して利用できます。GUI はページングと SQLite の EXPLAIN QUERY PLAN に対応しています。クエリはデフォルトで読み取り専用です。書き込みには他の SQL エンジンと同じ明示的な認可が必要で、GUI は読み取り専用のままです。

local、dev、prod はラベルです。データを分離するには別々のファイルを使用します。同じファイルを指す環境は同じデータにアクセスします。本番環境の保護とデフォルトの Manual モードを有効にするには、production = true を明示的に設定します。SQLite は qy local up、Docker、SSH トンネルを使用しません。リモートファイル、:memory: データベース、SQLite URI オプション、アタッチされたデータベースは、今回の初期実装の対象外です。アプリケーションで本番環境に PostgreSQL を使用している場合は、SQL とデータ型を一致させるため、ローカルでも PostgreSQL を使用してください。

ワークスペース

ワークスペースディレクトリは、接続とクエリの参照元です。

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

解決順序：--workspace PATH → ~/.config/quarry/config.toml → 現在のディレクトリ。

数値／文字列の損失のない表現、各エントリーポイントの書き込みサポート、安定したインターフェース、テスト済みの環境境界については、COMPATIBILITY.md を参照してください。

CLI リファレンス

コマンド	目的
qy connections [list|add|set|remove|test]	接続を管理します
qy ping <db>|--all [--timeout N] [--format text|json]	到達可能性を確認します（成功／失敗＋レイテンシー。いずれかが失敗した場合は終了コード 1）
qy exec <db> --sql "..." [--format json|ndjson|csv|table] [--timeout N]	アドホック SQL を実行します
qy speedtest <db> [--env dev] [--bytes N] [--runs N]	現在の PostgreSQL／MySQL トンネル経路のベンチマークを実行します
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 up/down/status [--format text|json]	ワークスペースのトンネルを維持するキーパーです
qy local up/down/status/sync [--engine postgres|redis|neptune|all]	ローカル開発サービス（下記参照）
qy gui	ローカル GUI を起動します
qy mcp [--write]	MCP インターフェースを stdio 経由で提供します（AI エージェント向け）

MCP（エージェントネイティブなインターフェース）

qy mcp は、純粋な標準ライブラリで、SDK への依存なしに、stdio 経由で Model Context Protocol を使用します。エージェントは 6 つのツール（list_connections、list_tables、describe_table、exec_sql、list_saved_queries、run_saved_query）を、同じカーネルの安全策とともに利用できます。サーバー起動時に --write が指定され、かつ呼び出しで write: true が渡された場合を除き、読み取り専用です。さらに、prod 環境では confirm_prod: true が必要です。

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

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

MCP Registry に io.github.yiminspace/quarry として公開されています。 以前の個人名前空間の掲載情報は、引き続き管理者の支援による移行または非推奨化が必要です。上記の組織エントリーを使用してください。qy mcp の直接設定に変更はありません。

安全対策（AI ネイティブならではの強み）

• CLI はデフォルトで読み取り専用：書き込み／DDL は終了コード 8 でブロックされます。許可するには --write を指定します
• 行数を自動で制限：外側の LIMIT がない読み取りクエリは、デフォルトで 500 行に制限されます。--max-rows N で上限を引き上げ、--max-rows 0 で無効にできます（ユーティリティ／ロック関連のクエリは書き換えられません。Redis では受信後に上限が適用されます）
• CLI の本番環境保護：すべての環境でデフォルトは読み取り専用です。dev では --write が必要です。prod では --write に加えて対話形式の確認が必要です（自動化では --yes を指定します）
• クエリの終了コード：0 成功（行の返却は任意）、1 使用方法、2 接続または CLI 引数の構文エラー、3 実行エラー、8 安全対策によるブロック。その他のコマンドには、それぞれドキュメントに記載されたコードがあります

タイムアウト

クエリ実行と接続確立（SSH トンネルのセットアップを含む）には、それぞれ独立した上限が設定されています。そのため、到達不能なホストに対してクエリ全体の時間を費やすことなく、すぐに失敗します。

• 接続タイムアウト：15s、固定。トンネル／ダイヤルのみを制限します。
• 実行タイムアウト：CLI／GUI ではデフォルトで 300s、MCP では 120s（エージェントはより早く収束する必要があります）。

有効な実行タイムアウトは、次の優先順位で決定されます。

1. --timeout N（CLI、qy exec／qy run で指定）
2. QUARRY_TIMEOUT 環境変数
3. connections.toml 内の接続の timeout フィールド（qy connections add/set --timeout N で設定）
4. 上記のデフォルト値

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

PostgreSQL では、クエリの実行前に qy がサーバー側の statement_timeout（実行タイムアウトの約 90%）も設定します。MySQL／MariaDB では、サーバーがサポートする同等のセッション変数（MAX_EXECUTION_TIME／max_statement_time）をベストエフォートで設定します。PostgreSQL はサーバー側でステートメントのタイムアウトを適用します。MySQL のサポートはベストエフォートであり、MAX_EXECUTION_TIME は SELECT に適用されます。クライアントのタイムアウトは、書き込みがキャンセルされたことの証明にはなりません。タイムアウトエラーには、タイムアウトの延長方法（--timeout、QUARRY_TIMEOUT、または接続の timeout 設定）が必ず表示されます。--timeout と timeout フィールドには、正の秒数を指定する必要があります。

ライブラリとして（GUI とエージェントが使用）

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 トンネル

踏み台経由でのみアクセスできるデータベースの場合は、ssh_* フィールドを追加すると、qy がトンネルを自動的に開きます（システムの ssh を使用し、依存関係はありません）。

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

Neptune も、現在は同じトンネル経路を使用します。Neptune 接続に ssh_host（および任意の ssh_user／ssh_key／ssh_port）がある場合、 Postgres／MySQL／Redis と同様に、トンネルのプーリング／キープアライブに参加します。

ワークスペースのキープアライブ（qy up/down/status）

同じ SSH 接続を CLI、GUI、MCP から繰り返しクエリする場合は、ワークスペースキーパーを一度起動し、プロセス間でウォーム状態のフォワードを再利用します。

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

keep_alive=true と reconnect=true は、ワークスペースごとに ~/.config/quarry/config.toml に保存されます。再接続が有効な場合、切断されたトンネルは指数バックオフで再接続され、qy status と GUI のヘッダーバッジの両方で reconnecting と表示されます。キープアライブが有効でもキーパーが停止している場合、コールドな qy exec／qy run は引き続き動作します（従来の動作）。また、qy up の実行を促すヒントが stderr に 1 行表示されます。

再接続が明示的に無効になっている場合、キーパーは最初の接続を試みますが、失敗したトンネルや切断されたトンネルへの再試行は行いません。キーの不足、認証エラー、無効な SSH 設定は blocked として報告されます。該当する接続または SSH ファイルを修正すると、再度接続を試行できます。qy status が示すのはトンネルのトランスポート状態であり、データベースの認証状態やクエリの健全性ではありません。GUI の「keeper up」バッジは、バックグラウンドプロセスが実行中であることを意味します。経路全体をテストするには、読み取り専用クエリを使用してください。

レジストリは、フォワードを共有する前にプロセスの識別情報を検証します。PID しか含まない古いキーパーの記録は信頼されません。アップグレードする前に、古いバージョンのキーパーを停止してください。プロキシを変更した場合、実行中のクエリは既存のフォワードを引き続き使用します。キーパーが所有する使用終了済みのフォワードは、外部クライアントがまだ使用している可能性があるため、キーパーが停止するまで維持されます。

PostgreSQL サーバーの識別情報を検証するには、データベース URL に sslmode=verify-full と信頼できる sslrootcert を追加します。Quarry は証明書検証用にデータベースのホスト名を保持し、転送ポートと hostaddr=127.0.0.1 を libpq に渡します。SSH トンネルだけではデータベースサーバーを検証できません。

プロキシ（速度制限のあるトンネル用）

SSH トンネルのスループットが制限されている場合（たとえば、国境を越える踏み台サーバーで、ハンドシェイクは正常に接続するものの、データ転送が極端に遅い場合）は、マシンの HTTP(S) プロキシ経由でルーティングします。

qy proxy              # show the discovered proxy + each workspace's toggle state
qy proxy on           # enable for the current workspace
qy proxy off          # disable it again
qy exec mydb --no-proxy --sql "..."   # skip the proxy for one call, even if enabled

プロキシは自動検出されます。まず macOS のシステムプロキシ設定（scutil --proxy）を使用し、見つからない場合は ALL_PROXY／HTTPS_PROXY を使用します。切り替え設定はワークスペースごとに config.toml に保存されます（connections.toml には保存されません）。これは ssh_host を持つ接続（ProxyCommand 経由のトンネル）と、Neptune の直接 HTTPS リクエストにのみ影響します。直接接続（トンネルを経由しない）する DB 接続には影響しません。また、ssh_host のない接続でプロキシを有効にすると、qy connections add/set が警告します。プロキシが有効でも、そのポートで何も待ち受けていない場合、qy はエラーを返さず、直接接続にフォールバックします。システムプロキシの例外リスト（ループバック、プライベート CIDR 範囲）の対象となる宛先は、プロキシ経由になりません。

プロキシが実際に使用されていることを確認する

上記の直接接続へのフォールバックは、クエリを実行し続ける必要があるため、意図的に通知されません。指定した呼び出しが実際にプロキシ経由だったかどうかを確認する方法を知っておくと便利です。

• qy の出力：ワークスペースでプロキシが有効でも呼び出しが直接接続で実行された場合、qy exec／qy run は stderr に理由を 1 行表示します。プロキシが見つからない、検出されたがポートで待ち受けているものがない、または宛先がプロキシの例外リストの対象である、のいずれかです。--no-proxy を指定すると、この表示は抑制されます（直接接続を指定したため、報告する内容はありません）。
• qy proxy：検出されたプロキシと各ワークスペースの切り替え設定に加え、プールされたすべての SSH トンネルを一覧表示します。ssh の宛先、ローカルポート、実際にプロキシ経由でルーティングされているか（およびそのアドレス）、基盤となる ssh プロセスがまだ実行中かどうかを確認できます。スクリプトで便利な、同じフィールドを含む tunnels 配列を表示するには、--format json を追加します。
• GUI：サイドバーの環境ピルには、その接続のトンネルがプロキシ経由でルーティングされている場合に、小さなバッジが表示されます。ワークスペースマネージャーには、各ワークスペースのプロキシ切り替え設定と、現在検出されているプロキシアドレスが表示されます。どちらもブラウザー側で推測するのではなく、qy が使用するものと同じロジックをサーバー側で実行して判定されます。

Redis

engine = "redis"（システムの redis-cli を使用します）。クエリには Redis コマンドを使います。

qy exec cache --sql "SCAN 0 COUNT 100"
qy exec cache --sql "HGETALL user:42"

ここでも読み取り専用の制限が適用されます。GET/SCAN/TYPE/TTL/HGETALL は許可されますが、SET/DEL/FLUSHALL は --write を指定しないとブロックされます。GUI では、Redis のキーをクリックすると、TYPE に応じた値が表示されます。

グループと環境セット

接続はプロジェクトフォルダー（group）と環境セット（同じ db、異なる env、共有スキーマ）に整理できます。

[shop_dev]
url = "postgresql://user:[email protected]:5432/shop"
group = "shop"
db = "shop"
env = "dev"
[shop_prod]
url = "postgresql://user:[email protected]:5432/shop"
group = "shop"
db = "shop"
env = "prod"
production = true

• 同じ db を持つ接続は 1 つの環境セットにまとめられます。保存済みクエリはどの環境に対しても実行できます。例：qy run recent_orders --env prod
• qy connections add/set は --db と --group を受け付けます。shop_prod --env prod のような新しいキーが既存の環境セットと一致すると、Quarry はその識別情報を自動的に継承します。
• ある環境セットのメンバーで group が省略されていても、グループ化された他のメンバーがすべて同じグループを指定していれば、CLI/GUI/MCP は OTHER に重複して作成せず、そのグループ内に論理 DB をまとめます。
• 環境が指定されていない場合は、最も安全な dev が既定値になります。
• GUI には環境切り替え機能が表示されます。本番環境のスタイルは production = true に従います。

複数のワークスペース

qy は ~/.config/quarry/config.toml に記載されたすべてのワークスペースを集約し、すべてのプロジェクトを 1 つの GUI/CLI から利用できます。

qy workspace add ~/projects/acme/db-workspace
qy workspace add ~/projects/side-project/db
qy connections    # both projects, grouped
qy gui            # sidebar shows both groups side by side

--workspace a:b（os.pathsep 区切り）は一時的な上書きとして機能します。最初のディレクトリが書き込み先のプライマリになります。

エージェントスキルと保存済みクエリ

移植可能なスキルは skills/quarry にあります。その ディレクトリをエージェントのスキル保存先にインストールし、このバージョンからビルドした qy CLI とともに使用してください。このスキルには、個人の接続情報やクエリは含まれません。 英語版が既定の SKILL.md で、対応する 簡体字中国語版 は SKILL.zh-CN.md です。 インストール時のエントリーポイントとして中国語版を使用するには、インストール先ディレクトリでその版を SKILL.md にコピーしてください。 重複するスキルを 2 つインストールせず、片方だけをインストールしてください。スキルの動作を変更するときは、両方の版を一緒に更新してください。

qy --skill-dir /path/to/installed/quarry list
qy --skill-dir /path/to/installed/quarry --workspace ~/db/acme save customer-count \
  --db customers --sql 'SELECT count(*) FROM customers'

save はファイル形式を管理し、<workspace>/queries/<db>/<name>.sql に書き込みます。 --skill-dir を指定すると、コマンドの実行前に <skill>/queries/<workspace-name> をそのクエリディレクトリへのシンボリックリンクとして作成します。認証情報はリンクの外に保管されます。 更新後にリンクが失われた場合は、再作成するため、呼び出しごとにこのオプションを指定してください。 CLI はスキルのインストール先を記憶したり推測したりしません。存在しないワークスペースディレクトリは報告され、再作成されません。既存のファイルや、別の場所を指すリンクが置き換えられることはありません。ワークスペースのディレクトリ名が重複している場合は、--workspace で 1 つを選択する必要があります。リンクの作成エラーが発生すると、使用方法エラーでコマンドが停止します。クエリデータは削除されません。生成された queries/ の項目は、公開するスキルパッケージに含めないでください。

queries/ がスキルリポジトリ内を指す従来のワークスペースでは、まずバックアップを作成し、クエリファイルを実際のワークスペースの queries/ ディレクトリに移動してから、--skill-dir を使う前に古いスキルのクエリ項目を削除してください。CLI は既存のユーザーデータを自動的に移動しません。

ローカル開発コンテナ

デフォルトのポートが使用中の場合は、空いているポートを明示的に選択します。

qy local status --engine postgres
qy local up --engine postgres --port 55434

ポートは Quarry の config.toml 内の [local] postgres_port（または redis_port）に保存され、CLI と GUI のローカルセットアップで使用されます。env=local の接続のうち、Quarry の名前付きボリュームのメタデータが引き続き古いループバックポートを指しているものは、設定済みのすべてのワークスペースで更新されます。それ以外の接続は変更されません。変更された接続ファイルは、元のファイルと同じ場所にバックアップされます。

ポートを変更するには、まず qy local down --engine postgres を実行して、実行中の Quarry コンテナを停止する必要があります。停止済みのコンテナは、既存のイメージと名前付きボリュームを使って再作成されます。カスタムのデータマウントは手動で処理する必要があります。Docker が実行中である必要があります。クエリコマンドは障害の診断のみを行い、Docker を起動したり、競合するサービスを自動的に停止したりすることはありません。

ローカルで実行中のサービスがリモート（開発用）データベースを共有している場合、すべての読み取り／書き込みがパブリックネットワークを経由するため、データベースに大量のアクセスを行うテスト／e2e の実行は、往復遅延によって不安定になります。qy local は Docker コンテナ内で Postgres／Redis を実行するため、サービスは localhost のみを通じて通信します。

qy local up shop            # start local Postgres + register a shop `local` connection
qy local up                 # start Postgres, Redis, and the empty Neptune endpoint
qy local up neptune --engine neptune  # register neptune@local independently
qy connections              # shop now shows a [local] env alongside [dev]
qy run active_customers --env local

qy local status             # running? which port / image?
qy local sync shop          # copy dev schema into local (staging db + rename swap)
qy local down               # stop, keep the data volume (data survives)
qy local down --purge       # stop + delete the volume (next up is an empty DB)

qy local up <db> は、ソースデータベースのワークスペースに新しいローカル接続を保存します。作成前に、Quarry は設定済みのすべてのワークスペースを確認し、同じプロジェクトスコープ（group、またはグループに属していない場合はソースワークスペース）にある既存のローカルエントリを再利用します。そのスコープに複数の一致がある場合は、設定エラーとして報告されます。異なるプロジェクトで同じ論理 DB 名を安全に使用できます。たとえば、物理 Postgres データベースは brain_matrix_runtime や yiminlab_matrix_runtime のように名前空間で分けられます。管理対象のローカルエントリは、共有コンテナの再作成時に、設定済みのポート、名前空間、localhost の認証情報に合わせて調整されます。

ローカル Neptune サービスは https://localhost:18182 で待ち受け、Quarry と AWS Neptune Data API の両方の openCypher リクエストを受け付けます。デフォルトの empty モードでは行を返さず、書き込みを永続化せずに受け付けます。

テストを決定論的に行うには、qy local up neptune --engine neptune --fixture /path/to/responses.json を実行して、Neptune のみを起動します。フィクスチャには順序付きの responses 配列を含めます。query_contains の部分文字列と、任意のパラメーターの部分集合が一致する最初のルールが、その results をそのまま返します。

{"responses": [{"query_contains": "MATCH (n)", "parameters": {"user_id": "test-user"}, "results": [{"n": {"name": "example"}}]}]}

query_exact: true を設定すると、クエリ全体が query_contains と等しい場合に限り一致します。parameters_exact: true を設定すると、パラメーター辞書全体が一致する場合に限り一致します。既存の部分文字列／部分集合によるフィクスチャでは、どちらのフラグもデフォルトで false です。パラメーターの完全一致では JSON の型を再帰的に比較し、ブール値と数値を区別します。

モックモードでは、一致しないクエリ（未設定の書き込みを含む）に対して HTTP 501 を返すため、テストが空の応答で知らないうちに成功することはありません。qy local neptune-calls --format json は、すべての openCypher 呼び出し、そのパラメーター、一致状況、単調増加する next カーソルを一覧表示します。--after <cursor> を指定すると、後続のテスト期間の呼び出しだけを抽出できます。フィクスチャと呼び出し履歴はプロセスメモリ内に保持され、エンドポイントの停止時にリセットされます。これはプロトコルレベルの応答モックであり、Cypher グラフデータベースではありません。モックモードはループバックのみにバインドされます。empty と mock の切り替え、またはフィクスチャの変更には、既存のエンドポイントを明示的に停止する必要があります。qy local status --engine neptune でアクティブなバックエンドを確認できます。

1 つの共有 Postgres コンテナが、スコープごとの論理接続に対して名前空間付きの物理データベースを 1 つずつホストします（固定ポートは 5433、Redis は 6380）。データは名前付き Docker ボリュームに保存されます。Docker デーモンが必要です。イメージタグは --image で上書きできます。

GUI

GUI のリンクには /quarry/?db=auth_db&env=prod&table=oauth_accounts を使用します。 アドレスは、設定済みの論理データベースと環境を使ってアクティブなタブに追従します。ワークスペースのフォルダー名は URL に含まれません。テーブルにフォーカスしたリンクを開くと、SQL を実行せずに選択状態を復元します。/app/ は提供されなくなりました。

qy gui — ローカルで動作する、ビルド不要の Web GUI（Slate & Copper テーマ、ライト／ダーク）：

• デフォルトは中国語です。言語切り替えで英語を選択でき、選択内容は保存されます。
• 環境切り替え機能付きのグループ化されたサイドバイツリー、本番環境を明示するスタイル、接続状態を示すドット
• マルチタブエディター — ブラウザーのストレージが利用可能な場合、SQL と接続の下書きが保持されます。結果のスナップショットには上限があり、大きな結果はセッション中保持されます。
• SQL のハイライト表示＋ローカル補完（キーワード／テーブル／列）
• SQL アシスタント — 折りたたみ可能なエディターパネルで現在の SQL の説明や変更を行います。ストリーミング返信とチェックポイントに対応し、閉じた会話は履歴から復元できます。クエリの実行には既存の「実行」コントロールを使います。
• EXPLAIN ボタン — ワンクリックでクエリプランを表示
• 型を認識するデータグリッド：並べ替え、列幅の変更、キーボード操作（矢印キー＋Enter）、折りたたみ可能な JSON ツリーによるセルの確認
• CSV／JSON エクスポート、検索可能なクエリ履歴（接続＋時刻付き）
• 折りたたみ可能な名前空間ツリーを使った、TYPE を認識する Redis キーの閲覧
• 更新チェック — バックグラウンドスレッドが 24 時間ごとに PyPI を確認し、新しい quarry-db がリリースされている場合は、ヘッダーバッジ（アップグレードコマンド＋リリースノート付き）を表示します。編集可能モード／開発用インストールは自動的に除外されます。完全に無効にするには QUARRY_UPDATE_CHECK=0 を設定します。

SQL assistant

対話形式で設定するには qy ai configure を実行するか、フラグを使って OpenAI 互換のモデルエンドポイントを設定します。

qy ai configure --base-url https://model.example/v1 --model your-model \
  --api-key-env QUARRY_AI_API_KEY
qy ai show
qy ai explain --db planning --env dev --file query.sql
qy ai sql --db planning --env dev 'Show the latest record per session'

名前付きのキー環境変数を、qy gui または CLI コマンドを起動する環境で設定します。または、--api-key-stdin を使うと、標準入力から読み取ったキーを所有者のみがアクセスできる別ファイルに保存できます。認証が不要なローカルエンドポイントには --no-key を使用できます。--bifrost は Bifrost Virtual Key 認証を選択し、--thinking disabled は思考なしの応答を要求します。プロバイダーの選択とフォールバック順序は、設定されたゲートウェイが管理します。Quarry は 2 つ目のプロバイダーをハードコードしません。

設定は ~/.config/quarry/config.toml の [assistant] セクションに保存されます。GUI と CLI の両方で QUARRY_CONFIG を指定すると、そのパスが優先されます。認証情報を保存する場合、API キーは設定ファイルと同じ場所にある assistant-credentials.json に別途保存され、所有者のみがアクセスできます。qy ai show は、キーをマスクした状態で有効な設定を表示します。 assistant-credentials.json は Quarry 内部の保存形式で、qy ai configure によって自動的に作成されます。自分で JSON を書く必要はありません。 Quarry は API キーの登録や発行を代行しません。

設定は CLI でのみ行います。モデルが設定されていない場合、GUI はメッセージを保持し、実行するコマンドを表示します。エンドポイントは、メタデータの検出に必要な Chat Completions のストリーミングとツール呼び出しに対応している必要があります。

SQL エディター左側の縦型 SQL 助手 / SQL Assistant レールを開きます。チャットは左側に、SQL エディターとクエリ操作部は右側に表示されます。パネルはクエリツールバーの下端まで伸び、チャット入力欄は下部に固定されます。チャットはパネルの上端から始まり、仕切りの上部にある小さな矢印でパネルを非表示にできます。チャットのスクロールバーは細く、仕切りのすぐ横に表示されます。パネルを非表示にすると、ツールバーが全幅に戻り、結果グリッドの表示領域が広がります。展開時は、サイズを変更してもチャット入力欄が見えるよう、エディターに十分な高さが保たれます。横方向の仕切りを下にドラッグすると、ステータスバーより上の利用可能な高さを使えます。仕切りを上に戻すと、結果が再び表示されます。上限はウィンドウとツールバーのサイズに合わせて調整されます。2 つの仕切りで、つまみのサイズ、色、ホバー時の表示は共通です。縦方向の仕切りには左側に細い枠線があり、その下端は隙間なくツールバーの枠線につながります。 パネルを開いても、モデルへのリクエストは送信されません。SQL があり、チャット入力欄が空の場合、説明プロンプトの全文が薄く表示されます。 Tab キーで表示されたテキストを確定し、Enter キーで説明をリクエストします。

返信言語は CLI からのみ設定できます。デフォルトでは、Quarry を実行しているマシンのシステム言語に従います。中国語の場合は中国語に、それ以外の言語の場合は英語になります。この GUI 設定を確認または変更するには、次のコマンドを実行します。

qy ai language          # Show the GUI preference and resolved reply language
qy ai language zh       # Chinese GUI replies
qy ai language en       # English GUI replies
qy ai language system   # Follow the system language (default)

選択した言語は Quarry の設定ファイルの [gui.assistant] reply_language に保存され、インターフェース言語とは独立して、すべての GUI アシスタントの返信に適用されます。GUI を再度開くか、フォーカスを戻すと変更が読み込まれます。GUI には言語設定のコントロールはありません。既存の下書き、SQL、履歴は保持されます。旧式の auto 値は system の別名です。この設定は CLI の返信やモデルのエンドポイント設定には影響しません。

手書きのメッセージは変更せずに送信されます。ほかのメッセージは Enter キーで送信し、Shift+Enter キーで改行します。アシスタントは、現在の接続先にある PostgreSQL、MySQL、SQLite のテーブル構造やキーの関係を調べ、JOIN の作成を支援できます。独立した接続同士を結合したり、SQL を実行したりすることはできません。Run を使うと、Quarry 既存の読み取り専用クエリ経路からクエリを実行できます。

未送信のメッセージは、アシスタントを非表示にしたりタブを切り替えたりしても、そのタブに残ります。

説明では、見出し、リスト、強調、コードブロック、表などの Markdown に対応しており、ストリーミング返信や再度開いた履歴でも表示できます。見出しにはテーマのアクセントカラーが使われ、SQL コードブロックではキーワード、文字列、数値が区別されます。幅の広いコードや表は、チャットパネル内でスクロールできます。説明に表示された SQL はメッセージ内にとどまり、編集が完了した場合のみ SQL エディターが更新されます。

編集が完了すると SQL エディターが更新され、Restore previous SQL が表示されます。返信の受信中にクエリを編集した場合、アシスタントは明示的に適用されるまで提案を保持します。チェックポイントを復元すると SQL のみが変更され、会話はそのまま保持されます。復元されたことが記録されますが、復元アクションがさらに追加されることはありません。データベースの変更がロールバックされることはありません。保存済みのクエリを編集すると、クエリファイルを変更するのではなく、下書きが作成されます。

タブを閉じても会話は削除されません。History → Conversations を選択すると、クエリは実行せずに、最新の SQL、メッセージ、チェックポイントを再度開けます。会話はブラウザーで開いているタブとは別に、qy gui を実行しているマシンの Quarry の config.toml と同じ場所にある assistant/history.sqlite3 に保存されます。QUARRY_AI_HOME で別の会話ディレクトリを指定できます。

プライバシーとサポートの範囲

Quarry は接続認証情報、クエリ、結果を Quarry のサービスにアップロードしません。クエリは設定したデータベースに送信されます。GUI はデフォルトで localhost にバインドされ、ローカルのオリジンを確認します。インストール済みの GUI パッケージは、定期的に PyPI で更新を確認します。これを無効にするには、QUARRY_UPDATE_CHECK=0 を設定してください。

オプションの SQL アシスタントは、SQL、会話メッセージ、関連するスキーマメタデータを、設定したモデルのエンドポイントに送信します。クエリ結果の行やデータベース／SSH の認証情報が自動的に送信されることはありません。モデルの認証情報はローカルのバックエンドに保持され、ブラウザーにはモデルキーの入力フォームがありません。会話と SQL のチェックポイントはローカルに保存され、入力した SQL のリテラルやテキストが含まれる場合があります。

Neptune/openCypher は実験的な機能であり、安定したデータベースサポートの対象外です。エンドポイントと、ローカルの空サービスに対するテストでは、実際の AWS/IAM の動作は検証されません。サポート対象のテスト環境、永続性の制限、最終的な 1.0 の受け入れチェックリストについては、COMPATIBILITY.md を参照してください。

ロードマップ

• すべてのエンジンの結果コントラクトに列型を追加
• DuckDB エンジン
• 環境をまたいだスキーマ／データの差分
• 書き込み監査ログ（誰が、何を、どこで、いつ実行したか）
• 単一バイナリでの配布

開発とテスト

pip install -e ".[dev]"
createdb quarry_test && psql quarry_test -f tests/seed.sql   # or: make seed
make test        # layered run with a per-layer PASS/FAIL summary

テストは4つのレイヤーに分類されています。現在の件数には python -m pytest --collect-only -q を、現在のカバレッジには CI レポートを使用してください。

レイヤー	対象	必要なもの
unit	純粋なロジックとモック化されたエンジンの動作	テスト依存関係
integration	実際のデータベースと、プロセス内での CLI/GUI/MCP ディスパッチ	該当するデータベース。ローカルのライフサイクル／同期には Docker
e2e	実際の CLI/MCP サブプロセス	PostgreSQL
browser	Chromium で操作する実際のビルド済み GUI（e2e にも含まれます）	PostgreSQL + Playwright。キーの閲覧には Redis

依存関係が不足している場合、テストはスキップされることがあります。スキップを含む実行が成功しても、リリース検証を完了したことにはなりません。CI では PostgreSQL 16、MySQL 8.4、Redis 7 を使用します。unit/integration のカバレッジゲートは ≥95% です。フロントエンドの動作は別途検証されます。

テスト状況をひと目で確認する

• GitHub 上： 上記の CI バッジはリアルタイムで更新され、いずれかのレイヤーまたはカバレッジゲートに失敗すると赤くなります。コミットごとおよび PR ごとの結果は、Actions タブと PR のチェックに表示されます。
• ローカルでの成否： make test はレイヤーごとのサマリーを色付きで表示します。make test-unit / test-integration / test-e2e / test-browser で、個別のレイヤーを実行できます。
• ローカルでのカバレッジ： make cov はゲートを適用し、HTML レポートを作成します。htmlcov/index.html を開くと、カバーされている範囲を行ごとに確認できます。

アーキテクチャ、フィクスチャ、CI の構成については TESTING.md を、貢献ガイドラインについては CONTRIBUTING.md を参照してください。

Quarry の開発とテストは macOS および Linux で行われています。Windows は現在テストされていません（psql/ssh 統合とポートの引き継ぎは Unix 系の仕様です）。PR をお待ちしています。

ライセンス

MIT

本番環境への明示的な接続

環境名はラベルであり、安全性を保証する設定ではありません。該当する接続の connections.toml セクションで production = true を設定してください。たとえば、env = "jp" に production = true を設定します。このフラグを省略すると、env = "prod" であってもデフォルトは false です。アップグレード時は、既存の本番環境接続を使用する前に明示的に指定してください。

接続を指定するには qy connections set CONNECTION_KEY --production --no-test を使用します。フラグを解除するには --no-production を使用します（特定のワークスペースを指定する場合は、connections の前に --workspace PATH を追加してください）。その他の更新ではフラグは保持されます。本番環境への移動では、実行せずにプレビューが準備されます。Run は明示的な操作です。CLI での書き込みには確認（または --yes）が必要であり、MCP での書き込みには通常の書き込みオプトインに加えて confirm_prod: true が必要です。