srv

StackQL をサービスとして起動するためのコマンドです。起動したサービスには、mTLS で認証された Postgres ワイヤプロトコルクライアントからアクセスできます。srv コマンドは、PostgreSQL ワイヤプロトコルサーバーと並行して Model Context Protocol（MCP）サーバーを実行することもできます。これにより、従来のデータベースクライアントと AI エージェントの両方からのデュアルプロトコルアクセスが可能になります。

---

構文

stackql srv [server_options] [flags]

---

注記

StackQL サーバーは Postgres ワイヤプロトコルを使用しますが、Postgres サーバーではなく、Postgres サーバーを必要ともしません。ワイヤプロトコルは、クライアントがサーバーと通信するために使用されます。サーバーは StackQL を使用して、リモートのクラウドベンダーや SaaS ベンダーに対してクエリや DML 操作を実行し、結果をクライアントに返します。

拡張クエリプロトコル（psycopg 3、pgx、JDBC が使用する Parse / Bind / Execute）で送信されたパラメーターは、サーバー側で文字列リテラルとしてバインドされます。v0.12.742 以降では、文字列リテラル、引用符で囲まれた識別子、コメントの中にある $n プレースホルダーはそのまま残され、パラメーター値内のバックスラッシュはエスケープされます。また、テキスト値の NULL は文字列 NULL のままです（SQL の NULL は別途伝達されます）。

サーバーオプション

オプション	説明
--pgsrv.address	サーバーがリッスンするアドレス（通常は 0.0.0.0）
--pgsrv.port	サーバーがリッスンするポート（たとえば 5444）
--pgsrv.tls	mTLS 設定オブジェクト（下記の例を参照）
--pgsrv.loglevel	ログレベル（デフォルトは WARN）

その他のオプションについては、グローバルフラグを参照してください

MCP サーバーオプション

srv コマンドを MCP サポート付きで実行する場合、次の追加オプションを使用できます。

オプション	説明
--mcp.server.type	MCP サーバーの種類：http（インメモリ）または reverse_proxy（TCP ベース）
--mcp.config	MCP サーバーの JSON 設定オブジェクト（MCP ドキュメントを参照）
--mcp.log.format	MCP 監査ログのエンコーディング：jsonl（デフォルト）または otel（OTLP/JSON ログレコード）。設定オブジェクトの server.audit.format を上書きする
--mcp.protocol.version	公開する最新の MCP プロトコルリビジョン：auto（デフォルト）、2026-07-28（セッションレスのみ）、または 2025-11-25 などの古いリビジョン。設定オブジェクトの server.protocol_version を上書きする

v0.12.742 での破壊的変更

v0.12.742 以降、MCP HTTP トランスポート（--mcp.server.type=http または reverse_proxy）は、設定オブジェクトが server.auth_token_env_var で Bearer トークンを指定するか、"allow_unauthenticated": true で明示的にオプトアウトしない限り、起動を拒否します。HTTP クライアント認証を参照してください。

ヒント

デプロイモード、設定オプション、AI アシスタントとの統合など、MCP サーバーの設定と使用に関する詳細については、MCP コマンドのドキュメントを参照してください。

備考

サーバーを起動する前に、プロバイダーの認証に必要な環境変数を設定してください。詳細については、プロバイダーの使用を参照してください。

長時間稼働するサーバーでは、--env.file フラグを使用すると、変数をシェルにエクスポートする代わりに、起動前にディスク上の dotenv 形式のファイルに認証情報を配置したりローテーションしたりできます。

stackql srv --pgsrv.port 5444 --env.file /etc/stackql/credentials.env

stackql srv では、このファイルは起動時に 1 回だけ読み込まれます。セッションの途中で再読み込みする手段は、MCP の reload_credentials ツールです。

フラグ

フラグ	説明
-H,--help	ヘルプ情報を表示する
-v,--verbose	詳細モードでクエリを実行し、追加の出力を stdout に送信します。-f オプションを指定した場合、 この追加のログ情報はクエリ結果とともに出力ファイルに書き込まれます。

その他のオプションについては、グローバルフラグを参照してください

---

例

StackQL サーバープロセスを起動し、psql コマンドラインクライアントを使用して接続します。

まず、stackql/stackql から openssl.cnf 設定ファイルをダウンロードします。

次に、相互 TLS 認証（mTLS）のためにサーバーとクライアントが使用する証明書ファイルとキーファイルを生成します。

openssl req -x509 -keyout ~/stackqlcreds/server_key.pem -out ~/stackqlcreds/server_cert.pem -config ./openssl.cnf -days 365
openssl req -x509 -keyout ~/stackqlcreds/client_key.pem -out ~/stackqlcreds/client_cert.pem -config ./openssl.cnf -days 365
chmod 400 ~/stackqlcreds/client_key.pem

続いて、環境変数を設定します。クライアントとサーバーが同じホスト上にある場合、これらは共有できます。

export PGPORT=5444
export PGSSLCERT=~/stackqlcreds/client_cert.pem
export PGSSLKEY=~/stackqlcreds/client_key.pem
export PGSSLROOTCERT=~/stackqlcreds/server_cert.pem
export PGSSLSRVKEY=~/stackqlcreds/server_key.pem
export CLIENT_CERT=$(base64 -w 0 ~/stackqlcreds/client_cert.pem)
export PGSSLMODE=allow

サーバーがアクセスする必要のあるプロバイダーについて、認証オブジェクトを設定します（たとえば GitHub の場合）。

export STACKQL_GITHUB_USERNAME=youruser
export STACKQL_GITHUB_PASSWORD=ghp_youraccesstoken

次に、1 つのターミナルでサーバーを起動します。

stackql srv \
--pgsrv.address=0.0.0.0 \
--pgsrv.port=$PGPORT \
--pgsrv.tls='{ "keyFilePath": "'${PGSSLSRVKEY}'", "certFilePath": "'${PGSSLROOTCERT}'", "clientCAs": [ "'${CLIENT_CERT}'" ] }'

別のターミナルで、psql コマンドラインクライアントを使用してサーバーに接続します。

psql 127.0.0.1

次に、認証済みのプロバイダーに対して StackQL クエリを実行します。

psql (12.11 (Ubuntu 12.11-0ubuntu0.20.04.1), server 0.0.0)
Type "help" for help.

127.0.0.1=> SHOW SERVICES IN github LIKE '%repos%';
      id      | name  |           title
--------------+-------+----------------------------
 repos:v0.3.3 | repos | GitHub v3 REST API - repos
(1 row)

127.0.0.1=>