Zum Hauptinhalt springen
Übersetzte Seite

Diese Seite wurde mit KI-Unterstützung aus dem Englischen übersetzt. Bei Abweichungen ist die englische Version maßgeblich.

srv

Befehl zum Starten von StackQL als Dienst, auf den anschließend Postgres-Wire-Protocol-Clients mit mTLS-Authentifizierung zugreifen können. Der Befehl srv kann zusätzlich zum PostgreSQL-Wire-Protocol-Server einen Model Context Protocol (MCP)-Server betreiben und so den Zugriff über beide Protokolle für klassische Datenbank-Clients und KI-Agenten ermöglichen.


Syntax​

stackql srv [server_options] [flags]


hinweis

Obwohl der StackQL-Server das Postgres-Wire-Protocol verwendet, ist er kein Postgres-Server und benötigt auch keinen. Das Wire-Protocol dient dem Client zur Kommunikation mit dem Server, der mit StackQL Abfragen oder DML-Operationen gegen entfernte Cloud- und SaaS-Provider ausführt und die Ergebnisse an den Client zurückgibt.

Parameter, die über das Extended Query Protocol gesendet werden (Parse / Bind / Execute, wie von psycopg 3, pgx und JDBC verwendet), werden serverseitig als String-Literale gebunden. Ab v0.12.742 bleibt ein $n-Platzhalter innerhalb eines String-Literals, eines quotierten Bezeichners oder eines Kommentars unangetastet, Backslashes in Parameterwerten werden escaped, und ein Textwert NULL bleibt der String NULL (SQL-NULL wird getrennt übertragen).

Serveroptionen​

OptionBeschreibungStandard
--pgsrv.addressAdresse, auf der der Server lauscht.0.0.0.0
--pgsrv.portTCP-Port, auf dem der Server lauscht.5466
--pgsrv.tlsJSON-Objekt mit der TLS-Konfiguration. Siehe das mTLS-Beispiel unten.keiner
--pgsrv.debug.enableAktiviert die Debug-Ausgabe von Abfragen für PostgreSQL-Clients, zum Beispiel mit stackql srv --pgsrv.debug.enable=true. Lassen Sie die Option ausgeschaltet, sofern Clients keine Debug-Informationen erhalten sollen.false
--pgsrv.sundryErweitertes JSON- oder YAML-Mapping, das nur dann an den PostgreSQL-Wire-Server übergeben wird, wenn --pgsrv.tls nicht gesetzt ist.{}
--pgsrv.loglevelWird akzeptiert, setzt in der aktuellen Engine aber nicht das Log-Level des Loggers. Verwenden Sie stattdessen --loglevel.WARN

weitere Optionen finden Sie unter Globale Flags

MCP-Serveroptionen​

Beim Ausführen des Befehls srv mit MCP-Unterstützung stehen die folgenden zusätzlichen Optionen zur Verfügung:

OptionBeschreibung
--mcp.server.typeMCP-Servertyp: http (In-Memory) oder reverse_proxy (TCP-basiert)
--mcp.configJSON-Konfigurationsobjekt für den MCP-Server (siehe MCP-Dokumentation)
--mcp.log.formatKodierung des MCP-Audit-Logs: jsonl (Standard) oder otel (OTLP/JSON-Log-Records); überschreibt server.audit.format im Konfigurationsobjekt
--mcp.protocol.versionNeueste angekündigte MCP-Protokollrevision: auto (Standard), 2026-07-28 (nur sitzungslos) oder eine ältere Revision wie 2025-11-25; überschreibt server.protocol_version im Konfigurationsobjekt

Inkompatible Änderung in v0.12.742

Ab v0.12.742 verweigert der MCP-HTTP-Transport (--mcp.server.type=http oder reverse_proxy) den Start, sofern das Konfigurationsobjekt nicht mit server.auth_token_env_var ein Bearer-Token benennt oder sich mit "allow_unauthenticated": true explizit abmeldet. Siehe HTTP-Client-Authentifizierung.

tipp

Ausführliche Informationen zur Konfiguration und Verwendung des MCP-Servers, einschließlich Deployment-Modi, Konfigurationsoptionen und Integration mit KI-Assistenten, finden Sie in der Dokumentation des MCP-Befehls.

info

Sie müssen die für die Provider-Authentifizierung erforderlichen Umgebungsvariablen setzen, bevor Sie den Server starten; weitere Informationen finden Sie unter Einen Provider verwenden.

Bei lang laufenden Servern können Sie mit dem Flag --env.file Anmeldedaten vor dem Start in einer Datei im dotenv-Stil auf der Festplatte ablegen oder rotieren, statt Variablen in die Shell zu exportieren:

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

Bei stackql srv wird die Datei einmal beim Start gelesen; der Weg zum erneuten Einlesen während der Sitzung ist das MCP-Tool reload_credentials.

Flags​

FlagBeschreibung
-h,--helpHilfeinformationen ausgeben
-v,--verboseFührt Abfragen im ausführlichen Modus mit zusätzlicher Ausgabe auf stdout aus; ist das globale Flag -f (--outfile) gesetzt,
werden diese zusätzlichen Protokollinformationen zusammen mit den Abfrageergebnissen in die Ausgabedatei geschrieben

weitere Optionen finden Sie unter Globale Flags


Beispiele​

Einen StackQL-Serverprozess starten und mit einem psql-Kommandozeilen-Client verbinden.

Laden Sie zuerst die Konfigurationsdatei openssl.cnf von stackql/stackql herunter.

Erzeugen Sie anschließend die Zertifikats- und Schlüsseldateien, die Server und Client für die gegenseitige TLS-Authentifizierung (mTLS) verwenden.

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

Setzen Sie nun die Umgebungsvariablen; befinden sich Client und Server auf demselben Host, können diese gemeinsam genutzt werden.

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

Setzen Sie die Anmeldedaten für die Provider, die der Server benötigt. Für GitHub liest der Provider einen Benutzernamen und ein Personal Access Token aus diesen beiden Variablen:

export STACKQL_GITHUB_USERNAME=youruser
export STACKQL_GITHUB_PASSWORD=ghp_youraccesstoken

Starten Sie nun den Server in einem Terminal.

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

Verbinden Sie sich in einem anderen Terminal mit dem psql-Kommandozeilen-Client mit dem Server.

psql -h 127.0.0.1 -d stackql

Führen Sie nun eine StackQL-Abfrage gegen einen authentifizierten Provider aus.

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

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

stackql=>