Перейти до основного вмісту
Перекладена сторінка

Цю сторінку перекладено з англійської мови за допомогою ШІ. Якщо тексти відрізняються, еталоном є англійська версія.

srv

Команда для запуску StackQL як служби, до якої потім можуть звертатися клієнти мережевого протоколу Postgres, автентифіковані за допомогою mTLS. Команда srv також може запускати сервер Model Context Protocol (MCP) поряд із сервером мережевого протоколу PostgreSQL, що забезпечує доступ за двома протоколами як для традиційних клієнтів баз даних, так і для агентів ШІ.


Синтаксис​

stackql srv [server_options] [flags]


примітка

Хоча сервер StackQL використовує мережевий протокол Postgres, він не є сервером Postgres і не потребує його. Клієнт використовує мережевий протокол для зв'язку із сервером, який за допомогою StackQL виконує запити або операції DML щодо віддалених постачальників хмарних послуг і SaaS та повертає результати клієнтові.

Параметри, надіслані через розширений протокол запитів (Parse / Bind / Execute, як у psycopg 3, pgx і JDBC), прив'язуються на боці сервера як рядкові літерали. Починаючи з v0.12.742, заповнювач $n усередині рядкового літерала, ідентифікатора в лапках або коментаря залишається без змін, зворотні скісні риски в значеннях параметрів екрануються, а текстове значення NULL залишається рядком NULL (значення NULL у SQL передається окремо).

Параметри сервера​

ПараметрОписЗа замовчуванням
--pgsrv.addressАдреса, яку прослуховує сервер.0.0.0.0
--pgsrv.portПорт TCP, який прослуховує сервер.5466
--pgsrv.tlsОб'єкт конфігурації TLS у форматі JSON. Див. приклад mTLS нижче.немає
--pgsrv.debug.enableВмикає налагоджувальний вивід запитів для клієнтів PostgreSQL, наприклад stackql srv --pgsrv.debug.enable=true. Не вмикайте, якщо клієнти не повинні отримувати налагоджувальну інформацію.false
--pgsrv.sundryРозширене відображення JSON або YAML, що передається серверу мережевого протоколу PostgreSQL лише тоді, коли прапорець --pgsrv.tls не встановлено.{}
--pgsrv.loglevelПриймається, але не встановлює рівень журналювання в поточному рушії. Натомість використовуйте --loglevel.WARN

додаткові параметри див. на сторінці Глобальні прапорці

Параметри сервера MCP​

Під час запуску команди srv з підтримкою MCP доступні такі додаткові параметри:

ПараметрОпис
--mcp.server.typeТип сервера MCP: http (у пам'яті) або reverse_proxy (на основі TCP)
--mcp.configОб'єкт конфігурації сервера MCP у форматі JSON (див. документацію MCP)
--mcp.log.formatКодування журналу аудиту MCP: 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, транспорт HTTP для MCP (--mcp.server.type=http або reverse_proxy) не запускається, якщо в об'єкті конфігурації не вказано токен bearer через server.auth_token_env_var або автентифікацію не вимкнено явно за допомогою "allow_unauthenticated": true. Див. Автентифікація клієнтів HTTP.

порада

Докладні відомості про налаштування й використання сервера 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 (--outfile),
цю додаткову інформацію журналювання буде записано у файл виводу разом із результатами запитів

додаткові параметри див. на сторінці Глобальні прапорці


Приклади​

Запуск процесу сервера StackQL і підключення за допомогою клієнта командного рядка psql.

Спочатку завантажте файл конфігурації openssl.cnf з stackql/stackql.

Далі згенеруйте файли сертифікатів і ключів, які сервер і клієнт використовуватимуть для автентифікації за допомогою взаємного 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 -h 127.0.0.1 -d stackql

Тепер виконайте запит StackQL до автентифікованого провайдера.

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