# SPI_execute ## Name SPI_execute?--?執行一條命令 ## Synopsis ``` int SPI_execute(const char * command, bool read_only, long count) ``` ## 描述 `SPI_execute`執行聲明的 SQL 命令獲取`count` 行。如果`read_only`為`true`，命令必須是只讀的， 因此可以略微降低一些執行的開銷。 這個函數只能在已連接的過程中調用。 如果`count`是零，則在命令適合的所有行上執行。 如果`count`大于 0 ，那么將不會超過 `count`行被檢索；當達到計數時執行停止， 很像在查詢中添加了一個`LIMIT`子句。比如， ``` SPI_execute("SELECT * FROM foo", true, 5); ``` 將從表中最多檢索5行。請注意，這樣一個限制只在命令實際返回行時有效。例如， ``` SPI_execute("INSERT INTO foo SELECT * FROM bar", false, 5); ``` 插入`bar`中的所有行，忽略`count`參數。 不過， ``` SPI_execute("INSERT INTO foo SELECT * FROM bar RETURNING *", false, 5); ``` 將最多插入5行，因為在檢索到第5個`RETURNING`結果行之后執行將停止。 你可以在一個字符串里傳遞多個命令。`SPI_execute` 返回最后執行的命令的結果。`count` 的限制獨立地應用于每一個命令（即使實際只返回最后的結果）。 限制不會應用于規則生成的隱藏命令。 如果`read_only`是`false`，`SPI_execute` 遞增命令計數器并且在字符串里執行每個命令之前計算一個新的_快照_。 如果當前事務的隔離級別是`SERIALIZABLE`或`REPEATABLE READ`， 這個快照實際上并不改變，但是在`READ COMMITTED`模式里， 這個快照更新允許每個命令看到其它會話的新提交的事務的結果。 這樣實際上是為了修改數據庫的命令有一致的行為。 如果`read_only`是`true`，`SPI_execute` 并不更新快照或者命令計數器，并且它只允許簡單的`SELECT` 命令出現在命令字符串里。這個命令使用為周圍的查詢建立起來的快照執行。 這個執行模式比讀/寫模式執行得略微塊些，因為它消除了每個命令的一些開銷。 并且它還允許制作真正的_穩定_函數：因為隨后的執行都將使用同一個快照， 結果里不會有改變。 通常，在同一個使用 SPI 的函數里混雜只讀和讀寫命令是不明智的； 那樣可能導致非常混亂的行為，因為只讀的查詢不能看到任何讀寫的查詢做的數據庫更新。 (最后)一條命令執行返回的結果的實際行數會放在全局的變量 `SPI_processed`里。如果函數的返回值是`SPI_OK_SELECT`、 `SPI_OK_INSERT_RETURNING`、`SPI_OK_DELETE_RETURNING` 或`SPI_OK_UPDATE_RETURNING`，那么你可以使用全局指針 `SPITupleTable *SPI_tuptable`訪問結果行。一些實用命令 (比如`EXPLAIN`)還返回行集合，并且`SPI_tuptable` 也將在這種情況下包含結果。一些實用命令（`COPY`, `CREATE TABLE AS`） 并不返回行集，所以`SPI_tuptable`為NULL，但是它們仍然返回 `SPI_processed`中處理了的行數。 結構`SPITupleTable`是這樣定義的： ``` typedef struct { MemoryContext tuptabcxt; /* memory context of result table */ uint32 alloced; /* number of alloced vals */ uint32 free; /* number of free vals */ TupleDesc tupdesc; /* row descriptor */ HeapTuple *vals; /* rows */ } SPITupleTable; ``` `vals`是一個指向數據行的的指針數組(有效記錄的數目由 `SPI_processed`給出)。`tupdesc`是一個行描述符， 你可以傳遞給 SPI 函數處理這些數據行。`tuptabcxt`、 `alloced`和`free`是 SPI 的內部字段， 并非給 SPI 調用者使用的。 `SPI_finish`釋放所有在當前過程中分配的`SPITupleTable`。 如果你已經處理完特定的結果表，那么可以更早地釋放它，方法是調用 `SPI_freetuptable`。 ## 參數 `const char *` `command` 包含要執行的命令的字符串 `bool` `read_only` `true`用于只讀的執行 `long` `count` 返回的最大行數，或者沒有限制時為`0` ## 返回值 如果命令執行成功，那么返回下列值之一(非負數)： `SPI_OK_SELECT` 如果執行了一個`SELECT`但不是`SELECT INTO` `SPI_OK_SELINTO` 如果執行了一條`SELECT INTO` `SPI_OK_INSERT` 如果執行了一條`INSERT` `SPI_OK_DELETE` 如果執行了一條`DELETE` `SPI_OK_UPDATE` 如果執行了一條`UPDATE` `SPI_OK_INSERT_RETURNING` 如果執行了一條`INSERT RETURNING` `SPI_OK_DELETE_RETURNING` 如果執行了一條`DELETE RETURNING` `SPI_OK_UPDATE_RETURNING` 如果執行了一條`UPDATE RETURNING` `SPI_OK_UTILITY` 如果執行了一條實用命令(比如`CREATE TABLE`) `SPI_OK_REWRITTEN` 如果該命令通過一個[規則](#calibre_link-472)重新寫入了另一個類型的命令 （比如，`UPDATE`變成一個`INSERT`） 發生錯誤時，返回下列負數值之一： `SPI_ERROR_ARGUMENT` 如果`command`是`NULL`或 `count`小于 0 `SPI_ERROR_COPY` 如果企圖進行`COPY TO stdout`或`COPY FROM stdin` `SPI_ERROR_TRANSACTION` 如果嘗試事務操縱命令(`BEGIN`, `COMMIT`, `ROLLBACK`, `SAVEPOINT`, `PREPARE TRANSACTION`, `COMMIT PREPARED`, `ROLLBACK PREPARED`, 或它們的變種) `SPI_ERROR_OPUNKNOWN` 命令類型未知(不應該發生) `SPI_ERROR_UNCONNECTED` 如果從一個未連接的過程中調用 ## 注意 所有SPI查詢執行函數設置了`SPI_processed`和`SPI_tuptable` (只是一個指針，不是結構的內容)。如果你需要跨越后面的調用訪問`SPI_execute` 或者另一個查詢執行函數的結果表，那么需要把這兩個全局變量保存到一個局部過程變量中。