Scheduling jobs

Sextant has two kinds of timing. A delayed job runs once, later. A schedule creates a new job every time its expression fires.

Run once, later

Give the job a run_at time, or a relative delay in the CLI.

sextant jobs create --queue emails --handler send-receipt \
  --payload '{"orderId":"ord_4412"}' --in 10m

await sextant.jobs.create({
  queue: 'emails',
  handler: 'send-receipt',
  payload: { orderId: 'ord_4412' },
  runAt: new Date(Date.now() + 10 * 60_000),
});

from datetime import datetime, timedelta, timezone

client.jobs.create(
    queue="emails",
    handler="send-receipt",
    payload={"order_id": "ord_4412"},
    run_at=datetime.now(timezone.utc) + timedelta(minutes=10),
)

client.Jobs.Create(ctx, &sextant.JobCreateParams{
	Queue:   "emails",
	Handler: "send-receipt",
	Payload: map[string]any{"order_id": "ord_4412"},
	RunAt:   time.Now().Add(10 * time.Minute).Format(time.RFC3339),
})

The job stays scheduled until run_at, then becomes queued. Jobs are started on time within the scheduler tick, one second by default.

Recurring work

Create a schedule with either cron or every.

sextant schedules create nightly-report \
  --cron "0 2 * * *" --timezone Europe/Paris \
  --queue reports --handler build-report --payload '{"range":"24h"}'

Cron expressions have five fields: minute, hour, day of month, month, day of week.

For simple repetition use --every 15m instead. Intervals start counting when the schedule is created and are not aligned to the clock.

Time zones and daylight saving

Expressions are evaluated in the schedule’s timezone (an IANA name, UTC by default). Around a daylight saving change:

• a time that does not exist (02:30 on the spring-forward night) runs at the first valid moment after it;
• a time that happens twice (the autumn night) runs once, on the first occurrence.

When a run is still going

If a schedule fires while the job it created last time is still running, overlap decides:

Missed ticks

If the server is down when a tick is due, Sextant creates one job when it comes back, not one per missed tick. Set catch_up = true on the schedule to create every missed job instead, up to 100.

Pause, resume, delete

sextant schedules pause nightly-report
sextant schedules resume nightly-report
sextant schedules delete nightly-report

Pausing keeps the schedule and its history. Deleting a schedule never touches jobs it already created.