Skip to main content
Create SQL migration files following naming conventions that enable proper version tracking and execution order.

​
File Naming Convention

Migration filenames must follow this structure: 
<Version>_<Description>.sql
Components:
  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. .sql file extension

​
Version Formats

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
Format: YYYYMMDDHHmmss✅ No merge conflicts ✅ Chronological ordering ✅ Supports distributed teams⚠️ Less human-readable

​
Migration Type (MySQL Only)

For zero-downtime MySQL schema changes, add this comment at the top of your file: 
-- migration-type: ghost

ALTER TABLE users ADD COLUMN email VARCHAR(255);
This uses gh-ost to apply changes without blocking your database.

Online Schema Migration

Learn more about gh-ost

​
Next Steps

SQL Review CI

Set up automated validation in your CI/CD pipeline

Release

Deploy your migrations to databases