Schedules

A function can run on cron schedules per branch. At each due time the function's scheduled(controller, env, ctx) handler runs once, with controller.cron and controller.scheduledTime. See Handlers.

Manage schedulesCopy Anchor Link

Schedules are managed with the Management API (Developer access on an unprotected branch, Admin on a protected one; Viewer may list):

BASE="$API/v1/databases/$DB/branches/$BRANCH/functions/cleanup/schedules"

curl -X POST "$BASE" -H "Authorization: Bearer $MEMBER_TOKEN" -H 'content-type: application/json' \
  -d '{"cron": "*/15 * * * *", "timezone": "Europe/London"}'
curl "$BASE" -H "Authorization: Bearer $MEMBER_TOKEN"
curl -X PATCH "$BASE/$SCHEDULE_ID" -H "Authorization: Bearer $MEMBER_TOKEN" \
  -H 'content-type: application/json' -d '{"enabled": false}'
curl -X DELETE "$BASE/$SCHEDULE_ID" -H "Authorization: Bearer $MEMBER_TOKEN"

• cron: five fields (minute, hour, day of month, month, day of week), so the finest grain is a minute.
• timezone: an IANA name such as Europe/London. Default UTC. The cron is read in that zone, including its daylight-saving changes.
• enabled: a disabled schedule never runs. A schedule lists its next_run_at.
• An invalid cron or time zone answers 422 naming the field.

From the CLI:

chelabase functions schedule add NAME --cron '<5 fields>' [--timezone IANA]
chelabase functions schedule rm NAME ID
chelabase functions schedule list NAME

add prints the schedule's id (--timezone defaults to UTC). list prints one line per schedule: its id, cron, time zone, enabled or disabled, and next= its next run time. The CLI can't edit a schedule or turn one off; the Schedules section of Studio's function drawer can, and adds and deletes them too.

How runs happenCopy Anchor Link

• The worker looks for due schedules every 5 seconds. Several worker replicas never run the same tick twice.
• Missed ticks coalesce. If the worker was down for five minutes, it runs the function once when it returns, not five times.
• A disabled function skips the run, and the schedule's next_run_at still advances, so enabling it later doesn't replay what it missed.
• A run is an internal call: the function's auth mode doesn't apply. If the function has a run-as role, the handler's env.CHELABASE_SERVICE_KEY acts as that role; if not, the run still happens, without a key.
• A new branch copies its parent's schedules. They fire for the child only while the function is enabled on it. Deleting a branch or database stops its schedules within one loop.
• A handler that is missing or throws records scheduled handler: <outcome> as the function's last_error. Runs are not retried; the next tick is the next run.
• The 30 s wall-clock limit applies.