DocsServer

Scheduled jobs

Code that runs on a schedule, from an app’s jobs/ folder.

A job is a function that runs on a schedule, such as nightly at 2am or every Monday, with the same server API as the rest of your code. There is no cron, queue or worker to set up. To add one, export a schedule and a function from a file in jobs/:

jobs/tidy-drafts.js
export const schedule = "0 6 * * 1-5";   // weekdays at 06:00 UTC

export default async function (ctx) {
  const stale = await ctx.collection("drafts").list({ filter: "updated_at < @days_ago.30" });
  // clean up, send a digest, …
}

Features include:

  • Standard five-field cron schedules, and shorthands such as @daily
  • A job that never overlaps itself
  • One run per schedule in a swarm, on the leader
  • A Jobs screen in the admin, with each job’s last run and a button to run it now

Write a job

  • Put one file per job in jobs/, beside functions/.
  • Nothing in jobs/ is exposed over HTTP; jobs only run on their schedule.
  • A job runs as the system, with the same ctx as a server function and CRON as its method.
  • export const atStart = true also runs it once when the server starts, for example to reset demo data right after a deploy.

The schedule

Five fields of standard cron, in UTC: minute, hour, day of month, month and day of week (0 is Sunday).

0 2 * * *Daily at 02:00
*/15 * * * *Every 15 minutes
0 8 * * 1Mondays at 08:00
0 9 1 * *09:00 on the 1st of each month
@hourly, @daily, @weekly, @monthlyShorthands

*, */n, a-b, a-b/n and lists are supported. The schedule is read from the file’s source, so listing jobs never runs app code.

How they run

  • Every minute, the jobs whose schedule matches run.
  • A job never overlaps itself: if the previous run is still going, the next one is skipped.
  • As with cron, runs missed while the server was down aren’t caught up.
  • In a swarm, jobs run on the leader only, so each runs once.

Jobs in the admin lists every job with its last run and result, and can run one on demand. Backups are listed there too. By default they are off, until you set a schedule and how many to keep.

View as Markdown