DECLARE nome [ BINARY ] [ INSENSITIVE ] [ [ NO ] SCROLL ] CURSOR [ { WITH | WITHOUT } HOLD ] FOR comando [ FOR { READ ONLY | UPDATE [ OF coluna [, ...] ] } ]
O comando DECLARE permite o usuário criar cursores, que podem ser utilizados para retornar, 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 através do comando FETCH.
Os cursores normais retornam dados no formato texto, o mesmo que seria produzido pelo comando SELECT. Como os dados são armazenados nativamente no formato binário, o sistema necessita realizar uma conversão para produzir o formato texto. Como a informação retorna no formato texto, o aplicativo cliente poderá 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 for 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 o cursor binário será retornado um campo de 4 bytes contendo a representação interna do valor (na ordem de bytes big-endian). [1]
Os cursores binários devem ser usados com cuidado. Muitos aplicativos, incluindo o psql, não estão preparados para tratar cursores binários e esperam que os dados retornem no formato texto.
Nota: Quando o aplicativo cliente utiliza o protocolo "comando estendido" (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 prevalece sobre a forma como o cursor foi definido. O conceito de cursor binário como tal fica, portanto, obsoleto quando se utiliza o protocolo "comando estendido" — todo cursor pode ser tratado tanto como texto ou binário.
O nome do cursor a ser criado.
Faz o cursor retornar os dados no formato binário em vez do formato texto.
Indica que os dados retornados pelo cursor não devem ser afetados pelas atualizações feitas nas tabelas subjacentes ao cursor, enquanto o cursor existir. No PostgreSQL todos os cursores são INSENSITIVE; atualmente esta palavra chave não produz efeito, estando presente por motivo de compatibilidade com o padrão SQL.
SCROLL (rolar) especifica que o cursor pode ser utilizado para retornar linhas de uma maneira não seqüencial (por exemplo, para trás). Dependendo da complexidade do plano de execução do comando, especificar SCROLL pode impor uma penalidade de desempenho no tempo de execução do comando. NO SCROLL especifica que o cursor não pode ser utilizado para retornar linhas de uma maneira não seqüencial.
WITH HOLD especifica que o cursor pode continuar sendo utilizado após a transação que o criou ter sido efetivada com sucesso. WITHOUT HOLD especifica que o cursor não pode ser utilizado fora da transação que o criou. Quando não é especificado nem WITHOUT HOLD nem WITH HOLD, o padrão é WITHOUT HOLD.
O comando SELECT que produz as linhas retornadas pelo cursor. Para obter informações adicionais sobre as consultas válidas deve ser consultado o comando SELECT.
FOR READ ONLY indica que o cursor será utilizado no modo somente para leitura. FOR UPDATE indica que o cursor será utilizado para atualizar tabelas. Uma vez que as atualizações por cursor não são suportadas atualmente pelo PostgreSQL, especificar FOR UPDATE provoca uma mensagem de erro, e especificar FOR READ ONLY não produz efeito.
As colunas a serem atualizadas pelo cursor. Uma vez que as atualizações por cursor não são suportadas atualmente pelo PostgreSQL, a cláusula FOR UPDATE provoca uma mensagem de erro.
As palavras chave BINARY, INSENSITIVE e SCROLL podem estar em qualquer ordem.
A não ser que WITH HOLD seja especificado, o cursor criado por este comando poderá ser utilizado somente dentro da transação corrente. Portanto, DECLARE sem WITH HOLD não possui utilidade fora de um bloco de transação: o cursor sobreviveria apenas até o término do comando. 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 efetivação da transação que criou o cursor for bem-sucedida, o cursor poderá continuar sendo acessado pelas transações seguintes na mesma sessão (Mas se a transação que criou o cursor for interrompida, o cursor será removido). O cursor criado com WITH HOLD é fechado quando é submetido um comando CLOSE explícito para o cursor, ou quando a sessão termina. Na implementação atual as linhas representadas por um cursor com WITH HOLD 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 retornar linhas para trás. Isto é requerido pelo padrão SQL. Entretanto, para manter a compatibilidade com as versões anteriores, o PostgreSQL permite retornar linhas para trás sem a opção SCROLL, se o plano de comando do cursor for simples o bastante para que nenhum trabalho extra seja necessário para isto. Porém, aconselha-se aos desenvolvedores de aplicativos a não confiarem no uso de retornar linhas para trás a partir de um cursor que não tenha sido criado com a opção de SCROLL. Se for especificado NO SCROLL, então retornar linhas para trás não será permitido em nenhum 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 os comandos DECLARE e OPEN.
Para declarar um cursor:
DECLARE liahona CURSOR FOR SELECT * FROM filmes;
Para ver mais exemplos de utilização de cursor deve ser consultado o comando FETCH.
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.) |
