/api-baas-planetscale

name: api-baas-planetscale
description: Serverless MySQL platform with branching, deploy requests, and edge-compatible driver

PlanetScale Serverless MySQL Patterns

> **Quick Guide:** Use `@planetscale/database` for edge/serverless MySQL access via HTTP (Fetch API). Use `Client` to create per-request connections, `conn.execute()` for parameterized queries, and `conn.transaction()` for atomic operations. Never run DDL directly on production -- use deploy requests with safe migrations enabled. PlanetScale runs on Vitess: foreign keys are supported but opt-in, stored procedures are not supported, and all schema changes go through online DDL. The built-in `cast` handles regular integers and floats automatically, but provide a custom `cast` for BigInt, Date, and boolean columns. Branch your database like git branches for dev/preview environments.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST use `conn.execute(sql, params)` with parameterized queries -- never interpolate user input into SQL strings)**

**(You MUST use deploy requests for ALL schema changes on production branches with safe migrations enabled -- direct DDL is rejected)**

**(You MUST create a fresh `Client.connection()` per request in serverless environments -- do not reuse connections across invocations)**

**(You MUST handle the Vitess/MySQL compatibility differences: no stored procedures, no `RENAME COLUMN` via direct DDL, no `:=` operator, no `LOAD DATA INFILE`)**

**(You MUST provide a custom `cast` function for BigInt (INT64/UINT64), Date (DATETIME/TIMESTAMP), and boolean (TINYINT(1)) columns -- the default cast handles regular integers and floats but leaves these as strings)**

</critical_requirements>

---

**Auto-detection:** PlanetScale, @planetscale/database, planetscale serverless driver, pscale, deploy request, safe migrations, Vitess, database branching, planetscale branch, planetscale boost, mysql serverless, pscale CLI, planetscale connection

**When to use:**

• Querying MySQL from edge/serverless functions via the PlanetScale serverless driver
• Managing schema changes through deploy requests and safe migrations
• Creating database branches for dev, preview, or CI environments
• Setting up connections with `@planetscale/database` (host/username/password or URL)
• Running transactions in serverless contexts
• Handling Vitess-specific SQL compatibility constraints
• Programmatic branch management via `pscale` CLI

**Key patterns covered:**

• `connect()` / `Client` connection setup with host, username, password
• `conn.execute()` with positional (`?`) and named (`:param`) parameters
• `conn.transaction()` for atomic multi-statement operations
• Custom `cast` functions for type-safe value conversion (BigInt, Date, boolean)
• Deploy request workflow (branch, change schema, create DR, review, deploy)
• Safe migrations and the no-direct-DDL enforcement model
• Database branching for dev/preview/CI environments
• Vitess SQL compatibility constraints and workarounds
• `pscale` CLI for branch and deploy request management

**When NOT to use:**

• Long-running server processes with persistent TCP MySQL connections (use `mysql2` driver)
• Complex ORM-specific patterns (use your ORM's own skill)
• General MySQL query syntax (use a SQL/MySQL skill)
• PostgreSQL workloads (use Neon or another Postgres provider)

**Detailed Resources:**

• For decision frameworks, CLI reference, and quick lookup tables, see [reference.md](reference.md)

**Driver & Queries:**

• [examples/core.md](examples/core.md) -- Connection setup, parameterized queries, transactions, type casting

**Branching & Schema Changes:**

• [examples/branching.md](examples/branching.md) -- Dev branches, deploy requests, safe migrations, pscale CLI, CI/CD workflows

---

<philosophy>

Philosophy

PlanetScale is a serverless MySQL platform built on Vitess, the same technology that powers YouTube's database infrastructure. The `@planetscale/database` driver uses HTTP (Fetch API) instead of TCP, making MySQL accessible from edge runtimes that lack TCP support.

**Core principles:**

1. **HTTP-based, stateless connections** -- Every query is an HTTP request. There are no persistent connections to manage, no connection pools to configure. Create a connection, execute queries, done. PlanetScale handles connection pooling at the infrastructure level (Vitess VTTablet + Global Routing). 2. **Schema changes via deploy requests, never direct DDL** -- Production branches with safe migrations reject direct `CREATE`, `ALTER`, `DROP` statements. All schema changes go through deploy requests: branch, modify schema on the branch, create a deploy request, review the diff, deploy with zero downtime via online DDL. 3. **Branches are cheap** -- Database branches are isolated copies of your schema (and optionally data). Create them for feature development, PR previews, CI runs. Delete when done. 4. **Vitess under the hood** -- PlanetScale runs Vitess, which adds horizontal scaling but introduces SQL compatibility differences. No stored procedures, no `RENAME COLUMN` in DDL, no `:=` operator. Foreign keys are supported but opt-in and come with performance trade-offs. 5. **Default cast handles common types, customize for the rest** -- The driver's built-in `cast` function automatically converts INT8-32 and FLOAT32/64 to JavaScript numbers, and parses JSON. However, INT64/UINT64 (BigInt), DATETIME/TIMESTAMP (Date), DECIMAL, and TINYINT(1) (boolean) remain as strings -- provide a custom `cast` function for these.

**When to use PlanetScale serverless driver:**

• Edge/serverless functions that cannot open TCP connections
• Applications using PlanetScale's branching and deploy request workflow
• High-concurrency serverless apps benefiting from PlanetScale's infrastructure-level pooling
• Teams wanting git-li