Django Dramatiq

Django Dramatiq automatically discovers tasks located in tasks modules within your installed apps (e.g., customers.tasks).

To change the module names used for discovery, set DRAMATIQ_AUTODISCOVER_MODULES in your settings.

To prevent specific modules from being processed as tasks, use DRAMATIQ_IGNORED_MODULES with support for wildcards.

import dramatiq
from django.core.mail import send_mail
from .models import Customer

@dramatiq.actor
def email_customer(customer_id, subject, message):
    customer = Customer.get(pk=customer_id)
    send_mail(subject, message, "webmaster@example.com", [customer.email])

To install Django Dramatiq, you must install the package along with Dramatiq and a broker (RabbitMQ or Redis).

For RabbitMQ:

pip install django-dramatiq 'dramatiq[rabbitmq]'

For Redis:

pip install django-dramatiq 'dramatiq[redis]'

To include watch support:

pip install django-dramatiq 'dramatiq[rabbitmq, watch]'

Important: Add django_dramatiq to your INSTALLED_APPS before any of your custom apps.

INSTALLED_APPS = [
    "django_dramatiq",

    "myprojectapp1",
    "myprojectapp2",
    # etc...
]

To run the basic example application, you need Redis running. Use Docker Compose to start the infrastructure, then run the Django migrations and the development server.

1. Start Redis using Docker Compose: cd examples/basic && docker compose up -d
2. Run Django migrations: python manage.py migrate
3. Start the Django server: python manage.py runserver

If a middleware requires dynamic arguments (e.g., dramatiq.middleware.GroupCallbacks), you can provide them by extending DjangoDramatiqConfig.

Follow the naming convention: create a @classmethod named middleware_<middleware_name>_kwargs (where <middleware_name> is the lowercase name of the middleware).

Then, replace the default django_dramatiq app config in INSTALLED_APPS with your custom config class.

from django_dramatiq.apps import DjangoDramatiqConfig


class CustomDjangoDramatiqConfig(DjangoDramatiqConfig):
    @classmethod
    def middleware_groupcallbacks_kwargs(cls):
        return {"rate_limiter_backend": cls.get_rate_limiter_backend()}

To store task results, configure DRAMATIQ_RESULT_BACKEND in your settings. This allows you to specify the backend class, its connection options, and middleware options like result_ttl.

DRAMATIQ_RESULT_BACKEND = {
    "BACKEND": "dramatiq.results.backends.redis.RedisBackend",
    "BACKEND_OPTIONS": {
        "url": "redis://localhost:6379",
    },
    "MIDDLEWARE_OPTIONS": {
        "result_ttl": 1000 * 60 * 10
    }
}

Configure your broker in settings.py using the DRAMATIQ_BROKER dictionary. This dictionary defines the broker class, its options, and the middleware stack.

When using AdminMiddleware, you can also specify which database to use for persisting Task objects via DRAMATIQ_TASKS_DATABASE (defaults to "default").

DRAMATIQ_BROKER = {
    "BROKER": "dramatiq.brokers.rabbitmq.RabbitmqBroker", 
    "OPTIONS": {
        "url": "amqp://localhost:5672",
    },
    "MIDDLEWARE": [
        "dramatiq.middleware.prometheus.Prometheus",
        "dramatiq.middleware.AgeLimit",
        "dramatiq.middleware.TimeLimit",
        "dramatiq.middleware.Callbacks",
        "dramatiq.middleware.Retries",
        "django_dramatiq.middleware.DbConnectionsMiddleware",
        "django_dramatiq.middleware.AdminMiddleware",
    ]
}

DRAMATIQ_TASKS_DATABASE = "default"

A complete example of an application built using Django Dramatiq is available in the repository's examples directory.

https://github.com/bogdanp/django_dramatiq/tree/master/examples/basic

The rundramatiq command automatically discovers task modules by scanning your Django apps. You can control this behavior using the following Django settings:

• DRAMATIQ_AUTODISCOVER_MODULES: A tuple of module names to look for in each app (e.g., ('tasks', 'worker_tasks')). Defaults to ('tasks',).
• DRAMATIQ_IGNORED_MODULES: A list of module names or patterns to ignore during discovery.

The command always includes django_dramatiq.setup in the execution path to ensure the Django integration is initialized.

The following middleware are provided by django_dramatiq:

• django_dramatiq.middleware.DbConnectionsMiddleware: Vital for closing expired database connections after each message is processed.
• django_dramatiq.middleware.AdminMiddleware: Stores task metadata in a relational database and exposes it via the Django admin.

Use the rundramatiq management command to start workers. This command automatically discovers task modules.

Control Worker Scaling:

• Environment Variables: DRAMATIQ_NPROCS (processes) and DRAMATIQ_NTHREADS (threads per process).
• CLI Arguments: -p (processes) and -t (threads). CLI arguments take highest precedence.

Commands:

# Default execution
python manage.py rundramatiq

# Using environment variables
export DRAMATIQ_NPROCS=2 DRAMATIQ_NTHREADS=2
python manage.py rundramatiq

# Using CLI arguments
python manage.py rundramatiq -p 2 -t 2