Skip to content

CONCEPT Cited by 2 sources

Ghost table migration

Definition

A ghost table migration is an online DDL mechanism in which a schema change is applied to a new table (the "ghost" table) that is a copy of the original with the new schema, while ongoing writes to the original table are simultaneously replicated into the ghost. Once the ghost is fully caught up and verified, the table names are swapped atomically — the ghost takes on the original name and serves live traffic, the original (now holding the old schema) becomes the ghost.

This is the mechanism pioneered by GitHub's gh-ost and Percona's pt-online-schema-change — both use the same structural pattern. The canonical name on PlanetScale is "ghost table"; elsewhere on the wiki the same mechanism is referred to as shadow table (the term is interchangeable — both point at the same primitive).

Mechanism

  1. Create empty ghost table with the new schema.
  2. Copy rows from original → ghost in chunks, sized to avoid sustained replication lag.
  3. Apply ongoing writes to the original table also into the ghost (via triggers in pt-online-schema-change, via binlog replication in gh-ost).
  4. Verify consistency between original and ghost.
  5. Swap names: ghost takes over the original's name atomically.
  6. Keep the retired original (now holding old schema) for the schema revert window, with inverse sync in the opposite direction.
  7. Drop the retired table after the revert window expires.

Relationship to the revert path

The ghost-table's post-merge retention is what makes schema revert possible without data loss: the retired original keeps receiving post-merge writes via inverse replication, so flipping the name swap back gives you "the old production table active again, but it will contain the writes since the merge" (Morrison II, 2024). See patterns/instant-schema-revert-via-inverse-replication for the full mechanism.

Seen in

  • sources/2026-04-21-planetscale-three-surprising-benefits-of-sharding-a-mysql-database — Brian Morrison II (PlanetScale, 2023-11-20) canonicalises ghost-table migration as a shard-parallel primitive. Verbatim: "Schema migrations are another task that can be performed more efficiently. For example, when you merge in a Deploy Request on PlanetScale, we'll create a new table on the target database branch with the updated version of the schema and sync data from the live table into this 'ghost table'. Once the changes are merged in, the old table is dropped and the 'ghost table' becomes the new production table. Using the same scenario from above, performing this operation on the smaller databases in parallel will dramatically reduce the time it takes to complete." Load-bearing additional framing: the full-table-copy phase is the wall-clock bottleneck, not the name-swap. Running N ghost-table migrations in parallel across N shards reduces a 1 TB migration to N × (1/N TB) in wall-clock. The same embarrassingly-parallel property that drives shard-parallel backup applies to ghost-table migrations for the same structural reason: each shard's ghost-table copy is independent of every other shard's. Morrison's 2023-11-20 post predates the branching-vs-Aurora post (Morrison 2024-02-02) and names the ghost-table term earlier in the wiki corpus.

  • sources/2026-04-21-planetscale-planetscale-branching-vs-amazon-aurora-bluegreen-deployments — Brian Morrison II (PlanetScale, 2024-02-02). Canonical wiki framing of "ghost table" as PlanetScale's term for the mechanism under deploy requests. Verbatim: "PlanetScale approaches this differently by analyzing the delta between the two schemas and generating the DDL statements to execute on the upstream branch in the correct order. This operation is done using a deploy request. When the deploy request is merged, a 'ghost' table is created on the upstream database to apply the new schema. The data is then synchronized between the old table and this new 'ghost' table until you can put it into production."

Last updated · 470 distilled / 1,213 read