creating-database-migrations

name: creating-database-migrations description: Use when adding or editing Nango database migrations - covers migration directory selection, timestamped .cjs naming, matching recent migration style, down migration decisions, and foreign key ON DELETE conventions.

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:

   <YYYYMMDDHHMMSS>_<description>.cjs
   

   Example:

   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.