# MySQL 套件選型分析

## 1. 文件目的

本文件用於第二階段「MySQL TaskStore PoC」前，分析 .NET 5.0 與 MySQL 5.6.2 條件下應採用哪一種 MySQL 存取套件。

本文件只做套件選型分析，不代表已同意安裝套件、修改程式架構、建立 schema、改 public method 或變更專案啟動方式。

## 2. 既定限制

| 項目 | 條件 |
|---|---|
| .NET 版本 | .NET 5.0 |
| DB 版本 | MySQL 5.6.2 |
| 第一個目標 | MySQL TaskStore PoC |
| 第一版範圍 | Task / Node / Command / ErrorInfo 持久化 |
| 不做事項 | Web UI、WebApi、ServiceHost、多案場、報表、自動 migration |

MySQL 5.6.2 是舊版環境，因此 SQL 語法、欄位型態與套件選型要保守。第一版不使用 `JSON` 欄位，`RawRequest`、`RawResponse`、`AdapterData` 先以 `TEXT` 或 `LONGTEXT` 處理。

## 3. 候選方案

| 方案 | 套件 | 定位 |
|---|---|---|
| A | MySqlConnector | ADO.NET MySQL driver，直接執行 SQL |
| B | MySqlConnector + Dapper | ADO.NET driver 加輕量 SQL mapping |
| C | Pomelo.EntityFrameworkCore.MySql | EF Core provider，使用 MySqlConnector |
| D | MySql.Data | Oracle 官方 Connector/NET |

## 4. 評估標準

| 評估項 | 說明 |
|---|---|
| MySQL 5.6.2 相容性 | 是否適合連接 MySQL 5.6 系列 |
| .NET 5.0 相容性 | 是否可在 .NET 5.0 專案使用 |
| 範圍控制 | 是否會把 PoC 擴大成 ORM / migration / schema 管理 |
| 測試便利性 | 是否容易用測試或模擬資料驗證 |
| 維護風險 | 是否容易被套件生命週期或版本相依拖住 |
| 程式碼可讀性 | 是否能讓 TaskStore 實作清楚、可追蹤 |

## 5. 方案分析

### A. MySqlConnector

優點：

- 是純 ADO.NET driver，最貼近 PoC 需求。
- NuGet 顯示支援 `.NET Standard 2.0`，可供 .NET 5.0 專案使用。
- MySqlConnector 文件列出 MySQL 5.6 相容範圍，適合目前 MySQL 5.6.2 條件。
- 不會主動引入 ORM、migration 或 DbContext 架構。
- SQL 可完全保守設計，避免誤用 MySQL 8.0 功能。

風險：

- 需要自行撰寫 SQL 與 mapping。
- 需要自己定義交易、連線、錯誤轉換與測試資料建立方式。

適合程度：高。

### B. MySqlConnector + Dapper

優點：

- 保留 SQL 控制權，同時減少手寫 mapping。
- Dapper 是輕量 mapper，不會強迫導入 DbContext 或 migration。
- 適合查詢 Task / Node / Command / ErrorInfo 這類扁平資料。

風險：

- 比純 MySqlConnector 多一個套件。
- Dapper 不處理 MySQL 連線本身，仍需搭配 MySqlConnector。
- 若 PoC 目標只是驗證連線與寫入，第一步不一定需要 Dapper。

適合程度：中高，可作為第二步補強。

### C. Pomelo.EntityFrameworkCore.MySql

優點：

- 適合正式 ORM、DbContext、LINQ 與長期資料模型。
- Pomelo 5.0.x 對應 EF Core 5.0.x，與 .NET 5.0 路線相近。
- 底層使用 MySqlConnector。

風險：

- 會把 PoC 擴大到 EF Core、DbContext、migration 與模型設定。
- Pomelo 目前主要測試重點偏向較新的 MySQL 版本；MySQL 5.6.2 需額外驗證。
- 容易在資料模型尚未穩定前過早固定 ORM 結構。

適合程度：中，建議等 schema 穩定後再評估。

### D. MySql.Data

優點：

- Oracle 官方 Connector/NET。
- NuGet 顯示套件可透過 `.NET Standard 2.0` 供多種 .NET target 使用。
- 文件與企業環境接受度較直覺。

風險：

- 相較 MySqlConnector，社群常見做法較偏向 MySqlConnector / Pomelo 組合。
- 若搭配 EF Core，官方 MySQL EF Core provider 的版本相依需要另外檢查。
- 對第一版 PoC 來說，官方身分不是最重要，最重要是可控與好測。

適合程度：中，可列為備選。

## 6. 建議排序

| 建議順序 | 方案 | 理由 |
|---:|---|---|
| 1 | MySqlConnector | 最小、可控、符合 MySQL 5.6.2 與 PoC 範圍 |
| 2 | MySqlConnector + Dapper | 若手寫 mapping 開始變多，可在第二步加入 |
| 3 | MySql.Data | 官方備選，但第一版不優先 |
| 4 | Pomelo.EntityFrameworkCore.MySql | 適合 schema 穩定後再評估，不建議第一步導入 |

## 7. 推薦方案

建議第一版 MySQL TaskStore PoC 採用：

> MySqlConnector

暫不導入 Dapper、EF Core、Pomelo 或 migration。

理由：

- 第一版目標是驗證 TaskStore 寫入與查詢，不是建立完整資料存取框架。
- MySQL 5.6.2 條件下，保守 SQL 比 ORM 自動產生 SQL 更可控。
- 可把資料庫責任限制在 Infrastructure / TaskStore 實作，不影響 Core。
- 若後續 SQL mapping 重複增加，再評估加入 Dapper。

## 8. 建議第一版套件策略

第一步：

```text
MySqlConnector only
```

第二步，若 mapping 重複或查詢變多：

```text
MySqlConnector + Dapper
```

暫不建議：

```text
Pomelo.EntityFrameworkCore.MySql
EF Core migration
MySql.Data.EntityFrameworkCore
```

## 9. PoC 驗收建議

若後續進入實作，套件選型驗收至少包含：

1. 可連線 MySQL 5.6.2。
2. 可建立 PoC schema。
3. 可寫入 `task_executions`。
4. 可寫入 `node_executions`。
5. 可寫入 `command_executions`。
6. 可寫入 `task_errors`。
7. 可查詢指定 TaskId 的完整歷程。
8. DB 連線失敗時可轉成標準 ErrorInfo 或明確 Log。
9. 不影響既有 Core / Adapter / WorkflowSimulation 測試。

## 10. 需先確認

1. 是否接受第一版只加入 `MySqlConnector`。
2. 是否暫不導入 Dapper。
3. 是否暫不導入 EF Core / Pomelo。
4. 是否同意第一版 SQL 採手寫保守語法。
5. 是否同意先做 schema 初稿，再進入程式 repo 實作。

## 11. 參考來源

- MySqlConnector NuGet：支援 `.NET Standard 2.0`，可供 .NET 5.0 專案使用。
- MySqlConnector 官方網站：列出 MySQL 相容資料庫範圍，包含 MySQL 5.6。
- Dapper NuGet：可供 .NET 專案使用，但需搭配 ADO.NET provider。
- Pomelo GitHub README：Pomelo 5.0.x 對應 EF Core 5.0.x，且使用 MySqlConnector。
- MySql.Data NuGet / MySQL Connector/NET 文件：Oracle 官方 Connector/NET 套件。

## 12. 建議下一步

MySQL Schema 自動建表設計請參考：[MySQL Schema 自動建表設計](./mysql-schema-auto-create-design.md)。

MySQL schema Class 初稿請參考：[MySQL schema Class 初稿](./mysql-schema-class-draft.md)。

建議下一步做「Schema Attribute 實作前確認」，確認不改動 Core 與既有 public method 後再進入程式 repo。

在 schema 初稿確認前，不建議直接進入程式 repo 安裝套件。