본문으로 건너뛰기
번역된 페이지

이 페이지는 AI의 도움을 받아 영어에서 번역되었습니다. 두 내용이 다를 경우 영어 버전을 기준으로 합니다.

srv

StackQL을 서비스로 시작하는 데 사용하는 명령입니다. 시작된 서비스에는 mTLS로 인증된 Postgres 와이어 프로토콜 클라이언트로 액세스할 수 있습니다. srv 명령은 PostgreSQL 와이어 프로토콜 서버와 함께 Model Context Protocol (MCP) 서버도 실행할 수 있으므로, 기존 데이터베이스 클라이언트와 AI 에이전트 모두에 이중 프로토콜 액세스를 제공합니다.


구문​

stackql srv [server_options] [flags]


노트

StackQL 서버는 Postgres 와이어 프로토콜을 사용하지만 Postgres 서버가 아니며, Postgres 서버가 필요하지도 않습니다. 와이어 프로토콜은 클라이언트가 서버와 통신하는 데 사용됩니다. 서버는 StackQL을 사용하여 원격 클라우드 및 SaaS 제공업체에 대해 쿼리 또는 DML 작업을 수행하고 결과를 클라이언트에 반환합니다.

확장 쿼리 프로토콜(psycopg 3, pgx, JDBC에서 사용하는 Parse / Bind / Execute)로 전송된 매개 변수는 서버 측에서 문자열 리터럴로 바인딩됩니다. v0.12.742부터 문자열 리터럴, 따옴표로 묶은 식별자 또는 주석 안의 $n 자리 표시자는 그대로 유지되고, 매개 변수 값의 백슬래시는 이스케이프되며, NULL이라는 텍스트 값은 문자열 NULL로 유지됩니다(SQL NULL은 별도로 전달됩니다).

서버 옵션​

옵션설명
--pgsrv.address서버가 수신 대기하는 주소(일반적으로 0.0.0.0)
--pgsrv.port서버가 수신 대기하는 포트(예: 5444)
--pgsrv.tlsmTLS 구성 객체(아래 예제 참조)
--pgsrv.loglevel로그 수준(기본값 WARN)

추가 옵션은 전역 플래그를 참조하세요.

MCP 서버 옵션​

MCP 지원과 함께 srv 명령을 실행하는 경우 다음 추가 옵션을 사용할 수 있습니다:

옵션설명
--mcp.server.typeMCP 서버 유형: http(인메모리) 또는 reverse_proxy(TCP 기반)
--mcp.configMCP 서버의 JSON 구성 객체(MCP 문서 참조)
--mcp.log.formatMCP 감사 로그 인코딩: jsonl(기본값) 또는 otel(OTLP/JSON 로그 레코드). 구성 객체의 server.audit.format 설정을 재정의합니다.
--mcp.protocol.version서버가 알리는 최신 MCP 프로토콜 리비전: auto(기본값), 2026-07-28(세션 없는 방식 전용) 또는 2025-11-25 같은 이전 리비전. 구성 객체의 server.protocol_version 설정을 재정의합니다.

v0.12.742의 호환성이 손상되는 변경

v0.12.742부터 MCP HTTP 전송 방식(--mcp.server.type=http 또는 reverse_proxy)은 구성 객체가 server.auth_token_env_var 키로 Bearer 토큰을 지정하거나 "allow_unauthenticated": true 설정으로 명시적으로 옵트아웃하지 않으면 시작되지 않습니다. HTTP 클라이언트 인증을 참조하세요.

팁

배포 모드, 구성 옵션, AI 어시스턴트와의 통합을 포함하여 MCP 서버의 구성 및 사용에 대한 자세한 내용은 MCP 명령 문서를 참조하세요.

정보

서버를 시작하기 전에 프로바이더 인증에 필요한 환경 변수를 설정하세요. 자세한 내용은 프로바이더 사용을 참조하세요.

장기 실행 서버의 경우 --env.file 플래그를 사용하면 셸로 변수를 내보내는 대신 시작 전에 디스크의 dotenv 스타일 파일에 자격 증명을 작성하거나 교체할 수 있습니다:

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

stackql srv 명령의 경우 파일은 시작 시 한 번만 읽힙니다. 세션 도중에 다시 로드하려면 MCP reload_credentials 도구를 사용합니다.

플래그​

플래그설명
-H,--help도움말 정보 출력
-v,--verbose상세 모드로 쿼리를 실행하며 추가 출력은 stdout으로 전송됩니다. -f 옵션을 선택한 경우
이 추가 로깅 정보는 쿼리 결과와 함께 출력 파일에 기록됩니다.

추가 옵션은 전역 플래그를 참조하세요.


예제​

StackQL 서버 프로세스를 시작하고 psql 명령줄 클라이언트로 연결합니다.

먼저 stackql/stackql에서 openssl.cnf 구성 파일을 다운로드합니다.

다음으로 서버와 클라이언트가 상호 TLS 인증(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

이제 환경 변수를 설정합니다. 클라이언트와 서버가 같은 호스트에 있으면 이 환경 변수를 공유할 수 있습니다.

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

서버가 액세스해야 하는 각 프로바이더(예: GitHub)에 대한 인증 객체를 설정합니다.

export STACKQL_GITHUB_USERNAME=youruser
export STACKQL_GITHUB_PASSWORD=ghp_youraccesstoken

이제 한 터미널에서 서버를 시작합니다.

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

다른 터미널에서 psql 명령줄 클라이언트를 사용하여 서버에 연결합니다.

psql 127.0.0.1

이제 인증된 프로바이더에 대해 StackQL 쿼리를 실행합니다.

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=>