creating-database-migrations

# Creating Database Migrations ## Workflow 1. Identify the right migration directory. - Main database migrations live in `packages/database/lib/migrations/`. - Other services may have their own migration directories; use the directory for the service being changed. 2. Before writing a migration, read 2-3 recent migrations in the same directory and follow their style. 3. Name new main database migrations with the timestamped CommonJS format: ```text <YYYYMMDDHHMMSS>_<description>.cjs ``` Example: ```text 20260420120000_create_customer_keys.cjs ``` 4. Decide `exports.down` explicitly. - Ask the user whether rollback logic should be included or `exports.down` should be left empty. - If the user already specified rollback behavior, follow that direction. 5. Choose foreign key delete behavior from the relationship: - Use `ON DELETE CASCADE` for ownership relationships where the child cannot exist without the parent. - Use `ON DELETE SET NULL` for optional references where the child should survive parent deletion. - Check existing migrations for the closest matching relationship before choosing. ## Review Checklist - [ ] Migration is in the correct service migration directory. - [ ] Filename uses the timestamped `.cjs` migration format. - [ ] Style matches recent migrations in the same directory. - [ ] `exports.down` behavior was confirmed or explicitly requested. - [ ] Foreign keys use `CASCADE` for ownership and `SET NULL` for optional references.