## モジュール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 はまずブランチ上で試し、問題ないことを確認してから main 系に適用するか判断します。

### 2.3  Branch 隔離の検証：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. main ブランチと同様の接続パネル（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 \
   -D ${LAB:SERVERLESS_CLUSTER_DATABASE_NAME}
  ```

  ```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 削除による Branch 枠の確保

TiDB Cloud の無料枠では、作成できるブランチは最大 **5 個**です。本モジュールで手動作成したブランチ（例：`manual_sandbox`）は 1 枠を消費します。

> [!TIP]
> 次のモジュールを確実に完了するため（Notebook で 5 枠を同時に使い切ります：基礎 3 案 + 選択後の子ブランチ 2 つ）、先に手動で作成したブランチを削除してください。ブランチ削除はそのブランチ内の変更（`branch_only_demo` テーブルを含む）のみを消し、`main` には影響しません。

1. [TiDB Cloud コンソール](https://tidbcloud.com/project/clusters) に戻り、**Branches** リストで `manual_sandbox`（またはあなたの作成したブランチ名）を探します。
2. 右側の **Action** にある `...` をクリックします。
3. メニュー/ダイアログで **Delete** を選択し、**I understand, delete** を選んで削除を確定します。

### 2.4 （任意）接続情報と権限の考え方

実運用では、**Branch 隔離**は主に次の 2 点で成立します。

- **ブランチごとにアクセスエンドポイントがある**（host/port が異なる場合があります）。
- **ブランチごとに独立した資格情報/権限を用意する**（誤って別ブランチに操作する事故を防ぎます）。

本実験のコードでは、これを Agent のツールとしてカプセル化しています（次モジュールで扱います）。Agent はブランチ作成後、ブランチ専用の接続情報を使って `run_sql_on_branch` を実行し、DDL/DML が正しいブランチにのみ適用されるようにします。

### 2.5 （任意）PR テストでの Branch 活用のための GitHub Integration

手動/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 / 事前検証で、そのブランチに対してマイグレーション、回帰テスト、実データ検証を実行
- マージ後にブランチを削除（またはポリシーに応じて保持）

Schema 変更、SQL 変更、互換性問題など、データ層のバグ混入が疑われる PR に対して、この「PR 単位の実ブランチ検証」は特に有効です。

[Branch GitHub Integration](https://docs.pingcap.com/tidbcloud/branch-github-integration/?plan=starter) のガイドに従うことで、この機能を有効化できます。

### 2.6 （任意）API による Branch 管理

CI、Agent、社内プラットフォームなどに Branch 機能を組み込み、ブランチの自動作成/一覧取得/クリーンアップを行いたい場合は、TiDB Cloud の Serverless API を利用できます。

参考：[BranchService - ListBranches](https://docs.pingcap.com/tidbcloud/api/v1beta1/serverless/#tag/Branch/operation/BranchService_ListBranches)。