Импорт из Hasura¶

Provisa может преобразовать существующие метаданные Hasura в Provisa config.yaml, сохраняя отслеживаемые таблицы, связи, разрешения и удалённые схемы.

Интерактивный импорт (Admin → Import Hasura Config)¶

Административная поверхность запускает те же конвертеры, поэтому импорт не требует доступа к оболочке и не требует прохождения через файл конфигурации туда-обратно. Требуется возможность (capability) org_settings; импорт попадает в организацию, от имени которой действует сессия.

Загрузка. Выберите заархивированный каталог метаданных Hasura v2, заархивированный проект DDN, консолидированный экспорт метаданных (.yaml/.json, включая конверт {resource_version, metadata}, который возвращает API метаданных), либо один файл .hml. Оставьте формат на Detect automatically, если только загружаемый файл не является неоднозначным.
Сопоставление доменов (необязательно). Каждая пара сопоставляет схему v2 или подграф DDN с доменом Provisa; всё, что не сопоставлено, сохраняет исходное имя.
Преобразование и предпросмотр. Сервер выполняет преобразование и возвращает счётчики, предупреждения конвертера и сгенерированную конфигурацию. На этом шаге ничего не записывается.
Проверка и редактирование. Конфигурацию можно редактировать на месте — реквизиты подключения, имена доменов, имена ролей. Применяется именно то, что показано.
Применение. Replace the existing semantic layer удаляет все источники, таблицы, роли и правила, отсутствующие в конфигурации; если этот флаг выключен, импорт объединяется с тем, что уже есть у организации. Применение загружает конфигурацию и перестраивает схемы организации.

Конечные точки: POST /admin/import/hasura/preview и POST /admin/import/hasura/apply.

Hasura v2¶

Экспорт метаданных¶

Из консоли Hasura или через CLI:

hasura metadata export --output metadata.yaml

Либо через API Hasura:

curl -X POST http://localhost:8080/v1/metadata \
  -H "X-Hasura-Admin-Secret: <secret>" \
  -d '{"type":"export_metadata","args":{}}' \
  > metadata.json

Преобразование¶

Конвертер v2 читает каталог метаданных Hasura (структуру, создаваемую командой hasura metadata export, либо плоскую структуру tables.yaml / actions.yaml) и записывает конфигурацию Provisa:

python -m provisa.hasura_v2 ./metadata -o config.yaml

Опустите -o, чтобы вывести конфигурацию в stdout.

Флаги:

Флаг	Назначение
`-o`, `--output`	Путь к выходному YAML-файлу (по умолчанию: stdout)
`--source-overrides`	YAML-файл с переопределениями подключения для отдельных источников (хост, порт, учётные данные)
`--domain-map`	Сопоставления «схема → домен» в виде пар `SCHEMA=DOMAIN`
`--auth-env-file`	Файл `.env` с конфигурацией аутентификации; преобразует JWT/JWK, admin secret и карту claims
`--dry-run`	Разобрать и провалидировать без записи результата

Что преобразуется¶

Понятие Hasura	Эквивалент в Provisa
Отслеживаемая таблица	`tables[]` с `publish: true`
Объектная связь (object relationship)	`relationships[]` с `cardinality: many-to-one`
Массивная связь (array relationship)	`relationships[]` с `cardinality: one-to-many`
Разрешение select	Видимость роли + фильтр RLS
Разрешение на колонку	`visible_to` / `writable_by`
Разрешение insert/update/delete	Mutation `writable_by` + RLS
Удалённая схема (remote schema)	Регистрация источника `graphql_remote`
Вычисляемое поле	Запись `functions[]` с `kind: query`

Ограничения¶

Actions преобразуются автоматически: action с HTTP-обработчиком становится mutation в webhooks[]; action с обработчиком не через HTTP (базой данных) становится заглушкой functions[] и выдаёт предупреждение о необходимости проверить обработчик
Event triggers преобразуются в конфигурацию event_triggers для каждой таблицы (операции, URL webhook, политика повторов) и выдают предупреждение об ограниченной точности преобразования
Remote schemas преобразуются в записи источника graphql_remote
Пользовательские SQL-функции требуют проверки — простые случаи преобразуются в записи functions[], сложные требуют ручной доработки
Cron-триггеры преобразуются в записи конфигурации scheduler, сохраняя cron-выражение и флаг enabled

Hasura DDN (v3)¶

Расположение проекта HML¶

Конвертер DDN читает каталог проекта DDN с файлами .hml напрямую — шаг сборки supergraph не требуется. Первый компонент пути под корнем проекта берётся как имя подграфа; файлы под globals/ относятся к подграфу globals.

Преобразование¶

python -m provisa.ddn ./my-ddn-project -o config.yaml

Опустите -o, чтобы вывести конфигурацию в stdout.

Флаги:

Флаг	Назначение
`-o`, `--output`	Путь к выходному YAML-файлу (по умолчанию: stdout)
`--source-overrides`	YAML-файл с переопределениями подключения для отдельных источников
`--domain-map`	Сопоставления «подграф → домен» в виде пар `SUBGRAPH=DOMAIN`
`--aggregates-output`	Путь для вспомогательного файла агрегатных выражений (по умолчанию: `<output>-aggregates.yaml`)
`--dry-run`	Разобрать и провалидировать без записи результата

Метаданные AggregateExpression сохраняются во вспомогательном файле *-aggregates.yaml.

Что преобразуется¶

Понятие DDN	Эквивалент в Provisa
Модель подграфа	`tables[]` внутри источника
Связь (relationship)	`relationships[]`
Правило разрешения	Фильтр RLS
Command	Mutation-webhook или представление
Коннектор	Запись источника с реквизитами подключения

Ограничения¶

Lambda-коннекторы (функции на TypeScript/Python) требуют ручной настройки webhook
Плагины жизненного цикла (lifecycle plugins) не имеют прямого эквивалента
Режимы аутентификации DDN сопоставляются с провайдерами аутентификации Provisa, но пути claim в JWT может потребоваться скорректировать

После импорта¶

Проверьте сгенерированный config.yaml — обратите внимание на warnings от конвертера
Проверьте учётные данные подключения (конвертер использует значения-заполнители)
Запустите Provisa и убедитесь, что таблицы отображаются в Explorer
Запустите существующие GraphQL-запросы — схема совместима для типовых паттернов
Прежде чем включать управление (governance) для продакшена, отправьте запросы на утверждение через Admin API или UI