您现在的位置：程式碼之家 >> 數據庫知識 > >> MySQL 資料庫 >> MySQL 資料庫相關知識

MySQL C API 深度解析：mysql_real_connect() 參數全攻略

編輯：MySQL 資料庫相關知識

前言

mysql_real_connect() 是 MySQL C API 建立資料庫連線的核心函數。正確理解每個參數的含義、預設行為及常見陷阱，對開發穩健的 MySQL 客戶端程式至關重要。本文基於官方文檔深度解析各參數，並提供最佳實踐配置模板。

函數原型

MYSQL *mysql_real_connect(
    MYSQL *mysql,           // 已初始化的 MYSQL 結構指標
    const char *host,       // 主機名或 IP
    const char *user,       // 用戶名
    const char *passwd,     // 密碼
    const char *db,         // 預設資料庫
    unsigned int port,      // TCP 端口
    const char *unix_socket,// Unix socket/Windows named pipe 路徑
    unsigned long client_flag // 客戶端功能標誌位
);

參數詳細解析

1. mysql (MYSQL *)

必須先呼叫 mysql_init(NULL) 或 mysql_init(&my_struct) 初始化。
可呼叫 mysql_options() 設定連線選項（超時、字符集、SSL 等）。

2. host (const char *)

NULL 或 "localhost"：連線本機。Unix 走 Unix Socket，Windows 走 Named Pipe（若啟用），否則回退 TCP 127.0.0.1。
IP 地址 (如 "192.168.1.100")：強制 TCP/IP 連線。
主機名 (如 "db-server")：經 DNS 解析後 TCP 連線。
注意：host 參數決定連線協議類型，port/unix_socket 為輔助。

3. user (const char *)

NULL 或 ""：Unix 取當前登入用戶名；Windows 必須顯式指定（ODBC 環境）。
生產環境強烈建議顯式指定，避免環境差異導致連線失敗。

4. passwd (const char *)

NULL：僅匹配 mysql.user 表中 authentication_string 為空的賬號。
空字串 ""：明確要求密碼為空（不同於 NULL，選項檔無法覆蓋）。
切勿自行加密：客戶端庫自動處理認證協議（caching_sha2_password、mysql_native_password 等）。

5. db (const char *)

指定連線成功後的預設資料庫（相當於 USE db）。
NULL 或 ""：不切換資料庫，後續查詢需帶庫前綴或呼叫 mysql_select_db()。

6. port (unsigned int)

0：使用預設端口 3306（MySQL 預設）。
非 0：指定 TCP 端口。僅在 host 為 IP/主機名時生效；host 為 localhost/NULL 時被忽略（走 Socket/Pipe）。

7. unix_socket (const char *)

指定 Unix Socket 檔案路徑（如 /tmp/mysql.sock）或 Windows Named Pipe 名稱。
NULL：使用編譯時預設或 MYSQL_UNIX_PORT 環境變數。
僅在 host 為 localhost/NULL 時生效。

8. client_flag (unsigned long) - 關鍵功能開關

位元組合，常用標誌：

標誌常量	功能說明	適用場景
CLIENT_COMPRESS	啟用壓縮協議	跨公網/低帶寬環境傳輸大量數據
CLIENT_FOUND_ROWS	UPDATE 返回匹配行數而非影響行數	需區分「已是目標值」與「實際修改」的業務
CLIENT_IGNORE_SPACE	允許函數名後有空格	兼容非標準 SQL 生成器
CLIENT_INTERACTIVE	使用 interactive_timeout 替代 wait_timeout	長連線交互式客戶端（如 CLI 工具）
CLIENT_LOCAL_FILES	啟用 LOAD DATA LOCAL INFILE	需從客戶端導入本地文件
CLIENT_MULTI_STATEMENTS	允許單次查詢執行多條 SQL（分號分隔）	批量執行 DDL/DML、遷移腳本
CLIENT_MULTI_RESULTS	支援多結果集（存儲過程、多語句）	配合 MULTI_STATEMENTS 自動啟用
CLIENT_SSL	使用 SSL 加密連線	勿直接設定，應呼叫 `mysql_ssl_set()` 後自動置位
CLIENT_REMEMBER_OPTIONS	記住 mysql_options 設定供重連使用	需自動重連場景 (MariaDB/Connector/C)

推薦預設組合：CLIENT_MULTI_STATEMENTS | CLIENT_MULTI_RESULTS | CLIENT_REMEMBER_OPTIONS（現代應用常需多語句、存儲過程、自動重連）。

最佳實踐連線代碼模板 (C)

MYSQL *connect_mysql(const char *host, const char *user, const char *pass, const char *db, unsigned int port) {
    MYSQL *mysql = mysql_init(NULL);
    if (!mysql) { fprintf(stderr, "mysql_init() failed\n"); return NULL; }

    // 連線超時 5 秒
    mysql_options(mysql, MYSQL_OPT_CONNECT_TIMEOUT, (const char *)&(int){5});
    // 自動重連 (MariaDB/Connector/C 支援)
    my_bool reconnect = 1;
    mysql_options(mysql, MYSQL_OPT_RECONNECT, &reconnect);
    // 字符集 utf8mb4
    mysql_options(mysql, MYSQL_SET_CHARSET_NAME, "utf8mb4");
    // 讀取選項檔 [client] 區段
    mysql_options(mysql, MYSQL_READ_DEFAULT_GROUP, "myapp");

    unsigned long flags = CLIENT_MULTI_STATEMENTS | CLIENT_MULTI_RESULTS | CLIENT_REMEMBER_OPTIONS;

    if (!mysql_real_connect(mysql, host, user, pass, db, port, NULL, flags)) {
        fprintf(stderr, "Connection failed [%d]: %s\n", mysql_errno(mysql), mysql_error(mysql));
        mysql_close(mysql);
        return NULL;
    }
    printf("Connected to MySQL %s (Thread ID: %lu)\n", mysql_get_server_info(mysql), mysql_thread_id(mysql));
    return mysql;
}

錯誤碼速查與處理

錯誤碼	含義	典型原因與對策
CR_CONN_HOST_ERROR	無法連線到 MySQL Server	主機名解析失敗、防火牆阻攔、Server 未啟動
CR_CONNECTION_ERROR	無法連線到本地 MySQL Server	Socket 檔案不存在、權限不足、Server 崩潰
CR_IPSOCK_ERROR	建立 IP Socket 失敗	系統文件描述符耗盡、網路子系統故障
CR_OUT_OF_MEMORY	記憶體不足	進程/系統記憶體耗盡
CR_SOCKET_CREATE_ERROR	建立 Unix Socket 失敗	Socket 路徑目錄不存在、權限問題
CR_UNKNOWN_HOST	主機名解析失敗	DNS 故障、/etc/hosts 缺失
CR_VERSION_ERROR	協議版本不匹配	極舊客戶端連新 Server 需加 --old-protocol
CR_SERVER_LOST	連線過程中 Server 掛掉	connect_timeout 過短、Server 啟動中崩潰

常見坑點總結

localhost ≠ 127.0.0.1：前者走 Socket，後者走 TCP。Docker/容器環境必須用 127.0.0.1 或實際 IP。
密碼含特殊字符：在選項檔或命令列傳遞時需正確轉義，建議統一用選項檔 [client] password="..."。
SSL 驗證失敗：mysql_ssl_set() 必須在 mysql_real_connect() 前呼叫，且 CA 憑證路徑正確。
多語句執行：開啟 CLIENT_MULTI_STATEMENTS 後，需循環呼叫 mysql_next_result() 處理每個結果集，否則會「Commands out of sync」錯誤。
自動重連陷阱：重連後會話變數（SET NAMES、time_zone、用戶變數）丟失，需在重連回調中恢復。

結語

mysql_real_connect() 參數看似繁多，實則邏輯清晰：初始化結構 → 設定選項 → 指定目標與憑證 → 啟用功能標誌。掌握 host 決定協議、client_flag 控制能力、mysql_options() 微調行為三大核心，配合選項檔管理憑證，即可編寫出健壯、可移植、高性能的 MySQL C 客戶端程式。