---
name: naming-conventions
description: Migration file naming rules — timestamp prefixes, descriptive suffixes, ordering
---

# Naming Conventions

## Purpose

Defines standard naming patterns for migration files across all supported tools. This skill ensures consistent, descriptive, and correctly ordered migration files.

---

## General Rules

1. **Use lowercase with underscores** for descriptions (snake_case)
2. **Be descriptive but concise**: Describe WHAT changes, not WHY
3. **Use verb prefixes**: `add_`, `drop_`, `rename_`, `alter_`, `create_`, `remove_`
4. **Include the table name** when the migration affects a single table
5. **Never use generic names** like `migration_1`, `update`, `fix`

---

## Tool-Specific Patterns

### Alembic

**Format:** `{revision_hash}_{description}.py`

The revision hash is auto-generated by Alembic. The description is provided by the user.

| Example | Description |
|---------|-------------|
| `a1b2c3d4_create_users_table.py` | Initial table creation |
| `e5f6g7h8_add_email_to_users.py` | Add column |
| `i9j0k1l2_drop_legacy_users_columns.py` | Remove columns |
| `m3n4o5p6_rename_orders_total_to_amount.py` | Rename column |
| `q7r8s9t0_add_index_on_orders_user_id.py` | Add index |

**Description rules for Alembic:**
- Max 60 characters for the description portion
- No spaces (use underscores)
- Alembic auto-generates the revision hash

### Prisma

**Format:** `{YYYYMMDDHHMMSS}_{description}/migration.sql`

| Example | Description |
|---------|-------------|
| `20240115120000_create_users_table/migration.sql` | Initial table |
| `20240120093000_add_email_to_users/migration.sql` | Add column |
| `20240201110000_add_orders_table/migration.sql` | New table |

**Description rules for Prisma:**
- Prisma generates the timestamp automatically with `prisma migrate dev`
- Description is the `--name` argument
- Use snake_case, no spaces

### Raw SQL

**Format:** `{NNN}_{description}.sql`

Sequential numbering with zero-padded prefix:

| Example | Description |
|---------|-------------|
| `001_create_users_table.sql` | First migration |
| `002_add_email_to_users.sql` | Second migration |
| `003_create_orders_table.sql` | Third migration |

**Numbering rules:**
- Zero-pad to 3 digits minimum (001, 002, ..., 999)
- If project exceeds 999, use 4 digits (0001, 0002, ...)
- Never reuse numbers, even for deleted migrations
- Gaps in sequence are acceptable (001, 002, 005 is fine)

---

## Description Verb Prefixes

| Prefix | Use When |
|--------|----------|
| `create_` | New table |
| `add_` | New column, index, or constraint to existing table |
| `drop_` | Remove table |
| `remove_` | Remove column, index, or constraint |
| `rename_` | Rename table or column |
| `alter_` | Change column type or constraint |
| `backfill_` | Data-only migration (populate column values) |
| `merge_` | Combine tables or columns |
| `split_` | Separate table or column into multiple |

---

## Anti-Patterns

| Bad Name | Problem | Better Name |
|----------|---------|-------------|
| `migration_1.py` | Not descriptive | `create_users_table.py` |
| `update.sql` | Too vague | `add_status_to_orders.sql` |
| `fix_bug.py` | Describes why, not what | `alter_email_column_length.py` |
| `changes.sql` | Not descriptive | `add_index_on_users_email.sql` |
| `final_migration.py` | Nothing is ever final | `remove_deprecated_columns.py` |