O que é cron job e como agendar tarefas

Cron é o agendador de tarefas clássico dos sistemas Unix e Linux. Você diz quando algo deve rodar e o que deve rodar, e ele dispara o comando sozinho, sem ninguém apertar um botão. Cada tarefa agendada é chamada de cron job.

Quase todo projeto acaba precisando disso: limpar arquivos temporários toda madrugada, enviar um resumo diário, renovar um token, sincronizar dados com outra API. A parte difícil não é o conceito, é acertar a expressão de horário e lembrar dos detalhes que fazem o job rodar na hora errada.

Como é uma expressão cron?#

Uma expressão tem cinco campos separados por espaço, seguidos do comando:

┌───────── minuto (0-59)
│ ┌─────── hora (0-23)
│ │ ┌───── dia do mês (1-31)
│ │ │ ┌─── mês (1-12)
│ │ │ │ ┌─ dia da semana (0-6, domingo = 0)
│ │ │ │ │
* * * * *  comando a executar

Cada campo aceita um número, uma lista (1,15), um intervalo (1-5) ou *, que significa "todos os valores". Esses elementos fazem parte do padrão POSIX. O cron do Linux acrescenta passos (*/5), nomes de meses e dias (mon, jan) e aceita 7 como domingo. Os atalhos @daily, @hourly, @weekly, @monthly, @yearly e @reboot também são extensões do Linux, não do POSIX.

Quais exemplos de expressões você mais vai usar?#

Na dúvida, leia a expressão em voz alta, campo a campo: "minuto 30, hora 8, qualquer dia do mês, qualquer mês, de segunda a sexta".

Como instalar um cron job no Linux?#

Abra o seu crontab com crontab -e e adicione uma linha por tarefa. Esta limpa os arquivos temporários todo dia às 03:00 e grava a saída num log:

0 3 * * * /usr/local/bin/limpar-temporarios.sh >> /var/log/limpeza.log 2>&1

Liste o que está agendado com crontab -l. Três cuidados evitam a maioria dos problemas:

• Use caminhos absolutos. O cron roda o comando com /bin/sh e num ambiente mínimo, sem o seu perfil de shell. Um node ou um script que funciona no terminal pode não ser encontrado.
• Redirecione a saída. Por padrão, o cron tenta enviar a saída do job por e-mail ao dono do crontab. Sem e-mail configurado, a saída (e o erro) costuma se perder. Grave a saída num arquivo de log, como no exemplo.
• Dê permissão de execução ao script (chmod +x).

Quais são as pegadinhas mais comuns?#

Passo não é intervalo contínuo. O passo vale só dentro do próprio campo. */35 * * * * roda nos minutos 0 e 35 de cada hora, não a cada 35 minutos. Para intervalos que não dividem 60 ou 24, o cron puro não serve: agende uma tarefa mais frequente que decide se deve agir.

Dia do mês e dia da semana formam um "OU". Quando os dois campos estão preenchidos, o job roda se qualquer um casar. 30 4 1,15 * 5 roda às 04:30 nos dias 1 e 15 e também em todas as sextas. Quem espera um "E" se surpreende. Se você precisa de "toda sexta entre os dias 1 e 7", agende para toda sexta e teste a data dentro do script.

Fuso horário. O cron usa o fuso do servidor, que muitas vezes é UTC em ambientes de nuvem. Nesse caso, 0 3 * * * roda às 03:00 UTC, que é meia-noite no horário de Brasília (UTC-3). Implementações como o cronie aceitam a variável CRON_TZ no crontab, e as bibliotecas de aplicação têm uma opção de fuso. Declare o fuso de forma explícita sempre que o horário local importar.

Jobs sobrepostos. Se uma execução demora mais que o intervalo, a próxima começa por cima. Proteja tarefas longas com um arquivo de trava ou uma flag de "já está rodando".

Mudança de horário. Em fusos com horário de verão, uma hora pode pular ou se repetir. O cronie compensa isso para jobs de horário fixo, mas nem todo agendador faz o mesmo, e o job daquela hora pode rodar duas vezes ou nenhuma. Prefira UTC para tarefas críticas.

Como agendar tarefas dentro de uma aplicação Node.js?#

Nem todo ambiente deixa você editar um crontab. Em hospedagem de aplicações, o caminho comum é agendar dentro do próprio processo, com uma biblioteca. Uma das mais usadas em Node.js é o node-cron:

npm install node-cron

// index.js (precisa de "type": "module" no package.json)
import cron from "node-cron";

const tarefa = cron.schedule(
  "0 3 * * *",
  () => {
    console.log("Rotina das 03:00 em Brasília:", new Date().toISOString());
    // limpar arquivos, sincronizar dados, enviar relatório...
  },
  { timezone: "America/Sao_Paulo" },
);

// tarefa.stop() pausa e tarefa.start() retoma

A expressão é a mesma de cinco campos. O node-cron também aceita um campo opcional de segundos no começo (*/10 * * * * * dispara a cada 10 segundos), algo que o cron do Unix não faz.

Isso exige que o processo fique sempre ligado: se a aplicação está parada ou dormindo na hora marcada, o job não roda. Por isso, um agendador dentro do processo pede uma hospedagem que mantenha o container ativo, sem suspensão por inatividade. Se você tem várias instâncias da mesma aplicação, cada uma dispara o job, então rode o agendador em uma só. Guarde chaves e URLs em variáveis de ambiente, nunca no código.

Quando cron não é a melhor ferramenta?#

Cron é ótimo para rotinas guiadas pelo relógio. Ele é fraco quando a tarefa depende de um evento ("quando o usuário pagar, envie o recibo"), quando precisa de reexecução automática após uma falha, ou quando o trabalho é pesado e deve ser distribuído entre vários processos. Nesses casos, filas e workers resolvem melhor. Para a base, veja como hospedar uma aplicação Node.js ou um script em Python que fica rodando o tempo todo.

Como fazer isso na Square Cloud#

Um agendador dentro do processo depende de uma coisa: o processo estar vivo na hora marcada. Na Square Cloud o container fica sempre ligado, sem modo de suspensão e sem regra de inatividade, então o node-cron do exemplo dispara no horário mesmo que ninguém acesse a aplicação. Com o reinício automático, ligado por padrão no deploy pelo painel, o processo volta sozinho quando encerra com erro.

Na prática:

1. Escreva o job com a biblioteca e passe o fuso na opção timezone, em vez de depender do relógio do servidor.
2. Faça o deploy por ZIP no painel, pela CLI ou pelo GitHub. O arquivo squarecloud.app é opcional: o painel o gera com runtime, memória e arquivo principal.
3. Cadastre as chaves e URLs do job como variáveis de ambiente da aplicação e acompanhe cada execução nos logs em tempo real.

Um agendador sozinho roda como aplicação de fundo, sem subdomínio. Um app pequeno com node-cron cabe em 256 MB, o mínimo para esse tipo de aplicação, e o Hobby começa em R$ 12,49 por mês com 1 GB de RAM compartilhada entre as suas aplicações. Se a sua API divide o domínio entre várias aplicações com load balancing, cada cópia dispara o job: deixe o agendador numa aplicação só. Veja as opções para hospedar APIs e jobs em hospedagem de APIs e o runtime em Node.js.