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	Удаляет поле и сохраненные в нем сведения

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

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

Подготовка

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

Применение

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

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

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

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

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

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

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

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

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

uv run alembic downgrade e298f58dfdac

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

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

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

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

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

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