---
name: planetscale
description: Use when managing MySQL (Vitess), PostgreSQL, or Neki databases;
  creating branches and deploy requests; configuring sharding; monitoring query
  performance; connecting applications; or automating database operations via
  CLI or API.
metadata:
  mintlify-proj: planetscale
  version: "1.0"
---

# PlanetScale Skill

## Product summary

PlanetScale is a fully managed relational database platform supporting Vitess (MySQL), PostgreSQL, and Neki (sharded Postgres). Agents use PlanetScale to create and manage databases, make non-blocking schema changes via deploy requests, enable branching for development, configure sharding for scale, monitor query performance, and automate operations through the `pscale` CLI or REST API.

**Key files and commands:**
- CLI: `pscale` (install via `brew install pscale`)
- Authentication: Service tokens (API/CLI automation) or OAuth (user-facing apps)
- Primary docs: https://planetscale.com/docs
- Agent bootstrap: `pscale agent-guide --format json` or `pscale --skill`

## When to use

Reach for this skill when:
- Creating or managing Vitess, PostgreSQL, or Neki databases
- Making schema changes safely via deploy requests (non-blocking migrations)
- Creating development branches for testing schema changes
- Configuring sharding for horizontal scaling (Vitess or Neki)
- Connecting applications to databases (connection strings, roles, credentials)
- Monitoring query performance and anomalies via Insights
- Automating database operations (CLI commands, API calls, GitHub Actions)
- Importing data from external MySQL or PostgreSQL sources
- Setting up backups, replicas, or read-only regions
- Troubleshooting connection issues, query performance, or deployment failures

## Quick reference

### CLI essentials

| Task | Command |
|------|---------|
| Authenticate | `pscale auth login` or use service token with `--service-token` flag |
| Create database | `pscale database create <name>` |
| List databases | `pscale database list --org <org>` |
| Create branch | `pscale branch create <database> <branch-name>` |
| Connect to branch | `pscale shell <database> <branch>` or `pscale connect <database> <branch>` |
| Execute SQL (non-interactive) | `pscale sql <database> <branch> --query "SELECT ..."` |
| Create deploy request | `pscale deploy-request create <database> <branch>` |
| Deploy changes | `pscale deploy-request deploy <database> <number>` |
| Enable safe migrations | `pscale branch update <database> <branch> --enable-safe-migrations` |
| Create password | `pscale password create <database> <branch>` |
| View metrics | `pscale metrics show <database> <branch>` |
| View query insights | `pscale insights queries <database> <branch>` |

### Service token setup

```bash
# Create service token
pscale service-token create <name> --org <org>

# Use in API calls
curl -H "Authorization: Bearer <token>" https://api.planetscale.com/v1/organizations/<org>/databases

# Use in CLI
pscale database list --org <org> --service-token <token>
```

### Connection string format

```
mysql://username:password@host:port/database?sslmode=verify_identity
postgresql://username:password@host:port/database?sslmode=require
```

Port 3306 (MySQL) or 5432 (Postgres) for direct connections; 3306 (MySQL) or 6432 (Postgres) for pooled connections.

### Database types

| Engine | Use case | Key feature |
|--------|----------|------------|
| Vitess | MySQL-compatible, unlimited scale | Horizontal sharding, non-blocking schema changes |
| PostgreSQL | Standard Postgres workloads | High availability, query insights, branching |
| Neki | Postgres with sharding | Horizontal sharding for Postgres, query routing |

## Decision guidance

### When to use deploy requests vs. direct schema changes

| Scenario | Use deploy requests | Use direct changes |
|----------|-------------------|-------------------|
| Production database | ✅ Always (with safe migrations enabled) | ❌ Never |
| Development branch | ✅ Recommended for team review | ✅ OK if solo development |
| Non-blocking migrations | ✅ Required | N/A |
| Instant deployments | ❌ Not compatible | ✅ Use for fast, non-revertible changes |
| Gated deployments | ✅ For long-running migrations | ❌ Not applicable |

### When to use branching vs. direct production changes

| Scenario | Create branch | Direct to production |
|----------|---------------|---------------------|
| Schema testing | ✅ Always | ❌ Never |
| Development work | ✅ Recommended | ❌ Risky |
| Staging environment | ✅ Use with safe migrations | N/A |
| Data branching needed | ✅ Use Data Branching® feature | N/A |

### When to shard (Vitess or Neki)

| Condition | Action |
|-----------|--------|
| Database < 250 GB | Vertical scaling usually sufficient |
| Database > 250 GB + high QPS | Plan sharding strategy |
| Cross-shard queries required | Avoid sharding or use global routing |
| Foreign keys critical | Vitess sharding requires careful planning |

## Workflow

### Typical schema change workflow (Vitess)

1. **Enable safe migrations on production branch** — Run `pscale branch update <db> main --enable-safe-migrations` to prevent accidental direct changes.

2. **Create development branch** — `pscale branch create <db> feature-branch` to get an isolated copy of the schema.

3. **Make schema changes** — Connect to the branch with `pscale shell <db> feature-branch` and run DDL (CREATE, ALTER, DROP).

4. **Test locally** — Verify changes work with your application code before proposing to production.

5. **Create deploy request** — `pscale deploy-request create <db> feature-branch` to propose merging changes to main.

6. **Review schema diff** — Check the diff in the dashboard or CLI; PlanetScale validates for conflicts and lint errors.

7. **Approve if required** — Team members review and approve (if approval is enforced in database settings).

8. **Deploy** — `pscale deploy-request deploy <db> <number>` to run the non-blocking migration.

9. **Monitor** — Watch the deploy progress; replication lag is automatically throttled to avoid production impact.

10. **Revert if needed** — Within 30 minutes, `pscale deploy-request revert <db> <number>` to undo (data written during migration is preserved).

### Typical connection workflow

1. **Create password** — `pscale password create <db> <branch> --name app-password` to generate credentials.

2. **Get connection string** — View in dashboard or `pscale password show <db> <branch>`.

3. **Store securely** — Use environment variables or secrets manager; never commit credentials.

4. **Connect application** — Use connection string in your app's database config (Prisma, Django, Rails, etc.).

5. **Test connection** — `pscale ping` to verify latency; `pscale shell` to test interactively.

### Typical monitoring workflow

1. **Check Query Insights** — `pscale insights queries <db> <branch>` to see slow or frequent queries.

2. **Review anomalies** — `pscale insights anomalies <db> <branch>` to flag unexpected performance drops.

3. **Check metrics** — `pscale metrics show <db> <branch>` for CPU, memory, replication lag.

4. **Identify schema issues** — `pscale insights recommendations <db> <branch>` for suggested DDL improvements.

5. **Optimize or scale** — Add indexes, adjust cluster size, or enable replicas based on findings.

## Common gotchas

- **Safe migrations not enabled** — Deploy requests won't work without safe migrations on the target branch. Always enable it on production: `pscale branch update <db> main --enable-safe-migrations`.

- **Instant deployments can't be reverted** — If you use `--instant` flag or "Deploy changes instantly," you lose the 30-minute revert window. Use only for non-critical changes.

- **Gated deployments block the queue** — A gated deployment holds the serial deploy queue until you apply or cancel it. Other serial deploys wait behind it.

- **Foreign key constraints and sharding** — Sharded keyspaces don't support foreign key constraints. Plan schema carefully before sharding.

- **VSchema misconfiguration breaks routing** — When adding a sharded keyspace, ensure all tables from the unsharded keyspace are added to its VSchema, or queries will fail.

- **Revert data loss scenarios** — Reverting a deploy that dropped a column or table won't recover that data. Data written to the new schema during migration is also lost on revert.

- **Long-running transactions block deploys** — If a deploy can't acquire a table lock, check for long-running transactions. Kill them or wait for them to complete.

- **Connection pooling port confusion** — Port 3306 (MySQL) or 5432 (Postgres) bypasses pooling; port 6432 (Postgres) uses PgBouncer pooling. Choose based on your connection pattern.

- **Service token scopes** — Service tokens have granular access scopes (e.g., `read_branch`, `write_production_branch_vschema`). Verify the token has the required scope for your API call.

- **Approval dismissal on schema change** — If a deploy request is approved and then the schema is updated, the approval is automatically dismissed. Re-approve before deploying.

## Verification checklist

Before submitting work with PlanetScale:

- [ ] Safe migrations enabled on production branch (if using deploy requests)
- [ ] Deploy request created and reviewed (schema diff checked for conflicts)
- [ ] No schema lint errors or warnings in deploy request
- [ ] Approval obtained if required by database settings
- [ ] Connection string tested with application code
- [ ] Credentials stored securely (not in version control)
- [ ] Metrics and query insights checked post-deployment
- [ ] Revert window (30 min) understood if using non-instant deploy
- [ ] Long-running transactions killed before deploying large migrations
- [ ] Sharding plan validated (VSchema correct, no cross-shard queries if possible)

## Resources

- **Comprehensive page listing**: https://planetscale.com/docs/llms.txt
- **Getting started**: https://planetscale.com/docs/vitess/tutorials/planetscale-quick-start-guide
- **Deploy requests & schema changes**: https://planetscale.com/docs/vitess/schema-changes/deploy-requests
- **API reference**: https://planetscale.com/docs/api/reference/getting-started-with-planetscale-api
- **CLI reference**: https://planetscale.com/docs/cli
- **Sharding guide**: https://planetscale.com/docs/vitess/sharding/sharding-quickstart

---

> For additional documentation and navigation, see: https://planetscale.com/docs/llms.txt