Use custom SQL for data backfills and independent schema owned by your team. Configure ordinary generated entity fields and relationships in Generator UI first: arbitrary SQL does not change the generator's model.
Create a registered migration
After the first successful Generate, run from the generated project's root:
make migration-new NAME=backfill_labels
The command uses the generator CLI, reserves the next sequence and prints a path such as backend/migrations/custom/NNNNNN_custom_backfill_labels.sql. Edit the returned file. backfill_labels is an example task name; replace it with your own.
The same operation registers the path in backend/migrations/manifest.json. Commit both SQL and inventory. Do not allocate numbers manually or place unregistered SQL in the migrations tree.
Example backfill
This is a template, not a command for every database. Replace TABLE_NAME and FIELD_NAME with the physical names in your project's migrations:
UPDATE "TABLE_NAME"
SET "FIELD_NAME" = 'new value'
WHERE "FIELD_NAME" IS NULL;
Review WHERE and the expected row count before applying it. Use the supported generator workflow for ordinary model changes; custom SQL does not update the generated schema baseline.
Apply changes
Stop writers if your migration requires it, review the SQL and run:
make migrate
Generated and custom migrations share one sequence. Successful steps record their path, sequence and checksum in admingen_internal.schema_migrations. Execution stops at the first failed step; earlier successful files remain applied.
Once applied anywhere, do not edit the SQL. Add another migration to correct it. .down.sql is not supported, and application rollback does not restore database values. Data recovery requires a suitable backup.
Before dumping or transferring a database, apply pending local migrations with make migrate so the database matches the source being transferred. Continue with Migrations and Data transfer.