PlanetScale

PlanetScale is a serverless database platform compatible with MySQL. It is built on Vitess, the technology used by YouTube/Slack to scale massively.

When to Use

• Horizontally Scaled MySQL (Vitess): Scaling relational MySQL applications to millions of queries per second without manual sharding.
• Non-Blocking Schema Migrations: Executing online DDL schema changes on live multi-terabyte tables with zero downtime and zero locking.
• Database Branching & Developer Workflows: Branching production databases for local development and merging schema changes via Deploy Requests.
• Serverless Web Applications: Querying MySQL from serverless environments over HTTP using the PlanetScale serverless driver.

Quick Start

Uses standard MySQL drivers.

# Connect via CLI
pscale shell my-database main

Core Concepts

Vitess Horizontal Sharding Architecture

VTGate proxies route queries transparently across underlying VTTablet MySQL instances based on a VSchema keyspace:

[ Application Client ] ──→ [ VTGate Stateless Proxy ]
                                    ├── Routes to Shard 1 (-80)
                                    └── Routes to Shard 2 (80-)

Non-Blocking Online DDL & Deploy Requests

Applies schema changes via an isolated shadow table in the background, syncing changes asynchronously before an atomic cutover:

# 1. Create a development schema branch
pscale branch create my-database add-indexes

# 2. Apply migration on dev branch
pscale shell my-database add-indexes
# SQL: ALTER TABLE orders ADD INDEX idx_status (status);

# 3. Create Deploy Request to merge into production safely
pscale deploy-request create my-database add-indexes

PlanetScale Serverless Driver over Fetch / HTTP

Executes queries over HTTP/1.1 and HTTP/2 without persistent TCP connections:

import { connect } from "@planetscale/database";

const conn = connect({ url: process.env.DATABASE_URL });
const response = await conn.execute(
  "SELECT id, name FROM users WHERE active = :active",
  { active: 1 },
);
console.log("Users:", response.rows);

Common Patterns

Non-Blocking Deploy Requests for Zero-Downtime Migrations

Problem: Running ALTER TABLE on large production MySQL tables locks reads/writes and causes outages.

Solution: Use PlanetScale deploy requests to test changes on a branch and apply online:

# 1. Create a schema development branch
pscale branch create my-db add-index-branch

# 2. Apply ALTER schema change safely on the branch
pscale shell my-db add-index-branch < schema_update.sql

# 3. Create deploy request to merge into main branch with zero downtime
pscale deploy-request create my-db add-index-branch

Best Practices

Do:

• Always Use Deploy Requests for Migrations: Never attempt manual DDL migrations in production; let PlanetScale coordinate non-blocking cutovers.
• Define a Sharding Key (VSchema) Early: If planning to shard, select a high-cardinality sharding key (e.g. user_id or tenant_id).
• Use Safe Migrations Mode: Enable Safe Migrations on production branches to block accidental direct DDL executions.
• Leverage the Serverless Driver: Use @planetscale/database for serverless environments (Vercel, AWS Lambda, Cloudflare).

Don't:

• Use Foreign Key Constraints in Sharded Keyspaces: Vitess does not support distributed foreign key constraints; enforce integrity in application logic.
• Use auto-incrementing integers across sharded tables: Use distributed ID generators (UUIDv7, Snowflake IDs).
• Execute cross-shard joins frequently: Distributed joins across multiple shards incur heavy network latency.

Troubleshooting

References

• PlanetScale Documentation