django-celery-outbox

Transactional Outbox pattern for Celery tasks in Django.

Why Use This?

When you call task.delay() inside a database transaction, two things can go wrong:

1. Message lost: The task is sent to the broker, but the transaction rolls back. The task runs with data that doesn't exist.
2. Message never sent: The transaction commits, but the broker connection fails. The task is never executed.

django-celery-outbox solves both problems by storing tasks in a database table within the same transaction as your business data. A separate relay process reads the table and sends tasks to the broker asynchronously with durable recovery for committed rows and duplicate-tolerant relay semantics. Stronger end-to-end guarantees still depend on broker confirms.

Features

• Drop-in replacement for celery.Celery
• Duplicate-tolerant relay recovery
• Automatic retry with exponential backoff
• Dead letter queue for failed messages
• Sentry trace propagation
• structlog context propagation
• StatsD metrics
• Django admin integration
• Packaged pytest fixtures
• File-based relay liveness guidance

Quick Links

• Getting Started — Install and configure in 5 minutes
• Concepts — How the outbox pattern works
• Configuration — All settings reference
• Testing with pytest — Built-in fixtures for outbox and relay tests
• Example Project — Working Docker Compose setup