# DECLARE ## Name DECLARE?--?定義一個游標 ## Synopsis ``` DECLARE _name_ [ BINARY ] [ INSENSITIVE ] [ [ NO ] SCROLL ] CURSOR [ { WITH | WITHOUT } HOLD ] FOR _query_ ``` ## 描述 `DECLARE`允許用戶創建游標，用于在一個大的查詢里面檢索少數幾行數據。 在游標建立后，使用[FETCH](#calibre_link-74)可以從中取出行。 > **Note:** 本頁描述游標在SQL命令級別的使用。如果你試圖在一個PL/pgSQL函數里面使用游標， 結果往往是不同的；參閱[Section 40.7](#calibre_link-491)。 ## 參數 `_name_` 將要創建的游標名。 `BINARY` 令游標以二進制而不是文本格式返回數據。 `INSENSITIVE` 表明從游標檢索出來的數據不應該被發生在游標創建后的游標的更新動作影響。 在PostgreSQL里，這是缺省行為；這個關鍵字沒有什么作用， 只在為了和 SQL 標準兼容的時候接受它。 `SCROLL``NO SCROLL` `SCROLL`聲明該游標可以用于以倒序的方式檢索數據行(也就是反向檢索)。 根據查詢的執行計劃的不同，聲明`SCROLL`可能會對查詢的執行時間有不良影響。 `NO SCROLL`聲明該游標不能用于以倒序的方式檢索數據行。 缺省僅允許在某些情況下倒序檢索，這不同于指定`SCROLL`。 參見[_注意_](#calibre_link-492)獲取細節。 `WITH HOLD` `WITHOUT HOLD` `WITH HOLD`(缺省)聲明該游標可以在創建它的事務成功提交后繼續使用。 `WITHOUT HOLD`聲明該游標不能在創建它的事務之外使用。 `_query_` 一個[SELECT](#calibre_link-104)或[VALUES](#calibre_link-106)命令，它提供游標返回的行。 `BINARY`, `INSENSITIVE`, `SCROLL` 關鍵字可以以任何順序出現。 ## 注意 通常游標和`SELECT`一樣返回文本格式。`BINARY` 選項聲明游標應該返回二進制格式的數據。這樣就減少了服務器和客戶端的轉化工作， 花費程序員更多的工作解決平臺依賴的二進制數據格式問題。 比如，如果查詢從某個整數列返回 1 ，在缺省的游標里將獲得一個字符串`1`， 但在二進制游標里將得到一個 4 字節的包含該數值內部形式的數值(大端順序)。 應該小心使用二進制游標。一些客戶端應用(比如psql) 是不能識別二進制游標的，它們期望返回的數據是文本格式。 > **Note:** 如果客戶端應用使用"擴展查詢"協議發出`FETCH`命令， 那么 Bind 協議聲明數據是用文本還是用二進制格式檢索。這個選擇覆蓋游標的定義。 因此，在使用擴展查詢協議的時候，二進制游標的概念已經過時了， 任何游標都可以當作文本或者二進制的格式發出。 如果沒有聲明`WITH HOLD`，那么這個命令創建的游標只能在當前事務中使用。 這樣，不帶`WITH HOLD`的`DECLARE`在事務塊外面沒有任何用處： 游標將一直存活到事務結束。因此，PostgreSQL 將在這樣的命令出現在事務塊外面的時候報錯。使用[BEGIN](#calibre_link-493), [COMMIT](#calibre_link-494)和[ROLLBACK](#calibre_link-495)定義一個事務塊。 如果聲明了`WITH HOLD`并且創建該游標的事務成功提交， 那么游標還可以在同一會話隨后的事務里訪問。但如果創建它的事務回滾， 那么游標被刪除。帶`WITH HOLD`創建的游標是用一個明確的 `CLOSE`命令或者是會話終止來關閉的。在目前的實現里， 由一個游標代表的行是被拷貝到一個臨時文件或者內存區里的， 這樣他們就仍然可以在隨后的事務中被訪問。 當查詢包含`FOR UPDATE`或`FOR SHARE`的時候， 不能指定`WITH HOLD`。 在定義一個要用來反向抓取的游標的時候，應該聲明`SCROLL`選項， 這是 SQL 標準要求的。不過，為了和早期的版本兼容， 只要游標的查詢計劃簡單得不需要額外的開銷，PostgreSQL 在沒有聲明`SCROLL`的時候也允許反向抓取。不過， 建議應用開發人員不要依賴于使用沒有使用`SCROLL` 定義的游標的反向查找功能。如果聲明了`NO SCROLL` ， 那么不管怎樣都會禁止反向抓取的功能。 當查詢包含`FOR UPDATE`或`FOR SHARE`時也不允許反向抓取； 因此在這種情況下不能聲明`SCROLL`。 | **Caution** | |:--- | | 如果調用任何不穩定的函數，那么可以回滾并且`WITH HOLD` 游標可能給出意外的結果（參閱xref linkend="xfunc-volatility">）。 當重新抓取到以前抓取到的行時，函數可能會重新執行，可能導致結果與之前的不同。 一個繞開這種情況的方法是聲明`WITH HOLD`游標， 并且在從它讀取任何行之前提交事務。這將強制游標的整個輸出在臨時存儲中物化， 這樣不穩定的函數精確的每行只執行一次。 | 如果游標的查詢包括`FOR UPDATE`或`FOR SHARE`， 那么返回的行在它們第一次被抓取的時候鎖定，和有這個選項的[SELECT](#calibre_link-104) 一樣。另外，返回行將是最新的版本；因此提供這些選項相當于SQL標準調用一個 "敏感的游標"。（和`FOR UPDATE`或 `FOR SHARE`一起指定`INSENSITIVE`是錯誤的。） | **Caution** | |:--- | | 如果游標定義為使用`UPDATE ... WHERE CURRENT OF`或 `DELETE ... WHERE CURRENT OF`，通常推薦使用`FOR UPDATE`。 使用`FOR UPDATE`阻止其他會話在抓取和更新之間改變行。沒有`FOR UPDATE`， 如果在創建游標后改變了行，那么隨后的`WHERE CURRENT OF`命令將沒有作用。 使用`FOR UPDATE`的另外一個原因是，沒有它，如果游標查詢不符合SQL標準的 "簡單可更新"原則，那么隨后的`WHERE CURRENT OF`可能會失敗 （尤其是，游標必須只引用一個表，并且不使用分組或`ORDER BY`）。 不是簡單可更新的游標可能會也可能不會工作，取決于計劃選擇細節；所以在最壞的情況下， 應用可能在測試中工作而在生產中失敗。 不和`WHERE CURRENT OF`一起使用`FOR UPDATE`的主要原因是， 你需要游標是可回滾的，或對隨后的更新不敏感的（也就是說，持續顯示舊的數據）。 如果需要這樣，請注意上面顯示的注意事項。 | SQL 標準中的游標只能在嵌入SQL(ESQL)的應用中使用。 PostgreSQL服務器沒有一個明確的`OPEN` 語句；一個游標被認為在定義時就已經打開了。不過，PostgreSQL 嵌入的 SQL 預處理器(ECPG)支持 SQL 標準的習慣， 包括那些和`DECLARE`和`OPEN`相關的語句。 可以通過查詢[`pg_cursors`](#calibre_link-73) 系統視圖看到所有可用游標。 ## 例子 定義一個游標： ``` DECLARE liahona CURSOR FOR SELECT * FROM films; ``` 參閱[FETCH](#calibre_link-74)獲取有關游標使用的更多例子。 ## 兼容性 SQL標準說它是依賴于實現的，不管游標對缺省的底層數據的當前更新是否敏感。 在PostgreSQL中，游標缺省是敏感的，并且可以通過聲明 `FOR UPDATE`使其敏感。其他產品工作可能不同。 SQL 標準只允許在嵌入的SQL中和模塊中使用游標。 PostgreSQL允許交互地使用游標。 二進制游標是PostgreSQL擴展。 ## 又見 [CLOSE](#calibre_link-69), [FETCH](#calibre_link-74), [MOVE](#calibre_link-75)