# Options globales

> Options globales du binaire stackql, disponibles sur toutes les commandes : authentification, format de sortie, emplacement du registre, journalisation et backend SQL.

Source: https://stackql.io/fr/command-line-usage/global-flags

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`](/getting-started/using-stackql#the-stackqlrc-initialization-file)).  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](/command-line-usage/access-management) : 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](/getting-started/provider-sessions#persistent-os-secret-stores).  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](/getting-started/provider-sessions#secret-values-in-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`](/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` |
| `--mcp.config` | string | Objet de configuration JSON / YAML du [serveur MCP](/command-line-usage/mcp#mcp-configuration-object) (`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](/command-line-usage/mcp#log-format).  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](/command-line-usage/mcp#pinning-the-revision).  Disponible à partir de StackQL `v0.12.732`. | `auto` |
| `--mcp.server.type` | string | Type de serveur MCP, l'un de .  Consultez [Type de serveur MCP](/command-line-usage/mcp#mcp-server-type). | `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  (`ndjson` est accepté comme alias de `jsonl`).  `otel` émet des enregistrements de journal OpenTelemetry, consultez [Modes de sortie](/getting-started/output-modes#otel-output) ; 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](/getting-started/output-modes#pushing-to-an-otlp-endpoint).  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](https://github.com/stackql/stackql/blob/main/docs/preview.md) | `{}` |
| `--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`](#--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`](#--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](/developers/developing-stackql-providers#testing-a-provider-locally). | |
| `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 :

```bash
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 :

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

:::note

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

```bash
./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 :

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

:::note
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`).
:::