MySQL 9.0 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 將狀態 OK 傳送回用戶端。它也會傳送參數總數、欄數,以及如果是以結果集為導向的語句,則傳送其元資料。語句的所有語法和語意都會在此呼叫期間由伺服器檢查。

  • 用戶端會將此語句 ID 用於進一步的操作,以便伺服器可以從其語句池中識別該語句。

呼叫 mysql_stmt_execute() 時,MySQL 用戶端/伺服器協定會執行以下動作

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

  • 伺服器會使用用戶端提供的 ID 來識別語句,將參數標記取代為新提供的資料,並執行該語句。如果語句產生結果集,伺服器會將資料傳送回用戶端。否則,伺服器會傳送狀態 OK 和變更、刪除或插入的資料列數。

呼叫 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 行都會顯示以資料值取代 ? 參數後的預處理語句。