---
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.
title: creating-database-migrations
canonical_url: https://skilld.dev/gh/nangohq/nango/creating-database-migrations
last_updated: 2026-09-23T16:45:57.000Z
---

> **Skill from skilld.dev.** Follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install nangohq/nango/creating-database-migrations`. Install writes the Skill files into the project, so every session loads them.

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