Skip to content
DuckDB Extensions All extensions Cronjob

Scheduling functions in the Cronjob DuckDB extension

Function category

Scheduling

3 functions

Register, list, and cancel cron-style scheduled SQL queries. Six-field [cron expressions](https://en.wikipedia.org/wiki/Cron) with second-level resolution. Schedules live in memory inside the DuckDB process — when the process exits, every job is forgotten. For restart-safe scheduling, drive the DuckDB run from an external orchestrator (system [`cron(8)`](https://man7.org/linux/man-pages/man8/cron.8.html), `systemd` timers, Kubernetes CronJob).

cron

Scalar function Scheduling
Signature
cron(col0: VARCHAR, col1: VARCHAR) → VARCHAR
Arguments (Positional)
Argument col0 Type VARCHAR Mode Positional Description
Argument col1 Type VARCHAR Mode Positional Description
Description

Register a SQL query to run on a six-field cron expression (second minute hour day-of-month month day-of-week). Returns a job_id (e.g. task_0) you can later pass to cron_delete or look up in cron_jobs. The schedule fires only while this DuckDB process is alive — when the process exits, the registration is gone. Use crontab.guru to sanity-check expressions before registering.

1 Every 15 seconds during hours 1–4 
SELECT cron('SELECT now()', '*/15 * 1-4 * * *');
2 Weekdays at 7am — daily metrics export 
SELECT cron('CALL daily_metrics_export()', '0 0 7 ? * MON-FRI');
3 Top of every hour — refresh a materialized table 
SELECT cron('CREATE OR REPLACE TABLE hourly_rollup AS SELECT ...', '0 0 * * * *');
Related functions

cron_delete

Scalar function Scheduling
Signature
cron_delete(col0: VARCHAR) → BOOLEAN
Arguments (Positional)
Argument col0 Type VARCHAR Mode Positional Description
Description

Cancel a scheduled job by job_id (the value returned from cron or visible in cron_jobs). Returns TRUE if a matching job was found and removed. Process restarts also cancel jobs — cron_delete is for un-registering while DuckDB is still running.

1 Cancel a specific job 
SELECT cron_delete('task_0');
Related functions

cron_jobs

Table function Scheduling
Signature
cron_jobs() → None
Description

Table function listing every scheduled job in this process — job_id, query, schedule, next_run, status, last_run, and last_result. The introspection primitive: filter by status to find failing jobs, or join last_result against expected output to assert that recent runs succeeded.

1 List all scheduled jobs 
SELECT * FROM cron_jobs();
2 Find jobs that have never run 
SELECT job_id, schedule FROM cron_jobs() WHERE last_run IS NULL;
Related functions