MySQL C API 完整參考：資料結構、核心函數、連線流程與結果集處理詳解

核心資料結構

MYSQL_FIELD 關鍵成員

• name、table、def (預設值)
• type：FIELD_TYPE_TINY、_LONG、_LONGLONG、_STRING、_BLOB、_DATE 等
• length (定義寬度)、max_length (結果集實際最大寬度)
• flags：NOT_NULL_FLAG、PRI_KEY_FLAG、AUTO_INCREMENT_FLAG、UNSIGNED_FLAG 等
• decimals：數值欄位小數位數

連線與查詢基本流程

MYSQL mysql;
mysql_init(&mysql);
if (!mysql_real_connect(&mysql, "host", "user", "pass", "db", 0, NULL, 0)) {
    fprintf(stderr, "Connect failed: %s\n", mysql_error(&mysql));
    return 1;
}

/* 執行查詢 */
if (mysql_query(&mysql, "SELECT * FROM users")) {
    fprintf(stderr, "Query failed: %s\n", mysql_error(&mysql));
    return 1;
}

/* 取得完整結果集 (緩衝模式) */
MYSQL_RES *res = mysql_store_result(&mysql);
if (res) {
    MYSQL_ROW row;
    while ((row = mysql_fetch_row(res))) {
        unsigned long *lengths = mysql_fetch_lengths(res);
        for (unsigned int i = 0; i < mysql_num_fields(res); i++) {
            printf("[%.*s] ", (int)lengths[i], row[i] ? row[i] : "NULL");
        }
        puts("");
    }
    mysql_free_result(res);
}

/* 或使用非緩衝模式 (逐行拉取，省記憶體) */
MYSQL_RES *res = mysql_use_result(&mysql);
while ((row = mysql_fetch_row(res))) { ... }
mysql_free_result(res);

mysql_close(&mysql);

核心 API 函數分類速查

連線控制

• mysql_init()、mysql_real_connect()、mysql_close()
• mysql_change_user()、mysql_ping() (斷線重連)
• mysql_options()：MYSQL_OPT_CONNECT_TIMEOUT、MYSQL_READ_DEFAULT_FILE、MYSQL_OPT_COMPRESS 等

查詢執行

• mysql_query() (NUL 終結字串)、mysql_real_query() (含長度，支援二進位)

結果集處理

• 緩衝：mysql_store_result()、mysql_fetch_row()、mysql_data_seek()、mysql_num_rows()
• 非緩衝：mysql_use_result()、mysql_fetch_row() (不可隨機存取、不可預知行數)
• 通用：mysql_fetch_field(s)()、mysql_fetch_lengths()、mysql_field_seek/tell()、mysql_free_result()

資訊與錯誤

• mysql_affected_rows()、mysql_insert_id()、mysql_field_count()
• mysql_errno()、mysql_error()、mysql_sqlstate()
• mysql_get_server_info()、mysql_get_client_info()、mysql_get_host_info()

管理功能

• mysql_list_dbs/tables/fields/processes()
• mysql_kill()、mysql_shutdown()、mysql_reload()、mysql_dump_debug_info()

錯誤處理最佳實踐

if (mysql_query(&mysql, sql)) {
    fprintf(stderr, "Error %u: %s\n", mysql_errno(&mysql), mysql_error(&mysql));
    /* 依錯誤碼決定重試/告警/退出 */
}

永遠檢查回傳值：指標類函數非 NULL 表成功，整數類函數 0 表成功。

線程安全提醒

• 編譯時加 --with-thread-safe-client；
• 同一連線不可多線程並發 mysql_query；
• mysql_store_result 取得的 MYSQL_RES 可多線程唯讀；
• 使用 mysql_use_result 時，結果集未關閉前不可在同連線執行其他查詢。