How does clocked schedule work?

[realsuayip]

1. I want to run an one-off task at a certain datetime.
2. Celery has eta, but does not recommend using it for scheduling a lot of tasks.
3. So, using db-backed beat with clocked schedule seems to be the best option.

So why does every clocked task require creating a row in database using ClockedSchedule model? That's seems like waste of resources to me since I'm planning on scheduling some hundreds of thousands of tasks.

PeriodicTask already has start_time attribute, why don't we use that?

Whats the best way to schedule one-off tasks that will run at specified time?

[sidhavratha]

I've dealt with a similar situation using django-celery-beat, and here's what I've learned from experience:

---

⚠️ Issue with Using Many ClockedSchedule Entries

Creating a large number of ClockedSchedule entries (hundreds of thousands, as you mentioned) is not recommended due to how django-celery-beat works under the hood:

• It maintains an in-memory min-heap of all periodic and clocked tasks.
• This heap is re-heapified frequently (e.g., after each task run).
• Having too many scheduled entries bloats this structure, which:
  • Increases memory usage.
  • Slows down the scheduler significantly.
  • Can result in performance bottlenecks.

---

✅ Alternative Solution (What We Did)

We implemented a custom scheduling strategy using our own DB table (ClockedTask):

1. Create a model (ClockedTask) to store all one-off scheduled tasks.
2. Insert tasks into this table with their target execution datetime.
3. Create a periodic task (submit_scheduled_tasks) that runs every few seconds (we use 5s).
4. This task:
   • Picks up all due ClockedTask entries (scheduled_at <= now()).
   • Submits them to Celery using .delay() or .apply_async().
   • Marks them as inactive to prevent re-processing.

---

✅ Pros

• You can store millions of scheduled tasks, limited only by your DB capacity.
• Avoids polluting Celery Beat's memory with tons of scheduled entries.
• More control over task submission logic and deduplication.

---

❌ Cons

• There's a slight delay (up to 5 seconds, depending on the frequency you run submit_scheduled_tasks).
• You need to handle concurrency carefully:
  • Two instances of submit_scheduled_tasks running in parallel might pick and enqueue the same task.
  • Use database-level locking or atomic operations to prevent duplicates.

---

🔍 Why to store in db?

Any distributed system is designed in a way to provide consistency and failover guarantees. If celery-beat instance restarts, all in-memory entries will be lost.

🔍 Why Not Use start_time?

The start_time field in PeriodicTask is meant for recurring tasks—it only determines when the first run of the periodic task happens. It doesn't support one-off executions. That's why ClockedSchedule exists—for true one-time scheduling.

[realsuayip]

@sidhavratha Putting aside all the AI misinformation you missed to fact-check, Your "solution" basically involves implementing a basic scheduler, this defeats the entire purpose of celery beat and this library.

[sidhavratha]

@realsuayip

Please let me know which information is incorrect. I would prefer to fix my understanding. If you are right, then I might have overdone something, which was un-necessary.

[sidhavratha]

[realsuayip]

which information is incorrect.

specifically, this part:

The start_time field in PeriodicTask is meant for recurring tasks—it only determines when the first run of the periodic task happens

you can simulate clocked schedule, without creating a clocked schedule instance by using start_time + one_off combination with some arbitrary schedule (say every 1 ms)

however this did not scale well for my use case since at 300k objects it started to miss scheduling tasks (like by hours).

i tried to inspect what beat is doing but it seems for my use case its grossly inefficient since every time i create a scheduled task, the scheduler picks up a lot of objects from database, (and that query assumes the existence of periodic tasks, which makes it even slower)

not only did beat miss scheduling tasks, it also used an entire CPU (100%) and some decent amount of ram.

i eventually ended up what you suggested, in a slightly different manner. to schedule tasks, rather than using celery, i created another docker container that runs a loop to check due tasks. it does not pick up "immediate" tasks immediately due to delay but in my case i didn't need that (i guess you could achieve that with a signalling setup with redis)

for reference, the scheduler I implemented uses about 1% cpu and about 80mb of ram.

tl;dr if you need to schedule thousands of time-sensitive tasks, you need to create your own scheduler.

[sidhavratha]

i eventually ended up what you suggested, in a slightly different manner. to schedule tasks, rather than using celery, i created another docker container that runs a loop to check due tasks. it does not pick up "immediate" tasks immediately due to delay but in my case i didn't need that (i guess you could achieve that with a signalling setup with redis)

Very recently, we also moved to Redis to store scheduled task and pick it up based on scheduled_at time of task by another job. Only difference is instead of creating another container for loop, we used celerybeat to schedule the loop job every 5 secs.

Thanks for the information.