PlanetScale 分支操作 #
数据库分支是 PlanetScale 最具创新性的功能之一，本章将详细介绍如何使用分支进行开发和 Schema 变更。
分支概念回顾 #
分支类型 #
text
┌─────────────────────────────────────────────────────────────┐
│ 分支类型对比 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 生产分支（Production Branch） │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 特点： │ │
│ │ ├── 通常命名为 main │ │
│ │ ├── 包含真实生产数据 │ │
│ │ ├── 受保护，不能直接修改 Schema │ │
│ │ ├── 可以创建连接密码 │ │
│ │ └── 应用连接此分支 │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ 开发分支（Development Branch） │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 特点： │ │
│ │ ├── 从生产分支创建 │ │
│ │ ├── Schema 可以自由修改 │ │
│ │ ├── 不包含生产数据 │ │
│ │ ├── 用于开发和测试 │ │
│ │ └── 变更通过 Deploy Request 合并 │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
分支关系 #
text
┌─────────────────────────────────────────────────────────────┐
│ 分支层级结构 │
├─────────────────────────────────────────────────────────────┤
│ │
│ main (生产) │
│ ┌─────┐ │
│ │ │ │
│ └──┬──┘ │
│ │ │
│ ┌────────────────┼────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ develop │ │ feature │ │ hotfix │ │
│ │ (开发) │ │ (功能) │ │ (修复) │ │
│ └─────────┘ └─────────┘ └─────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────┐ ┌─────────┐ │
│ │ test │ │ exp │ │
│ │ (测试) │ │ (实验) │ │
│ └─────────┘ └─────────┘ │
│ │
│ 注意：开发分支只能从 main 创建 │
│ │
└─────────────────────────────────────────────────────────────┘
创建分支 #
通过 Web 控制台创建 #
text
┌─────────────────────────────────────────────────────────────┐
│ 创建分支界面 │
├─────────────────────────────────────────────────────────────┤
│ │
│ Create a branch │
│ │
│ Branch name │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ add-user-phone-field │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ Parent branch │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ main ▼ │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ Region (optional) │
│ ○ Same as parent (recommended) │
│ ○ Different region │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Create branch │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
通过 CLI 创建 #
bash
# 基本创建
pscale branch create my-database develop
# 从指定父分支创建
pscale branch create my-database feature-x --from main
# 指定区域
pscale branch create my-database develop --region us-east-1
# 查看创建状态
pscale branch show my-database develop
输出示例：
text
NAME PARENT READY CREATED AT
develop main false 2024-01-15 12:00:00
分支命名建议 #
text
┌─────────────────────────────────────────────────────────────┐
│ 分支命名规范 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 功能开发： │
│ ├── feature/add-user-phone │
│ ├── feature/new-auth-system │
│ └── feature/order-status │
│ │
│ Bug 修复： │
│ ├── fix/login-error │
│ ├── hotfix/security-patch │
│ └── bugfix/null-pointer │
│ │
│ 重构： │
│ ├── refactor/user-table │
│ └── refactor/indexes │
│ │
│ 实验： │
│ ├── exp/new-index-strategy │
│ └── exp/partition-test │
│ │
│ 环境： │
│ ├── develop │
│ ├── staging │
│ └── preview │
│ │
└─────────────────────────────────────────────────────────────┘
分支操作 #
查看分支 #
bash
# 列出所有分支
pscale branch list my-database
# 输出示例
NAME PARENT READY CREATED AT
main - true 2024-01-10 10:00:00
develop main true 2024-01-15 12:00:00
feature-auth main true 2024-01-16 09:00:00
# 查看分支详情
pscale branch show my-database develop
# 查看 Schema
pscale branch schema my-database develop
连接分支 #
bash
# 使用 Shell 连接
pscale shell my-database develop
# 使用代理连接
pscale connect my-database develop
# 指定本地端口
pscale connect my-database develop --port 3307
删除分支 #
bash
# 删除分支
pscale branch delete my-database develop
# 确认提示
# Are you sure you want to delete branch "develop"? [y/N] y
# 强制删除
pscale branch delete my-database develop --force
Schema 变更 #
在开发分支修改 Schema #
bash
# 连接到开发分支
pscale shell my-database develop
# 执行 DDL 语句
mysql> ALTER TABLE users ADD COLUMN phone VARCHAR(20);
mysql> CREATE INDEX idx_email ON users(email);
mysql> DROP TABLE old_table;
# 验证变更
mysql> DESCRIBE users;
Schema 变更示例 #
sql
-- 添加列
ALTER TABLE users
ADD COLUMN phone VARCHAR(20),
ADD COLUMN address TEXT;
-- 修改列
ALTER TABLE users
MODIFY COLUMN name VARCHAR(200);
-- 添加索引
CREATE INDEX idx_created_at ON users(created_at);
CREATE UNIQUE INDEX idx_email ON users(email);
-- 创建新表
CREATE TABLE orders (
id INT AUTO_INCREMENT PRIMARY KEY,
user_id INT NOT NULL,
total DECIMAL(10, 2),
status ENUM('pending', 'paid', 'shipped', 'completed'),
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
INDEX idx_user (user_id)
);
-- 删除列
ALTER TABLE users DROP COLUMN deprecated_field;
Schema 变更限制 #
text
┌─────────────────────────────────────────────────────────────┐
│ 变更限制 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 支持的操作： │
│ ✅ ADD COLUMN │
│ ✅ DROP COLUMN │
│ ✅ MODIFY COLUMN │
│ ✅ ADD INDEX │
│ ✅ DROP INDEX │
│ ✅ CREATE TABLE │
│ ✅ DROP TABLE │
│ ✅ RENAME TABLE │
│ │
│ 不支持的操作： │
│ ❌ 添加外键约束 │
│ ❌ 添加触发器 │
│ ❌ 添加存储过程 │
│ ❌ 修改主键（需要特殊处理） │
│ │
│ 注意事项： │
│ - 删除列会永久丢失数据 │
│ - 修改列类型可能导致数据丢失 │
│ - 大表变更需要更多时间 │
│ │
└─────────────────────────────────────────────────────────────┘
Schema 对比 #
查看差异 #
bash
# 对比两个分支的 Schema
pscale branch diff my-database develop main
# 输出示例
# --- main
# +++ develop
# @@ -1,5 +1,6 @@
# CREATE TABLE users (
# id INT AUTO_INCREMENT PRIMARY KEY,
# name VARCHAR(100) NOT NULL,
# email VARCHAR(255) UNIQUE NOT NULL,
# + phone VARCHAR(20),
# created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
# );
Web 控制台对比 #
text
┌─────────────────────────────────────────────────────────────┐
│ Schema 对比视图 │
├─────────────────────────────────────────────────────────────┤
│ │
│ Comparing: develop → main │
│ │
│ users table │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ - main │ + develop │ │
│ ├─────────────────────────────────────────────────────┤ │
│ │ CREATE TABLE users ( │ CREATE TABLE users ( │ │
│ │ id INT PRIMARY KEY, │ id INT PRIMARY KEY, │ │
│ │ name VARCHAR(100), │ name VARCHAR(100), │ │
│ │ email VARCHAR(255) │ email VARCHAR(255), │ │
│ │ │ + phone VARCHAR(20), │ │
│ │ created_at TIMESTAMP │ created_at TIMESTAMP│ │
│ │ ); │ ); │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ Changes summary: │
│ - 1 table modified │
│ - 1 column added │
│ │
└─────────────────────────────────────────────────────────────┘
Deploy Request #
创建部署请求 #
bash
# 创建 Deploy Request
pscale deploy-request create my-database develop
# 输出示例
# Deploy request #1 created successfully
# View at: https://app.planetscale.com/my-org/my-database/deploy-requests/1
Deploy Request 流程 #
text
┌─────────────────────────────────────────────────────────────┐
│ Deploy Request 流程 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. 创建 Deploy Request │
│ ┌─────────────┐ │
│ │ develop │ │
│ └──────┬──────┘ │
│ │ │
│ │ pscale deploy-request create │
│ ▼ │
│ ┌─────────────┐ │
│ │ DR #1 │ │
│ │ (待审核) │ │
│ └─────────────┘ │
│ │
│ 2. 审核变更 │
│ - 查看 Schema 差异 │
│ - 检查是否有冲突 │
│ - 团队成员审批 │
│ │
│ 3. 部署变更 │
│ ┌─────────────┐ │
│ │ DR #1 │ │
│ │ (部署中) │ │
│ └──────┬──────┘ │
│ │ │
│ │ 自动应用 │
│ ▼ │
│ ┌─────────────┐ │
│ │ main │ ← Schema 已更新 │
│ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
管理 Deploy Request #
bash
# 列出所有 Deploy Request
pscale deploy-request list my-database
# 查看详情
pscale deploy-request show my-database 1
# 查看变更
pscale deploy-request diff my-database 1
# 部署（需要权限）
pscale deploy-request deploy my-database 1
# 取消
pscale deploy-request close my-database 1
Deploy Request 状态 #
text
┌─────────────────────────────────────────────────────────────┐
│ 状态说明 │
├─────────────────────────────────────────────────────────────┤
│ │
│ pending_review - 等待审核 │
│ approved - 已批准，等待部署 │
│ in_progress - 部署进行中 │
│ complete - 部署完成 │
│ closed - 已关闭（取消或拒绝） │
│ error - 部署错误 │
│ │
│ 状态流转： │
│ │
│ pending_review ──> approved ──> in_progress ──> complete │
│ │ │ │
│ └────────────────┴──> closed │
│ │
└─────────────────────────────────────────────────────────────┘
分支数据管理 #
数据同步 #
text
┌─────────────────────────────────────────────────────────────┐
│ 数据说明 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 重要：开发分支不包含生产数据！ │
│ │
│ 创建分支时： │
│ ├── Schema 从父分支复制 │
│ ├── 数据不会复制 │
│ └── 分支是空的 │
│ │
│ 添加测试数据： │
│ ├── 手动 INSERT │
│ ├── 使用数据导入功能 │
│ └── 使用种子数据脚本 │
│ │
└─────────────────────────────────────────────────────────────┘
添加测试数据 #
bash
# 连接到开发分支
pscale shell my-database develop
# 插入测试数据
mysql> INSERT INTO users (name, email) VALUES
-> ('Test User 1', 'test1@example.com'),
-> ('Test User 2', 'test2@example.com'),
-> ('Test User 3', 'test3@example.com');
# 验证数据
mysql> SELECT * FROM users;
数据导入 #
bash
# 从文件导入
pscale database restore-dump my-database develop --dir ./data-dump
# 从生产分支复制数据（付费功能）
# 需要联系支持
分支策略 #
推荐工作流 #
text
┌─────────────────────────────────────────────────────────────┐
│ Git 风格工作流 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. 功能开发 │
│ main ──> feature/xxx ──> Deploy Request ──> main │
│ │
│ 2. 紧急修复 │
│ main ──> hotfix/xxx ──> Deploy Request ──> main │
│ │
│ 3. 长期开发 │
│ main ──> develop ──> feature/xxx │
│ └──> Deploy Request ──> main │
│ │
│ 最佳实践： │
│ ├── 每个 Schema 变更创建独立分支 │
│ ├── 分支命名清晰描述变更内容 │
│ ├── 变更完成后及时合并 │
│ ├── 合并后删除开发分支 │
│ └── 保持分支数量精简 │
│ │
└─────────────────────────────────────────────────────────────┘
团队协作 #
text
┌─────────────────────────────────────────────────────────────┐
│ 团队协作流程 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 开发者 A： │
│ 1. 创建分支 feature/add-users-table │
│ 2. 执行 Schema 变更 │
│ 3. 创建 Deploy Request │
│ │
│ 开发者 B： │
│ 1. 审核 Deploy Request │
│ 2. 检查 Schema 差异 │
│ 3. 批准或提出修改意见 │
│ │
│ 开发者 A： │
│ 1. 根据反馈修改 │
│ 2. 部署变更 │
│ 3. 删除开发分支 │
│ │
└─────────────────────────────────────────────────────────────┘
常见问题 #
分支创建失败 #
text
问题：分支创建卡在 creating 状态
原因：
- 达到分支数量限制
- 资源不足
解决：
1. 检查分支数量限制
2. 删除不需要的分支
3. 升级计划
Schema 变更冲突 #
text
问题：Deploy Request 显示冲突
原因：
- 多个分支修改同一表
- 父分支已有新变更
解决：
1. 从最新的 main 重新创建分支
2. 重新应用变更
3. 创建新的 Deploy Request
变更部署失败 #
text
问题：Deploy Request 部署失败
原因：
- Schema 变更不兼容
- 数据类型转换问题
- 系统错误
解决：
1. 检查错误信息
2. 修改 Schema 变更
3. 重新创建 Deploy Request
4. 联系支持
下一步 #
现在你已经掌握了分支操作，接下来学习 Schema 变更，深入了解非阻塞 DDL 的工作原理！
最后更新：2026-03-29