Цю сторінку перекладено з англійської мови за допомогою ШІ. Якщо тексти відрізняються, еталоном є англійська версія.
Глобальні прапорці
Команди StackQL приймають глобальні прапорці, але деякі з них діють лише в певному режимі. Вказуйте їх у командному рядку або, де це підтримується, у файлі ініціалізації StackQL (.stackqlrc). Прапорці --pgsrv.* перелічено в розділі Параметри сервера PostgreSQL.
| Прапорець | Тип даних | Опис | За замовчуванням |
|---|---|---|---|
--access.config | string | Конфігурація доступу сторін, що викликають, у вигляді обгортки JSON {"path": "/path/to/access.json"} (простий шлях до файлу також приймається). Вмикає керування доступом: сторони, що викликають, автентифікуються за JWT, статичним токеном bearer, взаємним TLS або ідентичністю локальної ОС, а інструкції авторизуються за правилами політики. Локальні облікові дані у вигляді токенів зчитуються з STACKQL_CALLER_TOKEN. Доступно в StackQL v1.0 і новіших версіях. | |
--allow-persistent-secrets | flag | Дозволяє сеансу вибрати постійне сховище секретів ОС (macOS Keychain, Linux Secret Service або Windows Credential Manager) за допомогою SET "$.secret_store". Сховища у вигляді простих файлів відхиляються навіть із цим прапорцем. Див. Сеанси провайдерів і секрети. Доступно в StackQL v1.0 і новіших версіях. | false |
--allow-secret-dereference | flag | Дозволяє розіменування значень секретів і облікових даних у виразах SQL ("$secrets.name", "$auth.provider.field"), унаслідок чого вони можуть потрапити в результати, журнали та збережені артефакти запитів. Не потрібен для звичайної автентифікації провайдерів. Див. Значення секретів у SQL. Доступно в StackQL v1.0 і новіших версіях. | false |
--apirequesttimeout | integer | Час очікування запиту до API в секундах, 0 - без обмеження часу очікування | 45 |
--approot | string | Кореневий шлях для конфігурації та кешу застосунку | {cwd}/.stackql |
--approotfilemode | uint32 | Режим файлів конфігурації та кешу застосунку | 493 |
--auth | string | Пари "ключ-значення" контексту auth у форматі json | |
--cachekeycount | integer | Початкова кількість ключів кешу | 100 |
--configfile | string | Повний шлях до файлу конфігурації | {cwd}/.stackqlrc |
--cpuprofile | string | Файл cpuprofile; якщо порожньо, не використовується | null |
--dataflow.dependency.max | int | Максимальна глибина залежностей потоку даних для одного запиту | 50 |
--dataflow.components.max | int | Максимальна кількість слабко зв'язних компонентів потоку даних для одного запиту | 50 |
--dbInternal | string | Рядок JSON / YAML для налаштування обробки службових запитів СКБД | {} |
-d, --delimiter | string | Роздільник для виводу csv. Лише один символ. Ігнорується для всіх форматів виводу, крім csv | , |
--dryrun | flag | Прапорець dryrun; виконується лише препроцесор, повертається вивід, сформований із шаблону | false |
--env.file | string | Необов'язковий файл у стилі dotenv, який завантажується в середовище процесу під час запуску (для всіх команд); інструмент MCP reload_credentials повторно завантажує його на вимогу. Відсутність файлу допускається; ключі з порожніми значеннями пропускаються; наявні змінні перезаписуються. Не зчитується з .stackqlrc. Доступно у випусках StackQL після v0.10.542. | null |
--execution.concurrency.limit | int | Обмеження паралельності під час виконання запитів | 1 |
--export.alias | string | Префікс псевдоніма експорту (простір імен або схема) | |
--gc | string | Рядок JSON / YAML з конфігурацією GC | {} |
-H, --hideheaders | flag | Вимикає заголовки стовпців, діє лише з --output csv або --output text | false |
--http.log.enabled | flag | Відображати відомості про запити HTTP у терміналі | false |
--http.proxy.host | string | Хост проксі (залиште порожнім, щоб не використовувати проксі) | null |
--http.proxy.password | string | Пароль проксі | null |
--http.proxy.port | integer | Порт проксі; будь-яке число, що не перевищує 0, означає порт за замовчуванням для відповідної схеми (наприклад, http -> 80) | -1 |
--http.proxy.scheme | string | Схема проксі, http або https | http |
--http.proxy.user | string | Користувач проксі | null |
--http.response.maxResults | integer | Максимальна кількість результатів на один запит HTTP; будь-яке число, що не перевищує 0, означає відсутність обмеження | -1 |
--http.response.pageLimit | integer | Максимальна кількість сторінок результатів, що повертаються для одного ресурсу; будь-яке число, що не перевищує 0, означає відсутність обмеження | 20 |
--indirect.depth.max | integer | Максимальна глибина непрямих запитів: подань і підзапитів | 5 |
-i, --infile | string | Вхідний файл (файл IQL), з якого зчитуються запити | {stdin} |
-q, --iqldata | string | Файл контексту (даних) для шаблонізації (файл json або jsonnet) | |
--loglevel | string | Рівень журналювання, має бути одним із {panic, fatal, error, warn, info, debug, trace} (warning приймається як псевдонім для warn) | fatal |
--mcp.config | string | Об'єкт конфігурації JSON / YAML для сервера MCP (stackql mcp і stackql srv) | {} |
--mcp.log.format | string | Кодування журналу аудиту MCP, jsonl або otel (записи журналу OTLP/JSON); перевизначає server.audit.format у --mcp.config. Див. Формат журналу. Доступно в StackQL v0.11.660 і новіших версіях. | jsonl |
--mcp.protocol.version | string | Найновіша ревізія протоколу MCP, яку оголошує сервер: auto, 2026-07-28 (лише в режимі без сеансу) або старіша ревізія, наприклад 2025-11-25; перевизначає server.protocol_version у --mcp.config. Див. Закріплення ревізії. Доступно в StackQL v0.12.732 і новіших версіях. | auto |
--mcp.server.type | string | Тип сервера MCP, одне зі значень {http, stdio, reverse_proxy}. Див. Тип сервера MCP. | http |
--metadatattl | integer | TTL кешованих документів метаданих, у секундах | 3600 |
--namespaces | string | Рядок JSON / YAML, що описує простори імен для кешування, подань тощо | {} |
--offline | flag | Працювати офлайн, використовуючи кешовані дані | false |
-f, --outfile | string | Файл виводу, у який записуються результати | {stdout} |
-o, --output | string | Формат виводу, має бути одним із {json, jsonl, table, csv, text, otel} (ndjson приймається як псевдонім для jsonl). Формат otel видає записи журналу OpenTelemetry, див. Режими виводу; доступно в StackQL v0.11.660 і новіших версіях. Якщо в --otel.config налаштовано експортер, записи otel також надсилаються до цієї кінцевої точки | table |
--otel.config | string | Рядок JSON / YAML, що налаштовує формат виводу otel; exporter.endpoint, exporter.headers, exporter.timeout_ms і exporter.batch_size керують надсиланням записів до кінцевої точки журналів OTLP/HTTP, див. Надсилання до кінцевої точки OTLP. Доступно в StackQL v0.12.732 і новіших версіях | {} |
--preview | string | Рядок JSON, що вмикає можливості попередньої версії. {"unstable": true} відкриває відношення stackql_unstable_<provider>.<service>.<resource>, засновані на документах: omnisdk визначає та виконує їх безпосередньо з документів провайдерів, передаючи рядки потоком у міру їх отримання; решта ключів (batchSize, flushInterval, endpoint, insecureSkipTLSVerify) налаштовують цей бекенд. Можливості попередньої версії нестабільні: поведінка, синтаксис і вивід можуть змінитися або перестати працювати між випусками без попередження, тому не покладайтеся на них у робочому середовищі. Починаючи з v1.0, те саме явне ввімкнення відкриває відношення stackql_preview.iac.run і stackql_preview.iac.destroy, які застосовують і знищують оголошений набір ресурсів через omnisdk, зберігаючи стан у кореневому каталозі застосунку. Див. Можливості попередньої версії | {} |
--provider | string | Початковий провайдер за замовчуванням. Наприклад, із --provider github ім'я repos.repos відповідає github.repos.repos без попередньої інструкції USE. Не виконує автентифікації для провайдера. | немає |
--querycachesize | integer | Розмір кешу LRU для планів запитів, у кількості записів | 10000 |
--registry | string | Рядок JSON / YAML, що налаштовує розташування реєстру провайдерів і перевірку підписів документів провайдерів | див. --registry |
--session | string | Рядок JSON / YAML з конфігурацією сеансу | {} |
--sqlBackend | string | Рядок JSON / YAML з конфігурацією системи бекенду SQL | див. --sqlBackend |
--store.txn | string | Рядок JSON / YAML з конфігурацією сховища Txn | {} |
--tls.CABundle | string | Шлях до пакета CA; якщо не вказано, використовуються системні значення за замовчуванням | |
--tls.allowInsecure | flag | Дозволити довіру до незахищених сертифікатів (не рекомендовано) | |
--upstream.errors | string | Політика JSON / YAML для явного допущення статусів відповідей HTTP під час читання з провайдерів. Див. --upstream.errors. | {} |
--var | string | Зовнішні змінні у вигляді пар "ключ-значення" для підстановки в запити StackQL через файли даних jsonnet | |
-v, --verbose | flag | Докладний вивід | false |
-h, --help | Контекстна довідка для stackql | ||
--version | Відображає версію програми StackQL |
Прапорець --colorscheme застарілий і більше не змінює кольори оболонки. Прапорець --usenonpreferredapis приймається, але в поточному рушії не впливає на вибір API.
--registry
Прапорець --registry налаштовує, звідки зчитуються документи провайдерів і чи перевіряються їхні підписи. Значення - це рядок JSON з такими ключами:
| Ключ | Опис | За замовчуванням |
|---|---|---|
url | URL реєстру. Якщо не вказано, використовується публічний реєстр провайдерів StackQL. | публічний реєстр |
localDocRoot | Локальний каталог із документами провайдерів, які зчитуються замість завантаження з реєстру. Використовується під час розробки провайдера. | |
srcPrefix | Префікс шляху в корені реєстру, за яким розташовані вихідні документи провайдерів. | src |
verifyConfig.nopVerify | Значення true вимикає перевірку підписів. Встановіть false, щоб вимагати вбудований підпис ML-DSA-65 (FIPS 204) для кожного зчитаного документа провайдера та сервісу, зокрема для відношень попередньої версії, заснованих на документах. | true |
verifyConfig.publicKeys | Об'єкт JSON, що зіставляє ідентифікатори ключів із відкритими ключами ML-DSA-65 у шістнадцятковому кодуванні, для приватних реєстрів. Він замінює вбудовані робочі ключі; явно вказаний порожній об'єкт є помилкою. | вбудовані ключі |
Приклад: вимога підписаних документів провайдерів
Вмикає перевірку для кожного документа провайдера та сервісу, зчитаного з публічного реєстру, за вбудованими робочими ключами:
stackql --registry '{"verifyConfig": {"nopVerify": false}}' shell
Приклад: зчитування непідписаних документів із локального каталогу
Спрямовує реєстр на каталог документів провайдерів, що перебувають у розробці. Ці документи не підписані, тому перевірка залишається вимкненою:
stackql --registry '{"localDocRoot": "/path/to/provider-dev/openapi", "verifyConfig": {"nopVerify": true}}' shell
Перевірка підписів доступна в StackQL v1.0 і новіших версіях і за замовчуванням вимкнена. Підписи охоплюють точні байти YAML документа, тому будь-яке редагування, зокрема зміна форматування або символів нового рядка, робить їх недійсними; підпишіть документ повторно за допомогою інструмента реєстру pqsig sign-doc. Для непідписаних локальних документів у розробці потрібно залишати nopVerify: true. Колишні параметри сертифікатів і файли sidecar .sig більше не використовуються, а архіви, опубліковані лише з файлами sidecar, потрібно опублікувати повторно, перш ніж використовувати їх із перевіркою. Перевірка автентифікує документи під час їх зчитування; завантаження та розпакування архівів не охоплюються.
--sqlBackend
Прапорець --sqlBackend налаштовує зовнішній бекенд SQL для StackQL, що дає змогу використовувати зовнішній рушій бази даних (наприклад, PostgreSQL) замість вбудованого рушія SQL за замовчуванням. Це корисно, якщо потрібно використовувати зовнішню базу даних для обробки запитів, постійного зберігання або інтеграції з наявною інфраструктурою баз даних.
Значення - це рядок JSON з такими ключами:
| Ключ | Опис | Приклади значень |
|---|---|---|
dbEngine | Тип рушія бази даних | postgres_tcp |
sqlDialect | Діалект SQL, який слід використовувати | postgres |
dsn | Ім'я джерела даних (рядок підключення) для бази даних | Див. приклади нижче |
Приклад: використання бекенду PostgreSQL
./stackql \
--sqlBackend='{"dbEngine": "postgres_tcp", "sqlDialect": "postgres", "dsn": "postgres://user:password@hostname:port/dbname?sslmode=require"}' \
shell
Приклад: використання інтерфейсу PostgreSQL у Databricks
Databricks надає сумісний із PostgreSQL інтерфейс, який можна використовувати як бекенд SQL для StackQL. DSN використовує стандартний формат рядка підключення PostgreSQL з вашими обліковими даними Databricks:
./stackql \
--sqlBackend='{"dbEngine": "postgres_tcp", "sqlDialect": "postgres", "dsn": "postgres://user%40domain.com:your-access-token@your-databricks-host.cloud.databricks.com/databricks_postgres?sslmode=require"}' \
shell
Спеціальні символи в імені користувача або паролі (наприклад, @) мають бути закодовані для URL у DSN (наприклад, @ стає %40).
--upstream.errors
За допомогою http.ignoreStatusCodes перелічіть статуси відповідей HTTP, які читання з провайдера має явно допускати. Записи є рядковими значеннями: використовуйте точний код, як-от "503", або клас, як-от "5xx". Значення за замовчуванням {} не додає жодних винятків до звичайної обробки відповідей upstream у рушії. Це налаштування не виконує повторних спроб для невдалих запитів і не застосовується до змінення даних або обміну даними автентифікації.
Проігнорована відповідь не додає рядків. Інші операції читання в запиті все одно можуть повертати рядки, тому успішний запит може повернути неповні результати. StackQL повідомляє про проігнорований статус HTTP як діагностичне повідомлення.
Наприклад, цей параметр використовує тест з'єднання з імітованим GitHub:
stackql exec --upstream.errors='{"http":{"ignoreStatusCodes":["5xx"]}}' \
"SELECT r.name, c.login FROM github.repos.repos r
JOIN github.repos.collaborators c ON c.repo = r.name
WHERE r.org = 'example-org' AND c.owner = 'example-org'
ORDER BY r.name;"
У тесті запит до API на отримання співавторів одного репозиторію повертає HTTP 500. Запит однаково повертає рядки співавторів для інших репозиторіїв, а stderr містить ignoring upstream response: 500 INTERNAL SERVER ERROR. Якщо очікується лише одна помилка, віддавайте перевагу точному коду статусу.