Triggers no SQLite: CREATE TRIGGER, BEFORE/AFTER e OLD/NEW

Um trigger executa SQL automaticamente

Um trigger no SQLite é um bloco de SQL armazenado que dispara sempre que um evento específico acontece em uma determinada tabela. Você escreve uma vez. O SQLite cuida do "quando" pra você.

A estrutura básica:

CREATE TABLE products (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    price REAL NOT NULL
);

CREATE TABLE price_history (
    product_id INTEGER,
    old_price REAL,
    new_price REAL,
    changed_at TEXT DEFAULT CURRENT_TIMESTAMP
);

CREATE TRIGGER log_price_change
AFTER UPDATE OF price ON products
BEGIN
    INSERT INTO price_history(product_id, old_price, new_price)
    VALUES (OLD.id, OLD.price, NEW.price);
END;

INSERT INTO products(name, price) VALUES ('Caderno', 5.00);
UPDATE products SET price = 6.50 WHERE name = 'Caderno';
SELECT * FROM price_history;

Em nenhum momento escrevemos um INSERT explícito em price_history — quem fez isso foi o trigger. Daqui pra frente, toda atualização de preço vai ser registrada do mesmo jeito, venha ela da CLI, de um script ou de um app.

Anatomia do CREATE TRIGGER no SQLite

Vamos destrinchar a sintaxe parte por parte:

CREATE TRIGGER trigger_name
{ BEFORE | AFTER | INSTEAD OF } { INSERT | UPDATE [ OF column_list ] | DELETE }
ON table_name
[ FOR EACH ROW ]
[ WHEN condition ]
BEGIN
    -- uma ou mais instruções
END;

• Momento de execução — BEFORE dispara antes da alteração, AFTER dispara depois, e INSTEAD OF substitui a operação (apenas em views).
• Evento — qual operação dispara o trigger. UPDATE OF col1, col2 restringe o disparo a colunas específicas.
• Tabela — a tabela que está sendo monitorada.
• FOR EACH ROW — o SQLite só suporta triggers por linha, então isso fica implícito. Você pode escrever para deixar claro, mas não muda nada.
• WHEN — uma condição opcional. O corpo do trigger só roda se ela for verdadeira.
• Corpo — um ou mais comandos entre BEGIN e END. Cada um precisa terminar com ponto e vírgula.

E é toda a sintaxe. Na prática, a maioria dos triggers tem entre cinco e dez linhas.

OLD e NEW: a linha que está sendo alterada

Dentro do corpo do trigger, você tem acesso a duas pseudo-linhas que representam os dados:

• NEW — a linha que está chegando. Disponível em triggers de INSERT e UPDATE.
• OLD — a linha que já existia. Disponível em triggers de UPDATE e DELETE.

Um trigger de DELETE só tem OLD. Um trigger de INSERT só tem NEW. Já um trigger de UPDATE tem os dois.

CREATE TABLE accounts (
    id INTEGER PRIMARY KEY,
    name TEXT,
    balance REAL NOT NULL
);

CREATE TABLE deletions (
    table_name TEXT,
    row_id INTEGER,
    snapshot TEXT,
    deleted_at TEXT DEFAULT CURRENT_TIMESTAMP
);

CREATE TRIGGER archive_account
AFTER DELETE ON accounts
BEGIN
    INSERT INTO deletions(table_name, row_id, snapshot)
    VALUES ('accounts', OLD.id, OLD.name || ' / ' || OLD.balance);
END;

INSERT INTO accounts(name, balance) VALUES ('Rosa', 120.00);
DELETE FROM accounts WHERE name = 'Rosa';
SELECT * FROM deletions;

A linha apagada some de accounts, mas os dados dela foram preservados em deletions antes do sumiço.

BEFORE: validar ou ajustar a linha

Os triggers BEFORE disparam antes da mudança ser gravada em disco. São ótimos para levantar um erro ou normalizar dados antes que a alteração se concretize:

CREATE TABLE users (
    id INTEGER PRIMARY KEY,
    email TEXT NOT NULL,
    created_at TEXT
);

CREATE TRIGGER lowercase_email
BEFORE INSERT ON users
BEGIN
    UPDATE users SET email = email; -- noop, apenas ilustrando o contexto
END;

CREATE TRIGGER reject_empty_email
BEFORE INSERT ON users
WHEN NEW.email IS NULL OR trim(NEW.email) = ''
BEGIN
    SELECT RAISE(ABORT, 'o e-mail não pode estar vazio');
END;

INSERT INTO users(email) VALUES ('ada@example.com');
INSERT INTO users(email) VALUES ('');
SELECT * FROM users;

O segundo INSERT é abortado antes que qualquer linha seja gravada. O RAISE(ABORT, '...') cancela a instrução atual e desfaz tudo que ela tinha feito até ali — já o RAISE(FAIL, ...), RAISE(ROLLBACK, ...) e RAISE(IGNORE) te dão um controle mais fino sobre o que acontece.

Para validação pura de dados, prefira restrições CHECK — elas são declarativas e o otimizador as enxerga. Recorra a um trigger BEFORE quando a regra precisar consultar outras tabelas ou fizer algo que um CHECK não consegue expressar.

Cláusula WHEN: triggers condicionais no SQLite

A cláusula WHEN filtra quais alterações de linha realmente disparam o corpo do trigger. Ela é avaliada linha a linha, depois que OLD e NEW já foram associados:

CREATE TABLE orders (
    id INTEGER PRIMARY KEY,
    total REAL NOT NULL,
    status TEXT NOT NULL
);

CREATE TABLE big_orders (
    order_id INTEGER,
    total REAL,
    flagged_at TEXT DEFAULT CURRENT_TIMESTAMP
);

CREATE TRIGGER flag_big_order
AFTER INSERT ON orders
WHEN NEW.total >= 1000
BEGIN
    INSERT INTO big_orders(order_id, total) VALUES (NEW.id, NEW.total);
END;

INSERT INTO orders(total, status) VALUES (50, 'paid');
INSERT INTO orders(total, status) VALUES (1500, 'paid');
INSERT INTO orders(total, status) VALUES (2200, 'paid');
SELECT * FROM big_orders;

O primeiro pedido fica de fora. Os outros dois passam. Sem a cláusula WHEN, todo INSERT cairia em big_orders e você teria que filtrar na hora da leitura.

INSTEAD OF: tornando uma view gravável

Por padrão, views em SQLite são somente leitura. Um trigger INSTEAD OF intercepta uma escrita feita contra a view e executa o seu SQL no lugar — normalmente traduzindo isso em escritas nas tabelas que estão por trás dela:

CREATE TABLE employees (
    id INTEGER PRIMARY KEY,
    first_name TEXT,
    last_name TEXT,
    salary REAL
);

CREATE VIEW employee_summary AS
SELECT id, first_name || ' ' || last_name AS full_name, salary
FROM employees;

CREATE TRIGGER employee_summary_insert
INSTEAD OF INSERT ON employee_summary
BEGIN
    INSERT INTO employees(first_name, last_name, salary)
    VALUES (
        substr(NEW.full_name, 1, instr(NEW.full_name, ' ') - 1),
        substr(NEW.full_name, instr(NEW.full_name, ' ') + 1),
        NEW.salary
    );
END;

INSERT INTO employee_summary(full_name, salary) VALUES ('Boris Petrov', 60000);
SELECT * FROM employees;

O aplicativo conversa com a view como se fosse uma tabela comum. Por trás dos panos, o trigger se encarrega de dividir o valor em first_name e last_name.

Listar e remover triggers no SQLite

Os triggers ficam guardados em sqlite_master, junto com as tabelas e índices:

CREATE TABLE notes (id INTEGER PRIMARY KEY, body TEXT);

CREATE TRIGGER touch_note
AFTER UPDATE ON notes
BEGIN
    SELECT 1; -- corpo de espaço reservado
END;

SELECT name, tbl_name, sql
FROM sqlite_master
WHERE type = 'trigger';

DROP TRIGGER IF EXISTS touch_note;

SELECT count(*) AS remaining
FROM sqlite_master
WHERE type = 'trigger';

DROP TRIGGER IF EXISTS nome; é a forma segura. Quando você dropa a tabela onde a trigger vive, ela some junto automaticamente — não precisa fazer faxina antes.

Armadilhas que vale conhecer

Algumas coisas pegam todo mundo de surpresa na primeira vez:

• Triggers disparam por linha, não por comando. Um UPDATE que afeta 1.000 linhas dispara a trigger 1.000 vezes. Se o corpo dela já é pesado, a conta explode rápido.
• Triggers rodam dentro da transação que as envolve. Se o comando externo der rollback, as escritas da trigger também voltam atrás. Geralmente é o que você quer, mas isso significa que trigger não é uma saída de emergência para "registrar isso aconteça o que acontecer".
• Triggers recursivas vêm desligadas por padrão. Uma trigger que altera a mesma tabela não vai se redisparar a menos que você ative PRAGMA recursive_triggers = ON;. Deixe desligado, a não ser que tenha um motivo bem específico.
• A aplicação só escapa das triggers se ela pular o banco. Enquanto toda escrita passar pelo SQLite, a trigger vai rodar. ORMs que mandam SQL cru em lote também disparam triggers normalmente.
• Não espalhe regra de negócio por várias triggers. Elas são invisíveis de quem chama o código — quem estiver debugando "por que essa linha apareceu?" vai ter que sair fazendo grep em sqlite_master. Use triggers para questões transversais (logs de auditoria, colunas derivadas, tornar views graváveis) e mantenha o resto na camada de aplicação.

Um exemplo realista de log de auditoria

Juntando os padrões — vamos rastrear toda mudança numa tabela posts:

CREATE TABLE posts (
    id INTEGER PRIMARY KEY,
    title TEXT NOT NULL,
    body TEXT,
    updated_at TEXT
);

CREATE TABLE post_audit (
    post_id INTEGER,
    action TEXT,
    old_title TEXT,
    new_title TEXT,
    at TEXT DEFAULT CURRENT_TIMESTAMP
);

CREATE TRIGGER posts_audit_update
AFTER UPDATE OF title, body ON posts
BEGIN
    UPDATE posts SET updated_at = CURRENT_TIMESTAMP WHERE id = NEW.id;
    INSERT INTO post_audit(post_id, action, old_title, new_title)
    VALUES (NEW.id, 'update', OLD.title, NEW.title);
END;

INSERT INTO posts(title, body) VALUES ('Rascunho', 'primeira versão');
UPDATE posts SET title = 'Publicado' WHERE id = 1;
SELECT id, title, updated_at FROM posts;
SELECT * FROM post_audit;

Com uma única trigger, você mantém o updated_at sempre correto e ainda grava uma linha de auditoria, tudo em um só lugar. O código da aplicação que faz o UPDATE nem precisa saber que essas duas coisas existem.

A seguir: suporte a JSON

As triggers cuidam da automação em torno de eventos de linha. O próximo recurso avançado do SQLite tem a ver com o que você consegue guardar dentro de uma linha — JSON. O SQLite oferece um conjunto completo de funções JSON para consultar e atualizar dados estruturados sem precisar sair do SQL, e é exatamente esse o tema da próxima página.