Skip to content
Get packs

Guide · Open source

How to use gh-ost: online MySQL schema migrations

Updated · written with AI from the project's own documentation and checked against our catalogue data

gh-ost is a command-line tool from GitHub for changing the structure of large MySQL tables while the database keeps serving traffic. It builds a ghost copy of your table with the new structure, copies rows in small batches, and replays ongoing changes from the binary log onto that copy. This guide explains how the process works, what you need before you start, and how to run a safe migration step by step.

gh-ostgithub/gh-ost · ★ 13.6k · MIT

Quick start

  1. 1Confirm MySQL prerequisites. Make sure your MySQL setup has binary logging enabled and that you understand your master, replicas and binlog format.
  2. 2Get gh-ost. Download a release for production use, or clone the repository and build with script/build to get bin/gh-ost.
  3. 3Test on a replica. Run a migration with --test-on-replica and compare the two resulting tables before relying on the tool.
  4. 4Run a noop migration. Issue a noop run on the master to confirm the migration is valid and good to go.
  5. 5Execute the migration. Issue the real migration with --execute once the noop run passes.
  6. 6Control cut-over timing. Use --postpone-cut-over-flag-file if you want to choose when the final table swap happens.

What gh-ost does and how it works

gh-ost follows the same general pattern as other online schema change tools. It creates a _ghost_ table with the structure you want, copies data from the original table into it slowly, applies ongoing changes to the ghost table, and at the right moment replaces the original table with the ghost table.

The difference is that gh-ost does not use database triggers. According to the README, triggers carry many limitations and risks. Instead, gh-ost reads the binary log stream to capture changes to the table and applies them asynchronously to the ghost table.

Check the requirements before you install

gh-ost is specifically for MySQL. The README's requirements document is the place to confirm the details for your setup, and it says MySQL needs binary logging enabled. Configuration requires an understanding of the master, replicas and binlog format, so this tool is a poor fit for someone new to MySQL replication.

The README also notes that Statement Based Replication requires running migrations through a replica. Review the requirements and limitations doc, the common questions doc and the fine print doc before running anything on production.

  • MySQL with binary logging enabled
  • Working knowledge of master, replicas and binlog format
  • Read doc/requirements-and-limitations.md before you start

Get gh-ost: download a release or build from source

The README says gh-ost is available as a binary for Linux and Mac OS/X on its releases page. Only releases are meant for production use; the master branch is described as stable but intended for testing. If you build from source, the project is written in Go and built with Go 1.15 and above.

To get the source, clone the repository. The README's build instructions point to script/build, which is the same script CI uses and produces the bin/gh-ost binary.

  • Download the latest release from the releases page for production use
  • Build from source with script/build, which outputs ./bin/gh-ost
git clone https://github.com/github/gh-ost

Run a noop migration first

Before touching a master, the README recommends issuing a noop migration. This checks that the migration is valid and ready to go without making changes.

Once the noop run passes, run the real migration by adding --execute. The README's tips say to do a noop first for each master migration and then issue the real command with --execute. The cheatsheet doc has the full set of flags.

  • Noop run: validates the migration without altering the table
  • Real run: add --execute to apply the migration

Test on a replica to build trust

gh-ost can run a migration on a replica without replacing the original table. The replica ends up with two tables you can compare, which lets you check that the tool behaved as expected. The README describes this as how GitHub continuously tests gh-ost in production.

The README recommends trying the --test-on-replica option the first few times you use the tool. A real migration can also run on a replica, leaving the master untouched.

  • Use --test-on-replica for test runs on a replica
  • Compare the two resulting tables to verify the result
  • Real migrations on a replica leave the master untouched

Control pausing, throttling and cut-over timing

gh-ost lets you pause a migration truly: when it throttles, it stops row copies and event processing on the master. You can also reconfigure it while it runs using interactive commands, and query it for status over a unix socket or TCP.

To control when the table swap happens, use --postpone-cut-over-flag-file. The README also suggests --exact-rowcount for accurate progress indication. Hooks let you connect gh-ost to your own environment. The interactive commands doc lists what you can change at runtime.

  • Throttle to pause writes on the master
  • Interactive commands to reconfigure a running migration
  • Status queries over a unix socket or TCP
  • --postpone-cut-over-flag-file to choose when the swap happens
  • --exact-rowcount for accurate progress

What people use it for

  • Altering a large production MySQL table without blocking traffic
  • Pausing and throttling a long migration to reduce load on the master
  • Rehearsing a schema change on a replica before running it on production
  • Scheduling the final table swap for a time when operators are available

Frequently asked questions

Is gh-ost free to use?

gh-ost is licensed under the MIT license, according to the README. The project also uses third-party libraries, each with its own license, which are listed in the vendor directory.

What databases does gh-ost support?

gh-ost is a schema migration tool for MySQL. The README does not describe support for other databases, so it should not be used with anything else.

Do I need triggers for gh-ost?

No. gh-ost is triggerless. It uses the binary log stream to capture ongoing table changes instead of database triggers, which the README says carry many limitations and risks.

How do I install gh-ost?

The README says it is available as a binary for Linux and Mac OS/X on the releases page. You can also clone the repository with git clone https://github.com/github/gh-ost and build it with script/build, which produces bin/gh-ost.

What is the difference between gh-ost and pt-online-schema-change?

Both are online schema change tools for MySQL. The README says gh-ost differs from existing tools by not using triggers. Other comparable projects mentioned in this directory include Vitess online DDL and Spirit.

Should I use gh-ost for a small table?

Probably not. For small tables where a plain ALTER TABLE is fast enough, the simpler command is usually the better choice, since gh-ost adds operational steps.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

gh-ost suits teams running large MySQL tables who need to avoid blocking downtime and want control over pausing, throttling and cut-over timing. It is a poor match for small tables, non-MySQL databases, or anyone without replication and binary log experience, who should consider a simpler ALTER TABLE or a comparable tool such as pt-online-schema-change, Vitess online DDL or Spirit.

Install options & downloads