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
---
name: planetscale
description: "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`)."
tags: [planetscale, vitess, mysql, deploy-requests, serverless-db]
recommends: [mysql, db-migrations, prisma-orm, drizzle-orm, github-actions, postgresdb]
origin: risco
---

# PlanetScale — Vitess serverless MySQL: branches, deploy requests, no FKs

PlanetScale is serverless, MySQL-compatible database-as-a-service built on **Vitess** — the same
horizontal-scaling layer that runs YouTube. You do not `ALTER TABLE` against production. Schema
changes live on an isolated **branch** (a full copy of the schema), reach production through a
**deploy request** (a pull request for your schema), and apply via **Online DDL**: Vitess builds a
shadow table holding the new schema, replicates rows and in-flight writes old→new with VReplication,
then **cuts over** with no table lock. Because Online DDL and sharding are the platform's center of
gravity, you **design without foreign keys** (FKs are now an opt-in but unsharded-only feature). This
skill owns that workflow — not MySQL the engine.

Heuristic for the boundary: **would this answer be identical on RDS MySQL? Then it is not this skill.**

| When the question is really about | Route to |
| --- | --- |
| A slow query, an `EXPLAIN` plan, an index decision, JSON columns, locking | `../mysql/SKILL.md` for MySQL-engine work; `../postgresdb/SKILL.md` when you want the transferable engine reasoning |
| PostgreSQL engine/design — even PlanetScale's own managed Postgres SQL semantics | `../postgresdb/SKILL.md`. PlanetScale sells Postgres too; this skill is strictly the **Vitess/MySQL branch+deploy-request** flow |
| Engine-agnostic migration *theory* (expand-contract, backfill ordering) | `../db-migrations/SKILL.md`. Here you get the concrete PlanetScale realization, not the theory |
| Postgres copy-on-write branches | `../neon/SKILL.md`. Postgres BaaS → `../supabase/SKILL.md` |
| ORM client ergonomics (Prisma `updateMany`, Drizzle query builder) | `../prisma-orm/SKILL.md` / `../drizzle-orm/SKILL.md`. This skill owns only the PlanetScale-specific knobs those ORMs expose (`relationMode`, serverless driver adapter) |

## Mental model

| PlanetScale concept | Git analogue | What it actually is |
| --- | --- | --- |
| Branch | branch | A full, isolated copy of the schema. `main` is your production branch. |
| Deploy request | pull request | The gate that carries schema from a dev branch to production. |
| Schema diff | the PR diff | The exact DDL the deploy will run, computed by PlanetScale. |
| Online DDL | (no git analogue) | Shadow table + VReplication + non-blocking cutover. No `ALTER` lock. |
| Schema revert | revert commit | A **~30-minute** window after deploy to undo while preserving post-deploy writes. |

The revert window is the one thing people get wrong: it is **not** forever, and it has carve-outs
(dropped tables/columns and FK-constraint changes are not cleanly revertible). After ~30 minutes the
deploy is permanent. Plan rollbacks as new forward deploys, not as "I'll just revert later."

## The deploy-request workflow

Production branches should have **safe migrations** enabled — that is what forces every schema change
through a deploy request instead of letting a raw `ALTER` hit `main`. Production branches are protected
by default. The full lifecycle (numbered steps, real `pscale` commands):

```bash
# 0. Install + authenticate (once)
brew install planetscale/tap/pscale   # or scoop / apt — see pscale docs
pscale auth login

# 1. Create the database (region close to your app)
pscale database create my_app --region us-east

# 2. Create a dev branch off production to hold the change
pscale branch create my_app add-orders-table

# 3. Apply your DDL on the BRANCH, never on main.
#    Open a MySQL shell scoped to the branch and run your CREATE/ALTER:
pscale shell my_app add-orders-table
#    mysql> CREATE TABLE orders (id BIGINT PRIMARY KEY AUTO_INCREMENT, ...);
#    mysql> ALTER TABLE users ADD COLUMN last_seen_at TIMESTAMP NULL;

# 4. Open a deploy request from the branch back to production.
#    --disable-auto-apply gates the cutover behind a manual apply (recommended for risky drops).
pscale deploy-request create my_app add-orders-table --disable-auto-apply

# 5. Inspect the exact schema diff the deploy will run. ALWAYS read this.
pscale deploy-request diff my_app 42

# 6. Review / approve (the schema-PR review step)
pscale deploy-request review my_app 42 --approve

# 7. Deploy. PlanetScale runs Online DDL: shadow table -> VReplication -> cutover.
pscale deploy-request deploy my_app 42

# 8. If you disabled auto-apply, the change waits gated until you apply the cutover:
pscale deploy-request apply my_app 42

# 9. Verify on production. If wrong, REVERT within the ~30-minute window:
pscale deploy-request revert my_app 42
```

**Auto-apply is ON by default.** With it on, step 7 deploys *and* cuts over in one motion. For
anything destructive — dropping a column/table, narrowing a type — pass `--disable-auto-apply` at
step 4 so the cutover sits gated (step 8) until a human applies it. That gap is your last cheap exit
before the revert window starts ticking.

For queued/gated deploys that won't move, lint errors that block a deploy, declarative vs imperative
schema, and the exact revert carve-outs, see [deploy-requests](references/deploy-requests.md).

## Design without foreign keys

Vitess's first-class features are Online DDL and horizontal sharding. Native foreign keys fight both:
a cross-shard FK is meaningless once a table is sharded, and FK constraint checks degrade
high-concurrency writes. PlanetScale **historically disallowed FKs entirely**; they are now an opt-in
but **unsharded-only** feature. The scale-safe default is **app-level referential integrity** with
emulated relations, not database-enforced FKs.

```sql
-- Bad on PlanetScale at scale: a DB-enforced FK with ON DELETE CASCADE.
-- Blocks sharding, conflicts with Online DDL, and the cascade is a hidden write amplifier.
CREATE TABLE orders (
  id        BIGINT PRIMARY KEY AUTO_INCREMENT,
  user_id   BIGINT NOT NULL,
  CONSTRAINT fk_user FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
);

-- Good: no DB FK. Index the relation column, enforce integrity in the app/ORM,
-- and do cascades explicitly in a transaction or background job.
CREATE TABLE orders (
  id        BIGINT PRIMARY KEY AUTO_INCREMENT,
  user_id   BIGINT NOT NULL,
  KEY idx_orders_user_id (user_id)   -- the relation still needs its index
);
```

With Prisma, declare `relationMode = "prisma"` so the client emulates relations and adds the implicit
indexes instead of emitting DB-level FKs:

```prisma
datasource db {
  provider     = "mysql"
  url          = env("DATABASE_URL")
  relationMode = "prisma"
}
```

With Drizzle, model the relation in app code (`relations()`), index the join column, and skip the
`references()`-backed FK constraint at the DB layer.

| Will this table shard? | FK strategy | Notes |
| --- | --- | --- |
| Yes, or unsure | No DB FK — emulate in app/ORM | Default. Index the relation column; cascade in code. |
| Never (small, bounded, unsharded) | Unsharded FK opt-in *is* acceptable | Accept Online DDL friction; document why it won't shard. |

See [no-foreign-keys](references/no-foreign-keys.md) for emulated cascades, ORM specifics, and the opt-in caveats.

## Connecting

Two connection paths. Pick by **runtime**, not by preference.

```ts
// Direct MySQL string — for Node/long-lived servers that can open a TCP socket.
// DATABASE_URL=mysql://user:pass@host/db?ssl-mode=require   (TLS required)

// Serverless HTTP driver — for edge/serverless where raw TCP MySQL is blocked.
import { connect } from "@planetscale/database";

const conn = connect({ url: process.env.DATABASE_URL });
const result = await conn.execute("SELECT id FROM users WHERE email = ?", [email]);
```

`@planetscale/database` is Fetch-API compatible: it speaks HTTP, so it works where you cannot open a
MySQL socket — Cloudflare Workers, Vercel Edge, Lambda. The spelling is exactly `@planetscale/database`;
there is no other official package name. Drizzle ships a matching adapter,
`drizzle-orm/planetscale-serverless`, that wraps this driver — see `../drizzle-orm/SKILL.md` for the
query-builder side.

| Runtime | Connection path | Why |
| --- | --- | --- |
| Node server, long-lived process | Direct `mysql://…?ssl-mode=require` | TCP socket available; pool it. |
| Vercel Edge / Cloudflare Workers | `@planetscale/database` (HTTP) | No raw TCP; the Fetch-based driver works. |
| AWS Lambda / short-lived serverless | `@planetscale/database` (HTTP) | Avoids per-invocation connection churn. |
| Drizzle on edge | `drizzle-orm/planetscale-serverless` | Wraps the HTTP driver; same constraints. |

## CI/CD

Wire the deploy-request flow into CI so schema changes are reviewed like code. A GitHub Actions job
installs `pscale`, authenticates with a service token (`PLANETSCALE_SERVICE_TOKEN` /
`PLANETSCALE_SERVICE_TOKEN_ID` as secrets), then drives the same verbs you run locally:

```yaml
# .github/workflows/schema.yml — open + diff a deploy request on PR
- run: |
    pscale deploy-request create "$DB" "${{ github.head_ref }}" --disable-auto-apply
    pscale deploy-request diff   "$DB" "$DR_NUMBER"   # surface the schema diff in the PR
```

For a **branch-per-PR preview database**, create a PlanetScale branch named after the PR head, run the
app's migrations against it, and tear the branch down when the PR closes. The orchestration (matrix,
secrets, cleanup-on-close) is generic CI — defer the Actions plumbing to `../github-actions/SKILL.md`
and keep the PlanetScale verbs here.

## Anti-patterns

| Anti-pattern | Why it bites | Do instead |
| --- | --- | --- |
| `ALTER TABLE` on the `main` production branch | Skips the gate; no diff, no review, no revert window | Branch → DDL → deploy request → diff → deploy |
| Relying on DB-enforced foreign keys at scale | Blocks sharding, fights Online DDL, degrades high-concurrency writes | App/ORM-level integrity; `relationMode="prisma"`; index the relation column |
| Leaving auto-apply ON for a destructive change | Deploy + cutover happen in one motion; no gated last-look before the drop | `--disable-auto-apply`, inspect, then `deploy-request apply` |
| Opening a direct `mysql://` connection from Vercel Edge / Workers | Raw TCP MySQL is blocked on edge runtimes → connection timeouts | Use `@planetscale/database` HTTP driver |
| Treating revert as available forever | The window is **~30 min** and excludes dropped tables/cols and FK changes | Plan rollbacks as new forward deploys |
| Deploying without reading `deploy-request diff` | You ship DDL you never saw; surprise table rewrites | Always run the diff before `deploy` |
| Inventing a driver name (`@planetscale/serverless`, `planetscale-js`) | There is no such package; install fails | The package is exactly `@planetscale/database` |
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