SchemaDryRunPlanner ConsoleHost / Initializer 承接設計
1. 文件目的
本文件整理 SchemaDryRunPlanner 第一版完成後，後續要如何被 ConsoleHost、Schema Initializer 與未來真實 MySQL 流程承接。
本節點仍屬於設計整理：
- 不導入
MySqlConnector。 - 不連線 MySQL。
- 不查詢
information_schema。 - 不執行 DDL。
- 不改 ConsoleHost 啟動方式。
- 不改既有 public method 簽章。
2. 目前已完成狀態
| 元件 | 狀態 | 說明 |
|---|---|---|
SchemaDefinitionParser | 已完成 | 可由 C# Class + Attribute 產生目標 schema |
MySqlSchemaSqlGenerator | 已完成 | 可產生 CREATE TABLE、ADD COLUMN、ADD INDEX 與 Dry Run Plan |
ISchemaInspector | 已完成 | 已建立抽象介面 |
MockSchemaInspector | 已完成 | 可用 mock snapshot 驗證 dry run |
SchemaDryRunPlanner | 已完成 | 可串接 inspector snapshot 與 dry run plan |
| 真實 MySQL Inspector | 未開始 | 需確認 MySQL 套件與連線資訊後才能導入 |
| Schema Initializer | 未開始 | 尚未定義 DryRun / Apply 模式 |
| ConsoleHost dry run 顯示 | 未開始 | 尚未將 plan 顯示到 ConsoleHost |
3. 承接原則
後續承接應拆成三層，避免 ConsoleHost、Initializer 與真實 DB 執行混在一起。
| 層級 | 責任 | 是否可自動實作 | 備註 |
|---|---|---|---|
| ConsoleHost 顯示層 | 顯示 dry run plan、warnings、manual review items | 可以 | 只顯示，不執行 SQL |
| Schema Initializer 協調層 | 決定 DryRun / Apply 模式，串接 inspector、planner、executor | 需先做設計與確認 | 第一版先只設計，不接真實 DB |
| Schema Executor 執行層 | 實際執行 DDL | 不可自動執行 | 必須等使用者明確確認、備份與權限確認 |
4. ConsoleHost 承接設計
4.1 第一版建議
ConsoleHost 第一版只應負責顯示 dry run 結果，不執行 DDL。
建議顯示內容：
| 顯示區塊 | 內容 |
|---|---|
Schema dry run: | dry run 是否成功 |
Mode | 固定顯示 DryRun |
Tables to create | 需要建立的 table |
Columns to add | 需要新增的 column |
Indexes to add | 需要新增的 index |
Manual review | 需要人工判斷的 schema 差異 |
Warnings | inspector 與 dry run warnings |
SQL preview | 預覽 SQL，但明確標示未執行 |
範例輸出：
Schema dry run:
Mode=DryRun Success=True
TablesToCreate=1 ColumnsToAdd=0 IndexesToAdd=0 ManualReview=0
SQL preview:
- CREATE TABLE IF NOT EXISTS `task_executions` (...)
Warnings:
- Dry Run 不會執行任何 MySQL DDL4.2 ConsoleHost 不應負責
- 不應保存 MySQL 密碼。
- 不應直接連線 MySQL。
- 不應直接執行 DDL。
- 不應把 schema 初始化流程寫死在 workflow 節點中。
- 不應讓 Adapter 或 WorkflowEngine 直接知道 schema 初始化細節。
5. Schema Initializer 承接設計
5.1 建議抽象模式
未來可建立 SchemaInitializerMode：
| 模式 | 說明 | 是否執行 DDL |
|---|---|---|
DryRun | 只產生 plan 與 SQL preview | 否 |
Apply | 依 plan 執行允許的 DDL | 是，需使用者確認 |
第一版只建議先支援 DryRun。
5.2 建議 Initializer 流程
SchemaDefinitionParser
|
v
Target Schema
|
v
Schema Initializer
|
+--> SchemaDryRunPlanner
| |
| +--> ISchemaInspector
| +--> MySqlSchemaSqlGenerator
|
v
SchemaDryRunResult未來 Apply 模式才會接：
SchemaDryRunResult
|
v
Schema Executor
|
v
MySQL DDL6. DryRun / Apply 分離規則
| 規則 | 說明 |
|---|---|
DryRun 是預設模式 | 避免誤執行 DDL |
Apply 必須明確指定 | 不可由設定缺省自動啟用 |
Apply 前必須有 plan | 不允許跳過 dry run 直接執行 |
Apply 只能執行 allow-list SQL | 第一版最多允許 CREATE TABLE、ADD COLUMN、ADD INDEX |
| destructive SQL 永遠不自動執行 | DROP、MODIFY、CHANGE、rename 必須人工處理 |
| manual review 存在時不得 apply | 需人工確認後才能進一步處理 |
7. 真實 MySQL Inspector 導入前條件
導入真實 MySQL Inspector 前，需先確認：
| 確認項目 | 說明 |
|---|---|
| MySQL 套件 | 是否採用 MySqlConnector |
| MySQL 版本 | 目前指定為 MySQL 5.6.2 |
| 連線資訊 | host、port、database、user、password 提供方式 |
| 權限 | 第一版只需要讀取 information_schema |
| Secret 管理 | 不可把密碼寫入 repo |
| 測試資料庫 | 建議先用測試 DB，不可直接打正式 DB |
| 備份策略 | 進入 Apply 前必須有備份與回復方式 |
8. 驗證節點設計
8.1 ConsoleHost dry run 顯示驗證
| 驗證項目 | 預期結果 |
|---|---|
| mock empty snapshot | Console 顯示 TablesToCreate 與 SQL preview |
| mock 缺 column / index | Console 顯示 ColumnsToAdd / IndexesToAdd |
| mock schema 差異 | Console 顯示 ManualReview |
| inspector 失敗 | Console 顯示標準錯誤碼與訊息 |
| warnings | Console 顯示 warning 清單 |
| SQL preview | 顯示 SQL，但標示未執行 |
8.2 Initializer dry run 驗證
| 驗證項目 | 預期結果 |
|---|---|
DryRun 模式 | 只回傳 plan，不呼叫 executor |
Apply 未確認 | 不可執行 DDL |
| manual review 存在 | 不可進入 apply |
| destructive SQL | 不可進入 apply |
9. 建議下一步
建議下一步先做：
SchemaDryRunPlanner ConsoleHost 顯示實作前確認該確認清單應包含：
- ConsoleHost 要顯示哪些欄位。
- 是否需要 formatter。
- 是否先用
MockSchemaInspector.Empty()做示範。 - 測試是否放在 ConsoleHost 相關測試中。
- 是否維持「只顯示 SQL preview，不執行 DDL」。