PlanetScale Explained: The Deploy Request Workflow and Why It Changes Schema Migrations

PlanetScale's deploy request workflow is the most misunderstood part of the platform. For developers coming from traditional Postgres or MySQL, the lack of foreign key constraints and the branch-based schema change model feel backwards. This guide explains why it works this way, how to work with it, and when it's the right database for your project.

What PlanetScale Actually Is

PlanetScale is a MySQL-compatible database built on Vitess — the database system YouTube has used since 2011 to scale MySQL to billions of rows. It's designed for high-availability, horizontal sharding, and zero-downtime schema changes. The trade-offs include no foreign key constraints and a more structured migration process.

The Deploy Request Workflow

Traditional ALTER TABLE on a busy MySQL table locks the table, potentially for minutes. PlanetScale's deploy request uses Vitess's online schema change (OSC) tool to run migrations non-blocking — your app keeps running with zero downtime while the migration completes in the background.

1. Create a development branch from main: planetscale branch create feat/add-embeddings main
2. Connect to the dev branch and run your schema changes (ALTER TABLE, CREATE INDEX, etc.)
3. Create a deploy request: a diff of the schema changes between the branch and main
4. Review the deploy request — PlanetScale shows you exactly what SQL will run
5. Deploy: PlanetScale runs the migration on main using online schema change, non-blocking

# Install PlanetScale CLI
brew install planetscale/tap/pscale
pscale auth login
 
# Create a branch for schema changes
pscale branch create my-database feat/add-embeddings --from main
 
# Connect to the branch (opens a local proxy on 3306)
pscale connect my-database feat/add-embeddings --port 3306
 
# In a separate terminal, run your migration
mysql -h 127.0.0.1 -P 3306 -u root
# ALTER TABLE documents ADD COLUMN embedding JSON;
 
# Create a deploy request
pscale deploy-request create my-database feat/add-embeddings
 
# Deploy it
pscale deploy-request deploy my-database 1

No Foreign Key Constraints: Why and How to Handle It

PlanetScale deliberately omits foreign key constraints because they conflict with horizontal sharding. When a table is split across multiple shards, cross-shard foreign key enforcement is impossible.

This doesn't mean you can't have referential integrity — it means you enforce it in application code rather than the database.

# Instead of relying on FK constraints, validate in application code
def create_document_chunk(document_id: str, chunk_text: str):
    # Verify parent exists before inserting child
    doc = db.execute(
        'SELECT id FROM documents WHERE id = %s', (document_id,)
    ).fetchone()
 
    if not doc:
        raise ValueError(f'Document {document_id} not found')
 
    db.execute(
        'INSERT INTO document_chunks (document_id, chunk_text) VALUES (%s, %s)',
        (document_id, chunk_text)
    )

ORMs like Prisma handle referential integrity checks in application code automatically when you define relations — even on databases that don't enforce foreign keys at the database level.

Connecting from Next.js with Prisma

npm install prisma @prisma/client
npx prisma init

// schema.prisma
datasource db {
  provider     = "mysql"
  url          = env("DATABASE_URL")
  relationMode = "prisma"  // handles FK logic in Prisma, not DB
}
 
model Document {
  id        String   @id @default(cuid())
  title     String
  content   String   @db.LongText
  chunks    Chunk[]
  createdAt DateTime @default(now())
}
 
model Chunk {
  id         String   @id @default(cuid())
  documentId String
  document   Document @relation(fields: [documentId], references: [id])
  chunkText  String   @db.Text
  @@index([documentId])
}

When PlanetScale Is the Right Choice

• High-volume MySQL workloads that need horizontal scaling without sharding your own database
• Teams with strict zero-downtime requirements where ALTER TABLE locks are unacceptable
• Applications already on MySQL that want managed hosting with branching

PlanetScale is likely not the right choice if: you need foreign key constraints enforced at the database level, you prefer Postgres (pgvector, PL/pgSQL, jsonb), or your workload is small enough that Neon or Supabase's Postgres simplicity outweighs the scaling benefits.