planetscale

PlanetScale

使用 PlanetScale 搭建与 MySQL 兼容的无服务器数据库，并通过基于 Vitess 的工作流实现非阻塞式架构变更。

适用场景

• 你需要托管式、与 MySQL 兼容且支持零停机迁移的数据库。
• 你的团队希望像使用 Git 分支一样开发数据库架构。
• 你正在构建可从连接池中受益的无服务器或边缘应用。
• 你需要水平分片，但不想直接管理 Vitess。

前提条件

• 一个 PlanetScale 账户（提供免费套餐）。
• 本地已安装 pscale CLI。
• 如果使用 Prisma 或其他 ORM 集成，需要 Node.js 18+。

安装 pscale CLI

# macOS
brew install planetscale/tap/pscale

# Linux (deb)
curl -fsSL https://github.com/planetscale/cli/releases/latest/download/pscale_linux_amd64.deb -o pscale.deb
sudo dpkg -i pscale.deb

# Verify installation
pscale version

# Authenticate
pscale auth login

创建和管理数据库

# Create a new database
pscale database create my-app --region us-east

# List databases
pscale database list

# Show database info
pscale database show my-app

# Delete a database (destructive)
pscale database delete my-app

分支工作流

PlanetScale 分支的工作方式类似于用于数据库架构的 Git 分支。默认情况下，main 分支是生产分支。

# Create a development branch from main
pscale branch create my-app add-users-table

# List all branches
pscale branch list my-app

# Open a shell on the branch to apply schema changes
pscale shell my-app add-users-table

在分支上应用架构变更

-- Inside the pscale shell on the development branch
CREATE TABLE users (
  id         BIGINT       NOT NULL AUTO_INCREMENT PRIMARY KEY,
  email      VARCHAR(255) NOT NULL,
  name       VARCHAR(255) NOT NULL,
  created_at TIMESTAMP    DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP    DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  UNIQUE KEY idx_users_email (email)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE orders (
  id         BIGINT    NOT NULL AUTO_INCREMENT PRIMARY KEY,
  user_id    BIGINT    NOT NULL,
  total      DECIMAL(10,2) NOT NULL DEFAULT 0.00,
  status     ENUM('pending','paid','shipped','cancelled') DEFAULT 'pending',
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  KEY idx_orders_user_id (user_id),
  KEY idx_orders_status (status)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

PlanetScale 不会在数据库层强制执行外键约束。请改用应用层约束或 Vitess 层路由规则。

部署请求

部署请求相当于数据库架构的拉取请求。它们会显示差异、运行代码检查，并以非阻塞方式合并到生产环境。

# Create a deploy request from branch to main
pscale deploy-request create my-app add-users-table

# List open deploy requests
pscale deploy-request list my-app

# Show diff for a deploy request
pscale deploy-request diff my-app 1

# Deploy (merge) the request
pscale deploy-request deploy my-app 1

# Close without deploying
pscale deploy-request close my-app 1

# Delete the branch after successful deploy
pscale branch delete my-app add-users-table

连接字符串和代理

# Create a password (connection credential) for a branch
pscale password create my-app main production-creds

# Output includes host, username, and password for the connection string:
# mysql://USERNAME:PASSWORD@HOST/my-app?sslmode=verify_identity

# Proxy a branch to localhost for local development (no password needed)
pscale connect my-app add-users-table --port 3306

环境变量模式

# .env (local development using pscale connect)
DATABASE_URL="mysql://[email protected]:3306/my-app"

# .env.production (using PlanetScale connection string)
DATABASE_URL="mysql://USERNAME:[email protected]/my-app?sslaccept=strict"

Prisma 集成

// prisma/schema.prisma
datasource db {
  provider     = "mysql"
  url          = env("DATABASE_URL")
  relationMode = "prisma"   // required — PlanetScale does not support foreign keys
}

model User {
  id        Int      @id @default(autoincrement())
  email     String   @unique
  name      String
  orders    Order[]
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

model Order {
  id        Int      @id @default(autoincrement())
  userId    Int
  total     Decimal  @db.Decimal(10, 2)
  status    String   @default("pending")
  user      User     @relation(fields: [userId], references: [id])
  createdAt DateTime @default(now())

  @@index([userId])
  @@index([status])
}

# Push schema changes to the PlanetScale branch
npx prisma db push

# Generate the Prisma client
npx prisma generate

Vitess 功能和查询洞察

# Open the query insights dashboard
pscale shell my-app main

# Inside the shell, check running queries
SHOW PROCESSLIST;

# Examine query statistics (PlanetScale Insights tab in the web UI)
# Or use the API:
pscale api organizations/my-org/databases/my-app/branches/main/query-statistics

实用的 Vitess 感知型查询

-- Check table sizes
SELECT table_name,
       ROUND(data_length / 1024 / 1024, 2) AS data_mb,
       ROUND(index_length / 1024 / 1024, 2) AS index_mb,
       table_rows
FROM information_schema.tables
WHERE table_schema = 'my-app'
ORDER BY data_length DESC;

-- Show index usage
SHOW INDEX FROM users;

-- Explain a query plan
EXPLAIN SELECT * FROM orders WHERE user_id = 42 AND status = 'paid';

用于本地开发的 Docker 设置

如果你处于离线状态，或希望不使用 CLI 代理、快速迭代，可以使用普通的 MySQL 8 容器在本地模拟 PlanetScale。

# docker-compose.yml
version: "3.9"

services:
  mysql:
    image: mysql:8.0
    restart: unless-stopped
    ports:
      - "3306:3306"
    environment:
      MYSQL_ROOT_PASSWORD: rootpass
      MYSQL_DATABASE: my-app
      MYSQL_USER: myapp
      MYSQL_PASSWORD: secret
    volumes:
      - mysql_data:/var/lib/mysql
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql
    command: >
      --default-authentication-plugin=mysql_native_password
      --character-set-server=utf8mb4
      --collation-server=utf8mb4_unicode_ci

volumes:
  mysql_data:

docker compose up -d
mysql -h 127.0.0.1 -u myapp -psecret my-app

生产环境最佳实践

• 确保每项架构变更都向后兼容；先部署架构，再部署应用代码。
• 将部署请求评审设为上线门槛；合并前至少需要一人批准。
• 为无服务器工作负载启用连接池（使用 @planetscale/database 驱动或 Prisma Data Proxy）。
• 每周监控查询洞察，并为执行时间超过 100 ms 的查询添加索引。
• 设置分支提升规则，仅允许特定团队成员部署到 main。
• 使用只读区域，降低地理位置分散的读取请求的延迟。

故障排除

症状	可能原因	解决方法
执行 pscale connect 时出现 Access denied	CLI 尚未通过身份验证	运行 pscale auth login
部署请求显示“schema conflict”	并发分支修改了同一张表	变基：删除分支，从当前的 main 重新创建分支，然后重新应用变更
出现 foreign key constraint 错误	PlanetScale 不支持外键	使用 relationMode = "prisma" 或移除外键定义
读取延迟较高	查询的列没有索引	通过新分支添加索引，然后创建部署请求
超过 max connections 限制	未启用连接池	使用 @planetscale/database 无服务器驱动或 PgBouncer 风格的代理
pscale connect 挂起	防火墙阻止了 TLS 出站连接	允许向 *.psdb.cloud 的 443 端口发起出站连接

相关技能

• mysql - MySQL 调优基础
• database-backups - 恢复规划
• postgresql - 另一种关系型数据库