srv

Comando que se usa para iniciar StackQL como servicio, al que después pueden acceder clientes del protocolo de red de Postgres autenticados mediante mTLS. El comando srv también puede ejecutar un servidor Model Context Protocol (MCP) junto con el servidor del protocolo de red de PostgreSQL, lo que permite el acceso mediante ambos protocolos tanto a clientes de bases de datos tradicionales como a agentes de IA.

---

Sintaxis

stackql srv [server_options] [flags]

---

nota

Aunque el servidor de StackQL usa el protocolo de red de Postgres, no es un servidor Postgres ni lo requiere. El cliente usa el protocolo de red para comunicarse con el servidor, que usa StackQL para realizar consultas u operaciones DML en providers remotos en la nube y de SaaS y devolver los resultados al cliente.

Los parámetros enviados mediante el protocolo de consulta extendido (Parse / Bind / Execute, como lo usan psycopg 3, pgx y JDBC) se vinculan en el servidor como literales de cadena. A partir de v0.12.742, un marcador de posición $n dentro de un literal de cadena, un identificador entre comillas o un comentario se deja intacto, las barras invertidas de los valores de parámetro se escapan y un valor de texto NULL sigue siendo la cadena NULL (el NULL de SQL se transmite por separado).

Opciones del servidor

Opción	Descripción
--pgsrv.address	Dirección en la que escucha el servidor (normalmente 0.0.0.0)
--pgsrv.port	Puerto en el que escucha el servidor (p. ej., 5444)
--pgsrv.tls	Objeto de configuración de mTLS, consulte el ejemplo siguiente
--pgsrv.loglevel	Nivel de log (valor predeterminado WARN)

consulte Opciones globales para ver opciones adicionales

Opciones del servidor MCP

Cuando se ejecuta el comando srv con compatibilidad con MCP, están disponibles las siguientes opciones adicionales:

Opción	Descripción
--mcp.server.type	Tipo de servidor MCP: http (en memoria) o reverse_proxy (basado en TCP)
--mcp.config	Objeto de configuración JSON para el servidor MCP (consulte la documentación de MCP)
--mcp.log.format	Codificación del log de auditoría de MCP: jsonl (valor predeterminado) u otel (registros de log OTLP/JSON); tiene prioridad sobre server.audit.format en el objeto de configuración
--mcp.protocol.version	Revisión más reciente del protocolo MCP que se anuncia: auto (valor predeterminado), 2026-07-28 (solo sin sesión) o una revisión anterior como 2025-11-25; tiene prioridad sobre server.protocol_version en el objeto de configuración

Cambio incompatible en v0.12.742

A partir de v0.12.742, el transporte HTTP de MCP (--mcp.server.type=http o reverse_proxy) se niega a iniciar a menos que el objeto de configuración indique un token bearer con server.auth_token_env_var o renuncie explícitamente a la autenticación con "allow_unauthenticated": true. Consulte Autenticación de clientes HTTP.

consejo

Consulte la documentación del comando MCP para obtener información detallada sobre la configuración y el uso del servidor MCP, incluidos los modos de despliegue, las opciones de configuración y la integración con asistentes de IA.

información

Debe establecer las variables de entorno necesarias para la autenticación de los providers antes de iniciar el servidor; para obtener más información, consulte Usar un provider.

Para los servidores de larga duración, la opción --env.file le permite colocar o rotar las credenciales en un archivo de estilo dotenv en disco antes del inicio, en lugar de exportar variables en el shell:

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

Para stackql srv, el archivo se lee una sola vez al iniciar; la vía para volver a cargarlo en mitad de la sesión es la herramienta MCP reload_credentials.

Opciones

Opción	Descripción
-H,--help	Muestra la información de ayuda
-v,--verbose	Ejecuta las consultas en modo detallado con salida adicional enviada a stdout; si se selecciona la opción -f, esta información de log adicional se escribe en el archivo de salida junto con los resultados de la consulta

consulte Opciones globales para ver opciones adicionales

---

Ejemplos

Iniciar un proceso de servidor de StackQL y conectarse a él con un cliente de línea de comandos psql.

Primero, descargue el archivo de configuración openssl.cnf de stackql/stackql.

A continuación, genere los archivos de certificado y de clave que usarán el servidor y el cliente para la autenticación TLS mutua (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

Ahora, establezca las variables de entorno; si el cliente y el servidor están en el mismo host, se pueden compartir.

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 un objeto de autenticación para los providers a los que el servidor necesite acceder, por ejemplo, para GitHub.

export STACKQL_GITHUB_USERNAME=youruser
export STACKQL_GITHUB_PASSWORD=ghp_youraccesstoken

Ahora, inicie el servidor en un terminal.

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

En otro terminal, conéctese al servidor con el cliente de línea de comandos psql.

psql 127.0.0.1

Ahora, ejecute una consulta de StackQL en un 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=>