Schema Inspector / information_schema 實作前確認
1. 文件目的
本文件整理進入 Schema Inspector / information_schema 前需要確認的範圍、資料來源、讀取欄位、測試方式與停止條件。
此節點的目標不是執行 DDL，也不是啟動自動建表，而是先確認「如何安全讀取 MySQL 既有 schema」，讓後續 Dry Run Plan 可以從真實資料庫現況產生。
2. 目前前置狀態
| 項目 | 狀態 |
|---|---|
| MySQL 版本 | 使用者指定為 MySQL 5.6.2 |
| SQL Generator | 已完成 CREATE TABLE IF NOT EXISTS、ADD COLUMN、ADD INDEX |
| Dry Run Plan | 已完成第一版純程式比對 |
| 目前測試數 | dotnet test 通過 278 個測試 |
| 最新程式 commit | db0b1b8 |
| 真實 MySQL 連線 | 尚未導入 |
| DDL 執行 | 尚未導入 |
| MySQL 套件導入 | 尚未在本節點執行 |
3. 本節點建議目標
第一版 Schema Inspector 建議只做「讀取真實 DB schema 快照」，不做任何修改。
| 目標 | 說明 |
|---|---|
| 讀取 table 清單 | 從 information_schema.TABLES 取得指定 database 的 table |
| 讀取 column 清單 | 從 information_schema.COLUMNS 取得欄位名稱、型別、nullable、預設值、comment |
| 讀取 index 清單 | 從 information_schema.STATISTICS 取得 index 名稱、欄位順序、是否 unique |
| 讀取 primary key | 可由 information_schema.KEY_COLUMN_USAGE 或 STATISTICS 判斷 |
| 轉成 schema snapshot | 轉成專案內部 SchemaDefinition / TableDefinition / ColumnDefinition / IndexDefinition 相容資料 |
| 提供給 Dry Run Plan | 將現有 DB snapshot 與目標 schema 比對 |
4. 明確不做的事
| 不做項目 | 原因 |
|---|---|
不執行 CREATE TABLE | Inspector 只讀，不負責建表 |
不執行 ALTER TABLE | 避免尚未確認前修改資料庫 |
不執行 DROP / MODIFY / CHANGE | 破壞性或高風險 SQL 必須另行確認 |
| 不把密碼寫進文件或 repo | 避免洩漏敏感資訊 |
| 不在 Core 直接依賴 MySQL 套件 | 避免破壞分層，DB 讀取應放在 Infrastructure 或專屬 schema 模組 |
| 不接 ConsoleHost 自動啟動流程 | 啟動自動建表需等 Inspector、Plan、Executor 都確認後再做 |
5. information_schema 查詢範圍
5.1 information_schema.TABLES
建議讀取欄位：
| 欄位 | 用途 |
|---|---|
TABLE_SCHEMA | 限制 database |
TABLE_NAME | 對應 table name |
TABLE_COMMENT | 對應 table description |
ENGINE | 確認是否為 InnoDB 等預期 engine |
TABLE_COLLATION | 後續判斷字元集與排序規則 |
5.2 information_schema.COLUMNS
建議讀取欄位：
| 欄位 | 用途 |
|---|---|
TABLE_NAME | 對應所屬 table |
COLUMN_NAME | 對應 column name |
COLUMN_TYPE | 保留完整 MySQL 型別，例如 varchar(64) |
DATA_TYPE | 判斷基礎型別，例如 varchar、datetime |
CHARACTER_MAXIMUM_LENGTH | 判斷字串長度 |
NUMERIC_PRECISION / NUMERIC_SCALE | 判斷數值精度 |
IS_NULLABLE | 對應 nullable |
COLUMN_DEFAULT | 保留 default 資訊 |
COLUMN_COMMENT | 對應欄位描述 |
ORDINAL_POSITION | 保留欄位順序 |
5.3 information_schema.STATISTICS
建議讀取欄位：
| 欄位 | 用途 |
|---|---|
TABLE_NAME | 對應所屬 table |
INDEX_NAME | 對應 index name |
COLUMN_NAME | 對應 index 欄位 |
NON_UNIQUE | 判斷 unique / non-unique |
SEQ_IN_INDEX | 還原複合 index 欄位順序 |
5.4 information_schema.KEY_COLUMN_USAGE
建議用途：
| 用途 | 說明 |
|---|---|
| 判斷 primary key | 可輔助確認 primary key 欄位 |
| 保留外鍵資訊 | 第一版可先讀取但不進入自動修正 |
第一版可以只把外鍵列為 ManualReviewItems 或 warning，不建議自動產生 foreign key DDL。
6. MySQL 5.6.2 注意事項
| 項目 | 注意事項 |
|---|---|
| JSON 型別 | MySQL 5.6.2 不支援原生 json，仍需映射為 text 或 varchar |
datetime 精度 | 需避免使用較新版本才穩定支援的語法 |
| generated column | 第一版不納入 |
| online DDL | 第一版不依賴 |
| collation | 先讀取與記錄，不在第一版自動修正 |
| foreign key | 先讀取與記錄，不在第一版自動建立或修改 |
7. 建議程式邊界
| 元件 | 建議責任 |
|---|---|
ISchemaInspector | 定義讀取目前 schema snapshot 的抽象介面 |
MySqlSchemaInspector | 透過 MySQL 連線讀取 information_schema |
SchemaDefinition | 表示目標 schema 或目前 DB snapshot |
MySqlSchemaSqlGenerator | 只負責產生 SQL 字串 |
SchemaMigrationPlan | 表示 dry run 比對結果 |
SchemaInitializer | 後續才負責串接 inspector、generator、executor |
建議第一版不要把 MySQL 讀取邏輯放進 Core。Core 可以保留抽象 model 與比對結果，真實 DB 讀取應放在 Infrastructure 或專門的 MySQL schema 實作區。
8. 測試策略
| 測試層級 | 建議方式 |
|---|---|
| 單元測試 | 使用 fake / in-memory reader 模擬 information_schema 查詢結果 |
| mapping 測試 | 確認 table、column、index 可正確轉成 schema snapshot |
| MySQL 5.6.2 相容測試 | 先以文件列出必要查詢語法，實際連線測試需使用者提供測試 DB |
| 安全測試 | 確認 Inspector 不產生 DDL、不呼叫 executor、不修改 DB |
| 異常測試 | 連線失敗、權限不足、database 不存在、查詢結果空集合 |
9. 需要使用者確認的項目
| 項目 | 為什麼需要確認 |
|---|---|
是否允許導入 MySqlConnector | 這會新增核心資料庫連線套件 |
| MySQL 測試 DB 連線資訊 | Inspector 若要做真實連線測試，需要 host、port、dbname、user 與密碼提供方式 |
| 測試帳號權限 | 第一版建議只需要 SELECT information_schema 與目標 database metadata |
| 是否允許新增 Infrastructure 專案或資料夾 | 會影響專案分層與檔案位置 |
| 是否需要先只做 mock inspector | 可避免先接真實 DB，也能完成 mapping 與 Dry Run 串接測試 |
10. 建議決策
我的建議是先採用「兩段式」：
1. 先做 ISchemaInspector 與 mock / fake inspector，驗證 mapping 到 SchemaDefinition 與 Dry Run Plan 串接。 2. 再經使用者確認後導入 MySqlConnector，實作 MySqlSchemaInspector 查詢 information_schema。
這樣可以先把架構與測試補齊，同時避免太早接觸真實資料庫、密碼與外部環境。
11. 建議下一步
建議下一步先做：
Schema Inspector 抽象介面與 mock inspector 實作前確認此步驟可先不導入 MySQL 套件、不連線 DB，只確認介面、回傳模型、錯誤格式與測試案例。
若要直接進入真實 MySQL Inspector，則需先確認：
- 是否允許新增
MySqlConnector。 - MySQL 測試連線資訊如何提供。
- 測試帳號是否只有讀取權限。
- Inspector 實作放在哪一層。