#21187·bytebase

Support gh-ost checkpointing and revertible migrations

Author: ondramieCreated Aug 17, 2026Updated Aug 20, 2026

Is your feature request related to a problem?

Bytebase's gh-ost integration does not expose gh-ost's checkpoint/revert functionality. I tested this with Bytebase 3.20.1 and MySQL 8.0.46 using:

sql
  -- gh-ost = {"checkpoint":"true","checkpoint-seconds":"10"}
  ALTER TABLE ghost_checkpoint_test
  ADD COLUMN email VARCHAR(255) NULL;

Bytebase rejected the online during validation:

  • failed to create migration context
  • failed to get user flags
  • unsupported flag: checkpoint

Bytebase retains the original _del table in bbdataarchive, but without a checkpoint and revert execution path it cannot use gh-ost to replay post-cutover binlog events into that table before restoring it.

Upstream gh-ost supports revertible migrations: https://github.com/github/gh-ost/blob/master/doc/revert.md The feature was introduced by: https://github.com/github/gh-ost/pull/1607

Bytebase's current gh-ost flag allowlist does not include checkpoint, checkpoint-seconds, gtid, revert, or old-table:

https://github.com/bytebase/bytebase/blob/main/backend/component/ghost/config.go

Describe the solution you'd like

Please support revertible gh-ost migrations as a Bytebase-managed workflow.

For the original migration, Bytebase would:

  1. Allow or internally enable gh-ost checkpointing.
  2. Prefer GTID checkpoints when the MySQL instance supports GTID.
  3. Retain the _ghk checkpoint table and _del original table.
  4. Record their exact names and the original cutover position in the Bytebase task/change history.
  5. Expose whether a completed migration is currently eligible for revert.

For a revert, Bytebase would:

  1. Create a new reviewed and auditable task rather than removing or rewriting the original migration history.
  2. Verify that the _del and _ghk tables still exist.
  3. Verify that the required binlogs are still available.
  4. Invoke gh-ost using its native --revert and --old-table mode.
  5. Show catch-up and cutover progress in the rollout.
  6. Preserve the displaced post-migration table until verification is complete.
  7. Clearly report when the reverse schema cannot accept post-cutover writes.

If this is intentionally unsupported, it would be helpful to document the reason and Bytebase's recommended rollback procedure for a completed gh-ost schema migration.

Additional context

Environment:

  • Bytebase: 3.20.1
  • MySQL: 8.0.46
  • Bytebase deployment: local Docker Compose
  • Online migration directive: -- gh-ost = {...}

Current behavior is understandable because Bytebase uses an explicit flag allowlist and embeds gh-ost as a Go library rather than passing arbitrary CLI arguments. However, merely preserving the _del table is not equivalent to native gh-ost revert: a simple table swap does not replay writes made after the original cutover.

The desired behavior is specifically gh-ost's synchronized revert, not generic Questions for the Bytebase team:

  1. Is the absence of gh-ost checkpoint/revert support intentional, or has it simply not been implemented yet?

  2. What recovery procedure does Bytebase currently recommend after a completed gh-ost migration, especially when writes occurred after cutover?

  3. If this is not an intentional limitation, would Bytebase accept a proposal or contribution for a managed gh-ost revert workflow?