Global Flags

Global flags specify runtime program behavior for the StackQL application, these flags are set at the command line when the StackQL application is launched (in either the interactive/shell mode or non-interactive exec mode) or are sourced from the StackQL initialization (.stackqlrc) file. Flags include:

Flag	Data Type	Description	Default
--acid	string	JSON / YAML string representing ACID config	{}
--apirequesttimeout	integer	API request timeout in seconds, 0 for no timeout	45
--approot	string	Application config and cache root path	{cwd}/.stackql
--approotfilemode	uint32	Application config and cache file mode	493
--auth	string	auth context keyvals in json form
--cachekeycount	integer	Cache initial key count	100
--configfile	string	Config file full path	{cwd}/.stackqlrc
--cpuprofile	string	cpuprofile file, none if empty	null
--dataflow.dependency.max	int	Maximum dataflow dependency depth for a given query	50
--dataflow.components.max	int	Maximum dataflow weakly connected components for a given query	50
--dbInternal	string	JSON / YAML string to configure DBMS housekeeping query handling	{}
-d, --delimiter	string	Delimiter for csv output. Single char only.  Ignored for all non-csv output	,
--dryrun	flag	dryrun flag; run preprocessor only, templated output will be returned	false
--execution.concurrency.limit	int	Concurrency limit for query execution	1
--export.alias	string	Export alias prefix (namespace or schema)
--gc	string	JSON / YAML string representing GC config	{}
-H, --hideheaders	flag	Disables column headers, valid only with --output csv or --output text	false
--http.log.enabled	flag	Display http request info in terminal	false
--http.proxy.host	string	Proxy host (leave blank for no proxy)	null
--http.proxy.password	string	Proxy password	null
--http.proxy.port	integer	Proxy port, any number less than or equal to 0 will result in the default port for a given scheme (e.g. http -> 80)	-1
--http.proxy.scheme	string	Proxy scheme, http or https	http
--http.proxy.user	string	Proxy user	null
--http.response.maxResults	integer	Maximum results per http request, any number less than or equal to 0 results in no limitation	-1
--http.response.pageLimit	integer	Maximum pages of results that will be returned per resource, any number less than or equal to results in no limitation	20
--indirect.depth.max	integer	Maximum depth for indirect queries: views and subqueries	5
-i, --infile	string	Input file (IQL file) from which queries are read	{stdin}
-q, --iqldata	string	Context (data) file for templating (json or jsonnet file)
--loglevel	string	Log level, must be one of fatal	fatal
--metadatattl	integer	TTL for cached metadata documents, in seconds	3600
--namespaces	string	JSON / YAML string representing namespaces for caching, views etc	{}
--offline	flag	Work offline, using cached data	false
-f, --outfile	string	Output file into which results are written	{stdout}
-o, --output	string	Output format, must be one of text	table
--querycachesize	integer	Size in number of entries of LRU cache for query plans	10000
--registry	string	openapi registry context keyvals in json form
--session	string	JSON / YAML string representing session config	{}
--sqlBackend	string	JSON / YAML string representing SQL Backend System Config	see --sqlBackend
--store.txn	string	JSON / YAML string representing Txn store config	{}
--tls.CABundle	string	Path to CA bundle, if not specified then system defaults used
--tls.allowInsecure	flag	Allow trust of insecure certificates (not recommended)
--var	string	External variables provided as key/value pairs for sourcing into StackQL queries through jsonnet data files
-v, --verbose	flag	Verbose output	false
-h, --help		Context specific help for stackql
--version		Displays the version of the StackQL program

--sqlBackend

The --sqlBackend flag configures an external SQL backend for StackQL, allowing you to use an external database engine (such as PostgreSQL) instead of the default embedded SQL engine. This is useful for leveraging an external database for query processing, persistent storage, or integration with existing database infrastructure.

The value is a JSON string with the following keys:

Key	Description	Example Values
dbEngine	The database engine type	postgres_tcp
sqlDialect	The SQL dialect to use	postgres
dsn	The data source name (connection string) for the database	See examples below

Example: Using a PostgreSQL Backend

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

Example: Using Databricks PostgreSQL Interface

Databricks exposes a PostgreSQL-compatible interface that can be used as a StackQL SQL backend. The DSN uses the standard PostgreSQL connection string format with your Databricks credentials:

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

Special characters in the username or password (such as @) must be URL-encoded in the DSN (e.g., @ becomes %40).