Skip to content

ericrisco/rsc-harness / skills/planetscale

planetscale

Verified

Use when operating PlanetScale (Vitess serverless MySQL) — branches and the `pscale` CLI, schema changes through deploy requests (Online DDL cutover, ~30-min revert window), tables without foreign keys, or the edge HTTP driver. NOT MySQL engine work like EXPLAIN or index choice (that is `mysql`), NOT generic migration theory (that is `db-migrations`).

FileKindSize
SKILL.mdskill md11.0 KB
evals/README.mdmarkdown912 B
evals/cases.yamlconfig4.0 KB
references/deploy-requests.mdmarkdown3.9 KB
references/no-foreign-keys.mdmarkdown3.8 KB
scripts/verify.shexecutablescript4.8 KB

references/deploy-requests.md

View on GitHub
# Deploy requests — lifecycle, gating, lint, reverts

Offloaded depth from SKILL.md §"The deploy-request workflow". The body has the happy path; this file
covers the states a deploy request moves through, why it stalls, and the revert carve-outs.

## Lifecycle states

A deploy request moves through roughly:

1. **Open** — created from a dev branch against production; PlanetScale has computed a schema diff.
2. **Approved** — a reviewer ran `pscale deploy-request review … --approve` (or approved in the UI).
3. **Queued / deploying** — the deploy is submitted; Vitess starts Online DDL (shadow table build +
   VReplication copy). Large tables spend most of their time here.
4. **Pending cutover / gated** — if auto-apply was disabled (`--disable-auto-apply`), the copy is done
   and the change waits for a manual `pscale deploy-request apply` before cutting over.
5. **Deployed** — cutover complete. The **~30-minute revert window** opens here.
6. **Reverted** or **permanent** — either reverted within the window, or finalized after it closes.

## Online DDL mechanics

A deploy does not run a blocking `ALTER`. Vitess:

- builds a **shadow table** with the target schema,
- uses **VReplication** to copy existing rows and continuously apply in-flight writes from old→new,
- waits for the shadow to catch up (lag → ~0),
- performs an atomic **cutover**, swapping the shadow in as the live table.

That is why a deploy against a big table can sit in "deploying" for a long time: it is copying rows,
not stuck. Watch the deploy's progress before assuming it hung.

## Why a deploy is queued / won't cut over

| Symptom | Likely cause | Action |
| --- | --- | --- |
| "Queued" for a long time on a large table | VReplication is still copying rows | Wait; check copy progress. It is working, not stuck. |
| Deployed-but-not-cut-over | Auto-apply disabled; it is gated | Run `pscale deploy-request apply <db> <number>`. |
| Another deploy already in flight | Deploys serialize per branch | Let the in-flight one finish or revert it first. |
| Blocked at open with lint errors | The diff violates a schema lint rule | Fix the DDL on the branch, re-diff, re-open. |

## Lint errors

PlanetScale lints the schema diff before it will deploy. Common blockers: a table without a primary
key (Vitess wants one for VReplication), or unsupported/foot-gun DDL. Resolve by editing the DDL on the
**branch** (open a `pscale shell`, fix the schema), regenerate the diff, and re-open the deploy request.
Never try to force a lint failure through.

## Revert carve-outs

The ~30-minute window lets you undo a deploy **while preserving writes that happened after the deploy**
— for most additive changes. It does **not** cleanly cover:

- **Dropped tables or columns** — the data is gone; a revert cannot resurrect it.
- **Foreign-key constraint changes** — excluded from clean revert.

After the window closes the deploy is permanent. Treat the window as a safety net for *additive*
changes, and plan destructive rollbacks (re-adding a dropped column, restoring data) as **new forward
deploys**, not as reverts.

## Declarative vs imperative schema

Two ways to express the change on a branch:

- **Imperative** — you run the `ALTER`/`CREATE` statements yourself in `pscale shell`; the deploy
  request diffs branch-vs-production and deploys that diff.
- **Declarative** — you keep the desired schema in version control and let PlanetScale compute the DDL
  needed to converge the branch to that target.

Either way the deploy request is the gate and the diff is the contract. Read the diff before deploying.

## Branch protection / safe migrations

Production branches are protected by default. **Safe migrations** on a branch is the setting that
*requires* the deploy-request flow — it stops raw schema edits from landing directly on the protected
branch. Keep it on for any branch that fronts production. Dev branches are disposable; protect the one
that matters.
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall