AI Platform Docs

Канонический механизм

Alembic — единственный поддерживаемый способ создания и изменения схемы PostgreSQL Agent Registry. Приложение не вызывает SQLModel.metadata.create_all при запуске.

Garden и Helm запускают отдельное задание миграции до запуска процессов приложения. Проверка в начальном контейнере повторно подтверждает достигнутую версию. Оба действия используют транзакционную рекомендательную блокировку, поэтому параллельный запуск безопасно упорядочивается.

Low-code Runtime не имеет собственной изменяемой базы данных. База рабочих версий Low-code IDE принадлежит проекту-владельцу и должна иметь отдельный версионированный план миграции; ее нельзя изменять миграциями Agent Registry.

Последовательность версий

Порядок	Версия	Изменение	Риск понижения
1	`e298f58dfdac`	Создает каталог R1, наблюдения, протокольные проекции, аудит, транзакционную очередь и задания поиска	Удаляет всю схему R1 и все ее данные
2	`b41f876a08c2`	Добавляет `reindex_job.retired_generations` для учета прежних поколений OpenSearch	Удаляет поле и сохраненные в нем сведения
3	`d3f62e716ad4`	Добавляет `exposure` и `authorization` в `invocation_route_projection_state` и заполняет их для принятых маршрутов	Удаляет поля и их сохраненные значения
4	`f62a9b7c4d11`	Удаляет одноразовую схему R1 и создает каталог публикаций R2: `catalog_agent`, версии, навыки, интерфейсы, состояния наблюдений и проекций, outbox событий, аудит	Понижение не поддерживается — `downgrade()` вызывает `RuntimeError`; восстановление только из резервной копии до R2

Опубликованные исходные файлы:

Отдельные up.sql и down.sql не публикуются. Функции upgrade() и downgrade() находятся в одном версионированном исходном файле Alembic. Ручной SQL рядом создал бы второй источник истины.

Подготовка

Зафиксируйте текущую версию Alembic, идентификатор образа приложения и версию конфигурации.
Подтвердите свежую резервную копию PostgreSQL и возможность восстановления на отдельном экземпляре.
Проверьте свободное место, длительность блокировок и окно изменения.
Выполните alembic check на исходных файлах выпуска.
Примените миграции к базе той же основной версии PostgreSQL и сопоставимого объема данных.
Проверьте параллельный запуск двух заданий миграции.
На одноразовой копии проверьте сценарий ошибки и понижение обратимой части цепочки: f62a9b7c4d11 необратима, поэтому проверьте возврат до d3f62e716ad4 (и дальше при необходимости) и восстановление из резервной копии до R2.
Убедитесь, что образ, совместимый с фактической схемой, доступен для возврата, так как после f62a9b7c4d11 прежний образ не совместим со схемой R2 и откат только через резервную копию.
Сохраните очищенный отчет без строки подключения и учетных данных.

Применение

Штатно миграцию запускает Garden. Для проверки на изолированной одноразовой базе допустимы команды:

uv run alembic upgrade head uv run alembic current uv run alembic check

Ожидаемая текущая версия — f62a9b7c4d11.

После применения проверьте:

наличие ожидаемых таблиц, ограничений и индексов;
одновременную фиксацию изменения каталога и записи транзакционной очереди;
отсутствие частично примененной схемы;
готовность API и Kubernetes Reconciler;
публикацию и обработку контрольного события;
создание нового задания пересчета поиска;
на одноразовой базе успешный возврат совместимого образа (для f62a9b7c4d11 — через восстановление резервной копии до R2).

Ошибка миграции

Остановите продвижение новой версии.
Сохраните версию Alembic, очищенную ошибку базы, время и идентификатор задания.
Определите, была ли транзакция отменена полностью.
Верните образ приложения, совместимый с фактической схемой.
Не запускайте разрушительный SQL из интерактивного контейнера.
Не изменяйте таблицу версии Alembic вручную.
Используйте понижение только после проверки сохранности затронутых данных.
При повреждении восстановите резервную копию, затем повторите совместимое обновление на копии до возврата трафика.

Понижение версии

Миграция f62a9b7c4d11 необратима: ее downgrade() вызывает RuntimeError. Вернуться ниже f62a9b7c4d11 можно только восстановлением базы из резервной копии, сделанной до применения R2.

Команда для снятия только третьей миграции:

uv run alembic downgrade b41f876a08c2

Она удаляет поля exposure и authorization таблицы invocation_route_projection_state и их сохраненные значения.

Команда для снятия только второй миграции:

uv run alembic downgrade e298f58dfdac

Она удаляет retired_generations и его содержимое. До выполнения сохраните сведения о прежних поколениях OpenSearch, которые еще нужны для возврата.

Переход ниже e298f58dfdac удаляет всю схему R1 и не является обычным откатом приложения. Для общей или промышленной среды он требует явного разрешения человека, проверенной резервной копии, плана восстановления и окна недоступности.

Проверка после понижения

Подтвердите:

соответствие версии Alembic выбранному образу;
чтение канонических данных;
свежесть наблюдения Kubernetes;
правильную работу отношений SpiceDB;
сокращение транзакционной очереди;
сходимость активного поколения OpenSearch;
ответы защищенного API при разрешенном, запрещенном и недоступном SpiceDB;
отсутствие ручных изменений производных хранилищ.

План миграции Agent Registry