planetscale-drizzle

name	planetscale-drizzle
description	Use when working with Drizzle ORM against this repo's PlanetScale MySQL (Vitess) database in @db/app — adding or changing mysqlTable schema, generating or applying migrations, planning a production deploy request, or hitting a Vitess/MySQL limit such as foreign keys, missing RETURNING, schema-lint rejections, or connection latency.

PlanetScale + Drizzle (@db/app)

@db/app is Drizzle ORM on PlanetScale MySQL (Vitess) — a single driver, drizzle-orm/planetscale-serverless, identical in local dev and production. This skill maps the repo's conventions to the official PlanetScale docs worth fetching for schema, migration, and deploy work.

Engine-level depth: load the mysql and vitess skills. Inspecting the live database: load lightfast-db. Canonical commands: db/CLAUDE.md.

Repo conventions at a glance

Rule	Detail
One driver	drizzle-orm/planetscale-serverless + @planetscale/database. Never import @planetscale/* directly — the client comes from @vendor/db (createDatabase).
Schema files	mysqlTable("lightfast_<snake_case>", …); lightfast_ prefix always; column builders imported from drizzle-orm/mysql-core. Follow existing db/app/src/schema/tables/.
No mysql2	Must not appear anywhere in the workspace. drizzle-kit prefers mysql2 over @planetscale/database and would route migrations over TCP, which PlanetScale branches don't expose. Load-bearing omission.
drizzle-kit	dialect: "mysql" (via createDrizzleConfig in @vendor/db) — not "planetscale", which isn't a valid value. tablesFilter: ["lightfast_*"].
No RETURNING	MySQL has none. Use .$returningId() (returns { id } only). Need other columns? Pre-compute client-side (e.g. nanoid() in a $defaultFn) or follow with a SELECT. Example: db/app/src/utils/org-binding.ts.
Migrations	pnpm db:generate runs offline from db/app/; local dev applies schema with pnpm db:push to the worktree branch; CI runs pnpm db:migrate against persistent staging, then deploys staging → main. Never hand-write or edit .sql.
Local dev	Per-worktree PlanetScale branch provisioned by lightfast-local-infra (db up). Runtime credentials live in apps/app/.env.overrides.local.
Foreign keys	Vitess FK support is limited; the repo avoids references(). Prefer application-level referential integrity.

Official PlanetScale docs — fetch when relevant

llms.txt is the full searchable index; the rest are pages worth fetching directly.

Topic	URL
Full docs index	https://planetscale.com/docs/llms.txt
Drizzle ↔ PlanetScale connect (MySQL)	https://orm.drizzle.team/docs/connect-planetscale
PlanetScale workflow / best practices	https://planetscale.com/docs/vitess/best-practices.md
Non-blocking schema changes	https://planetscale.com/docs/vitess/schema-changes.md
Deploy requests	https://planetscale.com/docs/vitess/schema-changes/deploy-requests.md
Safe migrations (zero-downtime, reverts)	https://planetscale.com/docs/vitess/schema-changes/safe-migrations.md
Schema-change recipes by type	https://planetscale.com/docs/vitess/schema-changes/how-to-make-different-types-of-schema-changes.md
Table / column renames	https://planetscale.com/docs/vitess/schema-changes/handling-table-and-column-renames.md
Schema lint errors (rejected deploys)	https://planetscale.com/docs/vitess/schema-changes/schema-lint-errors.md
Schema branching	https://planetscale.com/docs/vitess/schema-changes/branching.md
Foreign key constraints	https://planetscale.com/docs/vitess/foreign-key-constraints.md
Sequences / AUTO_INCREMENT on sharded keyspaces	https://planetscale.com/docs/vitess/sharding/sequence-tables.md
Connection strings	https://planetscale.com/docs/vitess/connecting/connection-strings.md
Network latency (HTTP driver)	https://planetscale.com/docs/vitess/connecting/network-latency.md
CLI — branch / deploy-request / shell	https://planetscale.com/docs/cli/branch.md · /docs/cli/deploy-request.md · /docs/cli/shell.md
AI tooling (skills, MCP server)	https://planetscale.com/docs/connect/ai-tooling.md

Common mistakes

• Reaching for .returning() (a Postgres-ism). MySQL → .$returningId().
• Adding mysql2 to clear a drizzle-kit error — it silently breaks PlanetScale migrations.
• Importing @planetscale/database directly instead of going through @vendor/db.
• Hand-editing a migration .sql file instead of re-running pnpm db:generate.
• Adding references() / FKs without first checking the FK constraints + schema-lint docs.
• Assuming a Drizzle column rename is safe — drizzle-kit emits drop+add; see the renames doc.