---
name: planetscale
description: Use when managing relational databases (Vitess, Postgres, or Neki),
  creating branches for schema changes, deploying with zero downtime, monitoring
  query performance, managing backups, 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 offering three engines: **Vitess** (MySQL-compatible with unlimited horizontal sharding), **Postgres** (single-primary PostgreSQL), and **Neki** (Postgres with horizontal sharding). All run on locally-attached NVMe drives for unlimited IOPS and ultra-low latency.

Key files and commands:
- **CLI**: `pscale` (install via `brew install pscale`)
- **API**: `https://api.planetscale.com/v1` (requires service token or OAuth)
- **Authentication**: Service tokens (for automation) or OAuth (for user-facing apps)
- **Primary docs**: https://planetscale.com/docs

## When to use

Reach for this skill when:
- Creating or managing databases (Vitess, Postgres, or Neki)
- Making schema changes with zero downtime (branching + deploy requests)
- Monitoring query performance or investigating slow queries
- Creating backups, restoring data, or managing replicas
- Automating database operations via CLI or API
- Connecting applications to databases
- Scaling databases horizontally (Vitess or Neki)
- Importing data from external databases

## Quick reference

### CLI essentials

| Task | Command |
|------|---------|
| Authenticate | `pscale auth login` |
| Create database | `pscale database create <db>` |
| List databases | `pscale database list --org <org>` |
| Create branch | `pscale branch create <db> <branch>` |
| Connect to branch | `pscale shell <db> <branch>` |
| Execute SQL | `pscale sql <db> <branch> --query "SELECT ..."` |
| Create deploy request | `pscale deploy-request create <db> <branch>` |
| Deploy changes | `pscale deploy-request deploy <db> <number>` |
| Create backup | `pscale backup create <db> <branch>` |
| List backups | `pscale backup list <db>` |
| Create password | `pscale password create <db> <branch>` |
| View query insights | `pscale insights queries <db> <branch>` |
| Agent bootstrap | `pscale agent-guide --format json` |

### API authentication

**Service token (automation):**
```bash
curl -H "Authorization: Bearer <SERVICE_TOKEN>" \
  https://api.planetscale.com/v1/organizations
```

**Service token ID + token (legacy):**
```bash
curl -H "Authorization: <SERVICE_TOKEN_ID>:<SERVICE_TOKEN>" \
  https://api.planetscale.com/v1/organizations
```

### Database engines

| Engine | Use case | Key feature |
|--------|----------|------------|
| **Vitess** | MySQL-compatible, massive scale | Unlimited horizontal sharding |
| **Postgres** | Standard PostgreSQL | Single primary, high availability |
| **Neki** | Postgres at scale | Horizontal sharding for Postgres |

### Connection types

| Type | Use | Port |
|------|-----|------|
| **Primary** | Write queries | 3306 (MySQL) / 5432 (Postgres) |
| **Replica** | Read queries, auto-routes to nearest replica | 3306 / 5432 |
| **Read-only region** | Scoped to specific region | 3306 / 5432 |

## Decision guidance

### When to use branching vs direct schema changes

| Scenario | Approach | Why |
|----------|----------|-----|
| Production database with safe migrations enabled | Create branch → make changes → deploy request | Zero downtime, reversible, team review |
| Development or testing branch | Direct schema changes on branch | Faster iteration, no deploy request needed |
| Large schema changes (>10 tables) | Split across multiple deploy requests | Single deploy request limited to 10 tables |
| Need to revert quickly | Use safe migrations + deploy request | 30-minute revert window with data preservation |

### When to use Vitess vs Postgres vs Neki

| Condition | Choice | Reason |
|-----------|--------|--------|
| MySQL-compatible workload, need sharding | **Vitess** | Battle-tested, unlimited sharding, proven at scale |
| PostgreSQL, single primary sufficient | **Postgres** | Native Postgres, simpler operations |
| PostgreSQL, need horizontal sharding | **Neki** | Postgres sharding without Vitess complexity |
| Unsure if you need sharding | **Postgres or Neki** | Start unsharded, upgrade later if needed |
| Data >250 GB and hitting limits | **Vitess or Neki** | Sharding becomes cost-effective |

### When to use CLI vs API

| Task | CLI | API | Why |
|------|-----|-----|-----|
| One-off operations | ✅ | ❌ | Faster to type |
| Automation/CI-CD | ✅ | ✅ | Both work; API more flexible |
| Programmatic database management | ❌ | ✅ | API designed for this |
| Local development | ✅ | ❌ | CLI is interactive |
| Webhooks/event-driven | ❌ | ✅ | API webhooks only |

## Workflow

### Typical schema change workflow (Vitess/Postgres with branching)

1. **Create a development branch** off production:
   ```bash
   pscale branch create <database> <dev-branch>
   ```

2. **Connect and make schema changes**:
   ```bash
   pscale shell <database> <dev-branch>
   # Run DDL: CREATE TABLE, ALTER TABLE, etc.
   ```

3. **Test changes locally** in your application against the dev branch.

4. **Create a deploy request** to merge into production:
   ```bash
   pscale deploy-request create <database> <dev-branch>
   ```

5. **Review the diff** in the dashboard. Check for conflicts or issues.

6. **Deploy when ready**:
   ```bash
   pscale deploy-request deploy <database> <deploy-request-number>
   ```

7. **Monitor the deployment** in the dashboard. PlanetScale throttles automatically to avoid impact.

8. **If issues arise**, revert within 30 minutes (safe migrations enabled):
   ```bash
   pscale deploy-request revert <database> <deploy-request-number>
   ```

### Typical backup and restore workflow

1. **Create a backup**:
   ```bash
   pscale backup create <database> <branch>
   ```

2. **Poll until ready** (backups take minutes):
   ```bash
   pscale backup show <database> <branch> <backup-id>
   ```

3. **Restore to a new branch**:
   ```bash
   pscale branch create <database> <new-branch> --restore <backup-id>
   ```

4. **Verify data** in the restored branch before deleting the original.

### Typical API workflow (programmatic database creation)

1. **Create a service token** with `create_database` permission.

2. **Create a database**:
   ```bash
   curl -X POST https://api.planetscale.com/v1/organizations/<org>/databases \
     -H "Authorization: Bearer <SERVICE_TOKEN>" \
     -d '{"name":"my-db","engine":"vitess"}'
   ```

3. **Poll until ready** (databases take minutes):
   ```bash
   curl https://api.planetscale.com/v1/organizations/<org>/databases/<db> \
     -H "Authorization: Bearer <SERVICE_TOKEN>"
   ```

4. **Create a password** for the branch:
   ```bash
   curl -X POST https://api.planetscale.com/v1/organizations/<org>/databases/<db>/branches/main/passwords \
     -H "Authorization: Bearer <SERVICE_TOKEN>" \
     -d '{"name":"app-password"}'
   ```

## Common gotchas

- **Polling for resource readiness**: Creating databases, branches, and backups returns immediately but resources aren't ready. Always poll until `state: "ready"` or `ready: true` before using.
- **Service token permissions**: Service tokens require explicit scopes. A token without `create_database` will fail silently. Check token permissions with `pscale service-token show-access <token-id>`.
- **Deploy request limits**: A single deploy request can only alter up to 10 tables. Split large migrations across multiple deploy requests.
- **Safe migrations must be enabled**: Without safe migrations on production, schema changes run directly and can lock tables. Enable in dashboard settings.
- **Foreign key constraints**: Foreign keys require explicit enablement in database settings. Disabling them simplifies some migrations but breaks referential integrity.
- **Replica routing**: Replica passwords auto-route to the nearest replica or read-only region. Don't use replica credentials for writes—they will fail.
- **Connection pooling**: Postgres uses PgBouncer (port 6432) for connection pooling. Direct connections (port 5432) bypass pooling. Use pooling for high-connection workloads.
- **Vitess sharding complexity**: Sharding requires careful vindex selection and query routing. Start with single-shard and migrate to sharding only when necessary.
- **Postgres vs Vitess SQL differences**: Vitess is MySQL-compatible, not Postgres-compatible. Migrating Postgres to Vitess requires SQL rewrites.
- **Backup retention**: Backups are retained per policy. Emergency backups have the same retention as manual backups. Deleting a branch does not delete its backups.
- **API rate limits**: The API has rate limits. Check `X-RateLimit-*` headers in responses. Implement exponential backoff for retries.
- **Webhook delivery**: Webhooks are not guaranteed to be delivered in order. Implement idempotency in webhook handlers.

## Verification checklist

Before submitting work with PlanetScale:

- [ ] **Database is ready**: Polled the API/CLI until `state: "ready"` or `ready: true`
- [ ] **Branch created successfully**: Verified branch exists with `pscale branch list <db>`
- [ ] **Schema changes tested**: Ran changes on dev branch and tested locally
- [ ] **Deploy request created**: Used `pscale deploy-request create` or API
- [ ] **No conflicts**: Reviewed deploy request diff for schema conflicts
- [ ] **Deployment successful**: Monitored deployment in dashboard; no errors
- [ ] **Revert window noted**: If safe migrations enabled, noted 30-minute revert window
- [ ] **Backups exist**: Verified backup was created before major changes
- [ ] **Connection strings correct**: Tested connection with correct host/port/credentials
- [ ] **Monitoring in place**: Set up query insights or alerts for performance issues
- [ ] **Service token scoped**: Verified token has only required permissions (principle of least privilege)
- [ ] **API polling implemented**: For automation, implemented polling with exponential backoff

## Resources

- **Comprehensive page listing**: https://planetscale.com/docs/llms.txt
- **PlanetScale API reference**: https://planetscale.com/docs/api/reference/getting-started-with-planetscale-api
- **CLI reference**: https://planetscale.com/docs/cli
- **Vitess schema changes**: https://planetscale.com/docs/vitess/schema-changes
- **Postgres quickstart**: https://planetscale.com/docs/postgres/tutorials/planetscale-postgres-quickstart
- **Neki overview**: https://planetscale.com/docs/neki

---

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