Skip to main content

Database backed asynchronous task queue

Project description

Django Background Task is a databased-backed work queue for Django, loosely based around Ruby’s DelayedJob library.

In Django Background Task, all tasks are implemented as functions (or any other callable).

There are two parts to using background tasks:

  • creating the task functions and registering them with the scheduler

  • setup a cron task (or long running process) to execute the tasks

Creating and registering tasks

To register a task use the background decorator:

from background_task import background
from django.contrib.auth.models import User

def notify_user(user_id):
    # lookup user by id and send them a message
    user = User.objects.get(pk=user_id)
    user.email_user('Here is a notification', 'You have been notified')

This will convert the notify_user into a background task function. When you call it from regular code it will actually create a Task object and stores it in the database. The database then contains serialised information about which function actually needs running later on. This does place limits on the parameters that can be passed when calling the function - they must all be serializable as JSON. Hence why in the example above a user_id is passed rather than a User object.

Calling notify_user as normal will schedule the original function to be run 60 seconds from now:


This is the default schedule time (as set in the decorator), but it can be overridden:

notify_user(, schedule=90) # 90 seconds from now
notify_user(, schedule=timedelta(minutes=20)) # 20 minutes from now
notify_user(, # at a specific time

Running tasks

There is a management command to run tasks that have been scheduled:

python process_tasks

This will simply poll the database queue every few seconds to see if there is a new task to run.

NB: to aid the management task in finding the registered tasks it is best to put them in a file called ‘’. You can put them elsewhere, but you have to ensure that they will be imported so the decorator can register them with the scheduler. By putting them in they will be auto-discovered and the file automatically imported by the management command.

Project details

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page