38.1. Visão geral do comportamento de gatilho de evento #

38.1.1. login
38.1.2. ddl_command_start
38.1.3. ddl_command_end
38.1.4. sql_drop
38.1.5. table_rewrite
38.1.6. Gatilhos de evento em transações interrompidas
38.1.7. Criação de gatilhos de eventos

Um gatilho de evento é disparado sempre que o evento ao qual está associado ocorre no banco de dados onde está definido. No momento, os eventos com suporte são ddl_command_start, ddl_command_end, table_rewrite e sql_drop. Poderá ser adicionado suporte para eventos adicionais em versões futuras.

38.1.1. login #

O evento login ocorre quando um usuário autenticado faz acessa o sistema. Qualquer erro no procedimento de ativação deste evento pode impedir o acesso bem-sucedido ao sistema. Estes erros podem ser contornados configurando event_triggers como false seja na cadeia de caracteres de conexão ou no arquivo de configuração. Como alternativa, pode-se reiniciar o sistema no modo de usuário único (já que os gatilhos de eventos são desativados neste modo). Veja a página de referência postgres para obter mais informações sobre como usar o modo de usuário único. O evento login também será disparado em servidores em espera. Para evitar que os servidores fiquem inacessíveis, estes gatilhos devem evitar escrever qualquer coisa no banco de dados quando estiverem em execução em um servidor em espera. Além disso, recomenda-se evitar consultas de longa duração em gatilhos de eventos login. Observe que, por exemplo, cancelar uma conexão no psql não cancelará o gatilho de login em andamento.

Para ver um exemplo de como usar o gatilho de evento login, veja Exemplo de gatilho de evento de login no banco de dados.

38.1.2. ddl_command_start #

O evento ddl_command_start ocorre imediatamente antes da execução de um comando de DDL. Os comandos de DDL neste contexto são:

  • CREATE

  • ALTER

  • DROP

  • COMMENT

  • GRANT

  • IMPORT FOREIGN SCHEMA

  • REINDEX

  • REFRESH MATERIALIZED VIEW

  • REVOKE

  • SECURITY LABEL

ddl_command_start também ocorre imediatamente antes da execução de um comando SELECT INTO, uma vez que este comando equivale a CREATE TABLE AS.

Como exceção, este evento não ocorre para comandos de DDL direcionados a objetos compartilhados:

  • bancos de dados

  • funções de banco de dados (roles) (definição ou participação)

  • espaços de tabelas

  • privilégios de parâmetro

  • ALTER SYSTEM

Este evento também não ocorre para comandos que têm como destino os próprios gatilhos de eventos.

Não é feita nenhuma verificação para determinar se o objeto afetado existe ou não antes que o gatilho do evento seja disparado.

38.1.3. ddl_command_end #

O evento ddl_command_end ocorre logo após a execução do mesmo conjunto de comandos que ddl_command_start. Para obter mais detalhes sobre as operações de DDL realizadas, deve ser usada a função que retorna conjunto pg_event_trigger_ddl_commands() do código de gatilho de evento ddl_command_end (veja Funções de gatilho de evento para obter mais informações). Note que o gatilho é disparado depois que as ações ocorreram (mas antes da transação ser efetivada) e, portanto, os catálogos do sistema podem ser lidos como já alterados.

38.1.4. sql_drop #

O evento sql_drop ocorre imediatamente antes do gatilho de evento ddl_command_end para qualquer operação que exclua objetos do banco de dados. Note que, além dos comandos óbvios DROP, alguns comandos ALTER também podem acionar um evento sql_drop.

Para listar os objetos excluídos, deve ser usada a função que retorna conjunto pg_event_trigger_dropped_objects() do código de gatilho de evento sql_drop (veja Funções de gatilho de evento para obter mais informações). Note that the trigger is executed after the objects have been deleted from the system catalogs, so it's not possible to look them up anymore.

38.1.5. table_rewrite #

O evento table_rewrite ocorre imediatamente antes da tabela ser reescrita por alguma ação dos comandos ALTER TABLE e ALTER TYPE. Embora existam outras instruções de controle disponíveis para reescrever uma tabela, como CLUSTER e VACUUM, o evento table_rewrite não é disparado por eles. Para encontrar o OID da tabela que foi reescrita deve ser usada a função pg_event_trigger_table_rewrite_oid(), e para descobrir o(s) motivo(s) da reescrita, deve ser usada a função pg_event_trigger_table_rewrite_reason() (veja Funções de gatilho de evento para obter mais informações).

38.1.6. Gatilhos de evento em transações interrompidas #

Os gatilhos de eventos (assim como outras funções) não podem ser executados em uma transação interrompida. Assim, se um comando de DDL falhar com um erro, quaisquer gatilhos ddl_command_end associados não serão executados. Por outro lado, se um gatilho ddl_command_start falhar com um erro, nenhum outro gatilho de evento será disparado e nenhuma tentativa será feita para executar o próprio comando. Da mesma forma, se um gatilho ddl_command_end falhar com um erro, os efeitos da instrução de DDL serão revertidos, assim como ocorreria em qualquer outro caso em que a transação que a contém fosse interrompida.

38.1.7. Criação de gatilhos de eventos #

Os gatilhos de evento são criados usando o comando CREATE EVENT TRIGGER. Para criar um gatilho de evento, se deve primeiro criar uma função com o tipo retornado especial event_trigger. Esta função não precisa (nem pode) retornar um valor; o tipo retornado serve apenas como sinal de que a função deve ser chamada como gatilho de evento.

Se for definido mais de um gatilho de evento para um determinado evento, eles serão disparados na ordem alfabética do nome do gatilho.

A definição de gatilho também pode especificar uma condição WHEN para que, por exemplo, um gatilho ddl_command_start possa ser disparado apenas para comandos específicos que o usuário deseja interceptar. Um uso comum desses gatilhos é restringir o intervalo de operações de DDL que os usuários podem executar.