DECLARE(7)

NAME
DECLARE - 定義一個游標

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)] 獲取有關 游標使用的更多例子。

COMPATIBILITY 相容性

SQL 標準只允許在嵌入的 SQL 中和模組中使用游標。 PostgreSQL 允許互動地使用游標。

SQL 標準允許游標更新表資料。 所有 PostgreSQL 的游標都是隻讀的。

 二進位制游標是 PostgreSQL 擴充套件。

譯者
Postgresql 中文網站 何偉平 <laser@pgsqldb.org>

跋
本頁面中文版由中文 man 手冊頁計劃提供。
中文 man 手冊頁計劃：https://github.com/man-pages-zh/manpages-zh