Globale Flags

Globale Flags legen das Laufzeitverhalten der StackQL-Anwendung fest; diese Flags werden auf der Kommandozeile beim Start der StackQL-Anwendung gesetzt (entweder im interaktiven Shell-Modus oder im nicht interaktiven exec-Modus) oder aus der StackQL-Initialisierungsdatei (.stackqlrc) gelesen. Die Flags umfassen:

Flag	Datentyp	Beschreibung	Standard
--access.config	string	Konfiguration des Aufruferzugriffs, ein JSON-Envelope {"path": "/path/to/access.json"} (ein bloßer Dateipfad wird ebenfalls akzeptiert). Aktiviert die Zugriffsverwaltung: Aufrufer werden per JWT, statischem Bearer-Token, Mutual TLS oder lokaler OS-Identität authentifiziert und Anweisungen anhand von Policy-Regeln autorisiert. Lokale Token-Anmeldedaten werden aus STACKQL_CALLER_TOKEN gelesen. Verfügbar in StackQL-Releases ab v1.0.
--acid	string	JSON-/YAML-String mit der ACID-Konfiguration	{}
--allow-persistent-secrets	flag	Erlaubt einer Sitzung, mit SET "$.secret_store" einen persistenten OS-Secret-Store (macOS Keychain, Linux Secret Service oder Windows Credential Manager) auszuwählen. Flat-File-Stores werden auch mit dem Flag verweigert. Siehe Provider-Sitzungen und Secrets. Verfügbar in StackQL-Releases ab v1.0.	false
--allow-secret-dereference	flag	Erlaubt das Dereferenzieren von Secret- und Anmeldedatenwerten in SQL-Ausdrücken ("$secrets.name", "$auth.provider.field"), mit der Folge, dass sie in Ergebnisse, Logs und persistierte Abfrageartefakte gelangen können. Für die normale Provider-Authentifizierung nicht erforderlich. Siehe Secret-Werte in SQL. Verfügbar in StackQL-Releases ab v1.0.	false
--apirequesttimeout	integer	Timeout für API-Anfragen in Sekunden, 0 für kein Timeout	45
--approot	string	Wurzelpfad für Anwendungskonfiguration und Cache	{cwd}/.stackql
--approotfilemode	uint32	Dateimodus für Anwendungskonfiguration und Cache	493
--auth	string	auth-Kontext-Schlüssel-Wert-Paare in json-Form
--cachekeycount	integer	Anfängliche Schlüsselanzahl des Caches	100
--configfile	string	Vollständiger Pfad der Konfigurationsdatei	{cwd}/.stackqlrc
--cpuprofile	string	cpuprofile-Datei, keine wenn leer	null
--dataflow.dependency.max	int	Maximale Tiefe der Datenflussabhängigkeiten für eine Abfrage	50
--dataflow.components.max	int	Maximale Anzahl schwach zusammenhängender Datenflusskomponenten für eine Abfrage	50
--dbInternal	string	JSON-/YAML-String zur Konfiguration der Behandlung von DBMS-Housekeeping-Abfragen	{}
-d, --delimiter	string	Trennzeichen für die csv-Ausgabe. Nur ein einzelnes Zeichen. Wird bei jeder Nicht-csv-Ausgabe ignoriert	,
--dryrun	flag	dryrun-Flag; nur den Präprozessor ausführen, die templatierte Ausgabe wird zurückgegeben	false
--env.file	string	Optionale Datei im dotenv-Stil, die beim Start in die Prozessumgebung eingelesen wird (alle Befehle); das MCP-Tool reload_credentials liest sie bei Bedarf erneut ein. Eine fehlende Datei wird toleriert; Schlüssel mit leeren Werten werden übersprungen; vorhandene Variablen werden überschrieben. Wird nicht aus .stackqlrc gelesen. Verfügbar in StackQL-Releases nach v0.10.542.	null
--execution.concurrency.limit	int	Parallelitätslimit für die Abfrageausführung	1
--export.alias	string	Präfix für Export-Aliase (Namespace oder Schema)
--gc	string	JSON-/YAML-String mit der GC-Konfiguration	{}
-H, --hideheaders	flag	Deaktiviert Spaltenüberschriften, nur gültig mit --output csv oder --output text	false
--http.log.enabled	flag	Zeigt http-Anfrageinformationen im Terminal an	false
--http.proxy.host	string	Proxy-Host (leer lassen für keinen Proxy)	null
--http.proxy.password	string	Proxy-Passwort	null
--http.proxy.port	integer	Proxy-Port, jede Zahl kleiner oder gleich 0 führt zum Standardport des jeweiligen Schemas (z. B. http -> 80)	-1
--http.proxy.scheme	string	Proxy-Schema, http oder https	http
--http.proxy.user	string	Proxy-Benutzer	null
--http.response.maxResults	integer	Maximale Ergebnisse pro http-Anfrage, jede Zahl kleiner oder gleich 0 bedeutet keine Begrenzung	-1
--http.response.pageLimit	integer	Maximale Anzahl von Ergebnisseiten, die pro Ressource zurückgegeben werden, jede Zahl kleiner oder gleich 0 bedeutet keine Begrenzung	20
--indirect.depth.max	integer	Maximale Tiefe für indirekte Abfragen: Views und Unterabfragen	5
-i, --infile	string	Eingabedatei (IQL-Datei), aus der Abfragen gelesen werden	{stdin}
-q, --iqldata	string	Kontextdatei (Daten) für das Templating (json- oder jsonnet-Datei)
--loglevel	string	Log-Level, muss einer von fatal sein	fatal
--mcp.config	string	JSON-/YAML-Konfigurationsobjekt für den MCP-Server (stackql mcp und stackql srv)	{}
--mcp.log.format	string	Kodierung des MCP-Audit-Logs, jsonl oder otel (OTLP/JSON-Log-Records); überschreibt server.audit.format in --mcp.config. Siehe Log-Format. Verfügbar in StackQL-Releases ab v0.11.660.	jsonl
--mcp.protocol.version	string	Neueste angekündigte MCP-Protokollrevision, auto, 2026-07-28 (nur sitzungslos) oder eine ältere Revision wie 2025-11-25; überschreibt server.protocol_version in --mcp.config. Siehe Revision festlegen. Verfügbar in StackQL-Releases ab v0.12.732.	auto
--mcp.server.type	string	MCP-Servertyp, einer von reverse_proxy. Siehe MCP-Servertyp.	http
--metadatattl	integer	TTL für zwischengespeicherte Metadatendokumente, in Sekunden	3600
--namespaces	string	JSON-/YAML-String mit Namespaces für Caching, Views usw.	{}
--offline	flag	Offline arbeiten, mit zwischengespeicherten Daten	false
-f, --outfile	string	Ausgabedatei, in die Ergebnisse geschrieben werden	{stdout}
-o, --output	string	Ausgabeformat, muss eines von otel sein (ndjson wird als Alias für jsonl akzeptiert). otel gibt OpenTelemetry-Log-Records aus, siehe Ausgabemodi; verfügbar in StackQL-Releases ab v0.11.660. Ist in --otel.config ein Exporter konfiguriert, werden otel-Records zusätzlich an diesen Endpunkt gesendet	table
--otel.config	string	JSON-/YAML-String zur Konfiguration des Ausgabeformats otel; exporter.endpoint, exporter.headers, exporter.timeout_ms und exporter.batch_size senden die Records an einen OTLP/HTTP-Logs-Endpunkt, siehe An einen OTLP-Endpunkt senden. Verfügbar in StackQL-Releases ab v0.12.732	{}
--preview	string	JSON-String zur Aktivierung von Preview-Funktionen. {"unstable": true} stellt die dokumentgetriebenen Relationen stackql_unstable_<provider>.<service>.<resource> bereit, die von omnisdk direkt aus den Provider-Dokumenten aufgelöst und ausgeführt werden, wobei Zeilen gestreamt werden, sobald sie entstehen; die übrigen Schlüssel (batchSize, flushInterval, endpoint, insecureSkipTLSVerify) stimmen dieses Backend ab. Preview-Funktionen sind nicht stabil: Verhalten, Syntax und Ausgabe können sich zwischen Releases ohne Ankündigung ändern oder brechen, verlassen Sie sich daher in der Produktion nicht darauf. Ab v1.0 stellt dasselbe Opt-in die Relationen stackql_preview.iac.run und stackql_preview.iac.destroy bereit, die eine deklarierte Ressourcenmenge über omnisdk anwenden und abbauen, wobei der Zustand unter dem Anwendungswurzelpfad gehalten wird. Siehe Preview-Funktionen	{}
--querycachesize	integer	Größe des LRU-Caches für Abfragepläne in Anzahl der Einträge	10000
--registry	string	JSON-/YAML-String zur Konfiguration des Speicherorts der Provider-Registry und der Signaturprüfung von Provider-Dokumenten	siehe --registry
--session	string	JSON-/YAML-String mit der Sitzungskonfiguration	{}
--sqlBackend	string	JSON-/YAML-String mit der Systemkonfiguration des SQL-Backends	siehe --sqlBackend
--store.txn	string	JSON-/YAML-String mit der Konfiguration des Txn-Stores	{}
--tls.CABundle	string	Pfad zum CA-Bundle, ohne Angabe werden die Systemstandards verwendet
--tls.allowInsecure	flag	Erlaubt das Vertrauen in unsichere Zertifikate (nicht empfohlen)
--var	string	Externe Variablen als Schlüssel/Wert-Paare, die über jsonnet-Datendateien in StackQL-Abfragen eingelesen werden
-v, --verbose	flag	Ausführliche Ausgabe	false
-h, --help		Kontextspezifische Hilfe für stackql
--version		Zeigt die Version des StackQL-Programms an

--registry

Das Flag --registry konfiguriert, woher Provider-Dokumente gelesen werden und ob ihre Signaturen geprüft werden. Der Wert ist ein JSON-String mit den folgenden Schlüsseln:

Schlüssel	Beschreibung	Standard
url	Registry-URL. Ohne Angabe wird die öffentliche StackQL-Provider-Registry verwendet.	öffentliche Registry
localDocRoot	Ein lokales Verzeichnis mit Provider-Dokumenten, das anstelle eines Downloads aus der Registry gelesen wird. Wird beim Entwickeln eines Providers verwendet.
srcPrefix	Pfadpräfix unterhalb der Registry-Wurzel, in dem die Provider-Quelldokumente liegen.	src
verifyConfig.nopVerify	true überspringt die Signaturprüfung. Auf false setzen, um für jedes gelesene Provider- und Service-Dokument eine eingebettete ML-DSA-65-Signatur (FIPS 204) zu verlangen, einschließlich der dokumentgestützten Preview-Relationen.	true
verifyConfig.publicKeys	Ein JSON-Objekt, das Schlüssel-IDs auf hex-kodierte öffentliche ML-DSA-65-Schlüssel abbildet, für private Registries. Es ersetzt die eingebetteten Produktionsschlüssel; ein explizit leeres Objekt ist ein Fehler.	eingebettete Schlüssel

Beispiel: Signierte Provider-Dokumente verlangen

Schaltet die Prüfung für jedes aus der öffentlichen Registry gelesene Provider- und Service-Dokument ein, geprüft gegen die eingebetteten Produktionsschlüssel:

stackql --registry '{"verifyConfig": {"nopVerify": false}}' shell

Beispiel: Unsignierte Dokumente aus einem lokalen Verzeichnis lesen

Verweist die Registry auf ein Verzeichnis mit Provider-Dokumenten in Entwicklung. Diese Dokumente sind unsigniert, daher bleibt die Prüfung ausgeschaltet:

stackql --registry '{"localDocRoot": "/path/to/provider-dev/openapi", "verifyConfig": {"nopVerify": true}}' shell

hinweis

Die Signaturprüfung ist in StackQL-Releases ab v1.0 verfügbar und standardmäßig ausgeschaltet. Signaturen decken die exakten YAML-Bytes eines Dokuments ab, sodass jede Änderung, auch eine Formatierungs- oder Zeilenumbruchänderung, sie ungültig macht; signieren Sie mit dem Tool pqsig sign-doc der Registry neu. Unsignierte lokale Entwicklungsdokumente müssen nopVerify: true beibehalten. Die früheren Zertifikatsoptionen und .sig-Sidecar-Dateien werden nicht mehr verwendet, und Archive, die nur mit Sidecars veröffentlicht wurden, müssen vor einer geprüften Verwendung neu veröffentlicht werden. Die Prüfung authentifiziert Dokumente beim Lesen; Download und Entpacken von Archiven sind nicht abgedeckt.

--sqlBackend

Das Flag --sqlBackend konfiguriert ein externes SQL-Backend für StackQL, sodass Sie anstelle der standardmäßig eingebetteten SQL-Engine eine externe Datenbank-Engine (etwa PostgreSQL) verwenden können. Das ist nützlich, um eine externe Datenbank für die Abfrageverarbeitung, persistente Speicherung oder die Integration in bestehende Datenbankinfrastruktur zu nutzen.

Der Wert ist ein JSON-String mit den folgenden Schlüsseln:

Schlüssel	Beschreibung	Beispielwerte
dbEngine	Der Typ der Datenbank-Engine	postgres_tcp
sqlDialect	Der zu verwendende SQL-Dialekt	postgres
dsn	Der Data Source Name (Verbindungszeichenfolge) der Datenbank	Siehe Beispiele unten

Beispiel: Ein PostgreSQL-Backend verwenden

./stackql \
  --sqlBackend='{"dbEngine": "postgres_tcp", "sqlDialect": "postgres", "dsn": "postgres://user:password@hostname:port/dbname?sslmode=require"}' \
  shell

Beispiel: Die PostgreSQL-Schnittstelle von Databricks verwenden

Databricks stellt eine PostgreSQL-kompatible Schnittstelle bereit, die als StackQL-SQL-Backend verwendet werden kann. Der DSN verwendet das Standardformat der PostgreSQL-Verbindungszeichenfolge mit Ihren Databricks-Anmeldedaten:

./stackql \
  --sqlBackend='{"dbEngine": "postgres_tcp", "sqlDialect": "postgres", "dsn": "postgres://user%40domain.com:your-access-token@your-databricks-host.cloud.databricks.com/databricks_postgres?sslmode=require"}' \
  shell

hinweis

Sonderzeichen im Benutzernamen oder Passwort (etwa @) müssen im DSN URL-kodiert sein (z. B. wird aus @ %40).