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 是不識別二進位制遊標的， 而且期望返回的資料是文字格式。

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;

COMPATIBILITY 相容性

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

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

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

譯者

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

跋

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