DECLARE

Name

DECLARE  --  define um cursor

Synopsis

DECLARE nome_do_cursor [ BINARY ] [ INSENSITIVE ] [ SCROLL ]
    CURSOR FOR consulta
    [ FOR { READ ONLY | UPDATE [ OF coluna [, ...] ] ]
  

Entradas

nome_do_cursor

O nome do cursor a ser utilizado nas operações de busca (FETCH) posteriores.

BINARY

Faz com que o cursor busque os dados no formato binário em vez do formato texto.

INSENSITIVE

Palavra chave do SQL92 indicando que os dados buscados pelo cursor não devem ser afetados pelas atualizações feitas por outros processos ou cursores. Como as operações do cursor ocorrem dentro de uma transação no PostgreSQL, este é sempre o caso. Esta palavra chave não provoca qualquer efeito.

SCROLL

Palavra chave do SQL92 indicando que várias linhas de dados devem ser trazidas em cada operação de busca (FETCH). Como é sempre permitido pelo PostgreSQL, esta palavra chave não provoca qualquer efeito.

consulta

Uma consulta SQL que fornece as linhas a serem controladas pelo cursor. Consulte o comando SELECT para obter mais informações sobre os argumentos válidos.

READ ONLY

Palavra chave do SQL92 indicando que o cursor será usado no modo apenas para leitura. Como este é o único modo de acesso do cursor disponível no PostgreSQL, esta palavra chave não provoca qualquer efeito.

UPDATE

Palavra chave do SQL92 indicando que o cursor será usado para atualizar tabelas. Como as atualizações pelo cursor não são suportadas no momento pelo PostgreSQL, esta palavra chave provoca uma mensagem informando o erro.

coluna

Coluna(s) a serem atualizadas. Como as atualizações pelo cursor não são suportadas no momento pelo PostgreSQL, a cláusula UPDATE provoca uma mensagem informando o erro.

Saídas

SELECT

Mensagem retornada se o SELECT for executado com sucesso.

NOTICE: Closing pre-existing portal "nome_do_cursor"

Esta mensagem é exibida se o mesmo nome de cursor já estiver declarado no bloco de transação corrente. A definição anterior é descartada.

ERROR: DECLARE CURSOR may only be used in begin/end transaction blocks

Este erro ocorre quando o cursor não é declarado dentro de um bloco de transação.

Descrição

O comando DECLARE permite ao usuário criar cursores, os quais podem ser usados para buscar 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.

Os cursores normais retornam os dados no formato texto, em ASCII ou outro esquema de codificação dependendo de como o servidor PostgreSQL foi compilado. Como os dados são armazenados nativamente no formato binário, o sistema necessita fazer uma conversão para produzir o formato texto. Adicionalmente, o formato texto geralmente possui um tamanho maior do que o formato binário correspondente. Quando a informação retorna na forma de texto, o aplicativo cliente pode precisar converter para o formato binário para manipulá-la. Os cursores binários retornam os dados na representação binária nativa.

Por exemplo, se uma consulta retornar o valor "um" de uma coluna inteira, será recebida a cadeia de caracteres 1 com o cursor padrão, enquanto que o cursor binário retornaria um valor de 4 bytes igual a control-A (^A).

Os cursores binários devem ser usados com cuidado. Aplicativos do usuário, como o psql, não estão atentos a cursores binários, esperando que os dados cheguem no formato texto.

A representação da cadeia de caracteres é arquiteturalmente neutra, enquanto que a representação binária pode ser diferente entre máquinas com arquiteturas diferentes. O PostgreSQL não soluciona a ordem dos bytes ou outros problemas de representação para os cursores binários. Portanto, se a máquina cliente e a máquina servidora usam representações diferentes, (por exemplo, "big-endian" versus "little-endian"), provavelmente não vai ser desejado que os dados retornem no formato binário. Entretanto, os cursores binários podem ser um pouco mais eficientes porque existe menos sobrecarga de conversão na transferência de dados do servidor para o cliente.

Tip: Se a intenção for mostrar os dados em ASCII, buscar os dados em ASCII reduz o esforço realizado pelo cliente.

Notas

Os cursores só estão disponíveis nas transações. Use os comando BEGIN, COMMIT e ROLLBACK para definir um bloco de transação.

No SQL92 os cursores somente estão disponíveis nos aplicativos com SQL embutido (ESQL). O servidor PostgreSQL não implementa o comando OPEN cursor explícito; o cursor é considerado aberto ao ser declarado. Entretanto, o ecpg, o pré-processador SQL embutido do PostgreSQL, suporta as convenções de cursor do SQL92, incluindo as que envolvem os comandos DECLARE e OPEN.

Utilização

Para declarar um cursor:

DECLARE liahona CURSOR
    FOR SELECT * FROM filmes;
   

Compatibilidade

SQL92

O SQL92 permite cursores somente no SQL embutido e em módulos. O PostgreSQL permite que o cursor seja usado interativamente. O SQL92 permite aos cursores embutidos ou modulares atualizar as informações no banco de dados. Todos os cursores do PostgreSQL são apenas para leitura. A palavra chave BINARY é uma extensão do PostgreSQL.