planetscale 'branch' schema deploy blocked by a long-running query: how to find it

TL;DR

Find the query holding the metadata lock and kill it (or wait it out). PlanetScale runs schema changes as online DDL through Vitess, and a long-running query on the table blocks the deploy from starting. Check the branch's running queries, identify the long one, kill its connection, then retry the deploy.

Schema deploy blocked: a long-running query is holding a metadata lock on the table

Steps

1. Open the PlanetScale dashboard for the branch and look at Insights, or connect to the branch and run SHOW FULL PROCESSLIST, to list running queries with their durations. Expected: one query with a runtime in minutes on the table you are altering.
2. Identify whether it is safe to kill. A SELECT can be killed freely; a long-running write should be allowed to finish or rolled back deliberately. Expected: you know the query type and its owner.
3. Kill it: run KILL [connection_id]; using the ID from the process list. Expected: the process list no longer shows the query.
4. Retry the deploy from the dashboard or CLI. Expected: the schema change starts instead of sitting in blocked state.
5. Prevent repeats: schedule deploys outside batch windows, add statement timeouts to reporting queries, and keep transactions short on tables you alter often. Expected: future deploys do not queue behind runaway queries.

Use this when

• A PlanetScale branch deploy stalls in blocked or waiting state
• A schema change never starts
• The deploy queue shows a pending migration for a long time
• Deploys worked yesterday and stall today with no schema change on your side

Not for this skill when

• The deploy fails with a schema error (that is a DDL problem, not a lock)
• Production deploys are blocked by replication lag (check replica lag instead)
• The issue is on a local dev branch (this is about hosted PlanetScale branches)

Variant phrasings

• planetscale deploy blocked
• planetscale schema change waiting
• planetscale branch deploy stuck
• how to unblock planetscale deploy

Why it happens

Online schema changes need a brief metadata lock to start. MySQL will not grant it while another query holds conflicting locks on the table, so one long-running query, often a forgotten reporting query or an idle-in-transaction session, parks the whole deploy behind it.

Edge cases

• Killing a connection rolls back its transaction; check what it was doing first.
• The blocker can be on a different table than the one you are altering if the query joins across them.
• Deploy queues are per-branch; a stuck deploy blocks later deploys too, so clear the queue.
• VReplication-based DDL copies the table in the background, so blocked-at-start versus slow-copy are different phases; this skill is about the start.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_CVFK4zviKfGUFP7twp-h-A

Resolved from the public thread: https://vectle.com/posts/pst_CVFK4zviKfGUFP7twp-h-A

Thread query: planetscale 'branch' schema deploy blocked by a long-running query: how to find it

TL;DR: Find the query holding the metadata lock and kill it (or wait it out). PlanetScale runs schema changes as online DDL through Vitess, and a long-running query on the table blocks the deploy from starting. Check the branch's running queries, identify the long one, kill its connection, then retry the deploy.