Como Agendar Tarefas Automáticas no Supabase

Agendar tarefas no Supabase significa programar rotinas para rodar sozinhas, em horários definidos, direto dentro do banco de dados, sem precisar manter um servidor separado só para isso. Isso é feito principalmente com a extensão pg_cron, que já vem disponível em todos os projetos Supabase e permite disparar consultas SQL, funções do banco ou até Edge Functions em intervalos programados. Para quem constrói sites e sistemas com Supabase no backend, dominar esse recurso economiza tempo, evita scripts manuais e mantém o sistema saudável de forma automática.

##O que é o pg_cron e por que ele existe

O pg_cron é uma extensão do PostgreSQL que funciona como um agendador de tarefas dentro do próprio banco. Em vez de configurar um cron job no servidor ou depender de um serviço externo, o pg_cron roda comandos SQL em horários definidos, usando a mesma sintaxe cron tradicional (minuto, hora, dia, mês, dia da semana).

No Supabase, esse recurso está organizado sob o nome de Supabase Cron, uma camada de interface construída em cima do pg_cron. Segundo a documentação oficial da Supabase, o módulo Cron permite quatro tipos de tarefa: comandos SQL diretos, chamadas a funções do banco, disparo de Edge Functions e chamadas a webhooks HTTP externos.

A vantagem de agendar tarefas no Supabase dessa forma é que tudo fica centralizado: não existe um segundo servidor para manter no ar, monitorar ou pagar separadamente.

##Casos de uso reais para agendar tarefas no Supabase

Na prática, agendar tarefas no Supabase resolve problemas do dia a dia de qualquer sistema em produção. Alguns exemplos comuns:

• Limpar ou arquivar registros antigos (sessões expiradas, logs, carrinhos abandonados).
• Gerar relatórios diários ou semanais e salvar os resultados em uma tabela de histórico.
• Disparar e-mails periódicos, como lembretes ou resumos automáticos.
• Rodar verificações de saúde (health checks) em integrações externas.
• Atualizar views materializadas e reconstruir índices para manter a performance do banco.

Para uma agência que cuida de sites, automações e sistemas para clientes, esse tipo de rotina automática reduz manutenção manual e evita que pequenos problemas (como uma tabela de logs crescendo sem controle) virem dores de cabeça maiores no futuro.

##Como agendar uma tarefa com pg_cron na prática

O primeiro passo é habilitar a extensão pg_cron no projeto, algo que pode ser feito direto pelo painel do Supabase, na seção de Database Extensions, ou via SQL. Depois, o agendamento básico segue este formato:

1. Escreva o comando SQL ou chame a função que você quer executar.
2. Defina a expressão cron (por exemplo, 0 3 * * * para rodar todos os dias às 3h).
3. Registre o job com cron.schedule, informando um nome, a expressão cron e o comando.
4. Confirme o agendamento consultando a tabela cron.job.

Vale lembrar que o pg_cron trabalha sempre em UTC, então é preciso ajustar o horário levando em conta o fuso do Brasil. Além disso, o Supabase também aceita sintaxe de segundos para agendamentos mais frequentes que um minuto, e até agendamento em linguagem natural em alguns fluxos da interface.

###Chamando Edge Functions com pg_cron e pg_net

Quando a tarefa exige lógica mais complexa, como acessar uma API externa ou rodar código no runtime Deno, o caminho é combinar o pg_cron com a extensão pg_net. O pg_net permite que o PostgreSQL faça requisições HTTP, então o job agendado pode simplesmente chamar a URL da Edge Function na hora certa. Esse padrão é muito usado para sincronizar dados com sistemas de terceiros ou enviar digests por e-mail em horários fixos.

##Monitorando e corrigindo falhas nos jobs agendados

De nada adianta agendar tarefas no Supabase se elas falham silenciosamente. Por isso, o monitoramento é parte essencial do processo. Duas tabelas do sistema ajudam nisso:

• cron.job: lista todos os jobs cadastrados, com nome, expressão cron e status ativo ou não.
• cron.job_run_details: mostra o histórico de execuções, incluindo sucesso, erro e tempo de execução de cada rodada.

Consultar essas tabelas periodicamente (ou até criar um alerta próprio a partir delas) evita que uma tarefa de manutenção fique quebrada por semanas sem ninguém perceber.

##Perguntas Frequentes

Preciso instalar algo para usar pg_cron no Supabase? Não é preciso instalar nada externo. Basta habilitar a extensão pg_cron pelo painel do projeto ou por SQL, já que ela é distribuída com o próprio Supabase.

O pg_cron substitui um serviço externo de automação? Para tarefas internas ao banco, sim, na maioria dos casos. Para fluxos que dependem de múltiplos serviços externos e lógica de negócio mais complexa, ferramentas de automação dedicadas ainda podem fazer sentido junto com o pg_cron.

Em qual fuso horário o pg_cron agenda as tarefas? Sempre em UTC. É importante converter o horário desejado (por exemplo, o horário de Brasília) para UTC antes de definir a expressão cron.

É possível agendar tarefas com intervalo menor que um minuto? Sim, o pg_cron dentro do Supabase aceita uma sintaxe estendida para agendamentos em nível de segundos, além da sintaxe cron tradicional.

Como saber se um job agendado falhou? Consultando a tabela cron.job_run_details, que registra o resultado de cada execução, incluindo erros e tempo de resposta.

Agendar tarefas no Supabase com pg_cron é uma forma simples e nativa de automatizar manutenção, relatórios e integrações sem complicar a infraestrutura do projeto. Se o seu sistema ainda depende de rotinas manuais ou de scripts rodando em outro servidor, vale revisar o que pode virar um job agendado direto no banco. A Stormcore trabalha com criação de sites, sistemas e automações usando justamente esse tipo de stack (React, Vite, Tailwind e Supabase), então esse é exatamente o tipo de ajuste que costuma entrar em projetos de manutenção e evolução contínua.