Skip to main content

srv

Command used to launch StackQL as a service, which can then be accessed by Postgres wire protocol clients authenticated using mTLS. The srv command can also run a Model Context Protocol (MCP) server alongside the PostgreSQL wire protocol server, enabling dual-protocol access for both traditional database clients and AI agents.


Syntax​

stackql srv [server_options] [flags]


note

Although the StackQL server uses the Postgres wire protocol, it is not a Postgres server, nor does it require one. The wire protocol is used by the client to communicate with the server which uses StackQL to perform queries or DML operations against remote cloud and SaaS providers and return results back to the client.

Parameters sent over the extended query protocol (Parse / Bind / Execute, as used by psycopg 3, pgx and JDBC) are bound server side as string literals. From v0.12.742 a $n placeholder inside a string literal, quoted identifier or comment is left alone, backslashes in parameter values are escaped, and a text value of NULL stays the string NULL (SQL NULL is carried separately).

Server Options​

OptionDescriptionDefault
--pgsrv.addressAddress the server listens on.0.0.0.0
--pgsrv.portTCP port the server listens on.5466
--pgsrv.tlsJSON TLS configuration object. See the mTLS example below.none
--pgsrv.debug.enableEnable query debug output for PostgreSQL clients, for example with stackql srv --pgsrv.debug.enable=true. Leave off unless clients should receive debug information.false
--pgsrv.sundryAdvanced JSON or YAML mapping passed to the PostgreSQL wire server only when --pgsrv.tls is not set.{}
--pgsrv.loglevelAccepted but does not set the logger level in the current engine. Use --loglevel instead.WARN

see Global Flags for additional options

MCP Server Options​

When running the srv command with MCP support, the following additional options are available:

OptionDescription
--mcp.server.typeMCP server type: http (in-memory) or reverse_proxy (TCP-based)
--mcp.configJSON configuration object for the MCP server (see MCP documentation)
--mcp.log.formatMCP audit log encoding: jsonl (default) or otel (OTLP/JSON log records); overrides server.audit.format in the configuration object
--mcp.protocol.versionNewest MCP protocol revision advertised: auto (default), 2026-07-28 (sessionless only) or an older revision such as 2025-11-25; overrides server.protocol_version in the configuration object

Breaking change in v0.12.742

From v0.12.742 the MCP HTTP transport (--mcp.server.type=http or reverse_proxy) refuses to start unless the configuration object names a bearer token with server.auth_token_env_var or opts out explicitly with "allow_unauthenticated": true. See HTTP client authentication.

tip

See the MCP command documentation for detailed information on configuring and using the MCP server, including deployment modes, configuration options, and integration with AI assistants.

info

You need to set environment variables required for provider authentication before starting the server, see Using a Provider for more information.

For long-running servers, the --env.file flag lets you lay down or rotate credentials in a dotenv-style file on disk before startup rather than exporting variables into the shell:

stackql srv --pgsrv.port 5444 --env.file /etc/stackql/credentials.env

For stackql srv the file is read once at startup; the mid-session re-source path is the MCP reload_credentials tool.

Flags​

FlagDescription
-h,--helpPrint help information
-v,--verboseRun queries in verbose mode with additional output sent to stdout, if the global -f (--outfile) flag is set
this additional logging information will be written to the output file along with the query results

see Global Flags for additional options


Examples​

Launch a StackQL server process and connect using a psql command line client.

First download the openssl.cnf configuration file from stackql/stackql.

Next generate the certificate and key files to be used by the server and client for mutual TLS authentication (mTLS).

openssl req -x509 -keyout ~/stackqlcreds/server_key.pem -out ~/stackqlcreds/server_cert.pem -config ./openssl.cnf -days 365
openssl req -x509 -keyout ~/stackqlcreds/client_key.pem -out ~/stackqlcreds/client_cert.pem -config ./openssl.cnf -days 365
chmod 400 ~/stackqlcreds/client_key.pem

Now set environment variables, if the client and server are on the same host, these can be shared.

export PGPORT=5444
export PGSSLCERT=~/stackqlcreds/client_cert.pem
export PGSSLKEY=~/stackqlcreds/client_key.pem
export PGSSLROOTCERT=~/stackqlcreds/server_cert.pem
export PGSSLSRVKEY=~/stackqlcreds/server_key.pem
export CLIENT_CERT=$(base64 -w 0 ~/stackqlcreds/client_cert.pem)
export PGSSLMODE=allow

Set the credentials for the providers the server needs. For GitHub, the provider reads a username and a personal access token from these two variables:

export STACKQL_GITHUB_USERNAME=youruser
export STACKQL_GITHUB_PASSWORD=ghp_youraccesstoken

Now start the server in one terminal.

stackql srv \
--pgsrv.address=0.0.0.0 \
--pgsrv.port=$PGPORT \
--pgsrv.tls='{ "keyFilePath": "'${PGSSLSRVKEY}'", "certFilePath": "'${PGSSLROOTCERT}'", "clientCAs": [ "'${CLIENT_CERT}'" ] }'

In another terminal, connect to the server using the psql command line client.

psql -h 127.0.0.1 -d stackql

Now run a StackQL query against an authenticated provider.

psql (12.11 (Ubuntu 12.11-0ubuntu0.20.04.1), server 0.0.0)
Type "help" for help.

stackql=> SHOW SERVICES IN github LIKE '%repos%';
id | name | title
--------------+-------+----------------------------
repos:v0.3.3 | repos | GitHub v3 REST API - repos
(1 row)

stackql=>