## モジュール3：Text2SQL シナリオ：Agent による Branch の実践

このモジュールでは、典型的な Text2SQL / データベース設計の課題に絞ります。新規の Todo アプリ用データベースを設計し、Agent に複数案を並行探索させ、そこから 1 つを選んで次のステップへ進めます。

本モジュールは Jupyter Notebook で実施します（Notebook が Agent にブランチ作成/管理を行わせ、ブランチ上で SQL を実行します）。

### 3.1 Notebook の起動

1. [VS Code](${LAB:HTTPS_REVERSE_PROXY_URL}?next=${LAB:"/vscode/?folder=/root/tidb-lab-branches"|urlencode} "VS Code") をクリックして IDE を開きます。

   > [!TIP]
   > プロンプトが表示されたら、`Yes, I trust the authors` をクリックしてください。

2. 左側の `EXPLORER` で以下を開きます。
   - `todo_branch_story.ipynb`
   - `tidb_agent.py`（併せて開くと、Agent が使えるツールを把握しやすいです）
3. Notebook 右上の `Select Kernel` をクリックし、`Python Environments...` を選択して、推奨の `Python 3.11.x` インタプリタを選びます。
4. Notebook 内の手順に従い、上から順にセルを実行してください。

   > [!TIP]
   > 演習終了後も `todo_branch_story.ipynb` および `tidb_agent.py` の内容にアクセスできるよう、事前にファイル内容をコピーしておくことをおすすめします。

### 3.2 ストーリーライン：三つの並行する道と選択後の進化

`todo_branch_story.ipynb` では、新規 Todo アプリのデータベース設計を題材に探索します。

**対象データ**：

- `todos`：Todo（例：タイトル、状態、期限、作成/更新時刻など）
- `users`：ユーザー（Todo の所有/割り当てに使用）
- `extensions`：タグ、チェックリスト項目など

以降は次の流れで進みます。

1. **Step 1：Todo 保存方式 3 案の並行生成（3 ブランチ）**
   - Agent が 3 ブランチ `todo_minimal`、`todo_tags`、`todo_checklists` を作成します。
   - ブランチごとに異なるモデリング方針でテーブル作成とサンプルデータ投入を行います。
2. **Step 1（確認と選択）：3 ブランチの比較と基準線の選択**
   - Notebook が各ブランチのテーブルとサンプル行を表示し、判断を支援します。
3. **Step 2：選んだ基準線からの再 Branch とユーザー体系追加（2 つの子ブランチ）**
   - 選択した親ブランチから次の 2 つの子ブランチを作成します。
     - `{base}_owners`：Todo は 1 人の owner を持つ（単一所有）
     - `{base}_assignments`：Todo とユーザーが多対多（協業割り当て）
   - Agent が `users` テーブル、外部キー/中間テーブル等の関係を作り、サンプル行を投入します。
4. **Step 3： Branch ツリーの可視化**
   - Notebook がクラスター内のブランチ系譜を可視化し、 Branch 元・ Branch 先・継続した経路を把握できるようにします。

### 3.3 注目すべき主要コード（資料）

本実験で特に重要な資料は次のとおりです。

- `tidb_agent.py`
  - Strands Agents で TiDB の機能を `create_branch` / `create_branch_from_display_name` / `run_sql_on_branch` などのツールにラップしています。
  - 重要点：ブランチ上で SQL を実行する場合は、必ずブランチの接続情報を使い、誤ってデフォルトブランチに DDL/DML を流さないようにします。
- `todo_branch_story.ipynb`
  - 「プロンプト + ツール呼び出し」で Branch 型の Schema 探索を駆動し、ハードコードされた SQL 手順に依存しません。