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.

1. Before writing a migration, read 2-3 recent migrations in the same directory and follow their style.

1. Name new main database migrations with the timestamped CommonJS format:

``text <YYYYMMDDHHMMSS>_<description>.cjs ``

Example:

``text 20260420120000createcustomer_keys.cjs ``

1. 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.

1. 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.