Skip to content

CONCEPT Cited by 2 sources

Deploy request

Definition

A deploy request is PlanetScale's first-class primitive for proposing a schema change against a target database. It is the database-schema analog of a pull request: an engineer opens a deploy request against a PlanetScale branch, reviewers approve it, the system executes the change as a staged online schema change, and a 30-minute revert window follows.

Verbatim introduction (Coutermarsh, 2024):

"The bot automatically opens a deploy request for us and leaves a comment linking to the change in GitHub. This allows our team to review both the schema change as well as the code. Giving full context around why and what is being changed." (Source: )

Five lifecycle stages

  1. Created — engineer (or PR-bot) opens a deploy request targeting a production branch. The request carries the proposed DDL.
  2. Linted — pre-execution lint catches "any common mistakes" before any DDL runs against production (Coutermarsh: "Before the schema change is even deployed, checks are run through a linter").
  3. Staged — Vitess begins the online migration (shadow-table build + backfill + binlog tail). See concepts/staged-then-sealed-migration.
  4. Ready — the shadow table has caught up and is ready to cut over. At this point the deploy request is either auto-applied or waits on operator click-through (see patterns/operator-scheduled-cutover). Multi-change deploy requests wait for every change to be ready (concepts/gated-schema-deployment).
  5. Cut over — the atomic table-swap seals the change. A 30-minute revert window follows during which the change can be rolled back by playing inverse replication.

Why it's a pull-request analog

Both PRs and deploy requests share:

Property Pull request Deploy request
Proposed change Code diff DDL diff
Target Branch Database branch
Review gate Approve / request changes Approve / cancel
Execution Merge → CI → deploy Apply → online migration → cut over
Reversible? git revert 30-min revert via inverse replication

Coutermarsh's PlanetScale-internal workflow exploits the symmetry: the PR-bot creates a deploy request whose link is posted back to the PR comment, so reviewers see both the code diff and the schema diff in one context. The two units deploy independently but are reviewed together.

Composition with other primitives

  • With concepts/schema-change-queue — when multiple deploy requests target the same branch concurrently, PlanetScale serialises them via the queue and runs combined-schema safety checks.
  • With gated deployment — a deploy request can carry multiple DDL statements that are staged independently and cut over together as a single near-atomic unit.
  • With patterns/operator-scheduled-cutover — an "Auto-apply" checkbox lets operators defer the cut-over moment past staging completion; the deploy request sits in ready state awaiting click.
  • With patterns/instant-schema-revert-via-inverse-replication — after cut-over, inverse replication runs for 30 minutes so the request can be rolled back.

Seen in

  • — Lucy Burns, PlanetScale, 2021-05-20. Canonical early public introduction of the deploy-request primitive — 3+ years before Coutermarsh and Noach deepened it. Burns 2021 establishes the three foundational properties: (a) the deploy request is opened from a branch (see concepts/database-branching), (b) the request gets a pre-flight conflict check before queue admission (see concepts/pre-flight-schema-conflict-check), and (c) the request has an optional teammate review gate or can be routed directly to the deploy queue. The 2021-era deploy request is single-execution- path (shadow-table only); the instant-vs-safe-path fork is introduced later by Noach 2024. Canonical verbatim framing: "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."

  • sources/2026-04-21-planetscale-instant-deploy-requests — fast-path-vs-safe-path altitude. Shlomi Noach (PlanetScale, 2024-09-04) canonicalises that a deploy request now carries a pre-evaluated execution-path choice at submission time. The eligibility analysis (see concepts/instant-deploy-eligibility) decides whether the deploy request can run as an instant deployment (MySQL ALGORITHM=INSTANT, seconds on a large table, non-revertible) or must run the default Online DDL path (shadow-table, hours, 30-minute revert window). When eligible, the deploy-request UI presents an explicit opt-in — see patterns/instant-deploy-opt-in for the shape. Canonical new lifecycle wrinkle: the deploy request's execution model is no longer uniform — eligibility determines the mechanism per request.

  • — operational altitude — Mike Coutermarsh describes PlanetScale's internal use of deploy requests via a GitHub Actions PR-bot, with co-located review on the PR.

  • — product-launch altitude — Shlomi Noach canonicalises the Auto-apply checkbox as a first-class property of the deploy-request UI.
  • sources/2026-04-21-planetscale-behind-the-scenes-how-schema-reverts-work — mechanism altitude — Guevara + Noach disclose how the revert half of the deploy-request lifecycle works via pre-staged inverse replication.

  • — axiom-layer altitude — Shlomi Noach's 2022-05-09 principles essay canonicalises the deploy-request as the instantiation of tenet 3 (asynchronous migration) of the operational relational schema paradigm. Verbatim: "Atomic or transactional migrations are appreciated, but they imply a connection to be held active for the duration of the migration, which we measure by hours or days. Deployment tools, or even scripts, should not be required to hold on to those connections for such long periods. … Databases should be able to receive a schema change request and move to run it asynchronously." Canonical framing: the deploy-request is not just a PR analog; it is the async-execution handle for a long-running operation where the client-side connection lifecycle does not gate the migration. This principles framing underlies Burns 2021's launch description of deploy-request + queue + conflict-check and every subsequent Noach post that extends the deploy-request surface with instant-deploy / gated-deployment / schema-revert capabilities. Principles / manifesto format — no new deploy-request mechanism here, but the philosophical basis for why the primitive exists.

  • — Shlomi Noach, PlanetScale, 2023-04-26. Canonical treatment of the deploy-request as the three-way-merge admission unit. Verbatim on the deploy-request's semantic-diff output: "The deploy request page presents a semantic diff of the changes made — e.g., an ALTER TABLE foo …, a CREATE TABLE bar (…), etc. PlanetScale uses Vitess's schemadiff library to generate the semantic diff between the main (production) branch and the developer's branch." The deploy-request is both the review artefact (carries the semantic SQL diff for engineers to approve) and the admission-check unit (the three-way-merge validation at queue admission time operates at deploy-request granularity). Noach frames the deploy-request workflow unchanged from the 2021 Burns disclosure, but adds the cross-branch conflict-detection layer explicitly.

Last updated · 542 distilled / 1,571 read