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