寫 C# 連 MySQL 這事兒看起來不就是“裝個驅(qū)動、寫個連接串、創(chuàng)建連接、執(zhí)行SQL”四步嘛但真到了項目里你會發(fā)現(xiàn)坑全藏在細節(jié)里。連接串里多一個分號、少一個參數(shù)程序可能就直接崩MySQL 8 默認的認證插件和舊版驅(qū)動不兼容報錯能讓你懷疑人生好不容易連上了中文亂碼、連接池超時又接踵而來。這篇東西我想把 C# 連接 MySQL 從零到一的完整過程拆開講一遍包括驅(qū)動怎么選、連接串每個參數(shù)什么意思、增刪改查怎么寫不容易出問題、以及我這些年踩過的典型坑適合剛接觸 MySQL 的 .NET 開發(fā)者也適合被各種連接問題折磨到想罵人的老手。先交代一下背景我在實際項目里用過幾種不同的 MySQL 驅(qū)動訪問方式也幫同事排查過不少“昨天還能跑、今天連不上”的詭異問題。下面所有內(nèi)容沒有用到什么高深理論全部是工程里反復驗證過的東西照著做基本能連通出了問題也知道該往哪兒查。1. 準備階段驅(qū)動選型與項目配置1.1 驅(qū)動怎么選官方 Connector/NET 還是第三方C# 訪問 MySQL 的第一步不是寫代碼而是選驅(qū)動。很多人直接在網(wǎng)上搜“C# MySQL”會看到兩個主流包一個叫 MySql.Data官方 Connector/NET另一個叫 MySqlConnector還有一個是配合 EF Core 使用的 Pomelo.EntityFrameworkCore.MySql。它們的關(guān)系容易讓人糊涂我簡單梳理一下。MySql.Data 是官方提供的驅(qū)動歷史最久網(wǎng)上能搜到的資料和案例絕大多數(shù)都是基于它。它支持 .NET Framework 和 .NET Core/.NET 5API 設計比較傳統(tǒng)用起來中規(guī)中矩。MySqlConnector 是社區(qū)維護的高性能驅(qū)動異步接口實現(xiàn)得更徹底還修復了官方驅(qū)動一些長期存在的問題比如某些場景下的連接池行為、異步阻塞隱患。Pomelo 不是單獨的驅(qū)動它是 EF Core 的數(shù)據(jù)庫提供器底層依賴 MySqlConnector。如果不是團隊已經(jīng)有明確的技術(shù)選型我建議普通項目直接用 MySql.Data。原因很簡單官方驅(qū)動兼容性最好遇到問題能找到的解決方案最多。如果你的項目對數(shù)據(jù)庫訪問性能特別敏感比如大量并發(fā)讀、消息隊列類場景可以考慮 MySqlConnector但沒必要上來就挑戰(zhàn)冷門選項。一個項目里別同時引用兩個驅(qū)動否則因為命名空間都有MySql前綴代碼里會出現(xiàn)各種摸不著頭腦的編譯沖突。1.2 安裝驅(qū)動一條命令搞定確定驅(qū)動后安裝其實很簡單。以 Visual Studio 為例打開 NuGet 包管理器搜索“MySql.Data”選擇穩(wěn)定版本點擊安裝即可。命令行方式更快dotnet add package MySql.Data如果你需要指定版本可以在包名后追加版本號dotnet add package MySql.Data --version 8.0.33安裝完成后項目 csproj 文件里會出現(xiàn)類似這樣的引用PackageReference IncludeMySql.Data Version8.0.33 /老一代 .NET Framework 項目ASP.NET Web Forms 那種用 NuGet 可視化界面安裝也一樣。需要注意的是NuGet 包版本和 .NET 運行時版本有對應關(guān)系新版驅(qū)動對老框架支持會收縮。比如較新的 9.x 版本已經(jīng)不再支持舊的 .NET Framework 4.x 那一套如果項目還卡在舊框架上老老實實用 8.x 或更老的版本不要盲目追新。1.3 確認版本和兼容性我見過不少詭異問題最后定位出來都跟驅(qū)動和數(shù)據(jù)庫版本錯配有關(guān)。比如 Server 是 MySQL 8.0驅(qū)動還停留在 5.6.x 時代最典型的表現(xiàn)就是連接時報錯“Authentication method caching_sha2_password not supported”。這句報錯是因為 MySQL 8 默認使用 caching_sha2_password 認證插件而老驅(qū)動沒有實現(xiàn)對應的客戶端認證協(xié)議。反過來如果數(shù)據(jù)庫是老的 MySQL 5.6/5.7驅(qū)動版本太新一般問題不大但也可能碰到 TLS 版本協(xié)商、密碼哈希方式不匹配的情況。所以安裝前最好先確認數(shù)據(jù)庫版本。在服務端命令行執(zhí)行select version();就能看到。然后對照驅(qū)動的 release notes 選擇合適的版本。工程上最穩(wěn)妥的做法是用當前時間往前推 1-2 年的穩(wěn)定版本不要用剛發(fā)布沒多久的首個大版本也不要堅持用已經(jīng)停止維護的老版本。2. 連接字符串里的學問連接字符串是 C# 連 MySQL 里最容易踩坑的地方也是排查問題時第一個要懷疑的環(huán)節(jié)。很多人一遇到“連不上”就直接懷疑代碼其實八成是連接串寫錯了。2.1 基礎參數(shù)逐項解析先看一個最常見的連接字符串示例Serverlocalhost;Port3306;Databasetestdb;Uidroot;Pwd123456;CharSetutf8mb4;這里每個參數(shù)都有具體作用Server數(shù)據(jù)庫服務器的 IP 或主機名。localhost 表示本機寫 127.0.0.1 也可以但兩者在某些網(wǎng)絡環(huán)境下行為并不完全一樣。服務器如果開了 IPv6localhost 可能被解析成 ::1而 MySQL 只監(jiān)聽了 127.0.0.1這種情況就連接不上。PortMySQL 服務端口默認 3306。如果你的 MySQL 改了端口比如為了安全改成 13306這里必須同步改否則客戶端默認連 3306會直接超時。Database要連接的庫名。不寫也可以連接成功但后續(xù)執(zhí)行的 SQL 都需要手動指定數(shù)據(jù)庫名容易出錯建議顯式寫上。Uid 和 Pwd登錄用戶名和密碼。注意用戶名和密碼里如果包含特殊字符比如分號、百分號處理起來比較麻煩后面會專門說。CharSet客戶端使用的字符集。中文項目推薦直接寫 utf8mb4不要寫 utf8。原因我后面亂碼那一節(jié)詳細解釋。2.2 高級參數(shù)和它們的作用基礎參數(shù)能連上但想穩(wěn)定、可控地運行還要知道幾個高級參數(shù)SslMode控制是否使用 SSL 加密連接。取值有 None、Preferred、Required 等。開發(fā)環(huán)境省事可以設成 None生產(chǎn)環(huán)境我建議 Required強制對傳輸層加密避免密碼在網(wǎng)絡上明文傳遞。MySQL 8 默認開啟了 SSL 支持如果連接串沒設置 SslMode驅(qū)動默認行為可能是 Preferred會嘗試協(xié)商加密一旦服務端配置了必須 SSL 校驗而你還要求無效證書就可能報證書驗證失敗。AllowPublicKeyRetrieval這個參數(shù)和 MySQL 8 的 caching_sha2_password 認證插件有關(guān)。當使用 RSA 公鑰加密傳輸密碼時客戶端默認不允許自動從服務器獲取公鑰所以要手動設置為 True。很多新手遇到Authentication method caching_sha2_password not supported就是忘了設置這個參數(shù)。但要提醒一下開啟它存在中間人攻擊風險只能在保證網(wǎng)絡可信的前提下用。ConnectionTimeout建立連接的超時時間單位秒默認 15。很多人在本地調(diào)試時覺得超時太慢就調(diào)成 300這是非常壞的習慣。超時是保護機制不是越慢越好。生產(chǎn)環(huán)境建議保持 5-10 秒連接不上就該快速失敗讓服務發(fā)現(xiàn)異常而不是卡住所有線程。Pooling連接池開關(guān)默認 True。C# 連接數(shù)據(jù)庫默認啟用連接池連接池能顯著提高性能。如果設成 False每次 Open 都會創(chuàng)建全新物理連接并發(fā)一高很容易撐爆服務端的最大連接數(shù)。Max Pool Size連接池最大連接數(shù)默認 100。如果達到上限會拋異常提示連接池耗盡。要確認這個值和 MySQL 服務端 max_connections 配置誰更小否則連接池認為還能再開連接服務端其實已經(jīng)拒絕了。ConnectionLifeTime連接在池中的最長存活時間默認 0 表示不限。對老 MySQL 網(wǎng)絡設備有斷空閑連接問題的環(huán)境可以設置一個值比如 300 秒讓超時連接自動重建。2.3 連接字符串放哪、怎么保護在控制臺程序里測試時把連接字符串直接寫死在代碼里沒問題但正式項目千萬別這么干。連接字符串里有數(shù)據(jù)庫密碼隨著代碼提交到倉庫等于把鑰匙送給了任何能讀到代碼的人。ASP.NET Core 項目建議放到配置文件里通過配置系統(tǒng)讀取{ ConnectionStrings: { Default: Serverlocalhost;Port3306;Databasetestdb;Uidroot;Pwd123456;CharSetutf8mb4;SslModeNone;AllowPublicKeyRetrievalTrue; } }代碼里這樣取var connectionString builder.Configuration.GetConnectionString(Default);再講究一點不要把真實密碼放在 appsettings.json 里。開發(fā)環(huán)境可以用環(huán)境變量或者用 User Secrets 工具部署時再用正式密碼覆蓋。密碼里如果包含特殊字符比如分號連接串會解析錯亂這時需要用引號包裹密碼值轉(zhuǎn)義規(guī)則讓人頭大。我最后的建議是密碼字段盡量只使用大小寫字母和數(shù)字降低解析出錯概率。3. 核心代碼從連接到事務代碼這部分并不難但有幾個習慣如果從一開始就養(yǎng)成后面能少踩很多坑。3.1 建立連接別小看 using 那行代碼C# 里最標準、最短的連接寫法是這樣var connStr Serverlocalhost;Port3306;Databasetestdb;Uidroot;Pwd123456;; using (var conn new MySqlConnection(connStr)) { conn.Open(); // 執(zhí)行操作 }新版 C# 還可以簡化成using var conn new MySqlConnection(connStr); await conn.OpenAsync();為什么要用 using因為 MySqlConnection 實現(xiàn)了 IDisposable它的 Dispose 方法不僅會關(guān)閉連接還會把連接對象歸還給連接池。如果你不用 using就得手動寫 try/catch/finally 保證 conn.Close() 或 conn.Dispose() 一定會執(zhí)行。任何一條代碼路徑漏了釋放連接都不會真正關(guān)閉最終效果就是連接池被占滿。這里還有一個很多人理解反的概念conn.Close()并不會真的斷開數(shù)據(jù)庫連接它只是把連接放回連接池物理連接還活著。下次再Open()時客戶端從池里取出一個已存在的連接直接復用省去了 TCP 握手和認證的開銷。所以不必擔心循環(huán)里頻繁 Open/Close 會拖垮數(shù)據(jù)庫連接池會幫你把物理連接管好。3.2 查詢數(shù)據(jù)的幾種姿勢執(zhí)行 SQL 的入口是 MySqlCommand。根據(jù)返回結(jié)果的不同有三種常見用法。第一種讀取單行單列的值比如查詢用戶數(shù)量用 ExecuteScalarusing var cmd new MySqlCommand(SELECT COUNT(*) FROM t_user, conn); var count Convert.ToInt32(await cmd.ExecuteScalarAsync());第二種執(zhí)行 INSERT、UPDATE、DELETE 這類不返回結(jié)果集的語句用 ExecuteNonQueryusing var cmd new MySqlCommand(UPDATE t_user SET statusstatus WHERE idid, conn); cmd.Parameters.AddWithValue(status, 1); cmd.Parameters.AddWithValue(id, 1001); var affected await cmd.ExecuteNonQueryAsync();受影響行數(shù)可以幫助判斷更新是否真的命中數(shù)據(jù)如果 affected 0說明條件沒匹配到任何行。第三種查詢返回多行結(jié)果集用 ExecuteReaderusing var cmd new MySqlCommand(SELECT id, name, created_at FROM t_user WHERE statusstatus, conn); cmd.Parameters.AddWithValue(status, 1); using var reader await cmd.ExecuteReaderAsync(); while (await reader.ReadAsync()) { var id reader.GetInt32(id); var name reader.GetString(name); var time reader.GetDateTime(created_at); }用 ExecuteReader 時有一個非常致命的細節(jié)DataReader 是流式讀取的它占用著連接期間不能關(guān)閉連接也不能斷開連接必須把 DataReader 讀完或 Dispose 掉之后連接才能執(zhí)行其他 SQL 操作。很多人報錯“connection already open, and already in use”就是因為在同一個連接上先開了一個 DataReader沒有關(guān)閉就接著執(zhí)行下一條命令。3.3 參數(shù)化查詢防 SQL 注入的第一道防線新手最常見的錯誤寫法是拼接字符串var sql SELECT * FROM t_user WHERE name name ;如果 name 的值是 OR 11這條 SQL 就變成了查詢所有數(shù)據(jù)嚴重的還可能被刪庫。必須使用參數(shù)化查詢把值作為參數(shù)傳給 SQL 語句而不是寫進 SQL 文本里。var cmd new MySqlCommand(SELECT * FROM t_user WHERE namename, conn); cmd.Parameters.AddWithValue(name, name);注意 MySQL 的參數(shù)占位符是開頭。如果你是從 SqlServer 項目轉(zhuǎn)過來的習慣可能還是這個倒是相同但在操作 SQLite 用$參數(shù)的地方就會踩坑。參數(shù)化還有一個好處傳入的值會自動做類型轉(zhuǎn)換和轉(zhuǎn)義日期、布爾、空值都處理得比較穩(wěn)妥。但我還要提一句AddWithValue 雖然寫著“用起來方便”它對所有類型都會做隱式推斷在某些場景下可能推斷錯誤導致查詢條件失效或者索引失效。更嚴謹?shù)淖龇ㄊ莿?chuàng)建參數(shù)時指定類型cmd.Parameters.Add(new MySqlParameter(createdFrom, MySqlDbType.DateTime)); cmd.Parameters[createdFrom].Value fromDate;3.4 事務處理多條語句一起成功或一起失敗如果業(yè)務邏輯要做兩步操作比如訂單創(chuàng)建成功后扣減庫存這兩步要么都成功要么都失敗必須使用事務。MySQL 默認每條 SQL 都是自動提交的不包事務的話第一步成功、第二步失敗數(shù)據(jù)就臟了。事務寫法如下using var conn new MySqlConnection(connStr); await conn.OpenAsync(); using var tx await conn.BeginTransactionAsync(); try { using var cmd1 new MySqlCommand(UPDATE t_stock SET countcount-1 WHERE idid, conn, tx); cmd1.Parameters.AddWithValue(id, 1); await cmd1.ExecuteNonQueryAsync(); using var cmd2 new MySqlCommand(INSERT INTO t_order(user_id, product_id) VALUES(uid,pid), conn, tx); cmd2.Parameters.AddWithValue(uid, 10); cmd2.Parameters.AddWithValue(pid, 100); await cmd2.ExecuteNonQueryAsync(); await tx.CommitAsync(); } catch { await tx.RollbackAsync(); throw; }關(guān)鍵點在于創(chuàng)建 MySqlCommand 時要把事務對象作為第三個參數(shù)傳進去否則這條命令就在連接自己的隱式事務里執(zhí)行了并不會歸屬到 tx 這個事務下。很多人明明寫了事務卻發(fā)現(xiàn)回滾不生效就是漏了這個參數(shù)。事務開啟后要注意別在里面做太耗時的操作比如調(diào)用外部接口、等用戶輸入、執(zhí)行大批量計算。長事務會一直持有行鎖其他會話更新同一行數(shù)據(jù)時會阻塞等待積壓多了容易造成連接耗盡和死鎖。如果數(shù)據(jù)庫默認隔離級別是 REPEATABLE READ長事務還會導致數(shù)據(jù)快照問題讀到的一直是事務開始時的版本。這類問題的排查信號是業(yè)務上明明更新了數(shù)據(jù)同一個事務里再查結(jié)果還是老值。這個現(xiàn)象非常隱蔽建議事務體盡可能短、快速提交。4. 常見問題排查實錄這一部分是我最想分享的。C# 連 MySQL 的代碼本身很簡單但運行起來之后各種詭異問題基本都是環(huán)境或配置導致的。4.1 連接不上的排查鏈路遇到Unable to connect to any of the specified MySQL hosts先別急著改代碼。我一般按這個順序排查確認 MySQL 服務真的在運行。服務端執(zhí)行systemctl status mysql或 Windows 服務列表里看 MySQL 服務狀態(tài)。確認端口是否正確。連接串寫了 3306服務端實際監(jiān)聽 3036肯定連不上。確認防火墻是否放行。云服務器和本地服務器最容易因為安全組規(guī)則沒放行 3306 導致外網(wǎng)連不上直接 telnet 測試一下telnet 192.168.1.10 3306如果提示能連通但連接后馬上斷開那多半是服務端拒絕認證如果一直卡著不動那是網(wǎng)絡不通。檢查 MySQL 的 bind-address 配置。如果只監(jiān)聽 127.0.0.1那任何外部 IP 都沒法直接連需要改成0.0.0.0或指定內(nèi)網(wǎng)網(wǎng)卡地址。還有一個我踩過的細節(jié)Server 參數(shù)填寫 localhost客戶端可能會優(yōu)先嘗試走 socket 連接而不是 TCP。某些官方驅(qū)動的早期版本在 Linux 上對 localhost 的處理和預期不一致導致連不上。遇到莫名問題先把 localhost 改成 127.0.0.1 試試這個改動經(jīng)常能救急。4.2 MySQL 8 認證插件錯誤這個坑太經(jīng)典了我要單獨拿出來講。報錯信息通常是Authentication method caching_sha2_password not supportedMySQL 8 默認新建的用戶認證插件是 caching_sha2_password舊版本驅(qū)動沒實現(xiàn)這個協(xié)議所以連不上。有三種解決辦法第一種升級驅(qū)動。MySql.Data 8.x 以上版本已經(jīng)支持 caching_sha2_password升級后問題自然消失。這是最推薦的方案。dotnet add package MySql.Data --version 8.0.33第二種連接串里顯式設置加密相關(guān)參數(shù)SslModeNone;AllowPublicKeyRetrievalTrue;這樣客戶端會在需要時向服務器請求 RSA 公鑰完成密碼加密傳輸。這種方式可行但前面說過有安全風險生產(chǎn)環(huán)境如果開著 SSL 就不要再用這個組合。第三種把 MySQL 用戶改回舊的認證插件ALTER USER rootlocalhost IDENTIFIED WITH mysql_native_password BY password; FLUSH PRIVILEGES;這種做法的本質(zhì)是降低數(shù)據(jù)庫的認證安全性我不建議在新項目里這么干。它確實能解決驅(qū)動兼容問題適合維護老項目、無法升級場景下的臨時救急。4.3 亂碼問題挨著試不如懂原理插入數(shù)據(jù)后查詢出來是問號或者查詢條件帶中文查不到結(jié)果這種問題幾乎可以確定是字符集不一致。MySQL 里有一整套字符集體系牽扯到服務端默認字符集、數(shù)據(jù)庫字符集、表字符集、列字符集、客戶端連接字符集。最簡單的排查思路把連接串里的 CharSet 明確寫成 utf8mb4Serverlocalhost;Databasetestdb;Uidroot;Pwd123456;CharSetutf8mb4;同時檢查數(shù)據(jù)庫和表的字符集SHOW CREATE DATABASE testdb; SHOW CREATE TABLE t_user;如果建庫建表時沒指定默認可能繼承服務端的 latin1 或其他字符集這時需要在客戶端之外改庫表結(jié)構(gòu)ALTER DATABASE testdb CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; ALTER TABLE t_user CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;我特別強調(diào)一點MySQL 的“utf8”不是真正的全量 UTF-8它其實是 utf8mb3只能存基本多語言平面的字符像 emoji、部分生僻字就存不進去會直接報錯或存成亂碼。從 5.5 之后官方推薦使用 utf8mb4所以 C# 連接 MySQL 時CharSet 不要寫 utf8直接寫 utf8mb4。4.4 連接池耗盡與超時報錯信息出現(xiàn)Pool exhausted以及舊版驅(qū)動里的Timeout expired是并發(fā)場景下最常見的問題。登錄上去看數(shù)據(jù)庫進程列表你會看到大量 Sleep 狀態(tài)的連接數(shù)量接近服務端 max_connections。出現(xiàn)這種情況我把排查重心放在三個地方第一檢查代碼里是不是有連接未釋放。最常見的是 DataReader 沒有 Dispose或者事務拋異常后沒有執(zhí)行 Rollback連接一直被占用。最簡單的自測方法把所有數(shù)據(jù)庫操作都改成 using 包裹運行一段時間再查連接數(shù)。第二檢查是不是有人把 Pooling 設為 False。如果項目里有這樣的代碼Poolingfalse;那每次 Open 都會新建物理連接并發(fā)上來很容易打滿數(shù)據(jù)庫連接數(shù)。正常情況應該讓連接池工作。第三評估連接池上限有沒有調(diào)低或者被誤改成很小的值比如 Max Pool Size10而應用并發(fā)是幾百那基本上一秒不到就池耗盡了。在無法快速優(yōu)化代碼的臨時場景下可以適度調(diào)大 Max Pool Size比如 200但這是治標不治本真正的根因還是連接沒釋放或并發(fā)模型不合理。這個問題的另一個隱蔽來源是異步方法里沒有使用 await而是用.Result或.Wait()導致線程阻塞在異步操作上連接被占用卻不歸還。只要你發(fā)現(xiàn)線程數(shù)飆升、連接池很快耗盡就要去檢查是不是有人在異步代碼里用了同步等待。最后提一句show processlist;是排查連接問題的神器。看到幾百個 Sleep 連接就知道有人在退出前沒關(guān)連接看到一堆Query狀態(tài)且執(zhí)行時間很長就要懷疑有慢 SQL 或者鎖等待。先看進程列表再回代碼里找原因比瞎猜高效得多。我自己在實際項目里最深的體會是連接字符串的每一個參數(shù)都不是擺設連不上或者連上了不穩(wěn)定十有八九是參數(shù)配置出了問題而連接資源的管理是保證穩(wěn)定性的基本功。如果這篇文章只能留下一句話我希望是這句話先確認連接串再看進程列表最后才懷疑驅(qū)動和代碼。這套排查順序幫我解決了很多看起來“莫名其妙”的問題。