Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.bytebase.com/llms.txt

Use this file to discover all available pages before exploring further.

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: 
-- gh-ost = {}

ALTER TABLE users ADD COLUMN email VARCHAR(255);
This uses gh-ost to apply changes without blocking your database. Use {} to run with default flags, or pass gh-ost flags as a JSON object: 
-- gh-ost = {"max-lag-millis":"1500","cut-over-lock-timeout-seconds":"10"}

ALTER TABLE users ADD COLUMN email VARCHAR(255);

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