真實 MySQL Inspector 前置確認
1. 文件目的
本文件整理進入「真實 MySQL Inspector」前需要確認的實作邊界、資料來源、連線安全、查詢欄位、測試策略與停止條件。
此節點仍屬於實作前確認，不會新增 MySQL 套件、不會連線資料庫、不會讀取真實 information_schema，也不會執行任何 DDL。
2. 目前前置狀態
| 項目 | 狀態 |
|---|
| MySQL 版本 | 使用者指定為 MySQL 5.6.2 |
| Schema Attribute | 已完成第一版設計與實作 |
| SQL Generator | 已完成 CREATE TABLE IF NOT EXISTS、ADD COLUMN、ADD INDEX |
| Schema Inspector 抽象 | 已完成 ISchemaInspector 與 mock inspector |
| Dry Run Planner | 已可用 mock schema 產生新增欄位、索引與人工確認項目 |
| Schema Initializer | 已完成 DryRun 第一版 |
| ConsoleHost 顯示 | 已可呈現 Schema Initializer DryRun 結果 |
| 自動測試 | dotnet test 通過 318 個測試 |
| 最新程式 commit | ac52376 |
| 真實 MySQL 套件 | 尚未導入，導入前需另行確認 |
| 真實 MySQL 連線 | 尚未執行，連線前需另行確認 |
| DDL / Apply | 尚未執行，任何寫入 DB 行為需另行確認 |
3. 本節點建議目標
真實 MySQL Inspector 第一版建議只做「唯讀 schema snapshot」，目標是把既有資料庫現況轉成專案內部 schema model，交給 Dry Run Planner 比對。
| 目標 | 說明 |
|---|
| 讀取 table metadata | 從 information_schema.TABLES 取得 table 名稱、註解、engine、collation |
| 讀取 column metadata | 從 information_schema.COLUMNS 取得欄位型別、nullable、default、comment、順序 |
| 讀取 index metadata | 從 information_schema.STATISTICS 取得 index 名稱、欄位順序、unique 狀態 |
| 判斷 primary key | 優先由 STATISTICS 的 PRIMARY 或 KEY_COLUMN_USAGE 判斷 |
| 轉成 snapshot | 轉成現有 SchemaDefinition / TableDefinition / ColumnDefinition / IndexDefinition 相容結構 |
| 串接 Dry Run | 用真實 DB snapshot 與 C# 目標 schema 產生 Dry Run Plan |
4. 明確不做的事
| 不做項目 | 原因 |
|---|
不執行 CREATE TABLE | Inspector 只讀，不負責建表 |
不執行 ALTER TABLE | 避免尚未確認前修改資料庫 |
不執行 DROP / MODIFY / CHANGE | 破壞性或高風險 SQL 必須另行設計與確認 |
| 不把密碼寫進 repo | 密碼、token、連線字串不可進入文件或程式碼 |
| 不把 MySQL 套件放進 Core | 避免 Core 依賴外部 DB provider |
| 不改 ConsoleHost 啟動方式 | CLI 參數與正式啟動流程需另行確認 |
| 不自動套用 Dry Run 結果 | Dry Run 只輸出計畫，不等於 Apply |
5. 連線資訊與安全規則
真實 Inspector 需要 DB 連線資訊，但第一版規劃應先定義資訊來源，不直接收集密碼。
| 資訊 | 建議處理 |
|---|
| Host / IP | 可由本機設定檔或環境變數提供 |
| Port | 預設 3306，但需允許覆寫 |
| DatabaseName | 必填，只允許讀取指定 database |
| User | 建議使用唯讀帳號 |
| Password | 只允許由環境變數、Secret 或本機未納版設定提供 |
| SSL / Timeout | 第一版可先保留設定欄位，實作時再確認預設值 |
| ConnectionString | 不建議完整寫入 repo，應由安全來源組合 |
建議第一個真實測試帳號只給：
SELECT 權限
information_schema 讀取能力
不得具有 CREATE / ALTER / DROP 權限
6. information_schema 查詢欄位
6.1 information_schema.TABLES
| 欄位 | 用途 |
|---|
TABLE_SCHEMA | 限定指定 database |
TABLE_NAME | 對應 table name |
TABLE_COMMENT | 對應 table description |
ENGINE | 確認 table engine |
TABLE_COLLATION | 後續判斷 charset / collation |
6.2 information_schema.COLUMNS
| 欄位 | 用途 |
|---|
TABLE_NAME | 對應所屬 table |
COLUMN_NAME | 對應欄位名稱 |
COLUMN_TYPE | 保留完整 MySQL 型別，例如 varchar(64) |
DATA_TYPE | 判斷基礎型別，例如 varchar、int、datetime |
CHARACTER_MAXIMUM_LENGTH | 字串長度 |
NUMERIC_PRECISION / NUMERIC_SCALE | 數值精度 |
IS_NULLABLE | 是否允許 null |
COLUMN_DEFAULT | 預設值 |
COLUMN_COMMENT | 欄位描述 |
ORDINAL_POSITION | 欄位順序 |
6.3 information_schema.STATISTICS
| 欄位 | 用途 |
|---|
TABLE_NAME | 對應所屬 table |
INDEX_NAME | 對應 index 名稱 |
COLUMN_NAME | index 欄位 |
NON_UNIQUE | 判斷 unique / non-unique |
SEQ_IN_INDEX | 還原複合 index 欄位順序 |
7. MySQL 5.6.2 注意事項
| 項目 | 注意 |
|---|
| JSON 型別 | MySQL 5.6.2 不支援原生 JSON，需使用 TEXT |
datetime(3) | 需確認 5.6.2 環境是否支援 fractional seconds；若不穩定，第一版先用 datetime |
utf8mb4 | 需確認資料庫與 table collation 是否支援，否則先採既有 DB 設定 |
| index 長度 | varchar 欄位建立索引時需注意編碼與長度限制 |
| default value | TEXT 欄位不可隨意設定 default |
| comment | table / column comment 可讀，但不同環境可能有空字串或編碼差異 |
8. 建議實作位置
| 類型 | 建議位置 | 原因 |
|---|
| 真實 MySQL Inspector | Infrastructure 或 schema 專屬模組 | 需要依賴 MySQL provider，不應放入 Core |
ISchemaInspector | 沿用目前抽象 | 讓 mock 與真實 Inspector 可替換 |
| 連線設定 model | Infrastructure config 或 ConsoleHost 專用設定 | 避免污染 Core schema model |
| 測試替身 | Tests helper / mock inspector | 單元測試不依賴真實 DB |
| 真實 DB 驗證 | 獨立人工驗證節點 | 避免 CI 需要密碼與外部 DB |
9. 測試與驗證策略
第一版建議拆成三層：
| 層級 | 驗證方式 | 是否需要真實 DB |
|---|
| SQL query builder 測試 | 驗證產生的查詢包含 database filter 與必要欄位 | 否 |
| row mapping 測試 | 用假資料列轉成 schema snapshot | 否 |
| 真實 DB 人工驗證 | 使用唯讀帳號讀取指定 database 並輸出 Dry Run Plan | 是，但需另行確認 |
真實 DB 人工驗證節點需回報：
- 連線是否成功。
- 讀到幾張 table、幾個 column、幾個 index。
- 是否正確限制在指定 database。
- 是否產生符合預期的 Dry Run Plan。
- 是否完全沒有執行 DDL。
- 若失敗，錯誤碼、錯誤訊息與連線階段需清楚。
10. 停止條件
遇到以下情況必須停下確認：
| 情況 | 原因 |
|---|
要新增 MySqlConnector 或其他 DB 套件 | 屬於新增核心套件 |
| 要建立真實 connection string | 可能涉及密碼與環境資訊 |
| 要連線實際 MySQL | 會碰到外部服務與權限 |
要讀取 information_schema | 已進入真實 DB metadata 存取 |
要執行 CREATE / ALTER / DROP | 會修改資料庫 |
| 要調整 public method 簽章 | 可能影響既有契約 |
| 要改 ConsoleHost 啟動方式 | 可能影響使用流程 |
11. 建議實作順序
- 整理
MySqlSchemaInspector 實作前確認清單。 - 確認是否允許導入
MySqlConnector。 - 建立唯讀 connection settings model，但不寫入密碼。
- 建立
information_schema query builder。 - 建立 metadata row mapping 測試。
- 實作
MySqlSchemaInspector，先以測試替身驗證 mapping。 - 經使用者確認後，再做真實 DB 人工驗證。
- 真實驗證通過後，再討論 Apply executor。
12. 本次結論
可以進入「MySqlSchemaInspector 實作前確認清單」。
但下一步若要真的導入 MySqlConnector、建立連線資訊、讀取真實 information_schema 或接上 ConsoleHost 啟動參數，仍需先取得使用者確認。
返回文件首頁