Triggers

Um trigger é uma regra que vive dentro da base de dados e dispara sozinha sempre que uma linha de uma tabela é inserida, alterada ou apagada. Não depende de quem escreveu: venha a escrita de um ecrã, de uma API, de um script ou de outra aplicação ligada à mesma base de dados, o trigger corre.

É esse o argumento a favor dos triggers, e também o cuidado que exigem — lógica que corre sem ninguém a chamar é lógica que ninguém vê a acontecer.

#Onde vivem os triggers

Na árvore do datasource, dentro do grupo Programação, ao lado das Funções / Procedimentos:

Clicar num trigger abre-o num separador do espaço de trabalho, com o seu fluxo desenhado.

#Criar um trigger

1. Passa o rato pelo datasource e abre o menu ⋯.
2. Escolhe Novo trigger. Abre-se o diálogo com os dados iniciais do trigger — o fluxo constrói-se a seguir no canvas.
3. Preenche:

Campo	O que é
Nome	O nome do trigger na base de dados. A convenção sugerida é trg_minha_tabela.
Tabela	A tabela vigiada.
Momento	BEFORE (antes de a linha ser escrita) ou AFTER (depois).
Eventos	INSERT, UPDATE, DELETE — pelo menos um. Alguns motores aceitam vários no mesmo trigger, outros só um.

4. Confirma com Criar e abrir canvas.

O trigger nasce como rascunho: já existe na plataforma, mas ainda não foi aplicado à base de dados. Enquanto for rascunho, a árvore identifica-o como tal.

#Momento e eventos, na prática

Escolha	Para quê
BEFORE INSERT/UPDATE	Normalizar ou completar valores antes de serem gravados — pôr um código em maiúsculas, preencher um campo derivado.
AFTER INSERT/UPDATE/DELETE	Reagir ao que já aconteceu — escrever um histórico, actualizar um total noutra tabela.

Os valores da linha estão disponíveis conforme o evento: os Valores novos (NEW) existem no INSERT e no UPDATE; os Valores antigos (OLD) só aparecem quando o trigger ouve UPDATE ou DELETE — num INSERT não há linha antiga para mostrar.

#O canvas do trigger

O fluxo desenha-se num canvas, e a dica no topo resume o gesto: arrasta funções/procedimentos da árvore para o canvas; duplo clique numa caixa configura os seus outputs/inputs.

Na barra por cima do canvas estão, da esquerda para a direita:

Botão	O que faz
Definições	Reabre nome, tabela, Momento e Eventos do trigger.
(o resumo)	O nome, a tabela, o momento e os eventos, sempre à vista.
Expressão	Acrescenta um nó de expressão ao fluxo.
Ver SQL	Mostra o trigger compilado, sem executar nada.
Guardar e aplicar na BD	Grava e aplica o trigger ao motor.

#A caixa da tabela — o que entra no fluxo

A primeira caixa do canvas é a tabela: é dela que saem os valores da linha que disparou o trigger. Faz-lhe duplo clique para abrir os Outputs do trigger e escolher o que este trigger expõe ao fluxo: colunas individuais, a linha inteira (JSON), ou ambos.

• Valores novos (NEW) — a linha como fica.
• Valores antigos (OLD) — a linha como estava.
• Em qualquer dos dois, além das colunas soltas, podes expor a linha inteira (JSON) — útil para entregar tudo de uma vez a uma função de histórico.

Cada saída escolhida vira uma porta na caixa, pronta a ser ligada.

#As funções e os procedimentos

O trabalho, num trigger, é feito por funções e procedimentos que já existem na base de dados. Arrasta-os da árvore (Programação ▸ Funções / Procedimentos) para o canvas: cada um vira uma caixa com um parâmetro por entrada.

1. Liga uma porta da tabela ao parâmetro que ela alimenta — o parâmetro passa a mostrar-se como ligado.
2. Um parâmetro sem ligação fica com o seu valor por omissão.
3. As funções também devolvem valor: a porta de retorno pode alimentar outra caixa, encadeando passos.
4. O menu da própria caixa tem Remover do fluxo.

Para desfazer uma ligação, clica na linha: Remover esta ligação? O parâmetro deixa de receber este valor.

#Os nós de expressão

Entre uma porta e um parâmetro nem sempre o valor serve como está. O botão Expressão acrescenta um nó que refina/transforma valores: declaras Inputs (com + input), ligas-lhes portas, e escreves a Expressão SQL usando {a}, {b}… para os inputs ligados — por exemplo upper({a}) || '-' || {b}. O resultado sai na porta do nó e segue para onde quiseres.

Faz duplo clique no nó para o configurar (a própria caixa diz duplo clique para editar… enquanto está vazia).

#Ver o SQL antes de aplicar

Ver SQL abre a pré-visualização — SQL do trigger (pré-visualização) — com o aviso que interessa: Compilado com as tuas alterações actuais — nada foi executado. Avalia e aplica quando quiseres.

É o passo de segurança: vês exactamente o que vai ser criado na base de dados, podes copiá-lo, mostrá-lo a quem administra o motor, e só depois aplicar. O mesmo diálogo tem o botão Guardar e aplicar na BD à mão.

#Aplicar o trigger

Guardar e aplicar na BD faz as duas coisas: grava o desenho e cria o trigger no motor. Quando corre bem, a plataforma confirma: Trigger aplicado na base de dados.

Antes de aplicar, o desenho é verificado. As recusas são explícitas:

Mensagem	O que falta
Dá um nome ao trigger (Definições).	O nome.
Escolhe a tabela (Definições).	A tabela vigiada.
Escolhe pelo menos um evento (Definições).	Pelo menos um de INSERT/UPDATE/DELETE.
O canvas não tem nenhuma função/procedimento.	Um fluxo vazio não faz nada — arrasta pelo menos uma função.
Há um nó de expressão sem expressão definida.	Um nó de expressão em branco.

#Eliminar um trigger

O menu ⋯ do trigger na árvore tem Eliminar, com confirmação — Eliminar o trigger "…"? — e é definitivo: o trigger sai da base de dados.

#Ver o que está na base de dados

A consola SQL, por baixo do diagrama do modelo, é o sítio para confirmar o efeito de um trigger: escreve uma consulta, Executar, e vê as linhas reais. É também por aqui que se inspecciona o que já lá estava antes de tu chegares.

#Trigger, script ou workflow?

As três coisas automatizam, e a escolha certa evita meses de confusão:

Ferramenta	Corre…	Boa para
Trigger	Dentro da base de dados, a cada escrita da tabela.	Regras que têm de valer para todas as escritas: histórico, campos derivados, totais.
Script	Fora da base de dados, à mão, agendado ou como passo de uma API.	Trabalho pesado, integrações, ficheiros, envios — tudo o que demora ou fala com o exterior.
Workflow	Como um processo com passos, decisões e tarefas humanas.	Aprovações, circuitos com pessoas pelo meio, esperas.

#Porque não…?

• Porque não aparece Novo trigger no menu do datasource? O motor ligado não suporta triggers desenhados no canvas. Continuas a poder criá-los em SQL, e eles aparecem na árvore como triggers externos.
• Porque é que o trigger continua a dizer que é rascunho? Foi criado mas ainda não foi aplicado. Abre-o e usa Guardar e aplicar na BD.
• Porque não vejo os Valores antigos (OLD)? O trigger não ouve UPDATE nem DELETE. Num INSERT não existe linha antiga.
• Porque é que não consigo ligar uma porta a um parâmetro? Nem todas as ligações fazem sentido — confirma que estás a ligar uma saída (à direita da caixa) a uma entrada (à esquerda da outra).
• Porque é que o trigger não faz nada? Um fluxo sem funções não gera trabalho nenhum: a compilação recusa-o. E confirma o Momento — um BEFORE e um AFTER não vêem a mesma coisa.
• Porque é que as escritas ficaram lentas depois de criar o trigger? O trigger corre em cada linha escrita. Se chama trabalho pesado, esse trabalho passou a acontecer em cada inserção — nesses casos, o sítio é um script agendado.