Opciones globales

Las opciones globales especifican el comportamiento del programa en tiempo de ejecución para la aplicación StackQL; estas opciones se establecen en la línea de comandos al iniciar la aplicación StackQL (ya sea en el modo interactivo/shell o en el modo exec no interactivo) o se cargan desde el archivo de inicialización de StackQL (.stackqlrc). Las opciones incluyen:

Opción	Tipo de datos	Descripción	Valor predeterminado
--access.config	string	Configuración de acceso de los llamadores, un sobre JSON {"path": "/path/to/access.json"} (también se acepta solo la ruta del archivo). Habilita la gestión de accesos: los llamadores se autentican mediante JWT, token bearer estático, TLS mutuo o identidad local del SO, y las instrucciones se autorizan según reglas de política. Las credenciales de token locales se leen de STACKQL_CALLER_TOKEN. Disponible a partir de StackQL v1.0.
--acid	string	Cadena JSON / YAML que representa la configuración ACID	{}
--allow-persistent-secrets	flag	Permite que una sesión seleccione un almacén de secretos persistente del sistema operativo (macOS Keychain, Linux Secret Service o Windows Credential Manager) con SET "$.secret_store". Los almacenes de archivo plano se rechazan incluso con la opción. Consulte Sesiones de provider y secretos. Disponible a partir de StackQL v1.0.	false
--allow-secret-dereference	flag	Permite desreferenciar los valores de secretos y credenciales en expresiones SQL ("$secrets.name", "$auth.provider.field"), con la consecuencia de que pueden acabar en los resultados, los logs y los artefactos de consulta persistidos. No es necesaria para la autenticación normal de los providers. Consulte Valores de secretos en SQL. Disponible a partir de StackQL v1.0.	false
--apirequesttimeout	integer	Tiempo de espera de las solicitudes a la API en segundos, 0 para no aplicar tiempo de espera	45
--approot	string	Ruta raíz de la configuración y la caché de la aplicación	{cwd}/.stackql
--approotfilemode	uint32	Modo de archivo de la configuración y la caché de la aplicación	493
--auth	string	Pares clave-valor del contexto auth en formato json
--cachekeycount	integer	Número inicial de claves de la caché	100
--configfile	string	Ruta completa del archivo de configuración	{cwd}/.stackqlrc
--cpuprofile	string	Archivo cpuprofile, ninguno si está vacío	null
--dataflow.dependency.max	int	Profundidad máxima de dependencias del flujo de datos para una consulta determinada	50
--dataflow.components.max	int	Número máximo de componentes débilmente conexos del flujo de datos para una consulta determinada	50
--dbInternal	string	Cadena JSON / YAML para configurar el tratamiento de las consultas de mantenimiento interno del SGBD	{}
-d, --delimiter	string	Delimitador para la salida csv. Un solo carácter. Se ignora para toda salida que no sea csv	,
--dryrun	flag	Opción dryrun; solo se ejecuta el preprocesador y se devuelve la salida generada a partir de la plantilla	false
--env.file	string	Archivo opcional de estilo dotenv que se carga en el entorno del proceso al iniciar (todos los comandos); la herramienta MCP reload_credentials lo vuelve a cargar bajo demanda. Se tolera que el archivo no exista; las claves con valores vacíos se omiten; las variables existentes se sobrescriben. No se carga desde .stackqlrc. Disponible en las versiones de StackQL posteriores a v0.10.542.	null
--execution.concurrency.limit	int	Límite de concurrencia para la ejecución de consultas	1
--export.alias	string	Prefijo de alias de exportación (espacio de nombres o esquema)
--gc	string	Cadena JSON / YAML que representa la configuración de GC	{}
-H, --hideheaders	flag	Deshabilita los encabezados de columna, válido solo con --output csv o --output text	false
--http.log.enabled	flag	Muestra la información de las solicitudes http en el terminal	false
--http.proxy.host	string	Host del proxy (déjelo en blanco para no usar proxy)	null
--http.proxy.password	string	Contraseña del proxy	null
--http.proxy.port	integer	Puerto del proxy; cualquier número menor o igual que 0 da como resultado el puerto predeterminado del esquema correspondiente (p. ej., http -> 80)	-1
--http.proxy.scheme	string	Esquema del proxy, http o https	http
--http.proxy.user	string	Usuario del proxy	null
--http.response.maxResults	integer	Número máximo de resultados por solicitud http; cualquier número menor o igual que 0 implica que no hay límite	-1
--http.response.pageLimit	integer	Número máximo de páginas de resultados que se devuelven por recurso; cualquier número menor o igual que 0 implica que no hay límite	20
--indirect.depth.max	integer	Profundidad máxima de las consultas indirectas: vistas y subconsultas	5
-i, --infile	string	Archivo de entrada (archivo IQL) del que se leen las consultas	{stdin}
-q, --iqldata	string	Archivo de contexto (datos) para el uso de plantillas (archivo json o jsonnet)
--loglevel	string	Nivel de log, debe ser uno de fatal	fatal
--mcp.config	string	Objeto de configuración JSON / YAML para el servidor MCP (stackql mcp y stackql srv)	{}
--mcp.log.format	string	Codificación del log de auditoría de MCP, jsonl u otel (registros de log OTLP/JSON); tiene prioridad sobre server.audit.format en --mcp.config. Consulte Formato del log. Disponible a partir de StackQL v0.11.660.	jsonl
--mcp.protocol.version	string	Revisión más reciente del protocolo MCP que se anuncia, auto, 2026-07-28 (solo sin sesión) o una revisión anterior como 2025-11-25; tiene prioridad sobre server.protocol_version en --mcp.config. Consulte Fijar la revisión. Disponible a partir de StackQL v0.12.732.	auto
--mcp.server.type	string	Tipo de servidor MCP, uno de reverse_proxy. Consulte Tipo de servidor MCP.	http
--metadatattl	integer	TTL de los documentos de metadatos en caché, en segundos	3600
--namespaces	string	Cadena JSON / YAML que representa los espacios de nombres para la caché, las vistas, etc.	{}
--offline	flag	Trabaja sin conexión, con datos en caché	false
-f, --outfile	string	Archivo de salida en el que se escriben los resultados	{stdout}
-o, --output	string	Formato de salida, debe ser uno de otel (ndjson se acepta como alias de jsonl). otel emite registros de log de OpenTelemetry, consulte Modos de salida; disponible a partir de StackQL v0.11.660. Con un exportador configurado en --otel.config, los registros otel también se envían a ese endpoint	table
--otel.config	string	Cadena JSON / YAML que configura el formato de salida otel; exporter.endpoint, exporter.headers, exporter.timeout_ms y exporter.batch_size envían los registros a un endpoint de logs OTLP/HTTP, consulte Enviar a un endpoint OTLP. Disponible a partir de StackQL v0.12.732	{}
--preview	string	Cadena JSON que habilita la funcionalidad en versión preliminar. {"unstable": true} expone las relaciones stackql_unstable_<provider>.<service>.<resource> basadas en documentos, que omnisdk resuelve y ejecuta directamente a partir de los documentos de provider, con las filas transmitidas a medida que se producen; las claves restantes (batchSize, flushInterval, endpoint, insecureSkipTLSVerify) ajustan ese backend. La funcionalidad en versión preliminar no es estable: el comportamiento, la sintaxis y la salida pueden cambiar o dejar de funcionar entre versiones sin previo aviso, así que no dependa de ella en producción. A partir de v1.0, la misma activación explícita expone las relaciones stackql_preview.iac.run y stackql_preview.iac.destroy, que aplican y eliminan un conjunto de recursos declarado mediante omnisdk, con el estado guardado en la raíz de la aplicación. Consulte Funcionalidad en versión preliminar	{}
--querycachesize	integer	Tamaño, en número de entradas, de la caché LRU para los planes de consulta	10000
--registry	string	Cadena JSON / YAML que configura la ubicación del registro de providers y la verificación de firmas de los documentos de provider	consulte --registry
--session	string	Cadena JSON / YAML que representa la configuración de la sesión	{}
--sqlBackend	string	Cadena JSON / YAML que representa la configuración del sistema de backend SQL	consulte --sqlBackend
--store.txn	string	Cadena JSON / YAML que representa la configuración del almacén de transacciones	{}
--tls.CABundle	string	Ruta del bundle de CA; si no se especifica, se usan los valores predeterminados del sistema
--tls.allowInsecure	flag	Permite confiar en certificados no seguros (no recomendado)
--var	string	Variables externas proporcionadas como pares clave/valor para cargarlas en las consultas de StackQL mediante archivos de datos jsonnet
-v, --verbose	flag	Salida detallada	false
-h, --help		Ayuda contextual de stackql
--version		Muestra la versión del programa StackQL

--registry

La opción --registry configura de dónde se leen los documentos de provider y si se verifican sus firmas. El valor es una cadena JSON con las siguientes claves:

Clave	Descripción	Valor predeterminado
url	URL del registro. Si se omite, se usa el registro de providers público de StackQL.	registro público
localDocRoot	Un directorio local que contiene documentos de provider, que se leen en lugar de descargarlos del registro. Se usa al desarrollar un provider.
srcPrefix	Prefijo de ruta bajo la raíz del registro donde se encuentran los documentos de origen de los providers.	src
verifyConfig.nopVerify	true omite la verificación de firmas. Establézcalo en false para exigir una firma ML-DSA-65 (FIPS 204) integrada en cada documento de provider y de servicio que se lea, incluidas las relaciones en versión preliminar basadas en documentos.	true
verifyConfig.publicKeys	Un objeto JSON que asigna ID de clave a claves públicas ML-DSA-65 codificadas en hexadecimal, para registros privados. Sustituye a las claves de producción integradas; un objeto vacío explícito es un error.	claves integradas

Ejemplo: exigir documentos de provider firmados

Activa la verificación para cada documento de provider y de servicio que se lee del registro público, que se comprueba con las claves de producción integradas:

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

Ejemplo: leer documentos sin firmar desde un directorio local

Apunta el registro a un directorio de documentos de provider en desarrollo. Esos documentos no están firmados, por lo que la verificación permanece desactivada:

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

nota

La verificación de firmas está disponible a partir de StackQL v1.0 y está desactivada de forma predeterminada. Las firmas cubren los bytes YAML exactos de un documento, por lo que cualquier modificación, incluido un cambio de formato o de salto de línea, las invalida; vuelva a firmar con la herramienta pqsig sign-doc del registro. Los documentos locales de desarrollo sin firmar deben mantener nopVerify: true. Las antiguas opciones de certificado y los archivos sidecar .sig ya no se usan, y los archivos comprimidos publicados solo con sidecars deben volver a publicarse antes de usarlos con verificación. La verificación autentica los documentos cuando se leen; la descarga y la extracción de los archivos comprimidos no están cubiertas.

--sqlBackend

La opción --sqlBackend configura un backend SQL externo para StackQL, lo que le permite usar un motor de base de datos externo (como PostgreSQL) en lugar del motor SQL integrado predeterminado. Esto resulta útil para aprovechar una base de datos externa para el procesamiento de consultas, el almacenamiento persistente o la integración con una infraestructura de bases de datos existente.

El valor es una cadena JSON con las siguientes claves:

Clave	Descripción	Valores de ejemplo
dbEngine	El tipo de motor de base de datos	postgres_tcp
sqlDialect	El dialecto SQL que se va a usar	postgres
dsn	El nombre del origen de datos (cadena de conexión) de la base de datos	Consulte los ejemplos siguientes

Ejemplo: usar un backend PostgreSQL

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

Ejemplo: usar la interfaz PostgreSQL de Databricks

Databricks expone una interfaz compatible con PostgreSQL que se puede usar como backend SQL de StackQL. El DSN usa el formato estándar de cadena de conexión de PostgreSQL con sus credenciales de 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

nota

Los caracteres especiales del nombre de usuario o de la contraseña (como @) deben codificarse como URL en el DSN (p. ej., @ se convierte en %40).