Descrição

O comando LISTEN registra a sessão corrente como ouvinte no canal de notificação chamado canal. Se a sessão corrente já estiver cadastrada como ouvinte desse canal de notificação, nada será feito.

Sempre que o comando NOTIFY canal é executado, seja por esta sessão, ou por outra conectada ao mesmo banco de dados, todas as sessões escutando este canal de notificação serão notificadas, e cada uma, por sua vez, notificará sua aplicação cliente conectada.

A sessão pode cancelar seu registro em um determinado canal de notificação usando o comando UNLISTEN. Os registros de ouvinte da sessão são cancelados automaticamente quando a sessão termina.

O método que a aplicação cliente deve usar para detectar eventos de notificação, depende de qual interface de programação de aplicação (API) do PostgreSQL está sendo usada. Com a biblioteca libpq, a aplicação executa LISTEN como um comando SQL comum e, em seguida, deverá chamar periodicamente a função PQnotify para descobrir se alguma notificação eventos foi recebida. Outras interfaces, como a libpgtcl, fornecem métodos de alto nível para lidar com eventos de notificação; de fato, com a libpgtcl o programador da aplicação nem mesmo deve executar LISTEN ou UNLISTEN diretamente. Veja a documentação da interface que se está sendo usada para obter mais detalhes.

Parâmetros

Notas

O comando LISTEN entra em vigor quando a transação é efetivada. Se for executado LISTEN ou UNLISTEN em uma transação que não for efetivada, o conjunto de canais de notificação que estão sendo ouvidos permanecerá inalterado.

Uma transação que executa o comando LISTEN não pode ser preparada para efetivação de duas fases.

Há uma janela de vulnerabilidade ao configurar inicialmente uma sessão ouvinte: se transações com efetivação concorrente estiverem enviando eventos de notificação, quais destes a nova sessão ouvinte receberá? A resposta é que a sessão receberá todos os eventos efetivados após um instante, durante a etapa de efetivação da transação. Mas isto é um pouco mais tarde do que qualquer estado do banco de dados que a transação poderia ter observado nas consultas. Isto leva à seguinte regra para usar o comando LISTEN: primeiro este comando deve ser executado (e efetivado!), em seguida, em uma nova transação, inspecionado o estado do banco de dados conforme necessário pela lógica da aplicação e, em seguida, contar com as notificações para descobrir as alterações subsequentes no estado do banco de dados. As primeiras notificações recebidas podem se referir a atualizações já observadas na inspeção inicial do banco de dados, mas isto geralmente é inofensivo.

O comando NOTIFY contém uma discussão mais detalhada sobre o uso dos comandos LISTEN e NOTIFY.

Exemplos

Configurar e executar uma sequência de ouvinte/notificação no psql:

LISTEN virtual;
NOTIFY virtual;
Notificação assíncrona "virtual" recebida do processo servidor com PID 8448.

Conformidade

Não existe o comando LISTEN no padrão SQL.

Veja também