django-celery-results: storing Celery task results in your own Django database

One model and one table

django-celery-results is a Celery result backend with Django, and the README describes the scope in its first line: Celery result backends using the Django ORM and the cache framework.

The implementation is small on purpose. It defines a single model, django_celery_results.models.TaskResult, used to store task results, and you can query that database table like any other Django model.

That single sentence is the whole value proposition. With a result backend that stores results in its own system, a task result is something you fetch over the network and then interpret. With this backend, the result is a row in a table your project already has a model layer for, so a view can join it to your own records, a management command can read it, and the Django admin can show it. If your application already has a pattern of polling for task state and then looking up the relevant object, that pattern becomes a query.

The extension is published on PyPI as django-celery-results, with the documentation hosted at django-celery-results.readthedocs.io and the source at github.com/celery/django-celery-results, and the version recorded in the README is 2.6.0 with a Changelog file in the repository.

Installing it and running the tests in Docker

The install from PyPI is the ordinary one:

$ pip install -U django-celery-results

The documentation also gives the from source route, which is the older pattern of unpacking a tarball and running setup.py, with the note that the install command has to be run as a privileged user if you are not in a virtualenv. There is also a development version install straight from the GitHub zipball:

$ pip install https://github.com/celery/django-celery-results/zipball/master#egg=django-celery-results

For running the project itself, the documentation recommends Docker Compose, with the assumption that you have Docker and Docker Compose installed:

$ docker-compose up --build

That starts a containerised PostgreSQL database and runs the tests using tox.

The PostgreSQL choice is worth noticing, because it is the opposite of the MySQL pitfall described further down, and the compose file in the repository is named compose.yml rather than the docker-compose.yml the older documentation refers to.

The main installation instructions are also cross-referenced to the Celery documentation, on the page for using the Django ORM and cache as a result backend, and the README itself is a thin pointer rather than a full guide.

The MySQL index length trap

There is a documented issue with MySQL, and it is the kind of thing that costs an afternoon if you hit it unprepared.

If you run django-celery-results with MySQL, you might run into some issues, and one of them is when you try to run the migrate command for the app, where you might get an error saying the specified key was too long, with a maximum key length of 767 bytes.

The workaround is an environment variable:

DJANGO_CELERY_RESULTS_TASK_ID_MAX_LENGTH=191

Or any other value, if a database other than MySQL is causing a similar issue, and the documentation notes that a max length of 191 seems to work for MySQL.

The reason is straightforward once you know it. MySQL's older InnoDB index key length limit and its default character set mean that a long task identifier column with a unique index exceeds what the index can hold, and the fix is to shorten the column rather than to change the server. The 191 figure comes from the classic utf8mb4 index limit of 767 bytes divided by four bytes per character.

The environment variable rather than a migration setting is a deliberate choice, and it has a consequence worth knowing: the value has to be present when the migration runs, and if it differs between the migration and the running application you can end up with a schema and a model that disagree.

Where django-celery-results is the wrong choice

The first limitation is that it is a results store and not a queue or a broker. It does not run your tasks, it records what happened when they ran, and a project looking for the wrong piece will find that it does nothing for task scheduling.

The second is the growth of the table. Every finished task produces a row, and nothing in this backend prunes them. On a project with a steady flow of background work, the result table becomes the largest table in the database, and on MySQL it may be the one whose index needs shortening to fit. A retention policy, a periodic delete or a partition is something you have to add, and the documentation does not provide it.

The third is the alternative. Celery's own result backends, the database and cache ones, exist for this, and the cache based ones are far cheaper to write and read than a database table. The reason to choose this one over a cache backend is the join, the admin, and the single database to operate, and if you do not need those, the cache backend is less machinery for the same information.

There is also the support dimension. The project is available as part of the Tidelift Subscription for commercial support and maintenance, which is a useful signal about who is behind it and how the maintenance is funded, and the repository itself carries its own LICENSE file, a Changelog, a CONTRIBUTING file, a cookiecutter configuration, a bumpversion configuration and a pre-commit configuration, which is the shape of a well-templated project rather than an abandoned one. The last push was on 2026-10-21 and the last release was v2.6.0 in April 2025.

Editorial conclusion

django-celery-results fits a Django team that wants task results in the same database as the rest of the application, so that a result can be joined to your own tables and queried with the ORM rather than fetched from a separate backend. It does not fit a project that wants results in a store built for them, such as Redis or a dedicated results system, or one that needs to avoid a database table growing without bound. Before adopting it, read the MySQL section of the documentation, because the task id column index exceeds the older MySQL key length and the fix is an environment variable rather than a migration, and set a retention policy on the result table, since the backend keeps writing rows for every finished task.

Frequently asked questions

Official sources

1. celery/django-celery-results on GitHub
2. Issues
3. README
4. Releases