Skip to main content
gh-ost is a triggerless online schema migration tool for MySQL. Bytebase leverages gh-ost to migrate MySQL table schemas with minimal downtime.

​
How it works

Online schema migration tools operate through a careful orchestration of steps:
  1. Ghost table creation: Creates a new table with the desired schema structure
  2. Data migration: Incrementally copies data from the original table to the ghost table while capturing ongoing changes (INSERT, DELETE, UPDATE operations)
  3. Table swap: Atomically replaces the original table with the fully synchronized ghost table

​
Requirements and limitations

​
Requirements

  • MySQL version 5.7 or higher
  • Row-based logging enabled
  • Primary key on the table
  • Primary database for migration (replica migration not currently supported)

​
Limitations

  • Foreign key constraints are not supported
  • Triggers are not supported
  • Large tables may require extended migration time
For a comprehensive list of requirements and limitations, refer to the gh-ost documentation.

​
Performing an online schema migration

​
Step 1 - Create a schema change issue

  1. Navigate to your database and click Edit Schema
  2. Enter your ALTER TABLE statement in the SQL editor
  3. Click Preview issue to review the changes

​
Step 2 - Enable online migration

Before creating the issue:
  1. Toggle on Online migration option
  2. Click Configure to customize migration parameters if needed
bb-issue-online-migration-on bb-issue-ghost-config
  1. Review your SQL statement and click Create to create the issue

​
Step 3 - Deploy the migration

Once the issue is created, the online migration task will be in one of these states:
  • Waiting for approval: If custom approval flow is configured
  • Waiting for rollout: Ready to execute
Deploy the task according to your configured workflow. The migration process will:
  1. Create temporary tables:
    • Changelog table: ~yourtablename_{timestamp}_ghc
    • Ghost table: ~yourtablename_{timestamp}_gho
  2. Begin copying data from the original table to the ghost table
  3. Continuously synchronize ongoing changes to keep tables in sync
  4. When synchronization is complete (tables are nearly identical), automatically perform the table swap:
    • Original table → ~yourtablename_{timestamp}_del
    • Ghost table → yourtablename
The entire process happens within a single task, ensuring atomic execution and consistency.

​
Step 4 - Post-migration cleanup

After successful migration:
  1. The original table is preserved as ~yourtablename_{timestamp}_del
  2. Verify your data integrity and application functionality
  3. To view the original table, click Show Bytebase reserved tables on the database page
bb-db-show-reserved-tables bb-db-reserved-tables
  1. Once verified, you can manually drop the ~yourtablename_{timestamp}_del table