planetscale

用途

PlanetScale 是一个基于 Vitess 构建的无服务器 MySQL 兼容数据库平台，主要面向需要托管式 MySQL 兼容数据库、零停机架构变更、类似 Git 的分支式架构开发、连接池支持的无服务器或边缘应用，以及无需直接管理 Vitess 即可实现水平分片的场景。

主要能力

分支工作流：数据库分支类似 Git 分支，默认 main 分支为生产分支。可从 main 创建开发分支，在分支上应用架构变更。
部署请求：相当于数据库架构的 Pull Request，展示差异、运行 lint 检查，并以非阻塞方式合并到生产环境。
非阻塞架构变更：基于 Vitess 实现零停机迁移。
连接池与代理：支持为分支创建连接凭据，也可通过 pscale connect 将分支代理到本地进行开发。
Vitess 特性与查询洞察：可查看运行查询、查询统计、表大小、索引使用情况，并支持 EXPLAIN 查询计划。
水平分片：无需直接管理 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

验证与认证：

pscale version
pscale auth login

创建与管理数据库

pscale database create my-app --region us-east
pscale database list
pscale database show my-app
pscale database delete my-app

分支工作流

pscale branch create my-app add-users-table
pscale branch list my-app
pscale shell my-app add-users-table

在分支的 pscale shell 中应用架构变更，例如创建 users 和 orders 表。注意：PlanetScale 不在数据库层面强制外键，需使用应用层约束或 Vitess 级路由规则。

部署请求

pscale deploy-request create my-app add-users-table
pscale deploy-request list my-app
pscale deploy-request diff my-app 1
pscale deploy-request deploy my-app 1
pscale deploy-request close my-app 1
pscale branch delete my-app add-users-table

连接字符串与代理

pscale password create my-app main production-creds
pscale connect my-app add-users-table --port 3306

环境变量模式示例：

# .env（本地开发，使用 pscale connect）
DATABASE_URL="mysql://root@127.0.0.1:3306/my-app"

# .env.production（使用 PlanetScale 连接字符串）
DATABASE_URL="mysql://USERNAME:PASSWORD@us-east.connect.psdb.cloud/my-app?sslaccept=strict"

Prisma 集成

在 prisma/schema.prisma 中配置 relationMode = "prisma"（必需，因 PlanetScale 不支持外键），定义模型后执行：

npx prisma db push
npx prisma generate

Vitess 特性与查询洞察

pscale shell my-app main
SHOW PROCESSLIST;
pscale api organizations/my-org/databases/my-app/branches/main/query-statistics

可用的 Vitess 感知查询包括查看表大小、显示索引、EXPLAIN 查询计划等。

Docker 本地开发

可使用普通 MySQL 8 容器在本地镜像 PlanetScale，适用于离线或快速迭代场景。提供 docker-compose.yml 示例，包含 MySQL 8.0 服务、环境变量、卷挂载和初始化脚本。

适用场景

需要托管式 MySQL 兼容数据库且要求零停机迁移的团队。
希望为架构开发引入类似 Git 分支工作流的团队。
构建无服务器或边缘应用，需要连接池支持。
需要水平分片但不想直接管理 Vitess。

限制与注意事项

PlanetScale 不在数据库层面强制外键约束，需使用应用层约束或 Vitess 级路由规则。
使用 Prisma 时必须设置 relationMode = "prisma"。
生产最佳实践包括：保持架构变更向后兼容（先部署架构再部署应用代码）、将部署请求审查作为门禁（至少一次批准）、为无服务器工作负载启用连接池、每周监控查询洞察并为超过 100ms 的查询添加索引、设置分支提升规则、使用只读区域降低延迟。
常见问题排查：pscale connect 访问被拒需运行 pscale auth login；部署请求显示“schema conflict”需删除分支并从当前 main 重建后重新应用变更；外键约束错误需使用 relationMode = "prisma" 或移除外键定义；读取高延迟需添加索引；连接数超限需启用连接池；pscale connect 挂起需允许出站 443 到 *.psdb.cloud。

技能介绍

用途