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.
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.
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.
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.
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.
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).
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.
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.