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`).

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 aboutRoute 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 conceptGit analogueWhat it actually is
BranchbranchA full, isolated copy of the schema. main is your production branch.
Deploy requestpull requestThe gate that carries schema from a dev branch to production.
Schema diffthe PR diffThe exact DDL the deploy will run, computed by PlanetScale.
Online DDL(no git analogue)Shadow table + VReplication + non-blocking cutover. No ALTER lock.
Schema revertrevert commitA ~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):

# 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.

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.

-- 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:

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 strategyNotes
Yes, or unsureNo DB FK — emulate in app/ORMDefault. Index the relation column; cascade in code.
Never (small, bounded, unsharded)Unsharded FK opt-in is acceptableAccept Online DDL friction; document why it won't shard.

See no-foreign-keys for emulated cascades, ORM specifics, and the opt-in caveats.

Connecting

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

// 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.

RuntimeConnection pathWhy
Node server, long-lived processDirect mysql://…?ssl-mode=requireTCP 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 edgedrizzle-orm/planetscale-serverlessWraps 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:

# .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-patternWhy it bitesDo instead
ALTER TABLE on the main production branchSkips the gate; no diff, no review, no revert windowBranch → DDL → deploy request → diff → deploy
Relying on DB-enforced foreign keys at scaleBlocks sharding, fights Online DDL, degrades high-concurrency writesApp/ORM-level integrity; relationMode="prisma"; index the relation column
Leaving auto-apply ON for a destructive changeDeploy + 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 / WorkersRaw TCP MySQL is blocked on edge runtimes → connection timeoutsUse @planetscale/database HTTP driver
Treating revert as available foreverThe window is ~30 min and excludes dropped tables/cols and FK changesPlan rollbacks as new forward deploys
Deploying without reading deploy-request diffYou ship DDL you never saw; surprise table rewritesAlways run the diff before deploy
Inventing a driver name (@planetscale/serverless, planetscale-js)There is no such package; install failsThe package is exactly @planetscale/database
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 319kUpdated 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: 196kUpdated 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: 118kUpdated 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: 117kUpdated Claude CodeCodexVerifiedInstall