Planetscale

# PlanetScale API Skill

## Quick Start
PlanetScale provides branching workflows for MySQL. Install the `@planetscale/database` serverless driver to interact with it seamlessly over HTTP in Edge environments.

```bash
npm install @planetscale/database
```

## Common Workflows
### Non-Blocking Schema Changes
PlanetScale prohibits direct schema modifications in production. You must branch your database, apply the DDL (e.g., via Prisma `db push`), test your application, and then create a Deploy Request in PlanetScale to merge the schema change without locking tables.

## Production Patterns
### Edge Database Access
Traditional MySQL TCP connections (`mysql2`) are difficult in Vercel Edge/Cloudflare Workers due to connection pooling limits. Always utilize the `@planetscale/database` fetch-based driver to eliminate connection overhead and utilize connectionless HTTP execution.

## Error Recovery
Handle standard MySQL errors wrapped by the serverless driver. The driver natively supports fetch retries. However, schema mismatch errors (e.g., querying a column that hasn't merged to `main` yet) require application-level feature flagging during the deploy window.

## Security Notes
PlanetScale passwords represent highly privileged access. Scope your database passwords explicitly (e.g., read-only for analytics branches).

## Performance Considerations
PlanetScale caches connections at the proxy layer, meaning HTTP fetch calls are remarkably fast. However, extremely large payloads over HTTP will incur JSON parsing overhead compared to binary TCP streams. Keep query results paginated.

## Testing Guidance
Integrate the PlanetScale CLI (`pscale`) into your CI/CD. Create a new branch dynamically for every pull request, run your E2E test suite against the branch, and delete it upon success.

## Troubleshooting
If you receive 'Foreign key constraints are not supported', note that PlanetScale relies on application-level relations (e.g., via Prisma's `relationMode = "prisma"`) rather than database-level FKs to ensure horizontal scalability across Vitess shards.

## References
- [PlanetScale Serverless JS](https://github.com/planetscale/database-js)

## Related Skills
- [Vercel](/skills/vercel)
- [Cloudflare](/skills/cloudflare)
- [Clerk](/skills/clerk)

## Why use this skill
Use this when your agent works with **planetscale** — structured patterns beat pasted docs and prevent common hallucinations.

## AI pitfalls
- Inventing column names or schema fields
- Using deprecated driver methods or wrong connection strings
- Omitting connection pooling or transaction boundaries

## Production checklist
- [ ] Migrations version-controlled and applied via CI
- [ ] Connection limits and pooling configured
- [ ] Backups and restore procedure documented

## Related skills
- [`vercel`](../vercel/SKILL.md) — related to
- [`cloudflare`](../cloudflare/SKILL.md) — related to
- [`clerk`](../clerk/SKILL.md) — related to

---
> **Last Verified:** 2026-07-02