gh-ost

gh-ost (GitHub's Online Schema Transmogrifier) is a MySQL schema migration tool built by GitHub to solve a practical problem: how do you add a column, change an index, or modify a constraint on a table with hundreds of millions of rows in a production database without locking the table and causing downtime?

Traditional MySQL DDL operations lock the table for the duration of the change, which can mean minutes or hours of unavailability for large tables. Tools that work around this using triggers (such as pt-online-schema-change) add write overhead to every row modification during the migration. gh-ost takes a different approach: it creates a ghost table with the new schema, copies rows in controlled batches, reads changes from the MySQL binary log to keep the ghost table current, and then performs an atomic cutover when the two tables are in sync.

Platform engineers and backend teams running high-availability MySQL infrastructure use gh-ost for schema changes that would otherwise require maintenance windows.

The key architectural decision in gh-ost is reading from the binary log rather than using triggers. MySQL triggers that intercept writes to the original table and duplicate them to the ghost table add latency to every write operation during the migration. On high-write tables, this overhead compounds and can cause replication lag and query timeouts.

gh-ost instead connects as a replica and reads the binary log stream for changes to the original table, applying those changes to the ghost table asynchronously. This means write operations to the original table have no additional overhead during the migration: they complete normally and gh-ost picks up the changes from the binary log on a slight delay. The ghost table stays current through log replay rather than trigger interception.

Row copying runs concurrently with log replay. gh-ost processes rows in chunks, pausing between chunks based on its throttle settings, until it has copied all historical rows. At that point the ghost table is equivalent to the original table under the new schema and ready for cutover.

gh-ost's throttling model is one of its strongest operational features. It can pause or slow row copying automatically when replication lag exceeds a configured threshold, when I/O utilisation on the MySQL host is above a limit, or when custom metric sources (HTTP endpoints, shell commands) return signals indicating the database is under load.

Operators can also interact with a running migration via a Unix socket: pause and resume the migration, change the chunk size, update throttle parameters, or trigger an immediate cutover once the tables are in sync. This makes gh-ost behave more like a controlled operation than a fire-and-forget process, which matters when running migrations during business hours on live traffic. For teams running platform infrastructure where database availability is a hard SLA requirement, this level of operational control is essential.

The cutover is the final phase where the original table is replaced by the ghost table. gh-ost uses a lock-based atomic rename rather than a simple RENAME TABLE: it acquires a brief lock, verifies the ghost table has caught up with the binary log, renames both tables atomically, and releases the lock. If anything goes wrong during this sequence, it rolls back automatically and the original table remains intact and unchanged.

The lock window during cutover is measured in milliseconds rather than the duration of the migration. Applications experience a brief pause at cutover but not the extended outage that comes from running DDL directly. gh-ost also supports postponing the cutover interactively until an operator explicitly signals readiness, useful when coordinating migrations with deployments or traffic shaping.

gh-ost is fully scriptable from the command line, which makes it straightforward to integrate into deployment pipelines. A standard pattern runs gh-ost as a step in a deployment workflow: the migration runs on the replica first to validate the schema change, then the same command is applied to the primary. Exit codes and verbose output allow pipeline tooling to handle success, failure, and timeout conditions programmatically.

gh-ost is compatible with MySQL 5.6 and above and works with MySQL-compatible databases including MariaDB. It also runs against cloud-hosted MySQL instances on AWS RDS and Google Cloud SQL with some configuration adjustments for environments where direct binary log access requires specific permissions. Teams managing schema migrations as part of a broader software engineering practice typically document gh-ost parameters per table size tier so that operators know the expected migration duration and appropriate throttle settings before starting. For organisations looking to formalise their database operations practices, starting a conversation with Scrums.com can help structure the right approach.