Schedule work and run background tasks

Two ways to run work without a user waiting

• Cron Jobs run on a schedule: every night, every Monday, every five minutes.
• Tasks (background jobs) run once, when your app asks, and retry automatically if they fail.

In this lesson you will schedule a nightly cleanup and enqueue a background job.

Schedule a nightly cleanup

1. Open Cron Jobs in the sidebar.
2. Choose New Cron Job.
3. Job Name: purge_old_notes.
4. Schedule Expression: choose Daily (Midnight), which fills 0 0 * * *. The five fields are minute, hour, day of month, month and day of week.
5. Timezone: pick yours, or leave UTC.
6. Target Execution Layer: SQL Query, with DELETE FROM notes WHERE created_at < now() - interval '365 days'.
7. Concurrency Policy: Forbid Concurrent (Skip if active), so runs never pile up.
8. Choose Save Cron Job.

Check the row: Next Execution shows when it will fire. Choose Run to start it now, then Logs to see the output. The Recent Execution History table shows each run's status (SUCCESS, FAILED or TIMEOUT), duration and attempt.

Targets you can choose instead: Function (with an optional JSON payload), Action, HTTP (a URL you call on schedule, which must be public) and Mail. A good pattern is a cron job whose target is a function, so the schedule stays simple and the logic stays in code.

Enqueue a background job

Suppose a new user should get a welcome task that calls an outside service. You do not want sign-up to wait for it, and you want a retry if it fails.

From your server with the secret key:

curl -X POST https://my-project.pgbhub.app/api/v1/projects/my-project/jobs \
  -H "Authorization: Bearer pgb_sec_..." -H "Content-Type: application/json" \
  -d '{"job_type": "welcome", "target_type": "function",
       "target_config": {"function_name": "note_summary"},
       "payload": {"email": "[email protected]"}, "max_attempts": 3}'

Open Tasks in the sidebar (the page is titled Background Tasks). The table lists the job with its Status, Attempts (for example 1/3), Next Attempt and Last Error. A successful job is Done. You can Cancel a Pending one.

How retries behave

If the job fails, it waits one second, then two, then four, and so on, up to five minutes between attempts. After the last attempt it is Dead-lettered, and a banner counts those so you notice. Because a retry can follow a partial success, make your function safe to run twice. Use an idempotency_key so the same job is not created twice if your app resends the request.

The default max_attempts is 5 and it can be 1 to 20.

Cron or job?

Need	Use
Every night, every Monday, every 5 minutes	Cron Jobs
After this event, without making the user wait	A background job
Many workers, custom delivery rules	A queue (next lesson)

Recap

• Cron Jobs take a 5-part schedule, a timezone, a target and a concurrency policy.
• Run and Logs let you test a job immediately.
• Background jobs retry with growing delays and end up Dead-lettered if they never succeed.
• Make everything you run safe to repeat.