github/gh-ost

★ 13,338GoAudience · ops devopsComplexity · 4/5LicenseSetup · moderate

Mindmap

mindmap
  root((gh-ost))
    What it does
      Live migration
      No table locks
      No triggers
    How it works
      Binary log reads
      Shadow table
      Final swap
    Features
      Pause and resume
      Replica testing
      Control socket
    Tech
      Go
      MySQL

mindmap root((gh-ost)) What it does Live migration No table locks No triggers How it works Binary log reads Shadow table Final swap Features Pause and resume Replica testing Control socket Tech Go MySQL

Click or tap to explore — scroll the page freely

Things people build with this

USE CASE 1

Add a new column or drop an index on a large production MySQL table without locking the table or taking downtime

USE CASE 2

Run a schema migration against a read replica first to verify the result before touching the primary database

USE CASE 3

Pause and resume a live migration automatically when the database is under heavy load, then pick up without losing changes

USE CASE 4

Control an in-progress migration via gh-ost's socket interface to check status, delay the final swap, or force completion

Tech stack

GoMySQL

Getting it running

Difficulty · moderate Time to first run · 1h+

Requires MySQL binary logging enabled and the appropriate database user permissions, production cutover timing needs careful planning.

Use freely for any purpose, including commercial use, as long as you include the MIT license notice.

In plain English

gh-ost is a tool built by GitHub for changing the structure of a MySQL database table while the database is still live and serving traffic. Databases used by real applications need to be available constantly, but sometimes the table structure needs to change, for example to add a new column or remove an old index. Doing that naively would lock the table and block all users. gh-ost solves that problem. The standard approach for this kind of live migration involves attaching database triggers, which are rules that fire automatically when data changes. gh-ost takes a different path: it reads the database's internal change log (called the binary log) to track every insert, update, and delete as it happens, and replays those changes onto a new copy of the table it is building in the background. This avoids triggers entirely, which removes a significant source of risk and unpredictable load. Because gh-ost controls the entire migration process itself, it can truly pause the operation when the database is under heavy load, then resume it without losing any changes. You can also interact with a running migration to check its status, force a pause, or delay the final table swap until you are ready. The final swap, where the old table is replaced by the new one, is the most critical moment and can be scheduled or held back until a convenient time. The tool supports running the migration against a read replica first as a testing mode. This lets you verify the result and build confidence before touching the main database. GitHub runs their own production tables through this test mode continuously. gh-ost is open source under the MIT license, written in Go, and available as a pre-built binary for Linux and macOS.

Copy-paste prompts

Prompt 1

Show me the gh-ost command to add a nullable varchar column to a 500M-row MySQL table using replica testing mode before the primary cutover

Prompt 2

How do I pause a running gh-ost migration when database CPU spikes above 80%, and how do I resume it safely?

Prompt 3

Walk me through the gh-ost final table swap: what happens during cutover and how do I delay it until off-peak hours?

Prompt 4

How does gh-ost read the MySQL binary log instead of using triggers, and why does that make it safer for production use?

Prompt 5

Show me how to run gh-ost in test-on-replica mode to fully validate a schema change before it touches the primary MySQL database

Open on GitHub → Explain another repo

← github on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.