ericrisco/rsc-harness / skills/planetscale
planetscale
VerifiedUse 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`).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.0 KB |
| evals/README.md | markdown | 912 B |
| evals/cases.yaml | config | 4.0 KB |
| references/deploy-requests.md | markdown | 3.9 KB |
| references/no-foreign-keys.md | markdown | 3.8 KB |
| scripts/verify.shexecutable | script | 4.8 KB |
references/no-foreign-keys.md
View on GitHub# Designing without foreign keys on PlanetScale
Offloaded depth from SKILL.md §"Design without foreign keys". The body has the rule and one Bad→Good
fence; this file covers emulated cascades, the ORM specifics, and the unsharded opt-in caveats.
## Why FKs fight Vitess
Two of Vitess's first-class features make native FKs a poor default:
- **Horizontal sharding** — a foreign key between rows on different shards has no meaning; the
constraint cannot be enforced across the shard boundary.
- **Online DDL** — FK constraints complicate the shadow-table copy + cutover dance.
On top of that, FK constraint checks add per-write overhead that **degrades high-concurrency
workloads**. PlanetScale historically disallowed FKs entirely; they are now an **opt-in but
unsharded-only** feature. So the scale-safe default is app-level referential integrity.
## Emulated relations
You keep the relationship — you just stop asking the database to enforce it.
- **Index the relation column.** A non-FK relation still needs its index for join/lookup performance.
`KEY idx_orders_user_id (user_id)`.
- **Enforce existence in the app/ORM.** Validate that `user_id` points at a real user before insert.
- **Cascade explicitly.** There is no `ON DELETE CASCADE`. Delete dependents yourself, in a
transaction or a background job:
```sql
-- App-side cascade, in one transaction (or a queued job for large fan-out):
START TRANSACTION;
DELETE FROM order_items WHERE order_id IN (SELECT id FROM orders WHERE user_id = ?);
DELETE FROM orders WHERE user_id = ?;
DELETE FROM users WHERE id = ?;
COMMIT;
```
For large fan-out, prefer a batched background job over one giant transaction so you do not hold writes.
## Prisma: relationMode = "prisma"
Setting `relationMode = "prisma"` tells Prisma to emulate relations in the client instead of emitting
DB-level foreign keys. Prisma then also creates the **implicit indexes** on relation scalar fields that
a real FK would have given you for free.
```prisma
datasource db {
provider = "mysql"
url = env("DATABASE_URL")
relationMode = "prisma"
}
model Order {
id BigInt @id @default(autoincrement())
userId BigInt
user User @relation(fields: [userId], references: [id])
@@index([userId]) // required under relationMode="prisma" — no implicit FK index from the DB
}
```
ORM-client ergonomics beyond this knob belong to `../../prisma-orm/SKILL.md`, not here.
## Drizzle: app-level relations
Drizzle models relations in app code via `relations()` and queries them with the relational API. On
PlanetScale you index the join column and skip the `references()`-backed DB constraint; the relation
lives in code, not in the database. The query-builder side is `../../drizzle-orm/SKILL.md`.
## The unsharded FK opt-in
Native FKs are available again, but **only on unsharded keyspaces**. It is acceptable to use one when:
- you are certain the table will **never** shard (small, bounded, low-write reference data), and
- you accept the extra Online DDL friction the FK introduces, and
- you remember that FK constraint changes are **excluded from clean schema reverts** (see
deploy-requests.md).
If any of those is shaky, default back to emulated relations. Document *why* a given table is allowed
an FK so the next person does not "fix" it.
## Bad → Good patterns
| Pattern | Bad on PlanetScale at scale | Good |
| --- | --- | --- |
| Relation | DB `FOREIGN KEY … REFERENCES` | Indexed column + app/ORM-emulated relation |
| Delete dependents | `ON DELETE CASCADE` | Explicit transactional or batched delete in app code |
| Index on relation column | Relying on the FK's implicit index | Declare the index yourself (`@@index`, `KEY`) |
| Integrity guarantee | "the database will reject orphans" | Validate before write; reconcile orphans in a job |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 119k | Updated | Claude CodeCodex | Verified | Install |
| 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: 118k | Updated | Claude CodeCodex | Verified | Install |