Um trigger faz o PostgreSQL chamar uma função automaticamente quando uma tabela muda. Escreva primeiro a função de trigger, declarada RETURNS trigger, e depois ligue-a: CREATE TRIGGER name BEFORE UPDATE ON table FOR EACH ROW EXECUTE FUNCTION fn();. O uso clássico é manter uma coluna updated_at sempre atualizada:
Só o post 1 foi atualizado, então só ele tem timestamp. NEW é a linha que está prestes a ser gravada; um trigger BEFORE pode alterá-la e precisa retorná-la. Você pode ligar a mesma função a todas as tabelas que têm uma coluna updated_at.
BEFORE, AFTER e INSTEAD OF
| Momento | Roda | Uso típico |
|---|---|---|
BEFORE | antes de a linha ser gravada | alterar ou validar NEW, ou pular a linha |
AFTER | depois de a linha ser gravada | gravar em outras tabelas: logs de auditoria, contadores |
INSTEAD OF | no lugar da alteração, só em views | tornar uma view gravável |
FOR EACH ROW roda a função uma vez por linha afetada. FOR EACH STATEMENT (o padrão) roda uma vez por comando, mesmo que nenhuma linha mude. Num trigger de linha, NEW tem a linha nova (INSERT, UPDATE) e OLD a anterior (UPDATE, DELETE). TG_OP diz qual operação o disparou e TG_TABLE_NAME, a tabela.
O valor de retorno de um trigger BEFORE de linha decide o que acontece: retorne NEW (alterado ou não) para seguir em frente, ou NULL para pular a linha sem erro. O retorno de um trigger AFTER é ignorado, então por convenção ele retorna NULL.
Gravar um log de auditoria com um trigger AFTER
A tabela de auditoria registra dois INSERT, um UPDATE de 10 para 12 e um DELETE do produto que custava 20. OLD é NULL num insert e NEW é NULL num delete, por isso o coalesce. Para guardar linhas inteiras, coloque to_jsonb(OLD) e to_jsonb(NEW) numa coluna jsonb.
Bloquear ou pular uma alteração
Um trigger BEFORE pode rejeitar uma alteração com RAISE EXCEPTION, que aborta o comando, ou pular uma linha retornando NULL:
O DELETE removeu o rascunho e manteve em silêncio a fatura paga. Um trigger BEFORE DELETE retorna OLD para deixar a exclusão acontecer. Para fazer o comando inteiro falhar, troque RETURN NULL por RAISE EXCEPTION 'invoice % is paid', OLD.id;. Um erro é mais fácil de depurar do que uma linha que fica sem ninguém perceber.
Disparar só quando uma coluna muda
UPDATE OF column limita um trigger aos updates que definem aquela coluna. Uma condição WHEN pula a chamada da função quando é falsa. IS DISTINCT FROM trata NULL como um valor, então também pega mudanças para ou de NULL:
O primeiro update define o mesmo preço, então o WHEN é falso e o contador fica em 0. O segundo muda o preço, e price_changed termina em 1.
Listar, desabilitar e excluir triggers
-- triggers you created (excludes the ones behind foreign keys)
SELECT tgrelid::regclass AS table_name, tgname
FROM pg_trigger WHERE NOT tgisinternal;
ALTER TABLE products DISABLE TRIGGER products_price;
ALTER TABLE products ENABLE TRIGGER products_price;
DROP TRIGGER products_price ON products;
No psql, \d products lista os triggers de uma tabela. CREATE OR REPLACE TRIGGER existe desde o PostgreSQL 14, e EXECUTE FUNCTION desde o PostgreSQL 11; código antigo usa EXECUTE PROCEDURE, que ainda funciona. Um trigger que grava na própria tabela pode se disparar de novo, então proteja contra loops (pg_trigger_depth() retorna o nível de aninhamento). O capítulo de funções de trigger lista todas as variáveis TG_, e funções e procedures cobre o PL/pgSQL.
Perguntas frequentes
Um trigger do PostgreSQL pode rodar sem uma função?
Não. CREATE TRIGGER sempre chama uma função declarada RETURNS trigger. Escreva a função primeiro, normalmente em PL/pgSQL, e depois ligue o trigger.
Em que ordem disparam os triggers da mesma tabela?
Triggers do mesmo tipo no mesmo evento disparam em ordem alfabética dos nomes. Coloque números ou letras no início dos nomes se a ordem importar.
Um erro no trigger desfaz o comando?
Sim. Um erro lançado num trigger, por exemplo com RAISE EXCEPTION, aborta o comando que o disparou, e a transação inteira, a menos que você o capture com um savepoint.
Triggers disparam no TRUNCATE?
Triggers DELETE de linha não. Crie um trigger de comando com BEFORE TRUNCATE ou AFTER TRUNCATE para reagir a ele.