SYNOPSIS
DECLARE name [ BINARY ] [ INSENSITIVE ] [ [ NO ] SCROLL ]
CURSOR [ { WITH | WITHOUT } HOLD ] FOR query
[ FOR { READ ONLY | UPDATE [ OF column [, ...] ] } ]
DESCRIPTION 描述
DECLARE 允許用戶創建游標， 用於在一個大的查詢里面檢索少數幾行數據。 使用 FETCH [fetch(7)]，游標可以既可以返回文本也可以返回二進制格式。
通常游標返回文本格式，和 SELECT 生成的是一樣的。 因為數據在系統內部是用二進制格式存儲的， 系統必須對數據做一定轉換以生成文本格式。 一旦數據是以文本形式返回，那么客戶端應用需要把它們轉換成二進制進行操作。 另外，文本格式一般都比對應的二進制格式占的存儲空間大。 二進制游標給你返回內部二進制形態的數據。當然，如果你想以文本方式顯示數據，那么以文本方式檢索會為你節約很多客戶端的工作。
比如，如果查詢從一個整數列返回一個一， 在缺省的游標里你將獲得一個字符串 1，而如果是一個二進制游標， 你將得到一個 4-字節的包含該數值內部形式的數值（大端序）。
游標應該小心使用二進制游標。一些用戶應用如 psql 是不識別二進制游標的， 而且期望返回的數據是文本格式。
- Note: 注意: 如果客戶端應用使用"擴展查詢"協議發出 FETCH 命令， 那么 Bind 協議聲明數據是用文本還是用二進制格式檢索。 這個選擇覆蓋游標的定義。因此，在使用擴展查詢協議的時候，二進制游標的概念已經過時了 － 任何游標都可以當作文本或者二進制的格式發出。
PARAMETERS 參數
- name
-
將在隨后FETCH操作中使用的游標名。 - BINARY
-
令游標以二進制而不是文本格式獲取數據。 - INSENSITIVE
-
表明從游標檢索出來的數據不應該被其他進程或游標的更新動作影響。 在 PostgreSQL 里，所有游標都是不敏感的，這個關鍵字沒有什么作用，提供它只是為了和 SQL 標准兼容。 - SCROLL
- NO SCROLL
- SCROLL 聲明該游標可以用於以非順序的方式檢索數據行（也就是向后檢索）。 根據查詢的執行計划的不同，聲明 SCROLL 可能會對查詢的執行時間附加一定的影響。 NO SCROLL 聲明該游標不能用於以非順序的方式檢索數據行（也就是向后檢索）。
- WITH HOLD
- WITHOUT HOLD
- WITH HOLD 聲明該游標可以在創建它的事務成功提交后繼續使用。 WITHOUT HOLD 聲明該游標不能在創建它的的事務提交后使用。如果既沒有聲明 WITHOUT HOLD，也沒有聲明 WITH HOLD， 那么缺省是 WITH HOLD。
- query
-
一個SELECT查詢，它提供由游標返回的行。 請參考 SELECT 語句獲取有關有效查詢的詳細信息。 - FOR READ ONLY
- FOR UPDATE
- FOR READ ONLY 表明游標將用於只讀模式。 FOR UPDATE 表明游標將被用於更新表。 因為目前 PostgreSQL 不支持游標更新， 所以聲明 FOR UPDATE 將產生一個錯誤信息。而聲明 FOR READ ONLY 沒有作用。
- column
-
將被更新的列。因為游標更新目前不被 PostgreSQL 支持， 所以 FOR UPDATE 子句將產生一個錯誤信息。
BINARY，INSENSITIVE，SCROLL 關鍵字可以以任何順序出現。
NOTES 注意
如果沒有聲明 WITH HOLD，那么這個命令創建的游標只能在當前事務中使用。 Thus, DECLARE without WITH HOLD is useless outside a transaction block: the cursor would survive only to the completion of the statement. Therefore PostgreSQL reports an error if this command is used outside a transaction block. 使用 BEGIN [begin(7)], COMMIT [commit(7)] 和 ROLLBACK [rollback(7)] 定義一個事務塊。
如果聲明了 WITH HOLD，並且創建該游標的事務成功提交， 那么游標還可以在同一會話隨后的事務里訪問。（但如果創建它的事務回滾，那么游標被刪除。） 帶着 WITH HOLD 創建的游標是用一個明確的 CLOSE 命令，或者是會話終止來關閉的。 在目前的實現里，由一個游標代表的行是被拷貝到一個臨時文件或者內存區里的，這樣他們就仍然可以在隨后的事務中被訪問。
在定義一個要用來向后抓取的游標的時候，我們應該聲明 SCROLL 選項。 這個是 SQL 標准要求的。不過，為了和早期的版本兼容， PostgreSQL 在沒有 SCROLL 的時候也允許向后抓取， 只要游標的查詢計划簡單得不需要額外的開銷就可以支持它。 不過，我們建議應用開發人員不要依賴於使用沒有帶着 SCROLL 定義的游標的后向查找功能。如果聲明了 NO SCROLL，那么不管怎樣都會禁止向后抓取的功能。
在 SQL 標准中游標只能在嵌入 SQL （ESQL） 的應用中使用。 PostgreSQL 服務器沒有一個明確的 OPEN 語句；一個游標被認為在定義時就已經打開了。 不過，PostgreSQL嵌入的 SQL 預編譯器， ecpg， 支持 SQL92 習慣，包括那些和DECLARE和OPEN相關的語句。
EXAMPLES 例子
定義一個游標：
DECLARE liahona CURSOR FOR SELECT * FROM films;
參閱 FETCH [fetch(7)] 獲取有關 游標使用的更多例子。