MySqlSchemaInspector 真實 DB provider 實作前確認

1. 文件目的

本文件整理進入 MySqlSchemaInspector 真實 DB provider 前的確認項目，目標是判斷是否可以從「純程式 helper」進入「導入 MySQL 套件並讀取真實 information_schema」。

此節點仍是實作前確認，不會導入 MySqlConnector、不會修改 .csproj、不會建立 connection string、不會連線 MySQL、不會讀取真實 information_schema，也不會執行任何 DDL。

2. 目前狀態

項目	狀態
MySQL 版本	使用者指定為 MySQL 5.6.2
Schema Attribute	已完成
SQL Generator	已完成
ALTER TABLE Dry Run	已完成
`ISchemaInspector`	已完成抽象與 mock inspector
`SchemaDryRunPlanner`	已完成
`SchemaInitializer` DryRun	已完成
ConsoleHost DryRun 顯示	已完成
Query Builder / Row Mapper / Snapshot Assembler	已完成，程式 repo commit `51cb17c`
測試數	`dotnet test` 合計 329 個測試通過
真實 DB provider	尚未開始
MySQL 套件	尚未導入
真實 DB 連線	尚未執行
DDL / Apply	尚未允許

3. 本節點建議結論

建議下一步可以進入「真實 DB provider 第一版」，但必須先取得使用者確認。

第一版 provider 建議只做唯讀 inspect：

範圍	是否納入	說明
導入 `MySqlConnector`	需確認後才可納入	需修改程式 repo `.csproj`。
建立 provider class	可在確認後納入	將真實 DB metadata 轉成既有 schema snapshot。
讀取 `information_schema`	需確認後才可納入	僅限指定 database。
產生 Dry Run Plan	可納入	只比對，不套用。
執行 `CREATE` / `ALTER` / `DROP`	不納入	Apply / DDL executor 需另行設計與確認。
寫入 TaskStore	不納入	等 inspect / dry run 穩定後再進入。

4. 實作位置建議

類型	建議位置	原因
真實 DB provider	新增 Infrastructure 或 MySQL 專屬實作專案	避免 Core 直接依賴 MySQL 套件。
`ISchemaInspector`	沿用 Core 既有抽象	讓 mock 與真實 provider 可替換。
Query Builder / Mapper / Assembler	沿用目前 internal helper	已有測試覆蓋，不需重寫。
Connection settings	Infrastructure / ConsoleHost 設定層	密碼不得寫死，不污染 Core schema model。
真實驗證入口	ConsoleHost 或獨立驗證工具	需明確標示只讀，不改既有代表流程。

若目前程式 repo 尚未建立 Infrastructure 專案，建議先停下確認「是否新增 Infrastructure 專案」，不得直接把 MySQL provider 放進 Core。

5. 套件導入確認

確認項	建議
套件	`MySqlConnector`
導入位置	Infrastructure / MySQL provider 專案，不放 Core
.NET 相容性	需選擇支援 .NET 5.0 的版本
CI 影響	GitHub Actions 需能 restore / build / test
測試策略	單元測試不依賴真實 DB；真實 DB 只做人工驗證節點
停止條件	套件導入失敗、CI restore 失敗、需要升級 .NET 時停下討論

6. 連線資訊來源

資訊	建議來源	是否可寫入 repo
Host / IP	本機未追蹤設定檔或環境變數	可寫範例，不可寫正式值
Port	本機未追蹤設定檔或環境變數	可寫預設 `3306`
DatabaseName	本機未追蹤設定檔或環境變數	可寫範例
User	本機未追蹤設定檔或環境變數	不建議寫正式帳號
Password	環境變數、Secret、本機未追蹤設定	不可寫入 repo
SSL / Timeout	設定檔欄位	可寫預設值，但需可覆寫

建議第一版環境變數命名：

HS_DB_HOST
HS_DB_PORT
HS_DB_NAME
HS_DB_USER
HS_DB_PASSWORD
HS_DB_SSL_MODE
HS_DB_TIMEOUT_SECONDS

7. 第一版 provider 流程

flowchart LR
    A["讀取安全來源設定"] --> B["建立 MySQL 連線"]
    B --> C["查詢 information_schema.TABLES"]
    B --> D["查詢 information_schema.COLUMNS"]
    B --> E["查詢 information_schema.STATISTICS"]
    C --> F["Metadata Rows"]
    D --> F
    E --> F
    F --> G["Snapshot Assembler"]
    G --> H["SchemaInspectResult"]
    H --> I["SchemaDryRunPlanner"]

8. 錯誤處理規則

情境	建議錯誤資訊
缺少 Host / Database / User	回傳設定錯誤，不嘗試連線
缺少 Password	回傳安全設定錯誤，不提示或寫出密碼
連線失敗	回傳 provider、host、database、exception type、message
權限不足	回傳權限錯誤，標示讀取 `information_schema` 失敗
database 不存在	回傳 schema not found 類型錯誤
metadata 欄位缺失	回傳 mapping error 或 warning
查詢逾時	回傳 timeout error 與 timeout 秒數

錯誤不得只回傳 false，也不得吞掉 exception。

9. 測試策略

測試類型	是否需要真實 DB	說明
Query Builder 單元測試	否	已有基礎，可補 provider 使用情境。
Row Mapper 單元測試	否	使用 fake metadata row。
Provider settings validation 測試	否	驗證缺少必要欄位會被擋下。
Provider command flow 測試	否	可用 fake executor 模擬 reader。
真實 MySQL inspect 人工驗證	是	使用唯讀帳號與指定 database。
CI 自動真實 DB 測試	第一版不做	避免 CI 需要密碼與外部 DB。

10. 人工驗證節點

未來真實 provider 完成後，需建立「真實 MySQL metadata inspect 人工驗證」。

回報至少包含：

項目	說明
驗證節點名稱	真實 MySQL metadata inspect 人工驗證
驗證目的	確認 provider 可唯讀讀取指定 database metadata
驗證方式	使用安全來源提供 Host / Port / Database / User / Password
實際結果	table / column / index 數量
安全結果	是否未執行任何 DDL
錯誤結果	若失敗，列出錯誤碼、階段、訊息與限制
下一步	是否串接 ConsoleHost dry run 顯示或補 mapping 規則

11. 必須停下確認

以下事項必須先取得使用者明確確認：

事項	原因
新增 `MySqlConnector`	新增套件與修改 `.csproj`
新增 Infrastructure 專案	改變 solution / project 結構
新增 connection settings 格式	可能影響設定檔格式
修改 public method 簽章	可能影響既有契約
修改 ConsoleHost 啟動方式	可能影響既有使用流程
連線真實 MySQL	涉及外部服務與敏感資訊
讀取真實 `information_schema`	進入真實 DB metadata 存取
執行任何 DDL	會修改資料庫

12. 本次結論

目前可以進入下一個決策點：「是否允許導入 MySqlConnector 並新增真實 DB provider 所需專案 / 設定」。

若使用者同意，建議下一步先做程式 repo 的「provider 實作前程式結構檢查」，確認現有 .sln、專案分層、Core helper、測試專案與是否需要新增 Infrastructure 專案。

若使用者尚未同意，則維持在文件與規劃階段，不修改 .csproj、不導入套件、不連 DB。

返回文件首頁