CLI: create a custom SQL migration

A custom migration is needed when a schema change alone is insufficient. For example, you added heading and want to fill it from the former title. Admingen creates a SQL file with the next number in the shared system/generated/custom sequence; you write the queries inside it.

Create and register a file

admingen-cli migration create --project ./docs-demo --name backfill_article_heading

The same invocation with the global path parameter:

admingen-cli --path ./docs-demo migration create --name backfill_article_heading

The result contains a number and a path such as backend/migrations/custom/NNNNNN_custom_backfill_article_heading.sql. The file is immediately registered in backend/migrations/manifest.json; separate accept/register steps are unnecessary.

The command does not connect to the database or execute SQL. From the generated application root, use the short form:

make migration-new NAME=backfill_article_heading

Write SQL and apply the migration

1. Open the created file and backend/migrations/custom/README.md.
2. Write SQL for the actual schema. In the example, fill heading from title before deleting title.
3. Save SQL and the migration manifest in version control.
4. Apply migrations from the application directory:

cd docs-demo
make migrate

The next generation accounts for the occupied number. After application, do not edit the SQL or renumber the file. Create a subsequent migration for a correction. Previously registered custom files retain their paths.

Validate database constraints

make constraints-list, make constraint-validate NAME=... and make constraints-validate belong to the generated application. They list and validate constraints, but do not repair data violating them.

The meaning of migrate --check and --verify, and the diagnostic sequence, are covered in migrations and constraints. Other maintenance operations are described in application commands.