DocumentationScheduled Jobs

Scheduled Jobs

Pidgey Scheduled Jobs

Run jobs on a recurring schedule using cron expressions.

Defining a Scheduled Job

Use defineScheduledJob for jobs that run on a cron schedule:

jobs/daily-digest.ts
import { pidgey } from '@/lib/pidgey';
 
export const dailyDigest = pidgey.defineScheduledJob({
  name: 'daily-digest',
  handler: async () => {
    // Scheduled jobs have no input data
    await sendDigestEmail();
  },
  schedule: {
    cron: '0 9 * * *', // Every day at 9am
    timezone: 'America/New_York',
  },
});

Cron Expression Syntax

Standard 5-field cron expressions:

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, Sun=0)
│ │ │ │ │
* * * * *

Common examples:

ExpressionDescription
0 9 * * *Every day at 9:00 AM
*/15 * * * *Every 15 minutes
0 0 * * 0Every Sunday at midnight
0 9 * * 1-5Weekdays at 9:00 AM
0 0 1 * *First day of every month

Automatic Schedule Sync

Schedules are automatically synced when you start the worker:

npx pidgey worker dev

Output:

🔍 Discovering jobs...
✓ Discovered job: daily-digest
✅ Discovered 1 job(s)

⏰ Syncing schedules...
   ✓ daily-digest (0 9 * * *)
✅ Synced 1 schedule(s)

🚀 Worker started...

The worker discovers jobs with schedule configs and automatically upserts them to the database.

Managing Schedules

Pause a schedule

await pidgey.pauseScheduledJob('daily-digest');

Resume a schedule

await pidgey.resumeScheduledJob('daily-digest');

Delete a schedule

await pidgey.deleteScheduledJob('daily-digest');

List all schedules

const schedules = await pidgey.listScheduledJobs();

CLI Commands

Manage schedules from the command line:

# List all scheduled jobs
npx pidgey schedules list
 
# Pause a schedule
npx pidgey schedules pause daily-digest
 
# Resume a schedule
npx pidgey schedules resume daily-digest
 
# Delete a schedule
npx pidgey schedules delete daily-digest
⚠️

The Redis adapter does not currently support pausing scheduled jobs.

Timezone Support

Specify a timezone to ensure jobs run at the correct local time:

schedule: {
  cron: '0 9 * * *',
  timezone: 'America/Los_Angeles', // Pacific Time
}

Timezones use IANA format (e.g., America/New_York, Europe/London, Asia/Tokyo).

Next Steps

JobsWorker