Django Celery Results

Warnings

• breaking As of v2.4.0, the `TaskResult.task_name` field is no longer automatically populated by default due to a security concern. If your application relies on this field, you must explicitly set `CELERY_RESULT_EXTENDED = True` in your Django settings to store extended properties, which includes the task name, args, and kwargs.
  Fix: Set `CELERY_RESULT_EXTENDED = True` in your Django `settings.py`.
• breaking Support for older Django and Python versions has been dropped. v2.4.0 dropped Django 2.2 support, and v2.0.0 dropped support for Django < 2.2 and Python < 3.6. Ensure your environment meets the minimum requirements.
  Fix: Upgrade Django to `3.2.25` or newer and Python to `3.6` or newer. Refer to the project's `pyproject.toml` or `setup.cfg` for exact dependency ranges.
• gotcha When using MySQL, you might encounter `django.db.utils.OperationalError: (1071, 'Specified key was too long; max key length is 767 bytes')` during migrations. This is due to indexing long string fields.
  Fix: Set `DJANGO_CELERY_RESULTS_TASK_ID_MAX_LENGTH=191` in your Django `settings.py` to shorten the `task_id` field length.
• deprecated The `default_app_config` attribute was deprecated in Django 3.1 and removed in Django 4.0. `django-celery-results` fixed this in v2.3.0. If you are on an older version of `django-celery-results` with Django 3.1+, you might see deprecation warnings.
  Fix: Upgrade `django-celery-results` to v2.3.0 or higher.
• gotcha A common pitfall in Django and Celery integration is dispatching a task immediately that relies on database changes that haven't been committed yet. The Celery task might run before the database transaction is complete.
  Fix: If a task relies on data committed within the current request/transaction, use `transaction.on_commit` to defer the task dispatch until after the transaction is successfully committed. Example: `from django.db import transaction; transaction.on_commit(lambda: my_task.delay(arg))`
• gotcha The default Celery configuration might not store detailed task arguments, keyword arguments, or other metadata. This can make debugging or re-running tasks difficult.
  Fix: Set `CELERY_RESULT_EXTENDED = True` in your Django `settings.py` to enable storing extended task properties like `args`, `kwargs`, and `task_name` in the `TaskResult` model.

Install

• pip install django-celery-results Install with pip

Imports

• django_celery_results

  INSTALLED_APPS = ['django_celery_results']

  The PyPI package name uses a dash, but the Django app and Python import name uses underscores.
• TaskResult

  from django_celery_results.models import TaskResult

  Used for programmatic access to individual task results stored in the database.
• GroupResult

  from django_celery_results.models import GroupResult

  Used for programmatic access to Celery group results stored in the database.

Quickstart

To quickly integrate `django-celery-results`, first add `django_celery_results` to your `INSTALLED_APPS` in `settings.py`. Then, configure Celery to use the Django ORM backend by setting `CELERY_RESULT_BACKEND = 'django-db'` and run Django migrations. It's also recommended to set `CELERY_RESULT_EXTENDED = True` to store full task metadata like arguments and names. A basic Celery app and a sample task are shown, along with how to retrieve results from the task object or directly from the database model.

# myproject/settings.py
INSTALLED_APPS = [
    # ... other apps
    'django_celery_results',
]

CELERY_RESULT_BACKEND = 'django-db'
CELERY_RESULT_EXTENDED = True # Recommended to store task args/kwargs/name

# myproject/celery.py (or similar Celery app configuration)
import os
from celery import Celery

os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'myproject.settings')

app = Celery('myproject')
app.config_from_object('django.conf:settings', namespace='CELERY')
app.autodiscover_tasks()

# myapp/tasks.py
from celery import shared_task

@shared_task
def add(x, y):
    return x + y

# To run and get result in Django shell:
# from myapp.tasks import add
# result = add.delay(4, 5)
# print(result.get(timeout=10)) # Output: 9

# Or to query from the DB:
# from django_celery_results.models import TaskResult
# task_db_result = TaskResult.objects.get(task_id=result.id)
# print(task_db_result.status)
# print(task_db_result.result)