Support gh-ost checkpointing and revertible migrations · Issue #21187 · bytebase/bytebase · GitHub
Skip to content

Support gh-ost checkpointing and revertible migrations #21187

Description

@ondramie

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:

  -- 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: github/gh-ost#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?

Activity

  1. added theissue type on Aug 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions