PLANETSCALE 2021-05-20

PlanetScale — Non-blocking schema changes¶

Summary¶

Lucy Burns's 2021-05-20 launch-era narrative of PlanetScale's branch-based schema-change workflow. This is the canonical early public description of the deploy-request primitive (later deepened by Coutermarsh 2024 and Noach 2024): engineers open a branch off production, edit schema on the branch in an isolated sandbox with a copy of production schema, open a deploy request, and the platform runs a pre-cutover safety pipeline — schema- conflict analysis against main and against queued deploys, then a serialised deploy queue that dispatches changes one at a time, then the actual non-blocking migration using Vitess with gh-ost underneath, with traffic- aware throttling that scales migration work down if production traffic spikes. Positions the product against Liquibase and Flyway (manual schema-version tooling), pt-online-schema-change (Percona Toolkit) and gh-ost (GitHub's online migration tool) — the latter two providing non-blocking migration mechanics but "often run manually and require the support of additional infrastructure." PlanetScale's contribution is wrapping gh-ost inside a managed workflow so developers "push schema changes as easily, and as often, as they push code changes."

Key takeaways¶

Schema changes are the biggest DBA pain point.

"schema changes are one of the biggest pain points when it comes to using a relational database. We've heard about schema change processes that require opening tickets to get a DBA review for each change. This can take weeks." Some teams avoid columns entirely: "engineering teams won't change or update certain columns in their production databases because the migration will take too long"; others "turned columns in their relational databases into JSON stores, just to avoid schema migrations." Canonicalised as the motivating workload for patterns/branch-based-schema-change-workflow.
Prior-art taxonomy. Liquibase / Flyway do schema versioning + deployment management but are manual; pt-online-schema-change and gh-ost do online / non-blocking migration mechanics (copy-table-apply-schema-swap) but are "often run manually and require the support of additional infrastructure." PlanetScale's contribution is end-to-end workflow glue on top of the gh-ost mechanism — the mechanism is not novel, the productised workflow around it is.
Three product workflow commitments. Verbatim:

"- Allows users to test out schema changes on a branch that is isolated - Analyzes schema changes in advance to ensure there are no conflicts - Deploys schema changes in the background without impact to production" These are the three canonical pillars of the patterns/branch-based-schema-change-workflow.
Database branching as workflow primitive. "When a user needs to make a schema change, they create a database branch from their production database, which is automatically deployed with a copy of the production schema. The user can test out schema changes on their branch without worrying about impacting the production database." Canonical introduction of concepts/database-branching on the wiki — the sandbox-copy-of-prod-schema primitive that makes schema changes feel like git branches.
Deploy request + optional teammate review. "Once a user is satisfied with their schema changes, they can create a deploy request. Users have the option to request a review of their changes from a teammate, or they can add their deploy request directly to the deploy queue." 2021-era framing of what Coutermarsh later canonicalised as a five-stage lifecycle (see concepts/deploy-request).
Serialised deploy queue — one-at-a-time execution.

"The deploy queue represents all of the deploy requests, or schema changes, for a given database that are awaiting deployment. PlanetScale deploys schema changes in the order in which they are received. (In our experience, deploying schema changes one at a time is generally more efficient than running them concurrently, with a few exceptions.)" Canonicalises concepts/schema-change-queue with a production- experience disclosure: serial > concurrent for migration throughput despite the intuitive appeal of parallelism. The "few exceptions" are left unspecified.
Traffic-aware migration throttling. Verbatim:

"When the deploy request reaches the front of the queue, the deployment to production begins. This process happens in the background and is sensitive to production traffic. If there's a spike in traffic, the schema change migration will scale down to avoid using resources needed to handle the increased traffic." Canonical 2021-era disclosure of what later becomes the Vitess throttler — see concepts/traffic-aware-migration-throttling for the wiki concept. The migration is elastic workload that yields to production OLTP.
Pre-flight conflict detection — two independent checks. Verbatim:

"When a user creates a deploy request, PlanetScale automatically checks for conflicts, analyzing the schema on the branch against the main branch schema at the time of the branching. PlanetScale also analyzes the schema changes against current schema on main, which may have changed in the time since the branch was created, ensuring that no conflicts exist." — i.e. (a) branch-schema-at-fork ↔ branch-schema-now and (b) branch-schema-at-fork ↔ main-schema-now. Plus a third queue-level check: "when a user adds a deploy request to the deploy queue, PlanetScale checks the schema changes in the deploy requests ahead of that user's deploy request for any potential conflicts. If a conflict exists, the deploy request is rejected from the queue, and the user is notified of the conflict." Canonical three-check pre-flight pipeline; canonicalised as concepts/pre-flight-schema-conflict-check.
Days saved by pre-flight rejection. "with longer running migrations, this can mean a time savings of up to a few days." — operational rationale for catching conflicts before queue admission rather than at cutover.
gh-ost + Vitess stack disclosure. Verbatim:

"Using Vitess and gh-ost under the hood, we provide our users with a safe, easy, reliable way to push schema changes to production." Canonicalises the gh-ost-as-migration-engine architectural choice that PlanetScale inherited. Links the wiki's systems/gh-ost page to the product stack.

Systems¶

PlanetScale — managed Vitess- based relational DB platform; this post is the launch-era description of its flagship workflow.
Vitess — sharding / orchestration substrate; drives the migration workflow.
gh-ost — GitHub's online schema change tool (copy-table-based, replication-driven); the migration mechanism under PlanetScale's workflow. Also referenced as pt-online-schema-change's peer in the prior-art taxonomy.
MySQL — the target engine for the workflow.

Concepts¶

Online DDL — the family of techniques for non-blocking schema change; this post is the PlanetScale-workflow framing layer.
Database branching — new wiki concept — sandbox copy of production schema as the unit of schema-change development.
Deploy request — the PR analog for schema changes; existing concept, this post is the 2021-era introduction.
Schema-change queue — serialised one-at-a-time execution of deploy requests; existing concept, this post adds the "one at a time is generally more efficient than concurrent" production disclosure.
Pre-flight schema-conflict check — new wiki concept — three-check pipeline (branch-vs-fork, branch-vs-main- now, branch-vs-queue-ahead) that rejects conflicting deploy requests before they reach cutover.
Traffic- aware migration throttling — new wiki concept — migration scales down when production traffic spikes.

Patterns¶

Shadow- table online schema change — the gh-ost / pt-osc mechanism; this post discloses it verbatim: "creating a new table that is a copy of the given table. The schema changes are applied to the new table and the data in the original table is copied over. Once that is complete, the original table is replaced by the new table."
Branch- based schema-change workflow — new wiki pattern — the end-to-end PlanetScale product pattern: branch → deploy request → conflict check → serialised queue → non-blocking migration with traffic-aware throttling.
PR-bot auto- deploy-request — teammate-review alternative path; this 2021 post mentions the optional review step that Coutermarsh 2024 later couples with a bot.

Operational numbers¶

Ticket-based DBA review — "weeks" for schema change approval, pre-PlanetScale. Motivating pain.
Conflict-detection time savings — "up to a few days" on longer-running migrations — pre-flight rejection before queue admission vs. waiting until cutover.

Caveats¶

Launch-era marketing narrative. Tier-3 source + product-introduction post. No architecture diagrams, no code, no production metrics beyond the qualitative "weeks" / "days" framings above. Its wiki value is as the canonical early public articulation of the deploy-request + branch workflow that later posts (Coutermarsh 2024, Noach 2024) deepen with actual execution details.
No mention of instant DDL. 2021-era post predates the 2024 ALGORITHM=INSTANT fast-path. The workflow described here is the safe-default shadow-table path only.
No mention of schema reverts. Predates the [[patterns/instant-schema-revert-via-inverse- replication|30-minute inverse-replication revert window]] (Noach 2024). Original workflow was forward-only.
"Scale down" under load is not quantified. No disclosure of what metrics drive the throttling, what the thresholds are, or how aggressively the migration backs off — later posts on the Vitess throttler fill those details in (replication-lag threshold, probabilistic rejection, exemption lists, etc.).
"Few exceptions" to serial-over-concurrent are left unspecified. The post asserts one-at-a-time migration is "generally more efficient" without naming which narrow cases concurrent execution wins.

Source¶

Original: https://planetscale.com/blog/non-blocking-schema-changes
Raw markdown: raw/planetscale/2026-04-21-non-blocking-schema-changes-f580a194.md