PlanetScale 是一个无服务器、兼容 MySQL 的数据库平台，其非阻塞式 schema 变更流程构建于 Vitess 之上。本技能提供使用 pscale CLI 操作 PlanetScale 的完整说明。
适用场景
- 需要托管式 MySQL 兼容数据库，并要求零停机迁移。
- 团队希望用类似 Git 的分支方式开发数据库 schema。
- 构建无服务器或边缘应用，需要连接池支持。
- 需要水平分片但不想直接管理 Vitess。
前置条件
- PlanetScale 账号及已批准的预算；需自行查询当前定价（Hobby 免费套餐已于 2024 年停止）。
- 本地安装 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 / list / show / delete 等命令创建、列出、查看和删除数据库。删除为破坏性操作。
分支工作流 PlanetScale 分支类似 Git 分支，但作用于数据库 schema，默认 main 分支为生产分支。可用 pscale branch create 创建开发分支、pscale branch list 列出分支、pscale shell 在分支上打开 shell 执行 schema 变更。文档给出了创建 users 与 orders 表的 SQL 示例，并说明 PlanetScale 在符合条件的非分片 Vitess 数据库上支持选择性启用的外键约束；若未启用，需在应用层确保完整性。
部署请求 部署请求相当于 schema 的 pull request，可展示差异、运行 lint 并以非阻塞方式合并到生产。相关命令包括 pscale deploy-request create / list / diff / deploy / close，部署成功后可删除分支。
连接字符串与代理 用 pscale password create 为分支创建连接凭据，输出包含主机、用户名和密码；用 pscale connect 将分支代理到本地端口，便于本地开发且无需密码。文中还给出了本地与生产环境 DATABASE_URL 的写法示例。
Prisma 集成 提供 prisma/schema.prisma 示例（provider 为 mysql，可选 relationMode 为 prisma），以及用 npx prisma db push 推送 schema 变更、npx prisma generate 生成客户端。
Vitess 功能与查询洞察 可通过 pscale shell 执行 SHOW PROCESSLIST，或在 Web UI 的 Insights 标签查看查询统计，也可用 pscale api 调用 query-statistics。文中还列出查看表大小、索引和 EXPLAIN 查询计划的实用 SQL。
Docker 本地开发 提供 docker-compose.yml 示例，用普通 MySQL 8 容器在离线或快速迭代时本地模拟 PlanetScale。
生产最佳实践
- 每次 schema 变更保持向后兼容；先部署 schema，再部署应用代码。
- 将部署请求评审作为关卡，合并前要求至少一次批准。
- 为无服务器负载启用连接池（如 @planetscale/database 驱动或 Prisma Data Proxy）。
- 每周检查查询洞察，为超过 100 ms 的查询添加索引。
- 设置分支晋升规则，仅特定成员可部署到 main。
- 使用只读区域降低地理分布读取延迟。
故障排查
- pscale connect 提示拒绝访问：运行 pscale auth login。
- 部署请求显示 schema 冲突：检查并对比当前 main 的 schema 差异，在获得授权重建前保留分支工作。
- 外键约束错误：检查支持的约束与设置，不要盲目移除完整性保障。
- 读取延迟高：在新分支添加索引并经部署请求发布。
- 连接数超限：启用受支持的 MySQL/Vitess 连接策略（PgBouncer 是 PostgreSQL 连接池，不适用）。
- pscale connect 挂起：允许到 *.psdb.cloud 的出站 443 流量。
相关技能 mysql（MySQL 调优基础）、database-backups（恢复规划）、postgresql（替代关系型数据库）。
限制
- 基础设施命令可能中断服务：变更状态前确认目标主机与范围，并准备备份或快照。
- 本资料仅为文档导入，未附带上游脚本与模板。