Options globales

Les options globales déterminent le comportement de l'application StackQL à l'exécution ; elles sont définies sur la ligne de commande au lancement de l'application StackQL (en mode interactif/shell ou en mode exec non interactif) ou sont lues depuis le fichier d'initialisation de StackQL (.stackqlrc). Les options comprennent :

Option	Type de données	Description	Valeur par défaut
--access.config	string	Configuration de l'accès des appelants, une enveloppe JSON {"path": "/path/to/access.json"} (un simple chemin de fichier est également accepté). Active la gestion des accès : les appelants sont authentifiés par JWT, jeton bearer statique, TLS mutuel ou identité locale de l'OS, et les instructions sont autorisées au regard de règles de politique. Les identifiants locaux de type jeton sont lus depuis STACKQL_CALLER_TOKEN. Disponible à partir de StackQL v1.0.
--acid	string	Chaîne JSON / YAML représentant la configuration ACID	{}
--allow-persistent-secrets	flag	Autorise une session à sélectionner un magasin de secrets persistant du système d'exploitation (macOS Keychain, Linux Secret Service ou Windows Credential Manager) avec SET "$.secret_store". Les magasins sous forme de fichier plat sont refusés même avec cette option. Consultez Sessions de provider et secrets. Disponible à partir de StackQL v1.0.	false
--allow-secret-dereference	flag	Autorise le déréférencement des valeurs de secrets et d'identifiants dans les expressions SQL ("$secrets.name", "$auth.provider.field"), avec pour conséquence qu'elles peuvent se retrouver dans les résultats, les journaux et les artefacts de requête persistés. Inutile pour l'authentification normale des providers. Consultez Valeurs de secrets dans SQL. Disponible à partir de StackQL v1.0.	false
--apirequesttimeout	integer	Délai d'expiration des appels d'API en secondes, 0 pour aucun délai d'expiration	45
--approot	string	Chemin racine de la configuration et du cache de l'application	{cwd}/.stackql
--approotfilemode	uint32	Mode de fichier de la configuration et du cache de l'application	493
--auth	string	Paires clé-valeur du contexte auth au format json
--cachekeycount	integer	Nombre initial de clés du cache	100
--configfile	string	Chemin complet du fichier de configuration	{cwd}/.stackqlrc
--cpuprofile	string	Fichier cpuprofile, aucun si vide	null
--dataflow.dependency.max	int	Profondeur maximale des dépendances de flux de données pour une requête donnée	50
--dataflow.components.max	int	Nombre maximal de composantes faiblement connexes du flux de données pour une requête donnée	50
--dbInternal	string	Chaîne JSON / YAML configurant le traitement des requêtes de maintenance du SGBD	{}
-d, --delimiter	string	Délimiteur de la sortie csv. Un seul caractère. Ignoré pour toute sortie autre que csv	,
--dryrun	flag	Option dryrun ; exécute uniquement le préprocesseur, la sortie issue des modèles est renvoyée	false
--env.file	string	Fichier facultatif de type dotenv chargé dans l'environnement du processus au démarrage (toutes les commandes) ; l'outil MCP reload_credentials le recharge à la demande. Un fichier manquant est toléré ; les clés dont la valeur est vide sont ignorées ; les variables existantes sont écrasées. Cette option n'est pas lue depuis .stackqlrc. Disponible dans les versions de StackQL postérieures à v0.10.542.	null
--execution.concurrency.limit	int	Limite de concurrence pour l'exécution des requêtes	1
--export.alias	string	Préfixe d'alias d'export (espace de noms ou schéma)
--gc	string	Chaîne JSON / YAML représentant la configuration du GC	{}
-H, --hideheaders	flag	Désactive les en-têtes de colonnes, valide uniquement avec --output csv ou --output text	false
--http.log.enabled	flag	Affiche les informations des requêtes http dans le terminal	false
--http.proxy.host	string	Hôte du proxy (laisser vide pour ne pas utiliser de proxy)	null
--http.proxy.password	string	Mot de passe du proxy	null
--http.proxy.port	integer	Port du proxy, tout nombre inférieur ou égal à 0 donne le port par défaut du schéma concerné (par exemple http -> 80)	-1
--http.proxy.scheme	string	Schéma du proxy, http ou https	http
--http.proxy.user	string	Utilisateur du proxy	null
--http.response.maxResults	integer	Nombre maximal de résultats par requête http, tout nombre inférieur ou égal à 0 supprime la limite	-1
--http.response.pageLimit	integer	Nombre maximal de pages de résultats renvoyées par ressource, tout nombre inférieur ou égal à 0 supprime la limite	20
--indirect.depth.max	integer	Profondeur maximale des requêtes indirectes : vues et sous-requêtes	5
-i, --infile	string	Fichier d'entrée (fichier IQL) à partir duquel les requêtes sont lues	{stdin}
-q, --iqldata	string	Fichier de contexte (données) pour le templating (fichier json ou jsonnet)
--loglevel	string	Niveau de journalisation, doit être l'un de fatal	fatal
--mcp.config	string	Objet de configuration JSON / YAML du serveur MCP (stackql mcp et stackql srv)	{}
--mcp.log.format	string	Encodage du journal d'audit MCP, jsonl ou otel (enregistrements de journal OTLP/JSON) ; prévaut sur server.audit.format dans --mcp.config. Consultez Format de journal. Disponible à partir de StackQL v0.11.660.	jsonl
--mcp.protocol.version	string	Révision du protocole MCP la plus récente annoncée, auto, 2026-07-28 (sans session uniquement) ou une révision plus ancienne telle que 2025-11-25 ; prévaut sur server.protocol_version dans --mcp.config. Consultez Fixer la révision. Disponible à partir de StackQL v0.12.732.	auto
--mcp.server.type	string	Type de serveur MCP, l'un de reverse_proxy. Consultez Type de serveur MCP.	http
--metadatattl	integer	TTL des documents de métadonnées mis en cache, en secondes	3600
--namespaces	string	Chaîne JSON / YAML représentant les espaces de noms pour la mise en cache, les vues, etc.	{}
--offline	flag	Fonctionne hors ligne, avec les données en cache	false
-f, --outfile	string	Fichier de sortie dans lequel les résultats sont écrits	{stdout}
-o, --output	string	Format de sortie, doit être l'un de otel (ndjson est accepté comme alias de jsonl). otel émet des enregistrements de journal OpenTelemetry, consultez Modes de sortie ; disponible dans les versions de StackQL à partir de v0.11.660. Lorsqu'un exportateur est configuré dans --otel.config, les enregistrements otel sont également poussés vers ce point de terminaison	table
--otel.config	string	Chaîne JSON / YAML configurant le format de sortie otel ; exporter.endpoint, exporter.headers, exporter.timeout_ms et exporter.batch_size poussent les enregistrements vers un point de terminaison de journaux OTLP/HTTP, consultez Pousser vers un point de terminaison OTLP. Disponible à partir de StackQL v0.12.732	{}
--preview	string	Chaîne JSON activant les fonctionnalités en préversion. {"unstable": true} expose les relations stackql_unstable_<provider>.<service>.<resource> pilotées par les documents, qui sont résolues et exécutées par omnisdk directement à partir des documents de provider, les lignes étant diffusées au fur et à mesure de leur production ; les autres clés (batchSize, flushInterval, endpoint, insecureSkipTLSVerify) ajustent ce backend. Les fonctionnalités en préversion ne sont pas stables : le comportement, la syntaxe et la sortie peuvent changer ou cesser de fonctionner d'une version à l'autre sans préavis, ne vous y fiez donc pas en production. À partir de v1.0, la même activation explicite expose les relations stackql_preview.iac.run et stackql_preview.iac.destroy, qui appliquent et détruisent un ensemble de ressources déclaré par l'intermédiaire de omnisdk, l'état étant conservé sous la racine de l'application. Consultez Fonctionnalités en préversion	{}
--querycachesize	integer	Taille, en nombre d'entrées, du cache LRU des plans de requête	10000
--registry	string	Chaîne JSON / YAML configurant l'emplacement du registre de providers et la vérification de signature des documents de provider	consultez --registry
--session	string	Chaîne JSON / YAML représentant la configuration de session	{}
--sqlBackend	string	Chaîne JSON / YAML représentant la configuration système du backend SQL	consultez --sqlBackend
--store.txn	string	Chaîne JSON / YAML représentant la configuration du magasin Txn	{}
--tls.CABundle	string	Chemin du bundle de CA ; s'il n'est pas spécifié, les valeurs par défaut du système sont utilisées
--tls.allowInsecure	flag	Autorise la confiance envers des certificats non sécurisés (non recommandé)
--var	string	Variables externes fournies sous forme de paires clé/valeur pour être utilisées dans les requêtes StackQL par l'intermédiaire de fichiers de données jsonnet
-v, --verbose	flag	Sortie détaillée	false
-h, --help		Aide contextuelle pour stackql
--version		Affiche la version du programme StackQL

--registry

L'option --registry configure l'emplacement depuis lequel les documents de provider sont lus et la vérification éventuelle de leurs signatures. La valeur est une chaîne JSON avec les clés suivantes :

Clé	Description	Valeur par défaut
url	URL du registre. Le registre public de providers StackQL est utilisé si elle est omise.	registre public
localDocRoot	Répertoire local contenant des documents de provider, lus sur place au lieu d'être téléchargés depuis le registre. Utilisé lors du développement d'un provider.
srcPrefix	Préfixe de chemin, sous la racine du registre, où se trouvent les documents source des providers.	src
verifyConfig.nopVerify	true désactive la vérification de signature. Définissez false pour exiger une signature ML-DSA-65 (FIPS 204) embarquée à chaque lecture d'un document de provider ou de service, y compris pour les relations en préversion adossées aux documents.	true
verifyConfig.publicKeys	Objet JSON associant des ID de clé à des clés publiques ML-DSA-65 encodées en hexadécimal, pour les registres privés. Il remplace les clés de production embarquées ; un objet vide explicite est une erreur.	clés embarquées

Exemple : exiger des documents de provider signés

Active la vérification pour chaque document de provider et de service lu depuis le registre public, au regard des clés de production embarquées :

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

Exemple : lire des documents non signés depuis un répertoire local

Fait pointer le registre vers un répertoire de documents de provider en cours de développement. Ces documents ne sont pas signés, la vérification reste donc désactivée :

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

remarque

La vérification de signature est disponible dans les versions de StackQL à partir de v1.0 et est désactivée par défaut. Les signatures couvrent les octets YAML exacts d'un document : toute modification, y compris un changement de mise en forme ou de saut de ligne, les invalide ; signez à nouveau avec l'outil pqsig sign-doc du registre. Les documents de développement locaux non signés doivent conserver nopVerify: true. Les anciennes options de certificat et les fichiers sidecar .sig ne sont plus utilisés, et les archives publiées uniquement avec des sidecars doivent être republiées avant toute utilisation vérifiée. La vérification authentifie les documents au moment de leur lecture ; le téléchargement et l'extraction des archives ne sont pas couverts.

--sqlBackend

L'option --sqlBackend configure un backend SQL externe pour StackQL, ce qui vous permet d'utiliser un moteur de base de données externe (tel que PostgreSQL) à la place du moteur SQL embarqué par défaut. Cela permet de s'appuyer sur une base de données externe pour le traitement des requêtes, le stockage persistant ou l'intégration à une infrastructure de bases de données existante.

La valeur est une chaîne JSON avec les clés suivantes :

Clé	Description	Exemples de valeurs
dbEngine	Le type de moteur de base de données	postgres_tcp
sqlDialect	Le dialecte SQL à utiliser	postgres
dsn	Le nom de la source de données (chaîne de connexion) de la base de données	Consultez les exemples ci-dessous

Exemple : utiliser un backend PostgreSQL

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

Exemple : utiliser l'interface PostgreSQL de Databricks

Databricks expose une interface compatible PostgreSQL qui peut servir de backend SQL à StackQL. Le DSN utilise le format standard des chaînes de connexion PostgreSQL avec vos identifiants Databricks :

./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

remarque

Les caractères spéciaux du nom d'utilisateur ou du mot de passe (tels que @) doivent être encodés pour URL dans le DSN (par exemple, @ devient %40).