Linux 環境下使用 C/C++ 連接 MySQL 資料庫完整指南（上）

前言

在 Linux 系統上開發需要存取 MySQL 資料庫的 C/C++ 應用程式時，正確配置開發環境與理解核心 API 是關鍵。本文將詳細介紹從安裝開發函式庫、編譯參數設定，到核心連接函數的使用與完整程式碼範例，幫助你快速上手。

一、環境準備與安裝

1. 系統需求

• 作業系統：Ubuntu 12.04 LTS 或更新版本
• 已安裝 MySQL 5.5+ 伺服器
• 編譯工具：gcc/g++ 或 Code::Blocks IDE

2. 安裝 MySQL 開發函式庫

預設系統並未安裝 C/C++ 開發所需的標頭檔與連結庫，需透過套件管理器安裝 libmysqlclient-dev（舊版 Ubuntu 可能名為 libmysqld-dev）：

sudo apt-get update
sudo apt-get install libmysqlclient-dev

安裝完成後，標頭檔將位於 /usr/include/mysql/ 目錄下，包含 mysql.h 等關鍵檔案。

3. 編譯與連結設定

使用 g++ 命令列編譯

需加入 -lmysqlclient 連結選項：

g++ -lmysqlclient mysql_test.cpp -o mysqltest

使用 Code::Blocks IDE

1. 開啟專案屬性：Project → Build options
2. 選擇 Linker settings 分頁
3. 在 Link libraries 中新增 mysqlclient
4. 確定並重新建置專案

二、核心 API 深度解析

所有函數皆宣告於 <mysql/mysql.h>，程式開頭需包含：

#include <mysql/mysql.h>

1. 建立連線的兩步驟

步驟 1：初始化連線控制結構

MYSQL *mysql_init(MYSQL *connection);
// 成功返回 MYSQL 結構指標，失敗返回 NULL

傳入 NULL 可讓函數自動配置記憶體，建議寫法：

MYSQL *conn = mysql_init(NULL);
if (!conn) { /* 處理錯誤 */ }

步驟 2：建立實際資料庫連線

MYSQL *mysql_real_connect(
    MYSQL *connection,
    const char *host,        // 伺服器主機名或 IP
    const char *user,        // 使用者名稱
    const char *passwd,      // 密碼
    const char *db,          // 資料庫名稱（可為 NULL）
    unsigned int port,       // 連接埠，通常為 0 使用預設 3306
    const char *unix_socket, // Unix socket 路徑，通常為 NULL
    unsigned int client_flag // 客戶端旗標，通常為 0
);
// 成功返回連線控制指標，失敗返回 NULL

2. 關閉連線與資源釋放

void mysql_close(MYSQL *connection);
// 關閉連線並釋放連線控制結構記憶體，指標失效

3. 連線選項設定 mysql_options()

必須在 mysql_init() 之後、mysql_real_connect() 之前呼叫：

int mysql_options(MYSQL *connection, enum mysql_option option, const char *argument);

常用選項：

4. 錯誤處理函數

unsigned int mysql_errno(MYSQL *connection);  // 返回錯誤代碼，0 表示無錯誤
const char *mysql_error(MYSQL *connection);   // 返回以 null 結尾的錯誤訊息字串

5. 執行 SQL 語句

通用執行函數

int mysql_query(MYSQL *connection, const char *query);
// 成功返回 0，失敗返回非零值

非查詢類語句（INSERT/UPDATE/DELETE）影響列數

my_ulonglong mysql_affected_rows(MYSQL *connection);
// 返回上一條 SQL 語句影響的資料列數

三、完整程式範例：互動式 SQL 執行器

以下程式示範連線建立、錯誤處理、從標準輸入讀取 SQL 語句並執行、統計影響列數、最後正確關閉連線。

#include <iostream>
#include <fstream>
#include <cstdlib>
#include <mysql/mysql.h>
#include <string>

using namespace std;

void print_mysql_error(MYSQL *conn) {
    if (mysql_errno(conn)) {
        cerr << "Error " << mysql_errno(conn) << " : " << mysql_error(conn) << endl;
    }
}

int main() {
    MYSQL *conn = mysql_init(NULL);
    if (!conn) {
        cerr << "mysql_init() failed!" << endl;
        return EXIT_FAILURE;
    }

    // 連線參數請依實際環境修改
    if (!mysql_real_connect(conn, "localhost", "root", "123456", "test", 0, NULL, 0)) {
        cerr << "Connection to MySQL failed!" << endl;
        print_mysql_error(conn);
        mysql_close(conn);
        return EXIT_FAILURE;
    }

    cout << "Connected to MySQL server successfully." << endl;

    string sql_line;
    int total_affected = 0;
    int query_result = 0;

    cout << "Enter SQL statements (type 'close' or empty line to exit):" << endl;

    while (getline(cin, sql_line)) {
        if (sql_line == "close" || sql_line.empty()) break;

        query_result = mysql_query(conn, sql_line.c_str());
        if (query_result) {
            print_mysql_error(conn);
            break;
        }

        total_affected += mysql_affected_rows(conn);
        cout << "OK. Affected rows: " << mysql_affected_rows(conn) << endl;
    }

    cout << "Total affected rows: " << total_affected << endl;
    mysql_close(conn);
    cout << "Connection closed." << endl;

    return EXIT_SUCCESS;
}

四、常見問題與最佳實踐

• 編譯找不到標頭檔：確認 libmysqlclient-dev 已安裝，且包含路徑正確（-I/usr/include/mysql 通常由 pkg-config 自動處理）。
• 連線被拒絕：檢查 MySQL 服務是否運行、防火牆設定、bind-address 設定、使用者權限與密碼。
• 中文亂碼：連線建立後立即執行 SET NAMES utf8mb4 或使用 mysql_options(conn, MYSQL_SET_CHARSET_NAME, "utf8mb4")。
• 記憶體洩漏：所有路徑（正常結束、錯誤提前返回）都必須呼叫 mysql_close()。
• 預處理語句：生產環境強烈建議使用 mysql_stmt_prepare() 等預處理 API，防止 SQL 注入並提升效能。

五、總結

掌握 mysql_init、mysql_real_connect、mysql_query、mysql_affected_rows、mysql_error 等核心函數，配合正確的編譯連結參數，即可在 Linux 上開發高效穩健的 C/C++ MySQL 客戶端程式。下一篇將深入探討結果集處理、預處理語句與交易控制。