PlanetScale Basics Cheat Sheet

Introduces PlanetScale's Git-style branching workflow for MySQL schema changes, deploy requests, the pscale CLI, and connecting from application code.

2 PagesBeginnerMar 5, 2026

pscale CLI Setup

Authenticate, create a database, and open a branch shell.

bash

# Install the pscale CLI, then authenticatebrew install planetscale/tap/pscalepscale auth login# Create a database (its default branch is called "main")pscale database create my_app --region us-east# Open an interactive MySQL shell against a branchpscale shell my_app main

Branch & Deploy Request Workflow

Make schema changes on a branch, then merge them into main via a deploy request.

bash

# Create a development branch to make schema changes onpscale branch create my_app add-orders-table# Open a secure local proxy to the branch and connect any MySQL clientpscale connect my_app add-orders-table --port 3309# In another terminal: run DDL against the branchmysql -h 127.0.0.1 -P 3309 -u root <<'SQL'ALTER TABLE orders ADD COLUMN discount_code VARCHAR(20);SQL# Open a deploy request (like a pull request for schema)pscale deploy-request create my_app add-orders-table# Review it, then deploy — applies the diff to main with minimal lockingpscale deploy-request deploy my_app <deploy-request-number>

Connecting from Node.js

Connect to a PlanetScale branch from application code with mysql2 (TLS required).

javascript

import mysql from 'mysql2/promise'const connection = await mysql.createConnection({  host: process.env.DATABASE_HOST,        // e.g. aws.connect.psdb.cloud  user: process.env.DATABASE_USERNAME,  password: process.env.DATABASE_PASSWORD,  database: 'my_app',  ssl: { rejectUnauthorized: true },       // PlanetScale requires TLS})const [rows] = await connection.execute(  'SELECT * FROM orders WHERE customer_id = ?',  [customerId])

Core Concepts

Terminology and behavior specific to PlanetScale's workflow.

Branching workflow- Every schema change happens on a database branch (like a Git branch); production workflows never run DDL directly against main.
Deploy requests- PlanetScale's equivalent of a pull request for schema — diffs the branch against the target branch and applies changes using online, non-blocking DDL.
Built on Vitess- PlanetScale runs on Vitess, the MySQL sharding middleware originally built at YouTube, giving it horizontal scalability beyond a single MySQL instance.
Non-blocking schema changes- Deploy requests use online schema-change tooling so ALTER TABLE on large tables doesn't hold long locks against production writes.
Connection via secure proxy- pscale connect opens a local proxy so you can use any standard MySQL client without exposing raw database credentials.
Safe migrations- When enabled on a branch, PlanetScale can block schema changes that aren't backward-compatible, such as dropping a column the app still reads.
MySQL-compatible- Standard MySQL client libraries and the MySQL wire protocol work unmodified; PlanetScale is not a fork with a different query language.

Pro Tip

Keep each branch's schema change small and focused — large, multi-table deploy requests are harder to review, and PlanetScale's online schema-change process takes longer and holds resources longer the bigger the diff.

Was this cheat sheet helpful?

Supabase Basics Cheat Sheet

Azure CLI Cheat Sheet

Explore Topics

#PlanetScaleBasics#PlanetScaleBasicsCheatSheet#Database#Beginner#PscaleCLISetup#Branch#Deploy#Request#Databases#Git#DevOps#CommandLine#CheatSheet#SkillVeris

Sri Hayavadhana Info-Tech

Professional Web Designing Services