描述

SPI_prepare 建立並傳回指定命令的預處理語句，但不執行該命令。預處理語句之後可以使用 SPI_execute_plan 重複執行。

當相同或類似的命令需要重複執行時，通常只需執行一次剖析分析，並且重複使用該命令的執行計畫可能也很有利。SPI_prepare 將命令字串轉換為預處理語句，該語句封裝了剖析分析的結果。預處理語句還提供了一個位置來快取執行計畫，如果發現為每次執行產生自訂計畫沒有幫助。

預處理命令可以通過在正常命令中會是常數的位置寫入參數（$1、$2 等）來進行泛化。然後，在呼叫 SPI_execute_plan 時指定參數的實際值。這使得預處理命令可以比沒有參數的情況下用於更廣泛的情況。

SPI_prepare 傳回的語句只能在 C 函數的當前調用中使用，因為 SPI_finish 會釋放為此類語句分配的記憶體。但是，可以使用函式 SPI_keepplan 或 SPI_saveplan 將語句儲存更長時間。

引數

傳回值

SPI_prepare 傳回一個指向 SPIPlan 的非空指標，它是一個表示預處理語句的不透明結構。如果發生錯誤，將傳回 NULL，並且 SPI_result 將設定為與 SPI_execute 使用的相同的錯誤代碼之一，但如果 command 為 NULL，或者如果 nargs 小於 0，或者如果 nargs 大於 0 且 argtypes 為 NULL，則會設定為 SPI_ERROR_ARGUMENT。

註記

如果未定義任何參數，則將在首次使用 SPI_execute_plan 時建立一個通用計畫，並將其用於所有後續執行。 如果有參數，則前幾次使用 SPI_execute_plan 將產生特定於所提供參數值的自訂計畫。 在足夠多次使用相同的預處理語句後，SPI_execute_plan 將建立一個通用計畫，如果該計畫的成本不太高於自訂計畫，它將開始使用通用計畫而不是每次都重新規劃。 如果此預設行為不合適，您可以通過將 CURSOR_OPT_GENERIC_PLAN 或 CURSOR_OPT_CUSTOM_PLAN 標誌傳遞給 SPI_prepare_cursor 來更改它，以分別強制使用通用或自訂計畫。

儘管預處理語句的主要目的是避免重複的語句剖析分析和規劃，但每當語句中使用的資料庫物件自上次使用預處理語句以來發生了定義 (DDL) 更改時，PostgreSQL 都會在每次使用預處理語句之前強制重新分析和重新規劃語句。 此外，如果 search_path 的值從一次使用變更為下一次使用，則將使用新的 search_path 重新剖析該語句。 （後者行為是 PostgreSQL 9.3 中的新功能。） 有關預處理語句行為的更多資訊，請參閱 PREPARE。

此函式只能從連線的 C 函式呼叫。

SPIPlanPtr 在 spi.h 中宣告為指向不透明結構型別的指標。 嘗試直接存取其內容是不明智的，因為這會使您的程式碼在未來修訂的 PostgreSQL 中更容易崩潰。

名稱 SPIPlanPtr 在某種程度上是歷史性的，因為資料結構不再一定包含執行計畫。