Scheduled queries

A schedule runs a SQL statement against your database on a fixed interval. The smallest cadence is one minute; the largest is seven days. Schedules are visible per database in the console under the Schedules tab.

How it works

Each schedule lives on the database’s own Durable Object — there is no central sweep. When you create a schedule, the DO sets an alarm for next_run_at; when the alarm fires it runs the SQL, records the result, and re-arms for now + intervalSec. After each run we record:

• last_run_at
• last_status — ok or error
• last_error (truncated to 1 KB)
• last_duration_ms
• last_rows_read, last_rows_written

Failures don’t disable the schedule — the next alarm will try again. Toggle Pause to stop a misbehaving schedule.

Because scheduling is per-DO, the platform’s schedule throughput scales with the number of databases, not with a central worker.

Manual runs

Hit the refresh icon on a row to run the SQL right now. Manual runs record their last_* results but don’t shift the cadence — next_run_at only advances on alarm-driven runs.

Tips

• Use unixepoch() or datetime('now') for time-based predicates.
• Wrap multi-statement work in a transaction yourself (BEGIN; …; COMMIT;) if you need atomicity.
• INSERT … ON CONFLICT DO UPDATE is your friend for materialized aggregates.
• Each schedule run debits the namespace balance like a manual query.

REST

Two parallel surfaces — cookie-authed for the console, bearer-authed for agents and SDK callers:

Method	Console (cookie)	Agent (bearer)
GET	/api/namespaces/:ns/databases/:db/schedules	/v1/db/:ns/:db/schedules
POST	/api/namespaces/:ns/databases/:db/schedules	/v1/db/:ns/:db/schedules
PATCH	/api/namespaces/:ns/databases/:db/schedules/:id	—
DELETE	/api/namespaces/:ns/databases/:db/schedules/:id	/v1/db/:ns/:db/schedules/:id
POST	/api/namespaces/:ns/databases/:db/schedules/:id/run	—

POST body:

{
  "name": "cleanup-old-rows",
  "sql": "DELETE FROM sessions WHERE expires_at < unixepoch()",
  "intervalSec": 3600,
  "enabled": true
}

intervalSec must be between 60 and 604800.

MCP agents call the equivalent tools: list_schedules, create_schedule, delete_schedule.