# Opções globais

> Opções globais do binário stackql: autenticação, formato de saída, local do registro, logs e configurações do backend SQL, disponíveis em todos os comandos.

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

As opções globais especificam o comportamento do programa em tempo de execução para a aplicação StackQL; essas opções são definidas na linha de comando quando a aplicação StackQL é iniciada (no modo interativo/shell ou no modo exec não interativo) ou são obtidas do arquivo de inicialização do StackQL ([`.stackqlrc`](/getting-started/using-stackql#the-stackqlrc-initialization-file)).  As opções incluem:  

| Opção | Tipo de dados | Descrição | Valor padrão |
| -- | -- | -- | -- |
| `--access.config` | string | Configuração de acesso de chamadores, um envelope JSON `{"path": "/path/to/access.json"}` (um caminho de arquivo simples também é aceito).  Habilita o [gerenciamento de acesso](/command-line-usage/access-management): os chamadores são autenticados por JWT, token bearer estático, TLS mútuo ou identidade local do SO, e as instruções são autorizadas com base em regras de política.  As credenciais de token locais são lidas de `STACKQL_CALLER_TOKEN`.  Disponível a partir do StackQL `v1.0`. | |
| `--acid` | string | String JSON / YAML que representa a configuração ACID | `{}` |
| `--allow-persistent-secrets` | flag | Permite que uma sessão selecione um repositório de segredos persistente do SO (macOS Keychain, Linux Secret Service ou Windows Credential Manager) com `SET "$.secret_store"`.  Repositórios em arquivo simples são recusados mesmo com a opção.  Consulte [Sessões de provider e segredos](/getting-started/provider-sessions#persistent-os-secret-stores).  Disponível a partir do StackQL `v1.0`. | `false` |
| `--allow-secret-dereference` | flag | Permite que valores de segredos e de credenciais sejam desreferenciados em expressões SQL (`"$secrets.name"`, `"$auth.provider.field"`), com a consequência de que eles podem aparecer em resultados, logs e artefatos de consulta persistidos.  Não é necessária para a autenticação normal de providers.  Consulte [Valores de segredos no SQL](/getting-started/provider-sessions#secret-values-in-sql).  Disponível a partir do StackQL `v1.0`. | `false` |
| `--apirequesttimeout` | integer | Tempo limite das solicitações de API em segundos, 0 para nenhum tempo limite | `45` |
| `--approot` | string | Caminho raiz da configuração e do cache da aplicação | `{cwd}/.stackql` |
| `--approotfilemode` | uint32 | Modo de arquivo da configuração e do cache da aplicação | `493` |
| `--auth` | string | Pares chave-valor do contexto `auth` em formato json |  |
| `--cachekeycount` | integer | Número inicial de chaves do cache | `100` |
| `--configfile` | string | Caminho completo do arquivo de configuração | `{cwd}/.stackqlrc` |
| `--cpuprofile` | string | Arquivo `cpuprofile`, nenhum se vazio | `null` |
| `--dataflow.dependency.max` | int | Profundidade máxima de dependências do fluxo de dados para uma determinada consulta | `50` |
| `--dataflow.components.max` | int | Número máximo de componentes fracamente conexos do fluxo de dados para uma determinada consulta | `50` |
| `--dbInternal` | string | String JSON / YAML para configurar o tratamento das consultas de manutenção do SGBD | `{}` |
| `-d`, `--delimiter` | string | Delimitador para a saída csv. Somente um caractere.  Ignorado em todas as saídas que não sejam csv | `,` |
| `--dryrun` | flag | Opção `dryrun`; executa somente o pré-processador, e a saída processada pelo template é retornada | `false` |
| `--env.file` | string | Arquivo opcional no estilo dotenv carregado no ambiente do processo na inicialização (todos os comandos); a ferramenta MCP [`reload_credentials`](/mcp/reload_credentials) o carrega novamente sob demanda. Um arquivo ausente é tolerado; chaves com valores vazios são ignoradas; variáveis existentes são sobrescritas. Não é carregado a partir do `.stackqlrc`. Disponível nas versões do StackQL posteriores à `v0.10.542`. | `null` |
| `--execution.concurrency.limit` | int | Limite de concorrência para a execução de consultas | `1` |
| `--export.alias` | string | Prefixo de alias de exportação (namespace ou esquema) | |
| `--gc` | string | String JSON / YAML que representa a configuração de GC | `{}` |
| `-H`, `--hideheaders` | flag | Desabilita os cabeçalhos de coluna, válido somente com `--output csv` ou `--output text` | `false` |
| `--http.log.enabled` | flag | Exibe informações das solicitações http no terminal | `false` |
| `--http.proxy.host` | string | Host do proxy (deixe em branco para não usar proxy) | `null` |
| `--http.proxy.password` | string | Senha do proxy | `null` |
| `--http.proxy.port` | integer | Porta do proxy; qualquer número menor ou igual a 0 resulta na porta padrão do esquema em questão (por exemplo, `http -> 80`) | `-1` |
| `--http.proxy.scheme` | string | Esquema do proxy, `http` ou `https` | `http` |
| `--http.proxy.user` | string | Usuário do proxy | `null` |
| `--http.response.maxResults` | integer | Número máximo de resultados por solicitação http; qualquer número menor ou igual a 0 remove a limitação | `-1` |
| `--http.response.pageLimit` | integer | Número máximo de páginas de resultados retornadas por recurso; qualquer número menor ou igual a 0 remove a limitação | `20` |
| `--indirect.depth.max` | integer | Profundidade máxima para consultas indiretas: views e subconsultas | `5` |
| `-i`, `--infile` | string | Arquivo de entrada (arquivo IQL) do qual as consultas são lidas | `{stdin}` |
| `-q`, `--iqldata` | string | Arquivo de contexto (dados) para o uso de templates (arquivo `json` ou `jsonnet`)| |
| `--loglevel` | string | Nível de log, deve ser um de  | `fatal` |
| `--mcp.config` | string | Objeto de configuração JSON / YAML do [servidor MCP](/command-line-usage/mcp#mcp-configuration-object) (`stackql mcp` e `stackql srv`) | `{}` |
| `--mcp.log.format` | string | Codificação do log de auditoria do MCP, `jsonl` ou `otel` (registros de log OTLP/JSON); substitui `server.audit.format` em `--mcp.config`.  Consulte [Formato do log](/command-line-usage/mcp#log-format).  Disponível a partir do StackQL `v0.11.660`. | `jsonl` |
| `--mcp.protocol.version` | string | Revisão mais recente do protocolo MCP anunciada: `auto`, `2026-07-28` (somente sem sessão) ou uma revisão mais antiga, como `2025-11-25`; substitui `server.protocol_version` em `--mcp.config`.  Consulte [Fixar a revisão](/command-line-usage/mcp#pinning-the-revision).  Disponível a partir do StackQL `v0.12.732`. | `auto` |
| `--mcp.server.type` | string | Tipo de servidor MCP, um de .  Consulte [Tipo de servidor MCP](/command-line-usage/mcp#mcp-server-type). | `http` |
| `--metadatattl` | integer | TTL dos documentos de metadados em cache, em segundos | `3600` |
| `--namespaces` | string | String JSON / YAML que representa namespaces para cache, views etc | `{}` |
| `--offline` | flag | Trabalha offline, usando dados em cache | `false` |
| `-f`, `--outfile` | string | Arquivo de saída no qual os resultados são gravados | `{stdout}` |
| `-o`, `--output` | string | Formato de saída, deve ser um de  (`ndjson` é aceito como alias de `jsonl`).  `otel` emite registros de log do OpenTelemetry, consulte [Modos de saída](/getting-started/output-modes#otel-output); disponível a partir do StackQL `v0.11.660`.  Com um exportador configurado em `--otel.config`, os registros `otel` também são enviados para esse endpoint | `table` |
| `--otel.config` | string | String JSON / YAML que configura o formato de saída `otel`; `exporter.endpoint`, `exporter.headers`, `exporter.timeout_ms` e `exporter.batch_size` enviam os registros para um endpoint de logs OTLP/HTTP, consulte [Enviar para um endpoint OTLP](/getting-started/output-modes#pushing-to-an-otlp-endpoint).  Disponível a partir do StackQL `v0.12.732` | `{}` |
| `--preview` | string | String JSON que habilita funcionalidades em versão prévia.  `{"unstable": true}` expõe as relações `stackql_unstable_<provider>.<service>.<resource>` orientadas por documentos, que o `omnisdk` resolve e executa diretamente a partir dos documentos de provider, com as linhas transmitidas à medida que são produzidas; as demais chaves (`batchSize`, `flushInterval`, `endpoint`, `insecureSkipTLSVerify`) ajustam esse backend.  As funcionalidades em versão prévia não são estáveis: o comportamento, a sintaxe e a saída podem mudar ou deixar de funcionar entre versões sem aviso prévio, portanto não dependa delas em produção.  A partir da `v1.0`, a mesma ativação explícita expõe as relações `stackql_preview.iac.run` e `stackql_preview.iac.destroy`, que aplicam e desmontam um conjunto declarado de recursos por meio do `omnisdk`, com o estado mantido na raiz da aplicação.  Consulte [Funcionalidades em versão prévia](https://github.com/stackql/stackql/blob/main/docs/preview.md) | `{}` |
| `--querycachesize` | integer | Tamanho, em número de entradas, do cache LRU de planos de consulta | `10000` |
| `--registry` | string | String JSON / YAML que configura o local do registro de providers e a verificação de assinatura dos documentos de provider | consulte [`--registry`](#--registry) |
| `--session` | string | String JSON / YAML que representa a configuração da sessão | `{}` |
| `--sqlBackend` | string | String JSON / YAML que representa a configuração do sistema de backend SQL | consulte [`--sqlBackend`](#--sqlbackend) |
| `--store.txn` | string | String JSON / YAML que representa a configuração do armazenamento de transações | `{}` |
| `--tls.CABundle` | string | Caminho para o bundle de CAs; se não for especificado, os padrões do sistema são usados |  |
| `--tls.allowInsecure` | flag | Permite confiar em certificados inseguros (não recomendado) |  |
| `--var` | string | Variáveis externas fornecidas como pares chave-valor para uso em consultas do StackQL por meio de arquivos de dados `jsonnet` |  |
| `-v`, `--verbose` | flag | Saída detalhada | `false` |
| `-h`, `--help` | | Ajuda contextual do stackql | |
| `--version` | | Exibe a versão do programa StackQL | |

## `--registry`

A opção `--registry` configura de onde os documentos de provider são lidos e se as assinaturas deles são verificadas.  O valor é uma string JSON com as seguintes chaves:

| Chave | Descrição | Valor padrão |
| -- | -- | -- |
| `url` | URL do registro.  Quando ela é omitida, o StackQL usa o registro público de providers do StackQL. | registro público |
| `localDocRoot` | Um diretório local com documentos de provider, lidos no lugar do download a partir do registro.  Usado ao [desenvolver um provider](/developers/developing-stackql-providers#testing-a-provider-locally). | |
| `srcPrefix` | Prefixo de caminho, sob a raiz do registro, onde ficam os documentos de origem dos providers. | `src` |
| `verifyConfig.nopVerify` | `true` ignora a verificação de assinatura.  Defina como `false` para exigir uma assinatura ML-DSA-65 (FIPS 204) incorporada em todos os documentos de provider e de serviço lidos, incluindo as relações em versão prévia baseadas em documentos. | `true` |
| `verifyConfig.publicKeys` | Um objeto JSON que mapeia IDs de chave para chaves públicas ML-DSA-65 codificadas em hexadecimal, para registros privados.  Ele substitui as chaves de produção incorporadas; um objeto vazio explícito é um erro. | chaves incorporadas |

### Exemplo: exigir documentos de provider assinados

Ativa a verificação para todos os documentos de provider e de serviço lidos do registro público, com as chaves de produção incorporadas:

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

### Exemplo: ler documentos não assinados de um diretório local

Aponta o registro para um diretório de documentos de provider em desenvolvimento.  Esses documentos não são assinados, portanto a verificação permanece desativada:

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

:::note

A verificação de assinatura está disponível a partir do StackQL `v1.0` e vem desativada por padrão.  As assinaturas cobrem os bytes YAML exatos de um documento, portanto qualquer edição, incluindo uma alteração de formatação ou de quebra de linha, as invalida; assine novamente com a ferramenta `pqsig sign-doc` do registro.  Documentos de desenvolvimento locais não assinados devem manter `nopVerify: true`.  As antigas opções de certificado e os arquivos sidecar `.sig` não são mais usados, e os arquivos compactados publicados somente com sidecars precisam ser publicados novamente antes do uso com verificação.  A verificação autentica os documentos quando eles são lidos; o download e a extração de arquivos compactados não estão cobertos.

:::

## `--sqlBackend`

A opção `--sqlBackend` configura um backend SQL externo para o StackQL, o que permite usar um mecanismo de banco de dados externo (como o PostgreSQL) em vez do mecanismo SQL incorporado padrão. Isso é útil para aproveitar um banco de dados externo no processamento de consultas, no armazenamento persistente ou na integração com uma infraestrutura de banco de dados existente.

O valor é uma string JSON com as seguintes chaves:

| Chave | Descrição | Valores de exemplo |
| -- | -- | -- |
| `dbEngine` | O tipo de mecanismo de banco de dados | `postgres_tcp` |
| `sqlDialect` | O dialeto SQL a ser usado | `postgres` |
| `dsn` | O nome da fonte de dados (string de conexão) do banco de dados | Consulte os exemplos abaixo |

### Exemplo: usar um backend PostgreSQL

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

### Exemplo: usar a interface PostgreSQL do Databricks

O Databricks expõe uma interface compatível com PostgreSQL que pode ser usada como backend SQL do StackQL. O DSN usa o formato padrão de string de conexão do PostgreSQL com as suas credenciais do 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
Caracteres especiais no nome de usuário ou na senha (como `@`) devem ser codificados para URL no DSN (por exemplo, `@` se torna `%40`).
:::
