SQLX

SQLX

MySQL、MariaDB、TiDB、GreatSQL、OceanBase、PostgreSQL、CockroachDB、YugabyteDB、openGauss、Oracle、SQL Server、ClickHouse、Trino、Presto、StarRocks、Apache Doris、TDengine、Dameng、KingbaseES、Apache Kylin、XuguDB、IBM Db2、IBM Informix、SUNDB、GBase 8s、Redis、MongoDB に接続するか、ターミナルまたはエージェントからローカルの SQLite、DuckDB、H2 ファイルを開きます。接続情報は暗号化して保存され、1 回の実行で 1 つ以上のステートメントやコマンドを実行し、結果を完全かつ構造化された形式で取得できます。

クイックスタート

# 1. Install the CLI (macOS, Linux and Windows x64; Node.js 22 or newer)
npx -y @ottermind/sqlx@latest
export PATH="$HOME/.local/bin:$PATH"

# 2. Create a connection (an interactive terminal prompts for the username and password)
sqlx datasource add --name dev --type postgresql --host db.example.com --port 5432 --database app
sqlx datasource test --id dev

# 3. Run SQL
sqlx sql execute --datasource dev --command "SELECT current_database()"

エージェントで使用しますか？エージェントでの使用をご覧ください。プラグインまたは拡張機能を 1 つインストールすれば、エージェントが SQLX を直接呼び出します。

CLI のインストール

3 つの方法から選べます。GitHub Releases のビルド済みパッケージ、npx インストーラー、またはプラットフォーム用インストールスクリプトです。

macOS と Linux

curl -fsSL https://raw.githubusercontent.com/OtterMind/sqlx/main/scripts/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
sqlx --version
sqlx init

インストーラーはプラットフォームを選択し、実行ファイルをダウンロードして SHA-256 を検証します。~/.local/bin にインストールされるため、そのディレクトリをシェルの永続的な PATH に追加してください。SQLX_INSTALL_DIR で別のディレクトリを指定し、SQLX_VERSION でリリースバージョンを選択できます。

Windows x64

PowerShell で実行します。

$installer = Join-Path $env:TEMP 'sqlx-install.ps1'
Invoke-WebRequest 'https://raw.githubusercontent.com/OtterMind/sqlx/main/scripts/install.ps1' -OutFile $installer
powershell -NoProfile -ExecutionPolicy Bypass -File $installer
$env:Path = "$env:LOCALAPPDATA\Programs\SQLX;$env:Path"
sqlx --version
sqlx init

今後のセッションで使用できるように、%LOCALAPPDATA%\Programs\SQLX をユーザー PATH に追加してください。どちらのインストーラーも、すでに存在する sqlx という名前の無関係な実行ファイルを上書きしません。その場合は別のインストールディレクトリを使用してください。

ビルド済みの対象プラットフォームは macOS ARM64/x64、Linux ARM64/x64、Windows x64 です。Linux のベースラインは Ubuntu 24.04 です。リリース版のユーザーに Rust、Java、データベースドライバーは必要ありません。データベースワーカーと専用 JRE は、必要な場合にのみダウンロードされます。

Node.js（npx）

Node.js 22 以降を使用する macOS、Linux、Windows x64 が対象です。

npx -y @ottermind/sqlx@latest
export PATH="$HOME/.local/bin:$PATH"
sqlx --version

インストーラーは、リリースマニフェスト、SHA256SUMS、ダウンロードしたアーカイブを検証してからインストールします。プラットフォーム用インストーラーと同じユーザーレベルの場所を使用し、Skill を ./sqlx にインストールしますが、ここはどのエージェントも監視していません。--target codex、--target claude、--target dsh、--target pi、または --target <directory> を指定すると、Skill が実際に検出される場所にインストールされます。--cli-only を指定すると CLI のみをインストールします。それ以外の最初の引数はインストールではなく SQLX コマンドとして実行されるため、npx -y @ottermind/sqlx@latest mcp は MCP サーバーを起動します。Node.js が必要なのはインストーラーだけで、CLI には必要ありません。

アップデート

CLI は自身の実行ファイルをアップデートします。

sqlx update check       # report the latest stable version without installing it
sqlx update install     # download, verify and replace the executable
sqlx update status      # read local history without network access

sqlx update install --version <version> を実行すると、指定した安定版をインストールします。アップデートによって、実行中の SQL や UI サービスが停止したり、保存済みの接続情報が変更されたりすることはありません。また、Skill やプラグインも自動ではアップデートされません。管理対象の Skill には sqlx skill update を使用してください。インストール済みの UI プラグインは選択したバージョンを維持します（デフォルトのインターフェースは CLI のリリースに合わせて更新されます）。

対話型の使用時は、バックグラウンドで 1 日に最大 1 回確認し、stderr に通知のみを表示します。パイプ経由のコマンドと CI コマンドではこの確認をスキップし、SQLX_NO_UPDATE_CHECK=1 で無効にできます。ソースからのビルドとパッケージマネージャーが管理するパスでは、それぞれのインストール方法が維持されます。

エージェントでの使用

4 つのいずれも、インストール後すぐに使用できます。プラグインまたは拡張機能は、sqlx CLI が存在しない場合は自身でインストールするため、別途インストールする必要はありません。Codex と Claude ではさらに、CLI がプラグインの最小バージョン要件を満たす必要があり、互換性のない古い MCP サーバーが無言で起動することはありません。

いずれの場合も Skill はインストールされた状態になります。CLI だけではエージェントにツールを提供できても、エンジンに関する知識は提供できないためです。プラグインは、エージェント独自のディレクトリに Skill がまだない場合、初回起動時にインストールし、その際に stderr で通知します。

Codex

codex plugin marketplace add OtterMind/sqlx@plugins
codex plugin add sqlx@ottermind

プラグインは MCP 経由で sqlx mcp を起動します。読み取り専用操作はそのまま実行されます。実行用の 2 つのツール（sqlx_sql_execute と sqlx_sql_view）には破壊的操作のマークが付けられており、Codex はデフォルトで承認を求めます。

Claude Code

claude plugin marketplace add OtterMind/sqlx@plugins
claude plugin install sqlx@ottermind

ヘッドレス実行では、ツールの許可リストを明示する必要があります。

claude --allowedTools "mcp__plugin_sqlx_sqlx__*" -p "List my SQLX datasources"

DeepSeek Harness

dsh plugin --profile web add @ottermind/sqlx-dsh    # browser UI
dsh plugin --profile tui add @ottermind/sqlx-dsh    # terminal UI

プラグインはプロファイルに属します。使用するプロファイルにインストールしてから、dsh を再起動してください。

Pi

pi install npm:@ottermind/sqlx-pi

その他の MCP クライアント

プラグインシステムのないクライアントは、公開パッケージからサーバーを直接起動します。初回使用時に sqlx CLI 自体をインストールするため、セットアップはこれだけです。

{
  "mcpServers": {
    "sqlx": {
      "command": "npx",
      "args": ["-y", "@ottermind/sqlx@latest", "mcp"]
    }
  }
}

npx を使わずに起動するには、command にインストール済みのバイナリを指定してください。GUI アプリケーションでは PATH に ~/.local/bin が含まれていないことが多いため、絶対パス（macOS および Linux では ~/.local/bin/sqlx、Windows では %LOCALAPPDATA%\Programs\SQLX\sqlx.exe）を指定し、"args": ["mcp"] はそのままにしてください。

このクライアントには Skill が提供されないため、エージェントはエンジンのレシピなしでツールを実行します。クライアントが指示を読み込む場所に、sqlx skill install --path <directory> でインストールしてください。

SQLX は MCP Registry にも io.github.OtterMind/sqlx として掲載されており、そこからインストールするクライアント向けにコンテナイメージを指定しています。docker run -i --rm ghcr.io/ottermind/sqlx:latest。コンテナからアクセスできるのは SQL 実行経路のみです。認証情報ページ、結果ページ、ローカルワークベンチはコンテナ内の 127.0.0.1 で提供され、データディレクトリもコンテナ内にあるため、保存した接続を保持するには /root/.sqlx にボリュームをマウントしてください。ユーザーが認証情報を入力したり、結果を確認したりする場合は、上記のパッケージを優先してください。

Skill のみ

sqlx skill install --target codex     # Codex and dsh share ~/.agents/skills
sqlx skill install --target claude
sqlx skill install --target dsh
sqlx skill install --target pi

sqlx skill status                     # list managed installations
sqlx skill update                     # update them, keeping local edits

別のエージェントを使用する場合は、sqlx skill install --path <directory> でその Skill ディレクトリを指定してください。

接続と SQL

接続を作成する

sqlx datasource add --name dev --type postgresql --host db.example.com --port 5432 --database app
sqlx datasource test --id dev
sqlx sql execute --datasource dev --command "SELECT current_database()" --command "SELECT 1"

データベース	--type の値	実行方式	必須値とデフォルト
MySQL	mysql	ネイティブワーカー	デフォルトのポートは 3306 です
MariaDB	mariadb	MySQL ワーカーを再利用	デフォルトのポートは 3306 です
TiDB	tidb	MySQL ワーカーを再利用	デフォルトのポートは 4000 です
GreatSQL	greatsql	MySQL ワーカーを再利用	デフォルトのポートは 3306 です
OceanBase	oceanbase, ob	MySQL ワーカーを再利用	デフォルトのポートは 2881 です。user@tenant として接続します
StarRocks	starrocks	MySQL ワーカーを再利用	デフォルトのポートは 9030 です。ユーザーデータベースは作成するまで存在しません
Apache Doris	doris	MySQL ワーカーを再利用	デフォルトのポートは 9030 です。ユーザーデータベースは作成するまで存在しません
PostgreSQL	postgresql, postgres, pgsql	ネイティブワーカー	デフォルトのポートは 5432 です
CockroachDB	cockroachdb, cockroach, crdb	PostgreSQL ワーカーを再利用
YugabyteDB	yugabytedb, yugabyte, yb	PostgreSQL ワーカーを再利用	デフォルトのポートは 5433 です
openGauss	opengauss, gaussdb	JDBC ワーカー	デフォルトのポートは 5432 です。独自のドライバーで認証します
Oracle	oracle	JDBC ワーカー	--service <service-name> が必須です
SQL Server	sqlserver, mssql	JDBC ワーカー	デフォルトのポートは 1433 です
ClickHouse	clickhouse	JDBC ワーカー	HTTP ポートに接続します。デフォルトは 8123 です
Trino	trino	JDBC ワーカー	--database <catalog>[.<schema>] が必須です
TDengine	tdengine, taos	JDBC ワーカー	taosAdapter 経由で接続します。デフォルトのポートは 6041 です
Dameng	dameng, dm	JDBC ワーカー	デフォルトのポートは 5236 です。アカウントはデフォルトのスキーマとしても使用されます
KingbaseES	kingbase, kingbasees	JDBC ワーカー	デフォルトのポートは 54321 です
Redis	redis	ネイティブワーカー	デフォルトのポートは 6379 です。各 --command は SQL ではなく、1 つの Redis コマンドです
MongoDB	mongodb, mongo	ネイティブワーカー	デフォルトのポートは 27017 です。各 --command は SQL ではなく、1 つのコマンドドキュメントです
SQLite	sqlite, sqlite3	ネイティブワーカー	--path <file>（または --database）でローカルファイルを開くか作成します。ホスト、ポート、認証情報は不要です。--property mode=ro と --property busy_timeout=<ms> を指定できます
DuckDB	duckdb	ネイティブワーカー	--path <file> でローカルファイルを開くか作成し、:memory: で呼び出し中のみ使用するデータベースを作成します。--property read_only=true と --property threads=<n> を指定できます
H2	h2	JDBC ワーカー	--path <file> でローカルファイルを開くか、--host と --port（デフォルトは 9092）で TCP サーバーに接続します
Presto	presto, prestodb	JDBC ワーカー	デフォルトのポートは 8080 です。--database <catalog>[.<schema>] と --username が必須です。パスワードは TLS 経由の場合にのみ送信されます
Hive	hive	JDBC ワーカー	デフォルトのポートは 10000 です。--database で Hive データベースを選択します。未指定の場合は default です
Apache Kylin	kylin	JDBC ワーカー	デフォルトのポートは 7070 です。--database に Kylin プロジェクトを指定します。デフォルトのアカウントは ADMIN/KYLIN です
XuguDB	xugu, xugudb	JDBC ワーカー	デフォルトのポートは 5138 です。SYSTEM はシステムデータベースです
IBM Db2	db2, ibmdb2	JDBC ワーカー	デフォルトのポートは 50000 です。提供するドライバーが必要です。詳しくは提供するドライバーを参照してください
IBM Informix	informix, ifx	JDBC ワーカー	デフォルトのポートは 9088 です。--service <server-instance> が必須で、ドライバーを用意する必要があります
SUNDB	sundb	JDBC ワーカー	デフォルトのポートは 22581 です。Goldilocks エンジンを実行し、ベンダーイメージのドライバーが必要です
GBase 8s	gbase8s, gbasedbt	JDBC ワーカー	デフォルトのポートは 9088 です。--service <server-instance> が必須で、ドライバーを用意する必要があります

--id と --datasource には、安定したデータソース UUID または一意の名前を指定できます。

ローカルページでユーザーにパスワードを入力してもらい、会話やツールの応答にパスワードが含まれないようにするには、次のようにします。

sqlx datasource add --ui --name dev --type postgresql --host db.example.com --port 5432 --database app
sqlx datasource setup-status --request-id <request-id>

既存の接続を編集し、パスワードを置き換えない限り保存済みのパスワードを維持するには、sqlx datasource update --id dev --ui を実行します。 TLS を明示的に指定しない限り、接続では TLS は使用されません。--tls のデフォルトは disable です。データベース証明書を検証するには --tls verify-full を追加してください。マシンが信頼する証明書を提示しないデータベースでは、invalid peer certificate: UnknownIssuer（MySQL）、error performing TLS handshake（PostgreSQL）、または接続の切断（Oracle）が発生します。これはローカルコンテナーでよくあるケースです。どちらの設定も更新時に使用できます。

sqlx datasource add --name dev --type mysql --host 127.0.0.1 --port 3306 --database app \
  --username-env DB_USER --password-env DB_PASSWORD          # no TLS, the default
sqlx datasource update --id dev --tls verify-full             # verify the server certificate

認証情報

認証情報は、名前付き環境変数、非表示の対話型プロンプト、または標準入力の接続 JSON オブジェクトから取得できます。コマンド引数にパスワードを直接記述しないでください。

sqlx datasource add --name dev --connection-stdin

{
  "database_type": "postgresql",
  "host": "localhost",
  "port": 5432,
  "database": "app",
  "service": "",
  "username": "example_account",
  "password": "replace_with_real_input",
  "tls": "disable",
  "properties": {}
}

データソースの応答には、ユーザー名、パスワード、ベンダーのプロパティは含まれません。

接続のインポート

接続をすでに保存しているツールから、バージョン管理されたドキュメントにまとめてすべての接続を渡せるため、移行時にコマンド引数へパスワードを記述する必要はありません。examples/import-connections.json は、そのまま実行できる出発点です。

sqlx datasource import --stdin < connections.json

{
  "version": 1,
  "mode": "merge",
  "datasources": [
    {
      "name": "dev",
      "connection": {
        "database_type": "postgresql",
        "host": "localhost",
        "port": 5432,
        "database": "app",
        "username": "example_account",
        "password": "replace_with_real_input",
        "tls": "disable"
      }
    }
  ]
}

各 connection は、--connection-stdin が受け付けるオブジェクトと同じです。デフォルトの merge は新しい名前を追加し、既存の名前を ID を維持したまま更新します。また、保存済みの接続を削除することはありません。各エントリーは個別に検証されるため、未対応のエンジンや不完全な接続はドキュメント全体の失敗とはならず、理由とともに skipped に報告されます。

{"success":true,"data":{"mode":"merge","added":1,"updated":0,"unchanged":0,"total":1,"datasources":[{"id":"...","name":"dev","connection":{"database_type":"postgresql"}}],"skipped":[{"name":"legacy","reason":"invalid_connection","detail":"..."}]}}

--dry-run は保存せずに検証と報告を行い、--strict は無効なエントリーが一つでもある場合にドキュメント全体を拒否します。また、標準入力からのパイプができない呼び出し元は、--file <path> でファイルからドキュメントを読み込めます。ストアへの書き込みは一度だけ行われるため、インポートが一部だけ適用されることはありません。

total は、インポートで対象となったすべての接続を数えます。保存済みの接続とドキュメント内のエントリーが含まれ、スキップされたものも対象です。保存済みの接続が一つあり、エントリーが二つで、そのうち一つが無効な場合、応答には total: 3、added: 1、および一つの skipped エントリーが報告されます。

コマンド

操作	コマンド
ローカルストレージを初期化する	sqlx init
接続を作成する	sqlx datasource add --name dev --type mysql --host localhost --database app --username-env DB_USER --password-env DB_PASSWORD
接続一覧を表示する	sqlx datasource list
接続を確認する	sqlx datasource show --id dev
接続設定を変更する	sqlx datasource update --id dev --host db.example.com
保存済みの接続をインポートする	sqlx datasource import --stdin
保存済みの接続を削除する	sqlx datasource remove --id dev
接続をテストする	sqlx datasource test --id dev
SQL を実行する	sqlx sql execute --datasource dev --command "SELECT 1" --command "SELECT 2"
ワーカー、JDBC ランタイム、UI を事前にダウンロードする	sqlx prefetch mysql ui（mariadb、tidb、greatsql、oceanbase、starrocks、doris、postgres、cockroachdb、yugabytedb、opengauss、oracle、sqlserver、clickhouse、trino、presto、hive、kylin、xugu、db2、informix、sundb、gbase8s、tdengine、dameng、kingbase、redis、mongodb、sqlite、duckdb、h2、skill、または all。ドライバーを提供する 4 つのエンジンでは、共通ランタイムのみを取得します）
リリースに含められないドライバーをインストールする	sqlx driver add --type db2 --jar <path>、sqlx driver list、sqlx driver remove --type db2
SQL を実行して結果ページを開く	sqlx sql execute --datasource dev --command "SELECT 1" --view
保存された結果を読み取る	sqlx results list、sqlx results rows --id <result-id> --offset 100 --limit 50
設定を表示または変更する	sqlx setting list、sqlx setting set preview-rows 20、sqlx setting set results-dir ~/sqlx-results
大きな結果をインラインで返す	sqlx sql execute --datasource dev --command "SELECT …" --full
ローカルワークベンチ	sqlx ui、sqlx ui status、sqlx ui stop
チャートを作成してダッシュボードに配置する	sqlx analytics chart add --name revenue --datasource dev --command "SELECT month, SUM(revenue) AS revenue FROM sales GROUP BY month" --type line --x month --y revenue --run --dashboard "Sales"（ほかのコマンドと同様に、--sql もエイリアスとして使用できます）
保存済みチャートの SQL を再実行する	sqlx analytics chart run revenue
チャートやダッシュボードを一覧表示または削除する	sqlx analytics list、sqlx analytics dashboard add --name "Sales"、sqlx analytics remove chart revenue
stdio 経由で MCP を提供する	sqlx mcp
Skill をインストールする	sqlx skill install --target codex、--target claude、--target dsh、または --target pi
別の Skill ディレクトリにインストールする	sqlx skill install --path /path/to/skills/sqlx
管理対象の Skill を確認・更新する	sqlx skill status、sqlx skill update
Skill インストールの管理を停止する	sqlx skill remove --path /path/to/skills/sqlx（ファイルは保持されます）
ヘルプとバージョン	sqlx --help、sqlx --version

実行時の動作

各呼び出しは、データベース接続を1つ所有します。繰り返し指定された --command 引数は順番に実行され、最初は自動コミットが有効です。最初のエラーで停止し、暗黙的に全体をロールバックするトランザクションはありません。一時テーブルやセッション変数は、別の呼び出しには引き継がれません。GO、DELIMITER、psql のバックスラッシュコマンドなど、クライアント向けのディレクティブは送信しないでください。

--command が現在のフラグで、--sql もエイリアスとして引き続き使用できます。

出力は、実行されたステートメントごとに1項目を含む JSON オブジェクトです。results[].stmt はステートメントを示し、cols は列を [name, type] のペアで列挙します（値がプレーンテキストでない場合は、base64、boolean、json が3つ目の要素として加わります）。rows には位置に対応する値が格納され、count にはドライバーが返した行数が格納されます。重複するラベルも別々に保持されます。整数と小数の精度を保つため、数値は文字列としてエンコードされ、バイナリデータには Base64 が使用されます。失敗したステートメントには outcome を含む独自の error が付き、実行されなかったステートメントは skipped に列挙されます。オブジェクトの末尾には success があり、これはプロセスの終了ステータスにもなります。

標準出力に出力されるのはプレビューのみです。結果セットの行数が preview-rows（デフォルトは10）を超える場合、または値のサイズが16 KiBを超える場合、その結果セット全体が結果ディレクトリ内の results/<id>/<statement>-<result>.jsonl に書き込まれ、対応する項目には file パスとオブジェクトの id が含まれます。そのファイルから残りの行を読み取るか、sqlx results rows --id <id> --offset 100 でページ単位に取得できます。デフォルトの結果ディレクトリはシステムの一時ディレクトリ内に作られるプライベートなディレクトリなので、マシンを再起動すると結果は消えます。結果を保持するには sqlx setting set results-dir ~/sqlx-results を設定し、24時間後のクリーンアップを停止するには sqlx setting set results-retention-hours 0 を設定してください。

ファイルを読み取れない呼び出し元には、結果全体を1つの応答に含める必要があります。--full を指定すると、すべての行が出力され、何も保存されません。sqlx setting set result-mode full を設定すると、このマシンではそれがデフォルトになり、MCP ツール sqlx_sql_execute では1回の呼び出しに "full": true を指定できます。この場合、大きな結果は呼び出し元自身の出力予算を消費するため、デフォルトではプレビューが使用されます。

--events を指定すると、スクリプトで解析するための生のワーカーイベントストリーム（protocol_version、datasource_id、events、success）が出力され、何も保存されません。--preview <rows> は、1回の呼び出しに限ってプレビューの行数を上書きします。

最後の success フラグと終了ステータスを確認し、結果が不確かな書き込みを自動で再実行しないでください。

ローカルページ

ユーザーがブラウザーで結果を確認し、そこでパスワードを入力できるようにします。

sqlx sql execute --datasource dev --command "SELECT id, name FROM users ORDER BY id" --view

SQLX は1回実行され、ローカル URL を返します。ページは結果を自動的に読み込み、複数の結果セットとページネーションに対応し、値を正確に保持します。ページを再読み込みしたり、ページを移動したり、再び開いたりすると、キャッシュされた結果が読み込まれます。ページ上の 更新 を実行すると、元の SQL バッチがデータベースに対して再実行されるため、そのバッチ内の書き込みも再度実行されます。更新が成功すると、同じ URL に表示されるスナップショットが置き換わります。失敗した場合は前の結果が保持され、データベースの変更はロールバックされません。結果はローカルに24時間保持されます。

sqlx ui はローカルのワークベンチを開き、sqlx ui status と sqlx ui stop はサービスの状態を確認または停止します。--no-open を指定すると、ブラウザーを起動せずにリンクを返します。ワークベンチは sqlx analytics で作成したチャートとダッシュボードも表示します（ローカル分析を参照）。このコマンドを実行するために、サービスを起動しておく必要はありません。ページにアクセスできるのは SQLX を実行しているマシン上だけです。HttpOnly のブラウザーセッションは自動的に読み込まれ、サービスは sqlx ui stop を実行するまで起動したままです。

ページにパスワードを入力することで、認証情報が会話に含まれるのを防げます。ただし、同じオペレーティングシステムユーザーとしてファイルを読み取ったり、ブラウザーを操作したりできるエージェントから認証情報を隔離することはできません。インターフェースとストレージの境界については、ローカル UI の設計を参照してください。

UI を選択する

sqlx ui plugin install --url <plugin-zip-url> --sha256 <published-sha256>
sqlx ui plugin list
sqlx ui plugin use <plugin-id>          # default restores the default interface
sqlx ui plugin remove <plugin-id> --version <version>

インストールしてもプラグインは有効になりません。選択後に、開いているページを再読み込みするか、sqlx ui を実行してください。CLI を更新しても、インストール済みのプラグインのバージョンは維持され、デフォルトのインターフェースはリリースのバージョンに切り替わります。バージョンを切り替えるには、先に sqlx ui stop を実行する必要があります。プラグインはローカルで実行され、入力した認証情報や表示データにアクセスできます。そのため、信頼できる作成者のインターフェースをインストールしてください。チェックサムで確認できるのはダウンロードしたバイト列に破損がないことだけであり、作成者が信頼できることではありません。

独自のインターフェースを作成するには、UI プラグインガイド、型付きブラウザー SDK、および独立したターミナル UI の例を参照してください。ユーザーに Node.js ランタイムは必要ありません。

データとダウンロード

ユーザーデータは ~/.sqlx/ に保存されます。別の場所を使用するには、--data-dir または SQLX_DATA_DIR を指定してください。設定は ~/.sqlx/settings.json に保存され、sqlx setting list|get|set|unset で管理します。SQLX_PREVIEW_ROWS、SQLX_RESULTS_DIR、SQLX_RESULTS_RETENTION_HOURS、SQLX_RESULT_MODE は、実行環境ごとに設定ファイルを上書きし、コマンドラインフラグはその両方を上書きします。保存された結果は前述の結果ディレクトリに保存され、デフォルトでは24時間保持され、合計容量は1 GiB 以下になります。次のコマンドの実行前に古い結果が削除され、--view のページ結果はローカルサービスによって管理されます。保存済み接続には、個別に生成されたローカルキーを使った AES-256-GCM が使用されます。暗号化されたデータと一緒にキーもバックアップしてください。キーを失うと復号できなくなります。デバイス ID はローカルで生成され、このバージョンではデバイス情報をアップロードしません。

メインの実行ファイルにはデータベースドライバーが含まれていません。各データベースのワーカーは、初回使用時にダウンロードされます。MySQL、MariaDB、TiDB、GreatSQL、OceanBase、StarRocks、Apache Doris は MySQL ワーカーを共有し、Redis、MongoDB、SQLite、DuckDB はそれぞれ独自のネイティブワーカーで実行されます。PostgreSQL、CockroachDB、YugabyteDB は PostgreSQL ワーカーを共有し、Oracle、SQL Server、ClickHouse、Trino、Presto、TDengine、openGauss、Dameng、KingbaseES、H2、Hive、Apache Kylin、XuguDB、IBM Db2、IBM Informix、SUNDB、GBase 8s は JDBC ワーカーを使用します（各データベースに対応するワーカーはデータベースの表を参照してください）。ダウンロードされるリソースは、実行中の CLI バージョンに対応する固定リリースマニフェストから取得され、使用前に検証されます。別のマニフェストやローカルテストサーバーを選択するには、--manifest <https-url> を指定してください。

ダウンロードは初回使用時に行われ、その後はキャッシュされます。各ダウンロードでは、速度と推定時間を含む Downloading … が表示され、最後に標準エラー出力に Downloaded … in 12.3s (390 KB/s) と表示されます。進捗行が更新されるのは標準エラー出力がターミナルの場合だけなので、パイプで渡した JSON が汚れることはありません。転送が中断された場合は最大3回再試行されます。失敗したコマンドを再実行すると、インストール済みのコンポーネントはすべて再利用されます。最初のクエリやページの実行中に待たずに済むようにするには、次のようにします。

sqlx prefetch mysql ui      # MySQL worker and the local browser UI
sqlx prefetch all           # adds the PostgreSQL, CockroachDB, YugabyteDB, openGauss, MariaDB, TiDB, GreatSQL, OceanBase, StarRocks, Doris, Oracle, SQL Server, ClickHouse, Trino, Presto, Hive, Kylin, XuguDB, TDengine, Dameng, KingbaseES, Redis, MongoDB, SQLite, DuckDB and H2 components, the JDBC runtime and the JRE

データベースリファレンスでは、各 SQL 操作の目的、パラメーター、結果、公式ドキュメントへのリンクを説明しています。

トラブルシューティング

症状	対処方法
invalid peer certificate: UnknownIssuer、error performing TLS handshake	接続で TLS 検証が要求されていますが、データベースがマシンで信頼されている証明書を提示していません（ローカルコンテナーでよく発生します）。--tls verify-full を削除してください（デフォルトは disable です）
sqlx: command not found	インストール先ディレクトリが PATH に含まれていません。~/.local/bin（macOS、Linux）または %LOCALAPPDATA%\Programs\SQLX（Windows）を追加してください
最初のクエリでダウンロードが停止したように見える	先に sqlx prefetch <component> を実行してください。中断後に再実行すると、インストール済みのコンポーネントが再利用されます
UI プラグインのバージョン切り替えに失敗する	先に sqlx ui stop を実行してから、sqlx ui plugin remove を実行してください
更新に失敗する	sqlx update status を確認してください。必要に応じてインストーラーを再実行してください。保存済み接続には影響しません
Oracle または SQL Server で JDBC 関連のエラーが表示される	SQLX_JDBC_DEBUG=1 を指定して再実行すると、ドライバー自体の診断情報を確認できます

ソースからビルドする

ソース開発には、Git、Rust 1.95、Node.js 22、および各プラットフォームのネイティブビルドツールが必要です。Node.js は UI プラグインのアセットのビルドにのみ使用します。Oracle または SQL Server の開発を行う場合は、Java 17 JDK と Maven もインストールしてください。

macOS または Linux の場合：

git clone https://github.com/OtterMind/sqlx.git
cd sqlx
npm --prefix ui ci
npm --prefix ui run build
cargo build --workspace --release --locked
export PATH="$PWD/target/release:$PATH"
export SQLX_WORKER_DIR="$PWD/target/release"
sqlx --version
sqlx init
sqlx ui plugin install --path ui/dist
sqlx ui plugin use default

Windows PowerShell の場合：

git clone https://github.com/OtterMind/sqlx.git
Set-Location sqlx
npm --prefix ui ci
npm --prefix ui run build
cargo build --workspace --release --locked
$env:Path = "$PWD\target\release;$env:Path"
$env:SQLX_WORKER_DIR = "$PWD\target\release"
sqlx --version
sqlx init
sqlx ui plugin install --path ui/dist
sqlx ui plugin use default

チェックアウトをその場所に置いたままにするか、CLI と両方のネイティブワーカーを専用ディレクトリにコピーし、それに応じて PATH と SQLX_WORKER_DIR を更新してください。このソースビルドでは、公開済みのワーカーマニフェストがなくても MySQL と PostgreSQL を使用できます。

Oracle と SQL Server の場合は、JDBC ワーカーをビルドし、そのワーカーと同じ場所にドライバー JAR を配置してください。macOS または Linux の場合：

mvn -B -f java/jdbc/pom.xml package
cp java/jdbc/target/sqlx-jdbc-0.1.21.jar target/release/sqlx-jdbc.jar
curl -fL https://repo.maven.apache.org/maven2/com/oracle/database/jdbc/ojdbc11/23.6.0.24.10/ojdbc11-23.6.0.24.10.jar -o target/release/ojdbc.jar
curl -fL https://repo.maven.apache.org/maven2/com/microsoft/sqlserver/mssql-jdbc/12.10.1.jre11/mssql-jdbc-12.10.1.jre11.jar -o target/release/mssql-jdbc.jar

Windows PowerShell の場合：

mvn -B -f java/jdbc/pom.xml package
Copy-Item java/jdbc/target/sqlx-jdbc-0.1.21.jar target/release/sqlx-jdbc.jar
Invoke-WebRequest 'https://repo.maven.apache.org/maven2/com/oracle/database/jdbc/ojdbc11/23.6.0.24.10/ojdbc11-23.6.0.24.10.jar' -OutFile target/release/ojdbc.jar
Invoke-WebRequest 'https://repo.maven.apache.org/maven2/com/microsoft/sqlserver/mssql-jdbc/12.10.1.jre11/mssql-jdbc-12.10.1.jre11.jar' -OutFile target/release/mssql-jdbc.jar

Java 17 が PATH に含まれている必要があります。含まれていない場合は、SQLX_JAVA_BIN で実行ファイルを指定できます。これらの手動での依存関係の設定が必要なのはソース開発の場合のみです。バイナリリリースでは、専用の Java ランタイムとドライバーが自動的にダウンロードされます。

開発と検証

npm --prefix ui ci
npm --prefix ui run build
cargo build --workspace --locked
cargo test --workspace --locked
cargo clippy --workspace --all-targets --locked -- -D warnings
mvn -B -f java/jdbc/pom.xml verify
python3 tests/distribution.py
python3 tests/ui_lifecycle.py
python3 tests/ui_distribution.py
python3 tests/ui_plugins.py
python3 tests/updates.py
docker compose -f tests/compose.yaml up -d --wait mysql postgres
python3 tests/integration.py
python3 tests/ui_api.py
docker compose -f tests/compose.yaml down -v
# one group at a time; StarRocks and Doris each need a frontend and a backend
docker compose -f tests/compose.yaml up -d --wait tidb yugabytedb
python3 tests/databases.py tidb yugabytedb
docker compose -f tests/compose.yaml down -v
docker compose -f tests/compose.yaml up -d --wait starrocks
python3 tests/databases.py starrocks
docker compose -f tests/compose.yaml down -v
docker compose -f tests/compose.yaml up -d --wait doris
python3 tests/databases.py doris
docker compose -f tests/compose.yaml down -v
docker compose -f tests/compose.yaml up -d --wait greatsql tdengine
python3 tests/databases.py greatsql tdengine
docker compose -f tests/compose.yaml down -v
# Dameng and KingbaseES have no public image; point the fixtures at a local instance
# and export SQLX_TEST_DAMENG_PASSWORD or SQLX_TEST_KINGBASE_PASSWORD when they differ
python3 tests/databases.py dameng kingbase
docker compose -f tests/compose.yaml up -d --wait presto hive
bash scripts/jdbc-fixture.sh presto
bash scripts/jdbc-fixture.sh hive
python3 tests/databases.py presto hive
docker compose -f tests/compose.yaml down -v
# Kylin, XuguDB, Db2 and Informix take turns because each needs several gigabytes
docker compose -f tests/compose.yaml up -d --wait kylin
bash scripts/jdbc-fixture.sh kylin
python3 tests/databases.py kylin
docker compose -f tests/compose.yaml down -v
# GBase 8s takes the vendor driver and its own instance; SUNDB needs a licensed installation
# and XuguDB a trial image whose password is known. tests/databases.py lists every variable.
export SQLX_TEST_GBASE8S_DRIVER=~/gbasedbt-jdbc.jar
python3 tests/databases.py gbase8s

ローカルのネイティブワーカーを使う場合は、SQLX_WORKER_DIR に絶対パスで target/debug ディレクトリを設定してください。JDBC の開発では、このディレクトリに sqlx-jdbc.jar と ojdbc.jar または mssql-jdbc.jar も含めます。SQLX_JAVA_BIN を使って Java 17 を明示的に選択できます。これらの上書き設定は開発用であり、リリースを利用するユーザーには必要ありません。フィクスチャスクリプトでは、専用のテストコンテナとテスト専用の認証情報を使用します。

用意するドライバー

ほとんどの JDBC ドライバーはリリースに同梱されており、初回使用時にダウンロードされます。ドライバーの再配布を許可していないベンダーのものはパッケージに含まれていません。IBM Db2、IBM Informix、SUNDB、GBase 8s への接続には、ベンダーから一度インストールしたドライバーを使用します。

sqlx driver add --type db2 --jar ~/Downloads/jcc-12.1.0.0.jar
sqlx driver list
sqlx driver remove --type db2

sqlx driver add は JAR を <data-dir>/drivers/<engine>/ にコピーし、実際にそのエンジンのドライバークラスが含まれていることを確認します。それ以降の各コマンドでは、そこからドライバーが読み込まれます。用意した JAR はリリースコンポーネントより優先されるため、リリースが追いつく前に新しいベンダードライバーを使用できます。ドライバーがない状態でこれらのエンジンのいずれかに対してステートメントを実行すると、実行すべき正確なコマンドが表示されます。

sqlx sql execute --datasource <id> --command "SELECT 1 FROM SYSIBM.SYSDUMMY1"
# SQLX does not redistribute the db2 driver; run `sqlx driver add --type db2 --jar <path>` with the vendor driver jar first

scripts/release-driver-check.sh <engine> <jar> <data-dir> <connection-json> <statement> は、リリース利用者と同じ手順を実行します。まず JAR をインストールし、次に開発用の上書き設定を使わずに実行するため、CLI は公開済みマニフェストから JRE と JDBC ランナーを解決します。エンジンを認識する JDBC ランナーを含むリリースが必要なため、機能ブランチではなく公開済みバージョンに対して実行してください。

ドライバーの入手先：

エンジン	用意するファイル	ドライバークラス
IBM Db2	IBM または Maven Central の jcc-<version>.jar（com.ibm.db2:jcc）	com.ibm.db2.jcc.DB2Driver
IBM Informix	Informix JDBC ドライバーの 4.50 系（com.ibm.informix:jdbc）。15.x 系は Informix 14.10 サーバーで動作しません	com.informix.jdbc.IfxDriver
SUNDB	ベンダーイメージの /goldilocks_home/lib/ にある goldilocks8.jar	sunje.goldilocks.jdbc.GoldilocksDriver
GBase 8s	ベンダーの ifxjdbc.jar。これを含むラッパー JAR は、先に展開する必要があります	com.gbasedbt.jdbc.IfxDriver

リリースとドキュメント

• パッケージとチェックサム：GitHub Releases
• リリースノート：docs/release-notes.md
• 設計と実装の境界：docs/design.md
• 更新の動作と復旧：docs/updates.md
• ローカルインターフェースとプラグイン：docs/local-ui.md、docs/ui-plugins.md
• エージェント連携：integrations/README.md、スキル

含まれない機能：SQL ファイル入力、永続セッション、設定可能なトランザクションモードとエラーモード、結果ファイルのエクスポート、無人での更新インストール、テレメトリー。

ライセンス

この公開ソースリポジトリでは、改変した Chat2DB ライセンスを改変コードに適用しています。これは、改変されていない Apache 2.0 ライセンスではありません。LICENSE と NOTICE をご確認ください。サードパーティ依存関係には、それぞれのライセンスが適用されます。