Custom SQL нужен для переноса существующих данных и собственной схемы, которую поддерживает ваша команда. Создание поля или связи стандартной сущности сначала настраивайте в Generator UI: произвольный SQL не меняет модель генератора.
Создать зарегистрированную миграцию
После первой успешной генерации выполните из корня созданного проекта:
make migration-new NAME=backfill_labels
Команда вызывает генератор CLI, резервирует следующий номер и выводит путь вида backend/migrations/custom/NNNNNN_custom_backfill_labels.sql. Откройте именно возвращённый файл и напишите SQL. Имя backfill_labels — пример названия задачи; замените его своим.
Команда одновременно регистрирует файл в backend/migrations/manifest.json. В Git добавьте и SQL, и изменённый inventory. Не создавайте нумерацию вручную и не кладите незарегистрированные SQL-файлы рядом с миграциями.
Пример переноса значения
Ниже схема примера, а не готовая команда для любой БД. TABLE_NAME и FIELD_NAME замените фактическими именами таблицы и поля из миграций своего проекта:
UPDATE "TABLE_NAME"
SET "FIELD_NAME" = 'new value'
WHERE "FIELD_NAME" IS NULL;
До применения проверьте условие WHERE и ожидаемое количество записей. Для обычной смены модели используйте поддерживаемый сценарий генератора; custom SQL сам не обновляет его schema baseline.
Применить изменения
Остановите писателей, если того требует ваша миграция, просмотрите SQL и выполните:
make migrate
Generated и custom-файлы используют общую последовательность. Применённый файл записывается с путём, номером и checksum в admingen_internal.schema_migrations. При ошибке выполнение останавливается; уже успешные шаги остаются применёнными.
После применения где-либо SQL больше не редактируют. Для исправления создайте следующий шаг. .down.sql не поддерживается, а rollback приложения не возвращает данные назад. Для возврата данных нужна подходящая резервная копия.
Перед дампом и переносом БД сначала примените недостающие локальные миграции через make migrate: набор миграций должен соответствовать переносимому исходному коду. Подробнее: Миграции и Перенос данных.