MySQL 8.4 C API 開發者指南  /  C API 預處理語句介面  /  C API 預處理語句介面概述

6.1 C API 預處理語句介面概述

為了準備和執行語句,應用程式需要遵循以下步驟:

  1. 使用 mysql_stmt_init() 建立一個預處理語句處理器。若要在伺服器上準備語句,請呼叫 mysql_stmt_prepare() 並傳遞包含 SQL 語句的字串。

  2. 使用 mysql_stmt_bind_param()mysql_stmt_bind_named_param() 設定任何參數的值。必須設定所有參數。否則,語句執行會傳回錯誤或產生非預期的結果。

    如果需要傳送大量的文字或二進制資料值,您可以使用 mysql_stmt_send_long_data() 以區塊的方式將它們傳送到伺服器。

  3. 呼叫 mysql_stmt_execute() 以執行語句。

  4. 如果語句是 SELECT 或任何其他產生結果集的語句,若需要取得結果集的元資料,請呼叫 mysql_stmt_result_metadata()。這個元資料本身是以 MYSQL_RES 結果集的形式存在,但與包含查詢傳回的列的結果集是分開的。元資料結果集會指出結果中的欄位數,並包含每個欄位的相關資訊。

  5. 如果語句產生結果集,請呼叫 mysql_stmt_bind_result() 將資料緩衝區繫結以用於擷取列值。

  6. 透過重複呼叫 mysql_stmt_fetch(),直到找不到更多列為止,將資料逐列擷取到緩衝區中。

  7. 視需要重複步驟 3 到 6。您可以重複 mysql_stmt_execute(),透過變更透過 mysql_stmt_bind_param()mysql_stmt_bind_named_param() 提供的各自緩衝區中的參數值,重新執行語句。

  8. 語句執行完成時,使用 mysql_stmt_close() 關閉語句處理器,以便釋放與其關聯的所有資源。此時,處理器會變成無效,且不應再使用。

  9. 如果您透過呼叫 mysql_stmt_result_metadata() 取得 SELECT 語句的結果集元資料,您也應使用 mysql_free_result() 釋放元資料。

呼叫 mysql_stmt_prepare() 時,MySQL 客戶端/伺服器協定會執行這些動作:

  • 伺服器會剖析語句,並透過指派語句 ID 將「確定」狀態傳送回客戶端。它也會傳送參數總數、欄位計數,以及如果它是以結果集為導向的語句,則傳送其元資料。語句的所有語法和語意都會在此呼叫期間由伺服器檢查。

  • 客戶端會將此語句 ID 用於後續作業,以便伺服器可以從其語句池中識別出語句。

呼叫 mysql_stmt_execute() 時,MySQL 客戶端/伺服器協定會執行這些動作:

  • 客戶端會使用語句處理器,並將參數資料傳送到伺服器。

  • 伺服器會使用客戶端提供的 ID 識別語句,將參數標記替換為新提供的資料,並執行語句。如果語句產生結果集,伺服器會將資料傳送回客戶端。否則,它會傳送「確定」狀態和已變更、刪除或插入的列數。

呼叫 mysql_stmt_fetch() 時,MySQL 客戶端/伺服器協定會執行這些動作:

  • 客戶端會從結果集的目前列讀取資料,並透過執行必要的轉換,將其放入應用程式資料緩衝區中。如果應用程式緩衝區類型與伺服器傳回的欄位類型相同,則轉換會很簡單。

如果發生錯誤,您可以使用 mysql_stmt_errno()mysql_stmt_error()mysql_stmt_sqlstate() 分別取得語句錯誤編號、錯誤訊息和 SQLSTATE 代碼。

預處理語句記錄

對於使用 mysql_stmt_prepare()mysql_stmt_execute() C API 函式執行的預處理語句,伺服器會將 PrepareExecute 行寫入一般查詢日誌,以便您可以知道何時準備和執行語句。

假設您準備並執行語句,如下所示:

  1. 呼叫 mysql_stmt_prepare() 以準備語句字串 "SELECT ?"

  2. 呼叫 mysql_stmt_bind_param()mysql_stmt_bind_named_param(),將值 3 繫結至預處理語句中的參數。

  3. 呼叫 mysql_stmt_execute() 以執行預處理語句。

由於上述呼叫的結果,伺服器會將下列行寫入一般查詢日誌:

Prepare  [1] SELECT ?
Execute  [1] SELECT 3

日誌中的每個 PrepareExecute 行都會以 [N] 語句識別碼加上標籤,以便您可以追蹤記錄的是哪個預處理語句。N 是一個正整數。如果客戶端同時有多個預處理語句處於活動狀態,則 N 可能大於 1。每個 Execute 行都會顯示將資料值取代為 ? 參數後的預處理語句。