Skip to content

docs: update migration naming conventions to match implementation #953

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
d-bytebase merged 1 commit into from
Dec 2, 2025
Merged

docs: update migration naming conventions to match implementation #953

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
128 changes: 23 additions & 105 deletions mintlify/gitops/migration-based-workflow/develop.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,16 +9,17 @@ Create SQL migration files following naming conventions that enable proper versi
Migration filenames must follow this structure:

```
<Version>__<Description>_<Suffix>.sql
<Version>_<Description>.sql
```

**Components:**

1. **Version** (required) - Must begin with a number, optional `v` or `V` prefix
2. **Double underscore** (`__`) separator
1. **Version** (required) - Optional `v` or `V` prefix, followed by one or more numbers separated by dots
- Pattern: `^[vV]?(\d+(\.\d+)*)`
- Examples: `v1.2.3`, `1.0`, `V2`
2. **Underscore** (`_`) separator
3. **Description** - Human-readable description using underscores or hyphens
4. **Suffix** (optional) - Migration type indicator
5. **`.sql`** file extension
4. **`.sql`** file extension

## Version Formats

Expand All @@ -29,8 +30,8 @@ Choose a versioning strategy that fits your team:
**Timestamp-Based** - Recommended for teams with parallel development

```
20250120143000__add_user_email.sql
20250121091500__create_orders_table.sql
20250120143000_add_user_email.sql
20250121091500_create_orders_table.sql
```

Format: `YYYYMMDDHHmmss`
Expand All @@ -46,10 +47,10 @@ Choose a versioning strategy that fits your team:
**Semantic Versioning** - Meaningful version numbers

```
v1.0.0__initial_release.sql
v1.1.0__add_user_profiles.sql
v1.1.1__fix_profile_constraint.sql
v2.0.0__redesign_authentication.sql
v1.0.0_initial_release.sql
v1.1.0_add_user_profiles.sql
v1.1.1_fix_profile_constraint.sql
v2.0.0_redesign_authentication.sql
```

✅ Conveys change significance
Expand All @@ -63,9 +64,9 @@ Choose a versioning strategy that fits your team:
**Simple Sequential** - Easy to understand

```
001__initial_schema.sql
002__add_users.sql
003__add_products.sql
001_initial_schema.sql
002_add_users.sql
003_add_products.sql
```

✅ Simple and clear
Expand All @@ -75,104 +76,21 @@ Choose a versioning strategy that fits your team:
</Tab>
</Tabs>

## Change Type Suffixes
## Migration Type (MySQL Only)

Specify the migration type using an optional suffix:

| Suffix | Type | Description | Use Cases |
|--------|------|-------------|-----------|
| *(none)* | **DDL** | Data Definition Language | CREATE, ALTER, DROP tables, indexes, constraints |
| `_dml` | **DML** | Data Manipulation Language | INSERT, UPDATE, DELETE, data migrations |
| `_ghost` | **Ghost** | gh-ost online migration | Zero-downtime MySQL schema changes |

**Examples:**

```
v1.0.0__create_schema.sql (DDL - default)
v1.1.0__seed_initial_data_dml.sql (DML - data changes)
v1.2.0__add_user_index_ghost.sql (Ghost - online schema change)
```

<Card title="Online Schema Migration" icon="bolt" href="/change-database/online-schema-migration-for-mysql">
Learn about gh-ost for zero-downtime MySQL migrations
</Card>

## File Organization

**Recommended structure:**

```
migrations/
├── 001__initial_schema.sql
├── 002__add_users.sql
├── 003__add_products_dml.sql
└── 004__add_indexes.sql
```

**Or with subdirectories:**

```
migrations/
├── baseline/
│ └── 000__initial_schema.sql
├── features/
│ ├── 001__users.sql
│ ├── 002__products.sql
│ └── 003__orders.sql
└── hotfixes/
└── 004__fix_index.sql
```

## Best Practices

**Keep migrations small and focused:**

```sql
✅ Good - Single, clear purpose
-- 005__add_user_email.sql
ALTER TABLE users ADD COLUMN email TEXT;
```
For zero-downtime MySQL schema changes, add this comment at the top of your file:

```sql
❌ Bad - Too large and unfocused
-- 005__big_refactor.sql
ALTER TABLE users ADD COLUMN email TEXT;
ALTER TABLE users ADD COLUMN phone TEXT;
CREATE TABLE user_preferences (...);
-- 500 more lines
```

**Add comments for complex logic:**
-- migration-type: ghost

```sql
-- 020__migrate_legacy_permissions_dml.sql
-- Migrates old role system to new permission model
-- Old: roles.name -> New: permissions.scope + permissions.action

UPDATE permissions
SET scope = CASE
WHEN roles.name = 'admin' THEN 'database'
WHEN roles.name = 'editor' THEN 'database'
END
FROM roles
WHERE permissions.role_id = roles.id;
ALTER TABLE users ADD COLUMN email VARCHAR(255);
```

**Use transactions when possible:**

```sql
-- 015__multi_step_migration_dml.sql
BEGIN;

UPDATE users SET status = 'migrated' WHERE status = 'legacy';
This uses [gh-ost](https://github.com/github/gh-ost) to apply changes without blocking your database.

INSERT INTO user_audit_log (user_id, action)
SELECT id, 'status_migrated'
FROM users
WHERE status = 'migrated';

COMMIT;
```
<Card title="Online Schema Migration" icon="bolt" href="/change-database/online-schema-migration-for-mysql">
Learn more about gh-ost
</Card>

---

Expand Down