描述

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 具有一定的歷史性，因為該資料結構不再一定包含執行計劃。