## 模块 2：TiDB Cloud Branching 与手动创建

### 2.1 什么是 TiDB Cloud Branching

你可以把 TiDB Cloud 的 Branching 理解为：**在某个父分支的数据快照之上，创建一个新的数据库分支**。分支之间相互隔离，你可以在分支上自由做 DDL/DML/查询验证；不满意就丢弃，满意则以它为基线继续演进。

更多信息请参考官方文档：[TiDB Cloud Branching Overview](https://docs.pingcap.com/tidbcloud/branch-overview/)。

### 2.2 在控制台手动创建一个分支

1. 打开 [TiDB Cloud 控制台](https://tidbcloud.com/project/clusters)，选择为本实验准备的 TiDB Cloud 集群。如果你是在选择了“Create New Cluster”后开始的实验，集群名将会是 `${LAB:SERVERLESS_CLUSTER_NAME}`。
2. 在集群页面找到 **Branches**（分支）入口。
   ![image.png 85%](https://lab-static.pingcap.com/images/2025/12/15/c863b787f66c3a0f52fc843d950fa044f4325827.png)
3. 点击 **Create branch**（创建分支），并完成以下设置：
   - **Parent branch**：选择 main 分支。
   - **Branch name**：给分支起一个清晰的名字，例如 `manual_sandbox`。
4. 点击 **Create**，并等待分支状态变为可用（显示为 `Active`），表示分支已经就绪。
   ![image.png 85%](https://lab-static.pingcap.com/images/2025/12/15/5f4493e908fa1faa0f7d819d7f380d3ee72b7dac.png)

> [!TIP]
> 你可以把这个手动创建的分支理解为一个**安全沙盒**：后续任何有风险的 DDL/DML，都可以先在这个分支里跑一遍，确认无误后再决定要不要在主线上应用。

### 2.3 验证分支隔离：在 Branch 上建表不影响 main

这一小节的目标是：**在你刚创建的分支里创建一张表**，然后再回到 `main` 分支确认它**没有被影响**。

#### 2.3.1 连接到你新创建的 Branch

1. 在 TiDB Cloud 集群页面进入 **Branches** 列表。
2. 找到你刚刚创建的分支（例如 `manual_sandbox`），在该分支右侧点击 **Action** 下的 `...`。
3. 在弹出的菜单/对话框中点击 **Connect**。
   ![image.png 85%](https://lab-static.pingcap.com/images/2025/12/15/b8b5c24dd97aa25a7649027920c48606da30f2c1.png)
4. 你会看到一个和主分支类似的连接面板（包含 Host、Port、Username、Password、Database 等连接信息）。

- 在弹出的窗口中点击 `Generate Password`（生成密码）。

![demo_branch_UI_09.png 85%](https://lab-static.pingcap.com/images/2025/11/27/acda36b4b8b64f0e63910a71ee3a51bca663a969.png)

- 密码生成后，选择 `Connect with .env`，再点击“复制”图标。

![env-file-branch-1.jpg 50%](https://lab-static.pingcap.com/images/2025/12/2/d16d8e8bca04b77d597b2df188502031c49dd771.jpg)

- 点击 [终端 1](ssh://monitor1-ssh#1) 启动分配给你的 Ubuntu 虚拟机终端。

- 在终端中，粘贴你复制的 `manual_sandbox` 连接信息以设置环境变量。输出示例如下：

  ```output
  ~/tidb-lab-branches# DB_HOST=gateway01.us-west-2.prod.aws.tidbcloud.com
  DB_PORT=4000
  DB_USERNAME='3NViMyHWFBkJvQq.root'
  DB_PASSWORD='1Pbcc4CFXTtnZA4C'
  DB_DATABASE='${LAB:SERVERLESS_CLUSTER_DATABASE_NAME}'
  ```

- 执行如下命令，将 `manual_sandbox` 的连接环境变量保存为 `.env-ms` 文件：

  ```bash
  cat > .env-ms <<EOF
  BRANCH_HOST=$DB_HOST
  BRANCH_PORT=$DB_PORT
  BRANCH_USERNAME=$DB_USERNAME
  BRANCH_PASSWORD=$DB_PASSWORD
  BRANCH_DATABASE=${LAB:SERVERLESS_CLUSTER_DATABASE_NAME}
  EOF
  ```

- 连接到新分支 `manual_sandbox`。

  ```bash
  source .env-ms
  mysql \
  --comments -u $BRANCH_USERNAME -p$BRANCH_PASSWORD \
   -h $BRANCH_HOST -P $BRANCH_PORT \
   --ssl-mode=VERIFY_IDENTITY --ssl-ca=/etc/ssl/certs/ca-certificates.crt
  ```

  ```output
  mysql>
  ```

#### 2.3.2 在 Branch 内创建一张表

- 连接成功后，在你的 SQL 客户端里执行任意一段 DDL（示例）：

  ```sql
  CREATE TABLE IF NOT EXISTS branch_only_demo (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    note VARCHAR(255) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
  );
  ```

- 再执行一次查询确认它确实存在（示例）：

  ```sql
  SHOW TABLES;
  ```

  ```output
  +--------------------------------+
  | Tables_in_lab_demo_411_6930301 |
  +--------------------------------+
  | branch_only_demo               |
  +--------------------------------+
  1 row in set (0.01 sec)
  ```

#### 2.3.3 回到 main 分支确认未被影响

- 点击 [终端 2](ssh://monitor1-ssh#2) 打开另一个终端窗口。

- 连接到 main 分支下的实验数据库。

  ```bash
  mysql \
   --comments -u '${LAB:SERVERLESS_CLUSTER_USERNAME}' -p'${LAB:SERVERLESS_CLUSTER_PASSWORD}' \
   -h ${LAB:SERVERLESS_CLUSTER_HOST} -P ${LAB:SERVERLESS_CLUSTER_PORT} \
   --ssl-mode=VERIFY_IDENTITY --ssl-ca=/etc/ssl/certs/ca-certificates.crt \
   -D ${LAB:SERVERLESS_CLUSTER_DATABASE_NAME}
  ```

- 在 `main` 分支上执行相同的检查（例如）：

  ```sql
  SHOW TABLES;
  ```

  ```output
  Empty set (0.01 sec)
  ```

- 请关闭 [终端 1](ssh://monitor1-ssh#1) 和 [终端 2](ssh://monitor1-ssh#2) 两个终端窗口。

#### 2.3.4 删除该 Branch，释放分支配额

TiDB Cloud 免费集群当前最多允许创建 **5 个 Branch**。你在本模块手动创建的分支（例如 `manual_sandbox`）会占用 1 个配额。

> [!TIP]
> 为了确保你能顺利完成下一模块（我们会在 Notebook 里一次性用满 5 个 Branch 的配额：3 个基础方案 + 2 个基于选择的子分支），请在继续之前删除你刚刚手动创建的 Branch。删除分支只会移除该分支内的所有变更（包括你刚刚创建的 `branch_only_demo` 表），不会影响 `main` 分支。

1. 回到 [TiDB Cloud 控制台](https://tidbcloud.com/project/clusters)，在 **Branches**（分支）列表中找到 `manual_sandbox`（或你创建的分支名称）。
2. 点击该分支右侧 **Action** 下的 `...`。
3. 在弹出的菜单/对话框中选择 **Delete**（删除），并在确认框中选择 **I understand, delete** 来确认删除。

### 2.4 （可选）理解分支的连接信息与权限

在实际工程里，**分支隔离**需要两件事配合：

- **每个分支有自己的访问入口**（host/port 等连接信息可能不同）。
- **每个分支最好使用独立账号/权限**，避免误操作跑到不该跑的地方。

在本实验的代码里，这部分会被封装成 Agent 工具（你会在下一模块看到）：Agent 创建分支后，会用分支级别的连接信息去执行 `run_sql_on_branch`，确保所有 DDL/DML 都落在正确的分支上。

### 2.5 （可选）GitHub Integration：把 Branch 用在 PR 测试里

除了**人工 / Agent 手动创建分支**，TiDB Cloud 还提供了 GitHub Integration：你可以把 **TiDB Cloud Branch** 绑定到 GitHub 的 Pull Request 工作流中。

   ![image.png 85%](https://lab-static.pingcap.com/images/2025/12/15/262351d482862288176cd45db9c3ed78b583082c.png)

典型用法是：

- 每个 PR 自动创建一个独立的数据库分支（或复用/更新对应分支）；
- 在 CI / 预发验证中，针对这个分支运行迁移脚本、回归测试、真实数据验证；
- PR 合并后，再清理分支或按策略保留。

当你怀疑某个 PR 可能引入数据层 Bug（Schema 变更、SQL 变更、兼容性问题等）时，这种 **PR 级别的真实分支测试**会非常有用。

你可以按[此文档](https://docs.pingcap.com/tidbcloud/branch-github-integration/?plan=starter)指引开启该能力。

### 2.6 （可选）Branch API：用 API 管理分支

如果你希望把分支能力集成到自己的系统（例如在 CI、Agent、或内部平台里自动创建/列举/清理分支），可以直接使用 TiDB Cloud 的 Serverless API。
如需使用此能力，课参考文档 [BranchService - ListBranches](https://docs.pingcap.com/tidbcloud/api/v1beta1/serverless/#tag/Branch/operation/BranchService_ListBranches)。