PlanetScale

PlanetScale is serverless MySQL with a Git-like branching workflow. Great for teams that need MySQL compatibility.

Table of Contents

• Overview
• Quick Start
  • 1. Create Account
  • 2. Install CLI (Optional)
  • 3. Create Database
  • 4. Create Branch Password
  • 5. Configure Juntos
  • 6. Deploy
• Environment Variables
• Branching Workflow
  • Create a Branch
  • Make Schema Changes
  • Create Deploy Request
  • Review and Merge
• Safe Migrations
  • Deploy Requests
• Foreign Key Considerations
• Connection String Format
• Regions
• Troubleshooting
  • Access denied
  • Foreign key errors
  • Connection timeout
• Insights
• Pricing
• Resources

Overview

Quick Start

1. Create Account

Sign up at planetscale.com (GitHub login available).

2. Install CLI (Optional)

# macOS
brew install planetscale/tap/pscale

# Linux
curl -sSfL https://get.planetscale.com/download | bash

3. Create Database

Via Dashboard:

1. Click New database
2. Choose a region
3. Name your database

Via CLI:

pscale auth login
pscale database create myapp --region us-east

4. Create Branch Password

1. Go to Branches → main
2. Click Connect
3. Select Node.js → @planetscale/database
4. Copy the connection string

5. Configure Juntos

Add to .env.local:

PLANETSCALE_URL=mysql://username:password@aws.connect.psdb.cloud/myapp?ssl={"rejectUnauthorized":true}

6. Deploy

bin/juntos db:prepare -d planetscale
bin/juntos deploy -d planetscale

Environment Variables

Branching Workflow

PlanetScale’s killer feature is database branching—like Git for your schema.

Create a Branch

# Via CLI
pscale branch create myapp add-users

# Or via dashboard

Make Schema Changes

Connect to your branch and run migrations:

# Point to development branch
PLANETSCALE_URL=mysql://...@add-users.aws.connect.psdb.cloud/myapp

bin/juntos db:migrate -d planetscale

Create Deploy Request

pscale deploy-request create myapp add-users

Review and Merge

1. Review the schema diff in dashboard
2. Approve the deploy request
3. PlanetScale applies changes to main without downtime

Safe Migrations

PlanetScale uses Vitess for online schema changes. Large tables can be altered without locking:

# This won't lock the users table
add_column :users, :avatar_url, :string

Deploy Requests

For production changes, use deploy requests instead of direct migrations:

1. Create branch: pscale branch create myapp feature
2. Run migrations on branch
3. Create deploy request
4. Review schema diff
5. Merge when ready

Foreign Key Considerations

PlanetScale doesn’t enforce foreign keys at the database level (Vitess limitation). Instead:

• Use application-level validations
• The schema still documents relationships
• Referential integrity is your responsibility

# Foreign keys are documented but not enforced
class Comment < ApplicationRecord
  belongs_to :post
  validates :post, presence: true  # Application-level enforcement
end

Connection String Format

PlanetScale provides different connection formats. Use the @planetscale/database format for serverless:

mysql://username:password@aws.connect.psdb.cloud/database?ssl={"rejectUnauthorized":true}

Important: The SSL parameter is required for secure connections.

Regions

Choose a region close to your deployment:

Troubleshooting

Access denied

1. Verify your password hasn’t expired
2. Create a new password in the dashboard
3. Update .env.local

Foreign key errors

PlanetScale doesn’t support foreign key constraints. Remove foreign_key: true from migrations:

# Instead of:
add_reference :comments, :post, foreign_key: true

# Use:
add_reference :comments, :post

Connection timeout

PlanetScale connections may timeout after 5 minutes of inactivity. The adapter handles reconnection automatically.

Insights

PlanetScale provides query insights in the dashboard:

• Slow queries
• Query patterns
• Index recommendations

Use these to optimize your application.

Pricing

The free tier is suitable for small to medium applications.

Resources

• PlanetScale Documentation
• PlanetScale CLI Reference
• Branching Overview