DECLARE nome [ BINARY ] [ INSENSITIVE ] [ [ NO ] SCROLL ]
CURSOR [ { WITH | WITHOUT } HOLD ] FOR consulta
[ FOR { READ ONLY | UPDATE [ OF coluna [, ...] ] } ]
O comando DECLARE permite o usuário criar cursores, que podem ser utilizados para trazer, de cada vez, um pequeno número de linhas de uma consulta grande. Os cursores podem retornar dados tanto no formato texto quanto binário usando o comando FETCH .
Cursores normais retornam dados no formato texto, o mesmo produzido pelo comando SELECT. Como os dados são armazenados nativamente no formato binário, o sistema necessita realizar uma conversão para gerar o formato texto. Como a informação chega no formato texto, a aplicação cliente pode precisar convertê-la para o formato binário para manipulá-la. Além disso, dados no formato texto geralmente possuem um tamanho maior que no formato binário. Os cursores binários retornam os dados na representação binária, que pode ser manipulada mais facilmente. Entretanto, se o objetivo é exibir os dados na forma de texto, trazê-los na forma de texto reduz um pouco o esforço no lado cliente.
Como exemplo, se uma consulta retornar o valor "um" de uma coluna com tipo de dado inteiro, será recebida a cadeia de caracteres 1 com o cursor padrão, enquanto que com um cursor binário será retornado um campo de 4 bytes contendo a representação interna do valor (na ordem de byte "big-endian" [1] ).
Os cursores binários devem ser usados com cuidado. Muitas aplicações, incluindo o psql, não estão preparadas para tratar cursores binários e esperam que os dados cheguem no formato texto.
Nota: Quando a aplicação cliente utiliza o protocolo "consulta estendida" (extended query) para executar o comando FETCH, a mensagem Bind do protocolo especifica se os dados devem retornar no formato texto ou binário. Esta escolha substitui a forma como o cursor foi definido. Por isso o conceito de cursor binário fica obsoleto ao se utilizar o protocolo "consulta estendida" — todo cursor pode ser tratado tanto como texto ou binário.
As palavras chave BINARY, INSENSITIVE e SCROLL podem estar em qualquer ordem.
A menos que WITH HOLD seja especificado, o cursor criado por este comando poderá ser utilizado apenas dentro da transação corrente. Portanto, DECLARE sem WITH HOLD não possui utilidade fora do bloco de transação: o cursor existe apenas até o término da instrução. Por esse motivo, o PostgreSQL relata um erro se este comando for utilizado fora de um bloco de transação. Devem ser utilizados os comandos BEGIN , COMMIT e ROLLBACK para definir um bloco de transação.
Se WITH HOLD for especificado, e a transação que criou o cursor for efetivada com sucesso, o cursor pode continuar sendo acessado pelas transações seguintes na mesma sessão (Mas se a transação que o criou for interrompida, o cursor é removido). O cursor criado com WITH HOLD é fechado quando um comando CLOSE explícito é executado para o cursor, ou quando a sessão termina. Na implementação atual, as linhas representadas por um cursor mantido são copiadas para um arquivo temporário, ou para uma área de memória, para permanecerem disponíveis para as transações seguintes.
A opção SCROLL deve ser especificada ao se definir um cursor utilizado para trazer para trás. Isto é requerido pelo padrão SQL. Entretanto, para manter a compatibilidade com as versões anteriores, o PostgreSQL permite trazer para trás sem a opção SCROLL, se o plano da consulta do cursor for simples o suficiente para que nenhum trabalho extra seja necessário para isto. Entretanto, aconselha-se aos desenvolvedores de aplicação a não confiar na utilização de trazer para trás a partir de um cursor que não tenha sido criado com a opção de SCROLL. Se NO SCROLL for especificado, então trazer para trás não é permitido em qualquer caso.
O padrão SQL somente trata de cursores na linguagem SQL incorporada. O servidor PostgreSQL não implementa o comando OPEN para cursores; o cursor é considerado aberto ao ser declarado. Entretanto o ECPG, o pré-processador do PostgreSQL para a linguagem SQL incorporada, suporta as convenções de cursor do padrão SQL, incluindo as que envolvem as instruções DECLARE e OPEN.
Para declarar um cursor:
DECLARE liahona CURSOR FOR SELECT * FROM filmes;
Veja no comando FETCH mais exemplos de utilização de cursor.
O padrão SQL permite cursores somente na linguagem SQL incorporada e nos módulos. O PostgreSQL permite que o cursor seja utilizado interativamente.
O padrão SQL permite que os cursores atualizem os dados das tabelas. Todos os cursores do PostgreSQL são somente para leitura.
Os cursores binários são uma extensão do PostgreSQL.
| [1] |
big-endian — uma arquitetura de computadores na qual, em uma representação numérica com vários bytes, o byte mais significativo possui o menor endereço (a palavra é armazenada com o "maior-fim-primeiro"). FOLDOC - Free On-Line Dictionary of Computing (N. do T.) |