Schedules

Recurring work declared in sp00ky.yml. Each cycle creates an ordinary job row, with cron, fan-out and concurrency control.

Overview

A schedule runs a backend route on a clock, server-side, whether or not a client is connected. Use it for periodic syncs, polling an upstream API, cache warming, or scheduled cleanup.

Schedules are declared in sp00ky.yml and deployed like everything else in the manifest. Each cycle, the scheduler creates a new job row in the target backend’s outbox table, so a scheduled run is an ordinary atomic job, with the same retry policy, the same spky jobs visibility, and the same kill and crash-recovery behaviour as a job your app created with db.run().

# sp00ky.yml
schedules:
  nightly-cleanup:
    cron: "0 3 * * *"          # 03:00, every day
    backend: api               # an app with an outbox method
    route: /cleanupExpired     # a POST route on that backend
    payload:
      olderThanDays: 30

// Your backend, unchanged, a scheduled run is an ordinary job POST.
app.post('/cleanupExpired', async (req, res) => {
  const { olderThanDays } = req.body;
  const deleted = await purgeExpired(olderThanDays);
  res.json({ deleted });          // the response body is stored on the job row
});

That’s the whole integration: your backend doesn’t know it was called by a schedule.

For multi-step work (several routes in sequence, in parallel, or passing data to each other) see Workflows.

Cadence

A schedule sets exactly one of cron or every.

schedules:
  # Cron: 5 fields (minute hour day month weekday), evaluated in `timezone`.
  nightly:
    cron: "0 3 * * *"
    timezone: Europe/Berlin      # optional; defaults to UTC
    backend: api
    route: /nightly

  # Interval: measured from each fire, not from completion.
  poll-upstream:
    every: 5m                    # 30s | 5m | 1h30m, minimum 10s
    backend: api
    route: /pollUpstream

cron is a standard 5-field expression (a leading seconds field is also accepted) evaluated in timezone, so “daily at 03:00” stays 03:00 local across daylight-saving changes rather than drifting by an hour twice a year.

every is measured from each fire, not from each completion. A 5m schedule fires at a steady 5-minute rhythm regardless of how long a run takes; use concurrency (below) to decide what happens when a run is still going at the next fire.

Fan-out: one job per row

forEach turns one schedule into one job per row its query returns: a per-user sync, a per-connection poll, a per-tenant cleanup.

schedules:
  game-sync:
    every: 5m
    backend: api
    route: /syncGames
    forEach:
      query: SELECT id FROM connection WHERE active = true
      key: id                    # per-row concurrency key (default: id)
    concurrency: skip            # skip | allow | replace
    retry: { max: 3, strategy: linear }
    timeout: 120s

// Each row arrives under `payload.row`.
app.post('/syncGames', async (req, res) => {
  const { row } = req.body;      // { id: 'connection:abc' }
  const games = await syncGamesFor(row.id);
  res.json({ synced: games.length });
});

The query runs with root privileges on every fire, so it always sees current data: a row added since the last fire is picked up automatically, and a row that disappears simply stops being scheduled.

Concurrency

concurrency decides what a fire does when the previous run for that same key is still in flight. It is tracked per key, so one slow user never holds up anyone else.

Definitions in their own files

Once you have more than a handful, schedules: can live in separate files, per entry or wholesale. Paths are relative to the manifest that names them.

# The whole section from one file:
schedules: ./schedules.yml

# Or one file per definition, mixed with inline ones:
schedules:
  game-sync: ./schedules/game-sync.yml
  quick-ping:
    every: 1h
    backend: api
    route: /ping

Operating them

$ spky schedules list
NAME                     KIND      CADENCE        STATE     NEXT FIRE            LAST RUN
game-sync                job       every 5m       active    2026-07-25 09:35:00  ✔ success
monthly-report           workflow  0 6 1 * *      active    2026-08-01 06:00:00  ◐ running
nightly-cleanup          job       0 3 * * *      paused    2026-07-26 01:00:00  ✔ success
stale-poller             job       every 1h       error     -                    ·  -
  last error: forEach query failed: query: Parse error at 'FROM'

STATE is the one field worth reading closely: active is normal, paused means an operator stopped it, disabled means enabled: false in the manifest, planning means the scheduler has not computed its first fire yet, and error means the cadence or the forEach query is broken, with the reason printed underneath.

spky schedules get game-sync        # definition, clock, recent runs
spky schedules pause game-sync     # stop future fires
spky schedules resume game-sync    # plan the next fire from now
spky schedules trigger game-sync   # fire once now, cadence untouched
spky schedules runs game-sync      # run history, newest first
spky schedules runs --status failed
spky schedules sync                # re-push sp00ky.yml without a deploy

# Every read supports --json for scripting:
spky schedules list --json | jq '.[] | select(.paused) | .name'

pause is the big red button: it stops future fires, survives redeploys, and wins over a queued trigger. trigger fires one extra run without shifting the cadence, a manual run at 14:07 does not move tonight’s 03:00.

$ spky schedules runs game-sync
SCHEDULE               STATUS     FIRED                TRIGGER   KEY
game-sync              ✔ success  2026-07-25 09:30:00  cron      connection:alice
game-sync              ⊘ skipped  2026-07-25 09:30:00  cron      connection:bob
game-sync              ✔ success  2026-07-25 09:25:00  cron      connection:alice
game-sync              ✔ success  2026-07-25 09:25:00  cron      connection:bob

spky schedules list and runs cover workflow schedules too; to see a workflow run’s DAG, use spky workflows show / watch.

How it works

Worth knowing, because it explains what is and isn’t guaranteed:

• Definitions are rows. spky deploy (and spky dev) upserts each definition into an internal _00_schedule table. Three writers own disjoint fields: your manifest owns the definition, you own paused, and the scheduler owns the clock. That is why a redeploy can never un-pause something you paused, and why pausing never fights the scheduler over a field.
• One ticker. A sweep runs every 5 seconds, in the SSP for a singlenode deployment, in the scheduler service for a cluster. A fire is claimed with a compare-and-swap on the schedule’s next-fire time, so even two tickers cannot double-fire.
• Runs are recorded, not inferred. Every fire writes a _00_schedule_run row (including suppressed ones), which is both your history and the per-key concurrency state. Because it is state in the database rather than memory, restarts don’t lose it. History is not kept forever, though — see Retention below.
• The fan-out row is not duplicated. A run row records which key it was for, not a copy of the row itself; the row travels on the spawned job’s payload.row (and on a workflow run’s input), which is where spky jobs get shows it.
• Completion is observed, and also healed. The scheduler learns a job finished from the same event stream your app’s writes travel on, and every sweep also reconciles directly against the job rows. So a dropped event delays things by one sweep instead of stalling them.

Retention

Run history is pruned automatically, asymmetrically by outcome: success, skipped, and replaced runs are kept for 24h by default, while failed and killed are kept for 30d. A run that is still running is never pruned, however old.

That default is a project-wide setting (retention: in sp00ky.yml — see Jobs), and any single schedule can override it:

schedules:
  sync-every-tenant:
    every: 1m
    backend: api
    route: /sync
    forEach:
      query: SELECT id FROM tenant
      key: id
    history:
      success: 15m     # this schedule keeps far less than the project default
      failed: 30d

This matters most for fan-out. A minutely schedule over 500 rows writes 500 run rows and 500 job rows every minute; with concurrency: skip, a slow one writes 500 skipped rows per fire on top. Those are the rows nobody reads, so give that schedule a short history.success and keep the long window for failures.

Keeping nothing but failures

If successful runs are of no interest at all, skip the window and say so — per schedule, or project-wide as the default:

schedules:
  sync-every-tenant:
    every: 1m
    backend: api
    route: /sync
    forEach:
      query: SELECT id FROM tenant
      key: id
    history: failures-only    # successful runs never persist

  # Or combine the mode with a window for the failures you do keep:
  other-job:
    every: 5m
    backend: api
    route: /other
    history:
      mode: failures-only
      failed: 7d

# sp00ky.yml — the default for every schedule
retention:
  mode: failures-only
  failed: 14d          # failures still keep a real window

schedules:
  audit-trail:
    cron: "0 3 * * *"
    backend: api
    route: /audit
    history: all       # ...except this one, which keeps everything

A schedule’s own history: always wins over the project default, in either direction — so one project-wide line plus an opt-out is usually all you need. Note that retention.mode is resolved when you deploy, unlike the retention windows which can be retuned with a single UPDATE.

Then a successful run never persists: a suppressed tick writes no row at all, and a run that completes cleanly is deleted as it finalizes rather than waiting out a window. Failures and kills are kept as normal, on the usual long window.

Nothing you read gets worse for it. The counts still land in the rollup (spky schedules get reports lifetime totals), and the schedule still records its last outcome, so spky schedules list is unchanged.

Validation

spky lint checks schedules as part of the normal config pass, so mistakes surface before a deploy rather than at 03:00:

• every cron expression parses, and every every interval is at least 10s
• timezone is a real IANA zone
• each backend is an app with an outbox method, and each route exists in that backend’s OpenAPI spec
• forEach.query is a single SELECT
• no name is used by both a schedule and a workflow

Reference

Schedule fields

Run statuses

See also