# Сеанси провайдерів і секрети

> Сеанси провайдерів у StackQL: псевдоніми з власними обліковими даними, tenancy і параметрами, перевизначення облікових даних і секрети в пам'яті сеансу або сховищі ОС.

Source: https://stackql.io/uk/getting-started/provider-sessions

Див. також:  
[[` SET `]](/language-spec/set) [[` UNSET `]](/language-spec/unset) [[ Змінні сеансу ]](/getting-started/session-variables) [[ Глобальні прапорці ]](/command-line-usage/global-flags)

Сеанс може прив'язати провайдера під псевдонімом із власними обліковими даними, міткою tenancy, значеннями параметрів за замовчуванням і обмеженнями паралельності запитів, тож в одному сеансі, і навіть в одній інструкції, можна виконувати запити до кількох облікових записів або тенантів того самого провайдера.  Поля облікових даних також можна перевизначити для сеансу, а секрети можна зберігати в пам'яті сеансу або, якщо оператор явно це ввімкне, у сховищі секретів операційної системи.  Усе це налаштовують інструкціями [`SET`](/language-spec/set) і [`UNSET`](/language-spec/unset); ці можливості доступні в StackQL `v1.0` і новіших версіях.

Усе, що тут описано, діє в межах поточного сеансу.  Незалежні з'єднання із сервером `stackql srv` не мають спільних прив'язок чи секретів, а кожен запит MCP є окремим сеансом, тому під час роботи із сервером MCP налаштовуйте й виконуйте запити в одному пакеті інструкцій.

## Псевдоніми провайдерів

Інструкція `SET "$.providers.<alias>"` прив'язує псевдонім до провайдера.  Значенням є документ JSON, записаний як рядок:

| Ключ | Обов'язковий | Опис |
|--|--|--|
| `provider` | Так | Канонічний провайдер, якому відповідає псевдонім, наприклад `aws`. |
| `tenancy` | Так | Мітка групування, наприклад назва облікового запису або тенанта.  StackQL не звіряє її з провайдером. |
| `auth` | Один із `auth` або `auth_secret` | Документ автентифікації з тією самою формою, що й запис провайдера в об'єкті [`--auth`](/command-line-usage/global-flags).  Псевдонім не запозичує облікові дані канонічного провайдера. |
| `auth_secret` | Один із `auth` або `auth_secret` | Ім'я [секрету сеансу](#session-secrets), що містить документ автентифікації. |
| `params` | Ні | Значення за замовчуванням для оголошених параметрів провайдера, зокрема оголошених параметрів сервера.  Предикат у запиті перевизначає значення за замовчуванням. |
| `tuning` | Ні | Обмеження `max_concurrent` і `max_per_host` для запитів псевдоніма.  Псевдоніми зі спільними провайдером і tenancy мають спільні обмеження й повинні оголошувати однакові параметри налаштування. |

У наступному прикладі два облікові записи AWS прив'язано до окремих псевдонімів, кожен із яких зчитує свої ключі зі змінних середовища з різними іменами, а потім до обох виконується запит в одній інструкції:

```sql
SET "$.providers.production" = '{
  "provider": "aws",
  "tenancy": "production-account",
  "auth": {
    "type": "aws_signing_v4",
    "access_key_id_env_var": "PRODUCTION_AWS_ACCESS_KEY_ID",
    "secret_access_key_env_var": "PRODUCTION_AWS_SECRET_ACCESS_KEY"
  },
  "params": {"region": "ap-southeast-2"},
  "tuning": {"max_concurrent": 4, "max_per_host": 4}
}';

SET "$.providers.development" = '{
  "provider": "aws",
  "tenancy": "development-account",
  "auth": {
    "type": "aws_signing_v4",
    "access_key_id_env_var": "DEVELOPMENT_AWS_ACCESS_KEY_ID",
    "secret_access_key_env_var": "DEVELOPMENT_AWS_SECRET_ACCESS_KEY"
  },
  "params": {"region": "ap-southeast-2"},
  "tuning": {"max_concurrent": 2}
}';

SELECT name, 'production' AS account FROM production.s3.buckets
UNION ALL
SELECT name, 'development' AS account FROM development.s3.buckets;
```

Посилання на змінні середовища визначаються із середовища процесу StackQL; локального середовища сеансу немає.  Для тимчасових облікових даних AWS також потрібне поле токена сеансу або посилання на відповідну змінну середовища.

Для інструкцій метаданих і даних псевдонім поводиться як його провайдер: `SHOW`, `DESCRIBE`, `SELECT`, `INSERT`, `UPDATE`, `DELETE` і `EXEC` приймають псевдонім замість імені провайдера.  Псевдоніми не поширюються на нативні вбудовані відношення та на відношення IaC, доступні як попередня версія.  Гілки `UNION ALL`, що використовують різні псевдоніми, виконуються послідовно.

Кожен запит бере незалежний знімок облікових даних псевдоніма.  Зміна прив'язки впливає на пізніші запити, а не на той, що вже виконується.  Інструкція `UNSET "$.providers.<alias>"` видаляє прив'язку.

## Перевизначення полів облікових даних

Інструкція `SET "$.auth.<provider>.<field>"` змінює для сеансу одне поле контексту автентифікації провайдера; імена полів - це ключі запису провайдера в `--auth`:

```sql
SET "$.auth.github.password_var" = 'GITHUB_TOKEN_READONLY';
SELECT name FROM github.repos.repos WHERE org = 'stackql';
UNSET "$.auth.github.password_var";
```

Як і з псевдонімами, зміна застосовується до запитів, запущених після `SET`.  Запити до провайдера, для автентифікації якого скасовано значення, або до провайдера, псевдонім якого не має придатного `auth`, завершуються помилкою ще до надсилання будь-якого запиту до API.

## Секрети сеансу

За замовчуванням кожен сеанс має сховище секретів лише в пам'яті, яке не потребує налаштування.  Інструкція `SET "$.secrets.<name>"` зберігає літеральний рядок, зазвичай документ автентифікації JSON, а псевдонім провайдера посилається на нього через `auth_secret`:

```sql
SET "$.secrets.production" = '{"type":"aws_signing_v4","access_key_id_env_var":"PRODUCTION_AWS_ACCESS_KEY_ID","secret_access_key_env_var":"PRODUCTION_AWS_SECRET_ACCESS_KEY"}';
SET "$.providers.production" = '{"provider":"aws","tenancy":"production-account","auth_secret":"production","params":{"region":"ap-southeast-2"}}';

SELECT name FROM production.s3.buckets;

UNSET "$.secrets.production";
```

Ротація секрету впливає на пізніші запити; після його видалення подальші спроби використання завершуються помилкою.  Новий сеанс отримує нове порожнє сховище, а завершення сеансу звільняє його.  Інструкція `UNSET "$.secret_store"` скидає поточну прив'язку сховища й починає знову з порожньою пам'яттю сеансу.

Звичайне використання облікових даних та інструкції `SET`, що зберігають змінні або конфігурацію, не записують секрети в бекенд SQL.  За розміщення конфіденційних даних у звичайній змінній або таблиці відповідає сторона, що викликає.

## Постійні сховища секретів ОС

Постійне зберігання за замовчуванням вимкнено, і ввімкнути його може лише оператор, запустивши StackQL із прапорцем `--allow-persistent-secrets`; SQL не може надати цю можливість.  Якщо прапорець встановлено, сеанс вибирає сховище ОС так:

```sql
SET "$.secret_store" = '{"backend": "os", "namespace": "stackql/provider-auth"}';
```

Сховищем є macOS Keychain, Linux Secret Service (`secret-tool` із робочою службою сеансу) або Windows Credential Manager.  Приймається лише бекенд `os`: сховища у звичайних файлах, шляхи до файлів і будь-який неявний резервний варіант із файлом відхиляються навіть зі встановленим прапорцем, а недоступний механізм ОС призводить до помилки замість переходу на файл.

Значення, записані у сховище ОС, існують і після завершення сеансу SQL; їх видаляють явно інструкцією `UNSET "$.secrets.<name>"`.  Скидання прив'язки сховища не видаляє вже збережені значення.  Доступ до сховища визначається ідентичністю процесу StackQL в операційній системі; простір імен не є механізмом керування доступом для окремих користувачів, тому не розглядайте це явне ввімкнення як багатокористувацьке сховище секретів.

## Значення секретів у SQL

Значення секретів ніколи не розіменовуються в SQL, якщо оператор не запустив StackQL із прапорцем `--allow-secret-dereference`.  З цим прапорцем посилання, як-от `"$secrets.production"`, `"$secrets.production.credentials"`, `"$auth.github.password"` і `"$providers.production.auth.credentials"`, визначаються у виразах:

```sql
SELECT upper("$secrets.production.credentials") AS credential;

/*
-- the same statement in a session started without --allow-secret-dereference
SELECT upper("$secrets.production.credentials") AS credential;
-- FAILS with secret variable dereferencing is disabled
*/
```

Якщо StackQL запущено без цього прапорця, ту саму інструкцію буде відхилено ще до обчислення будь-чого, як показує закоментована копія.  Прапорець є підтвердженням того, що явно розіменовані значення можуть потрапити в проміжне середовище SQL, результати, журнали та збережені артефакти запитів.  Для звичайної автентифікації провайдера він не потрібен.

## Дозволи

Якщо ввімкнено [керування доступом](/command-line-usage/access-management), для читання змінних і секретів потрібен дозвіл `session/variables:read`, а для `SET` або `UNSET` - `session/config:write`.  Перед виконанням визначений псевдонім авторизується як його канонічний провайдер.  Володіння й надання дозволів на рівні окремих змінних і секретів не реалізовано.
