Every persistent database change requires a new SeaORM migration. While editing past migrations, is discouraged, it is acceptable only to migrations that were created since the last release tag (vX.X.X).
Use the repository recipe rather than invoking the CLI directly:
just add-migration add_widget_enabled
The recipe generates a migration under src/leicmin/src/data/migrations/ and adds its module to src/leicmin/src/data/migrations/mod.rs. Verify both changes.
The generated migration implements up and down methods. Edit the generated m*.rs file and perform the operations there. Use the built-in SeaORM migration API whenever possible.
Prefer SeaORM builders such as create_table, alter_table, and Index::create. Use execute_unprepared only for PostgreSQL operations that SeaORM cannot express, such as guarded enum changes.
Ordering and compatibility
Migrations run in the order listed by Migrator::migrations() in migrations/mod.rs. Add a migration at the end; do not reorder existing migrations.
When possible, try to avoid operations that both create and drop tables and structures in a single step. It is better to create and populate structures in one migration, then use a second to drop the old structures. That way, if populating the data causes a foreign key to fail, the code will stop at that migration instead of also destroying existing data.
Migration tracking means up normally runs once. Guards are appropriate for operations that must tolerate a partially initialized PostgreSQL object, but an existing object with an incompatible definition should cause a clear failure.
Rollbacks
Implement down when the change can be reversed without guessing or silently destroying data. For irreversible changes, make down an explicit no-op and explain why in a comment. Examples include deleting user data, adding a PostgreSQL enum value, or inserting required seed rows that the application must retain.
Migrations should only be run once and ideally everyone will create backups of their data, so there doesn't have to be an expectation that a migration will be called repeatedly without a rollback.