Django + PostgreSQL + Redis + Celery

Curated rule SaaS / Web App · Internal Admin Tool Updated Oct 2026 Which file does my tool read?

Production guidelines for Django 6 enterprise applications, PostgreSQL connection pooling, Redis caching, and Celery async workers.

Django Python PostgreSQL Redis Celery React

Formats: 4 files
AGENTS.md: 79 lines
CLAUDE.md: 16 lines
Languages: Python
Updated: Oct 2026
Used by: 4 projects

Install

Writes .claude/skills/django-postgres-redis/SKILL.md

$ curl -s --create-dirs -o .claude/skills/django-postgres-redis/SKILL.md https://stackitfast.com/rules/django-postgres-redis/SKILL.md

Rule files

AGENTS.md· 79 lines · 4.0 KB

1	# Project Architecture & Guidelines (Django + PostgreSQL + Redis + Celery)
2
3	## 1. System Architecture
4	- Backend Framework: Django 6.x with WSGI/ASGI (Gunicorn or Uvicorn).
5	- Database: PostgreSQL with connection pooling (PgBouncer or Django native pool, available since 5.1).
6	- Caching & Broker: Redis for Django cache backend, session store, and Celery task broker.
7	- Async Worker Queue: Celery for asynchronous background job execution.
8
9	## 2. PostgreSQL Connection Management (Critical)
10	- Configure the Django (5.1+) database connection pool in `settings.py`:
11	```python
12	DATABASES = {
13	'default': {
14	'ENGINE': 'django.db.backends.postgresql',
15	'NAME': env('DB_NAME'),
16	'USER': env('DB_USER'),
17	'PASSWORD': env('DB_PASSWORD'),
18	'HOST': env('DB_HOST'),
19	'PORT': env('DB_PORT', default='5432'),
20	'OPTIONS': {
21	'pool': {
22	'min_size': 2,
23	'max_size': 10,
24	'timeout': 10,
25	},
26	},
27	'CONN_MAX_AGE': 0, # Must be 0 when using native pooling or PgBouncer
28	}
29	}
30	```
31	- If deploying behind PgBouncer in `transaction` mode:
32	- Disable server-side cursors: `'DISABLE_SERVER_SIDE_CURSORS': True`.
33	- Set `CONN_MAX_AGE = 0` to prevent persistent connections from conflicting with the external pooler.
34
35	## 3. Redis & Celery Best Practices
36	- Configure thread safety and broker connection limits:
37	```python
38	CELERY_BROKER_URL = env('REDIS_URL')
39	CELERY_RESULT_BACKEND = env('REDIS_URL')
40	CELERY_RESULT_BACKEND_THREAD_SAFE = True
41	CELERY_TASK_ACKS_LATE = True
42	CELERY_WORKER_PREFETCH_MULTIPLIER = 1
43	```
44	- Use `django-redis` with `BlockingConnectionPool` to prevent unbounded Redis socket creation under heavy load:
45	```python
46	CACHES = {
47	'default': {
48	'BACKEND': 'django_redis.cache.RedisCache',
49	'LOCATION': env('REDIS_URL'),
50	'OPTIONS': {
51	'CLIENT_CLASS': 'django_redis.client.DefaultClient',
52	'CONNECTION_POOL_CLASS': 'redis.BlockingConnectionPool',
53	'CONNECTION_POOL_CLASS_KWARGS': {'max_connections': 50, 'timeout': 20},
54	},
55	}
56	}
57	```
58
59	## 4. Background Job & Task Rules
60	- All Celery tasks MUST be idempotent. Network glitches can cause worker retries.
61	- Separate CPU-heavy queues from fast I/O queues (e.g., `high-priority`, `default`, `analytics`).
62	- Pass record IDs (primary keys) to Celery tasks instead of serialized model instances to prevent stale data race conditions.
63
64	## 5. Common Pitfalls to Avoid
65	- ❌ Calculating connection pool without worker count: Total connections = `(Gunicorn Workers × DB Pool) + (Celery Workers × Concurrency)`. Ensure this is within PostgreSQL `max_connections`.
66	- ❌ Unindexed Foreign Keys: Always ensure database models define `db_index=True` on filtered columns.
67	- ❌ Blocking the HTTP Request Loop: Offload any third-party API calls, email dispatches, or heavy reporting to Celery.
68
69	## 6. Testing Conventions
70	- Use `pytest` + `pytest-django` with `--reuse-db` for fast local iteration; drop `--reuse-db` in CI to catch migration drift.
71	- Use `factory_boy` for model factories instead of fixtures — fixtures rot as schemas evolve, factories don't.
72	- Test Celery tasks synchronously with `CELERY_TASK_ALWAYS_EAGER = True` in the test settings module, and assert idempotency by calling the task twice.
73	- Cover connection-pool-sensitive code paths (long transactions, `CONN_MAX_AGE` interactions) with integration tests against a real Postgres instance, not SQLite.
74
75	## 7. Git Workflow & PR Conventions
76	- Conventional Commits (`feat:`, `fix:`, `refactor:`) with the Django app name in scope, e.g. `fix(billing): correct Stripe webhook idempotency key`.
77	- Every migration file ships in the same PR as the model change that generated it — never a follow-up PR.
78	- Run `python manage.py makemigrations --check --dry-run` in CI to block unmigrated model changes from merging.
79	- Require `pytest` and `ruff check .` green before merge; squash-merge to keep `main` bisectable.

Works with Cursor · Claude Code · Windsurf · AGY

Architecture notes

Architecture Overview

Production conventions for high-throughput, enterprise-scale Python backends using Django, PostgreSQL, Redis, and Celery.

Verified Real-World Adoption

This architecture powers heavy, analytics-intensive platforms including PostHog, Sentry, Plane, Baserow, and Authentik.

Key Architectural Nuances

Calculated Connection Sizing: Balances Gunicorn web workers and Celery background processes against PgBouncer pool limits.
Idempotent Queue Execution: Enforces CELERY_TASK_ACKS_LATE with atomic database transactions.

Frequently asked questions

Does this AGENTS.md work with Cursor, Claude Code, and Windsurf?

Yes — AGENTS.md is the open, cross-tool standard read by Cursor, Claude Code, Windsurf, GitHub Copilot, and 30+ other agents. A dedicated .mdc file is also included for Cursor's native .cursor/rules format.

Why must CONN_MAX_AGE be 0 when using PgBouncer?

PgBouncer in transaction-pooling mode already manages a persistent pool of real Postgres connections behind the scenes. If Django also holds connections open (CONN_MAX_AGE > 0), you get two overlapping pooling layers fighting for the same backend connections, which quickly exhausts Postgres's max_connections under load.

Why pass model IDs instead of model instances to Celery tasks?

Celery serializes task arguments and can execute them seconds or minutes later. A serialized model instance is a stale snapshot the moment it's queued, so any changes made before the task runs are silently lost. Passing the primary key and re-fetching inside the task guarantees the worker always operates on current data.

Used in production

Explore all stacks

GlitchTip

Open-Source Error Tracking & APM · 2-5 People

Lightweight Sentry-compatible application performance monitoring and error tracking platform. Built on Python Django and PostgreSQL with async Celery task queues for high-volume exception ingestion and Redis message buffering.

Authentik

Identity Provider & Access Management · 6-20 people

Replacing Redis with three purpose-built PostgreSQL-backed packages for channels, cache, and task queueing shrinks the required external dependencies to just PostgreSQL, while protocol proxying is pushed into separate Go outposts instead of the main Django process.

Baserow

No-Code Database Platform · 6-20 people

A Django/PostgreSQL core with Nuxt/Vue frontend layers lets Baserow add premium and enterprise features as separate installable packages on top of one open-source base, while Channels and Celery keep realtime sync and background work inside the same deployable unit.

Sentry

Error Tracking Platform · 20+ people

Pairing Django with Kafka and ClickHouse allows Sentry to ingest billions of events daily while providing sub-second analytical search across production traces.

Where this stack fits

Stack It First recommends it at:

Backend · Growth · Internal

Walk the backend roadmap

Every stack ships as files

More AI agent coding rules and skills

View all

fastapi-jev-decision-service/AGENTS.mdFastAPI + Jev Decision Service (Python)Python · FastAPI · Jev fastapi-python-postgres/AGENTS.mdFastAPI + Python + PostgreSQL (Async SQLAlchemy & Pydantic v2)FastAPI · Python · PostgreSQL go-echo-sqlite/AGENTS.mdGo + Echo + SQLite (Embedded, Self-Hosted Tools)Go · Echo · SQLite go-postgres-react/AGENTS.mdGo + PostgreSQL (pgx & sqlc) + ReactGo · PostgreSQL · React