Curso de MariaDB / Agendar tarefas com eventos e conferir os resultados

O agendador de eventos do MariaDB executa SQL em um horário ou intervalo definidos. A existência de um evento, o agendador ativo e a tarefa ter produzido seu resultado são condições diferentes: confira os metadados e os dados gerados.

Escolher uma tarefa e uma conta de execução adequadas

Um evento pode manter um resumo breve ou realizar uma limpeza limitada dentro do banco. APIs externas, arquivos ou novas tentativas e alertas coordenados entre sistemas podem exigir um processo da aplicação ou um agendador operacional. O exemplo insere um registro de execução em vez de apagar dados, tornando o resultado fácil de observar.

Use appops_lab e uma conta de estudos com CREATE TABLE, INSERT e EVENT. O evento atua com as permissões da conta DEFINER, sua definidora, e não pela conexão atual do cliente. Alterar essa conta ou suas permissões pode afetar execuções posteriores. A introdução oficial aos eventos explica o serviço e seus objetos.

Examinar o estado e os fusos horários

SELECT @@GLOBAL.event_scheduler, @@GLOBAL.time_zone, @@SESSION.time_zone;

O agendador precisa estar ON para executar os horários. Com OFF, as definições podem existir sem serem executadas. DISABLED exige revisar a configuração de inicialização e a política administrativa, em vez de presumir que uma mudança comum para ON funcionará. Habilitar globalmente em um servidor compartilhado também pode ativar outros eventos.

Somente em um servidor novo e dedicado a estudos, seu administrador pode habilitar o agendador, se necessário, com SET GLOBAL event_scheduler = ON;. Registre o valor original. Ao terminar, desative primeiro seu evento; desligar novamente o serviço global exige considerar as outras tarefas.

O script usa o fuso da sessão +00:00 para definir explicitamente como a programação é interpretada. Preserve o valor anterior e restaure-o ao final. O relógio e o fuso de apresentação do computador cliente não são necessariamente o contexto do servidor.

Criar uma tabela de resultados e uma definição desabilitada

Confira antes o servidor, o banco e os objetos existentes. Se appops_lab contiver outras práticas, preserve-as; confirme que event_runs e record_run não estão em uso antes de criar.

CREATE DATABASE IF NOT EXISTS appops_lab
  CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE appops_lab;
CREATE TABLE event_runs (
  run_id BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY,
  ran_at DATETIME(6) NOT NULL,
  run_label VARCHAR(40) NOT NULL
) ENGINE=InnoDB;
SET @event_saved_time_zone = @@SESSION.time_zone;
SET SESSION time_zone = '+00:00';
CREATE EVENT appops_lab.record_run
  ON SCHEDULE AT CURRENT_TIMESTAMP + INTERVAL 10 SECOND
  ON COMPLETION PRESERVE
  DISABLE
  DO INSERT INTO appops_lab.event_runs (ran_at, run_label) VALUES (UTC_TIMESTAMP(6), 'scheduled-check');

DISABLE impede a execução antes da revisão. ON COMPLETION PRESERVE mantém a definição de um evento de execução única após o fim de sua programação. Não é uma política de retenção de dados ou uma garantia de novas tentativas. A referência oficial de CREATE EVENT explica os horários e a conclusão.

SELECT @@GLOBAL.event_scheduler;
SELECT EVENT_NAME, STATUS, TIME_ZONE, EXECUTE_AT, LAST_EXECUTED
FROM information_schema.EVENTS
WHERE EVENT_SCHEMA = 'appops_lab' AND EVENT_NAME = 'record_run';
SELECT run_id, ran_at, run_label FROM appops_lab.event_runs ORDER BY run_id;

Inicialmente deve existir um evento com STATUS DISABLED, e a tabela de resultados deve estar vazia. É possível examinar a definição mesmo com o agendador desligado. Confira nome, banco e fuso antes de habilitar.

Definir um novo horário futuro e verificar a linha real

Os dez segundos do CREATE podem ter passado durante a leitura ou a conexão. Programe novamente um horário futuro ao habilitar para não reutilizar um instante já vencido.

ALTER EVENT appops_lab.record_run
  ON SCHEDULE AT CURRENT_TIMESTAMP + INTERVAL 10 SECOND
  ENABLE;

Após cerca de dez segundos, repita o bloco de inspeção. O agendador não é um temporizador exato de tempo real; a coincidência milimétrica com o relógio não é um critério de sucesso. Deve aparecer uma linha com scheduled-check, que significa verificação agendada, e LAST_EXECUTED deve ter um valor. O evento de execução única preservado fica DISABLED após concluir.

LAST_EXECUTED indica uma tentativa de execução; sozinho, não demonstra que toda uma tarefa de negócio terminou corretamente. Confira também a linha real. Cada execução usa outra conexão, portanto a contagem de linhas afetadas do cliente atual também não demonstra que o evento foi executado.

Limitar a programação periódica e definir novas tentativas

Depois de observar a execução única, a programação limitada abaixo permite testar a repetição. O término explícito evita deixar uma tarefa de estudos ativa indefinidamente:

ALTER EVENT appops_lab.record_run
  ON SCHEDULE EVERY 1 MINUTE
  STARTS CURRENT_TIMESTAMP + INTERVAL 1 MINUTE
  ENDS CURRENT_TIMESTAMP + INTERVAL 3 MINUTE
  ENABLE;

O corpo do exemplo acrescenta uma linha por execução. Um resumo real precisa de uma chave única para seu período e de uma política de repetição. Recalcular a partir das fontes ou tornar a operação idempotente, de modo que repeti-la não duplique seu efeito, evita somar duas vezes em uma nova tentativa. Examine também a sobreposição caso uma execução possa durar mais que o intervalo.

As limitações oficiais dos eventos explicam horários, ordem e conexões de execução separadas. Em replicação ou troca de servidor, defina quem é responsável pela tarefa para evitar executá-la involuntariamente em vários servidores.

Desativar, diagnosticar e remover a prática

ALTER EVENT appops_lab.record_run DISABLE;
SHOW CREATE EVENT appops_lab.record_run;
  1. Desabilite execuções futuras e confira se o trabalho terminou. Desabilitar a programação não cancela necessariamente uma chamada já em execução.
  2. Examine o estado do agendador, STATUS, permissões do DEFINER, TIME_ZONE e datas. Se LAST_EXECUTED mudar sem o resultado esperado, confira o log de erros e as condições do SQL.
  3. Quando não precisar mais dos resultados, remova primeiro o evento e depois sua tabela descartável.
DROP EVENT appops_lab.record_run;
DROP TABLE appops_lab.event_runs;
SET SESSION time_zone = @event_saved_time_zone;

Restaure também o fuso original da sessão. DROP EVENT e DROP TABLE não podem ser desfeitos com ROLLBACK comum; confirme os nomes e preserve outras práticas de appops_lab. Se uma tarefa periódica falhar, determine a causa e qual trabalho precisa ser repetido antes de editar uma definição ativa; caso contrário, fica difícil distinguir omissões de duplicações.