Цю сторінку перекладено з англійської мови за допомогою ШІ. Якщо тексти відрізняються, еталоном є англійська версія.
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, транспорт 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=>