Esta página foi traduzida do inglês com assistência de IA. Se houver diferenças entre as duas, a versão em inglês é a referência.
srv
Comando usado para iniciar o StackQL como serviço, que pode então ser acessado por clientes do protocolo de comunicação do Postgres autenticados com mTLS. O comando srv também pode executar um servidor Model Context Protocol (MCP) junto com o servidor do protocolo de comunicação do PostgreSQL, o que permite o acesso pelos dois protocolos tanto a clientes de banco de dados tradicionais quanto a agentes de IA.
Sintaxe
stackql srv [server_options] [flags]
Embora o servidor do StackQL use o protocolo de comunicação do Postgres, ele não é um servidor Postgres nem precisa de um. O cliente usa o protocolo de comunicação para se comunicar com o servidor, que usa o StackQL para executar consultas ou operações DML em provedores remotos de nuvem e de SaaS e retornar os resultados ao cliente.
Os parâmetros enviados pelo protocolo de consulta estendido (Parse / Bind / Execute, como usado pelo psycopg 3, pelo pgx e pelo JDBC) são vinculados no lado do servidor como literais de string. A partir da v0.12.742, um placeholder $n dentro de um literal de string, de um identificador entre aspas ou de um comentário não é alterado, as barras invertidas nos valores dos parâmetros são escapadas e um valor de texto NULL continua sendo a string NULL (o NULL do SQL é transmitido separadamente).
Opções do servidor
| Opção | Descrição |
|---|---|
--pgsrv.address | Endereço em que o servidor escuta (normalmente 0.0.0.0) |
--pgsrv.port | Porta em que o servidor escuta (por exemplo, 5444) |
--pgsrv.tls | Objeto de configuração do mTLS; consulte o exemplo abaixo |
--pgsrv.loglevel | Nível de log (valor padrão: WARN) |
consulte Opções globais para ver outras opções
Opções do servidor MCP
Ao executar o comando srv com suporte a MCP, as seguintes opções adicionais estão disponíveis:
| Opção | Descrição |
|---|---|
--mcp.server.type | Tipo de servidor MCP: http (em memória) ou reverse_proxy (baseado em TCP) |
--mcp.config | Objeto de configuração JSON do servidor MCP (consulte a documentação do MCP) |
--mcp.log.format | Codificação do log de auditoria do MCP: jsonl (padrão) ou otel (registros de log OTLP/JSON); substitui server.audit.format no objeto de configuração |
--mcp.protocol.version | Revisão mais recente do protocolo MCP anunciada: auto (padrão), 2026-07-28 (somente sem sessão) ou uma revisão mais antiga, como 2025-11-25; substitui server.protocol_version no objeto de configuração |
A partir da v0.12.742, o transporte HTTP do MCP (--mcp.server.type=http ou reverse_proxy) se recusa a iniciar, a menos que o objeto de configuração indique um token bearer com server.auth_token_env_var ou dispense explicitamente a autenticação com "allow_unauthenticated": true. Consulte Autenticação de clientes HTTP.
Consulte a documentação do comando MCP para obter informações detalhadas sobre como configurar e usar o servidor MCP, incluindo modos de implantação, opções de configuração e integração com assistentes de IA.
Você precisa definir as variáveis de ambiente necessárias para a autenticação do provider antes de iniciar o servidor; consulte Usar um provider para obter mais informações.
Para servidores de longa duração, a opção --env.file permite criar ou rotacionar as credenciais em um arquivo no estilo dotenv no disco antes da inicialização, em vez de exportar variáveis no shell:
stackql srv --pgsrv.port 5444 --env.file /etc/stackql/credentials.env
Para o stackql srv, o arquivo é lido uma vez na inicialização; para recarregar as credenciais no meio da sessão, use a ferramenta MCP reload_credentials.
Opções
| Opção | Descrição |
|---|---|
-H,--help | Exibe as informações de ajuda |
-v,--verbose | Executa consultas no modo detalhado, com saída adicional enviada para stdout; se a opção -f for selecionada,essas informações adicionais de log são gravadas no arquivo de saída junto com os resultados da consulta |
consulte Opções globais para ver outras opções
Exemplos
Inicie um processo do servidor do StackQL e conecte-se a ele com um cliente de linha de comando psql.
Primeiro, baixe o arquivo de configuração openssl.cnf de stackql/stackql.
Em seguida, gere os arquivos de certificado e de chave que o servidor e o cliente vão usar para a autenticação TLS mútua (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
Agora defina as variáveis de ambiente; se o cliente e o servidor estiverem no mesmo host, elas podem ser compartilhadas.
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
Configure um objeto de autenticação para cada provider ao qual o servidor precisará ter acesso, por exemplo, para o GitHub.
export STACKQL_GITHUB_USERNAME=youruser
export STACKQL_GITHUB_PASSWORD=ghp_youraccesstoken
Agora inicie o servidor em um terminal.
stackql srv \
--pgsrv.address=0.0.0.0 \
--pgsrv.port=$PGPORT \
--pgsrv.tls='{ "keyFilePath": "'${PGSSLSRVKEY}'", "certFilePath": "'${PGSSLROOTCERT}'", "clientCAs": [ "'${CLIENT_CERT}'" ] }'
Em outro terminal, conecte-se ao servidor com o cliente de linha de comando psql.
psql 127.0.0.1
Agora execute uma consulta do StackQL em um provider autenticado.
psql (12.11 (Ubuntu 12.11-0ubuntu0.20.04.1), server 0.0.0)
Type "help" for help.
127.0.0.1=> SHOW SERVICES IN github LIKE '%repos%';
id | name | title
--------------+-------+----------------------------
repos:v0.3.3 | repos | GitHub v3 REST API - repos
(1 row)
127.0.0.1=>