DEV Community: sribalu

Django REST API with PostgreSQL — Advanced Queries & Optimization

sribalu — Tue, 31 Mar 2026 18:20:16 +0000

Introduction
Building a REST API with Django REST Framework (DRF) is straightforward — but making it fast and scalable with PostgreSQL requires understanding advanced query techniques. In this guide, you'll learn how to write optimized queries, avoid common pitfalls like the N+1 problem, use PostgreSQL-specific features, and measure performance.

Prerequisites

Django + DRF project set up
PostgreSQL connected via psycopg2
Basic understanding of Django ORM

Project Setup We'll use a simple blogging API with these models: python# models.py from django.db import models

class Author(models.Model):
name = models.CharField(max_length=100)
email = models.EmailField(unique=True)
bio = models.TextField(blank=True)

def __str__(self):
    return self.name

class Tag(models.Model):
name = models.CharField(max_length=50, unique=True)

def __str__(self):
    return self.name

class Post(models.Model):
title = models.CharField(max_length=200)
content = models.TextField()
author = models.ForeignKey(Author, on_delete=models.CASCADE, related_name='posts')
tags = models.ManyToManyField(Tag, blank=True)
created_at = models.DateTimeField(auto_now_add=True)
published = models.BooleanField(default=False)
view_count = models.PositiveIntegerField(default=0)

class Meta:
    indexes = [
        models.Index(fields=['created_at']),
        models.Index(fields=['author', 'published']),
    ]

def __str__(self):
    return self.title

Notice the Meta.indexes — we're already thinking about query performance at the model level.

The N+1 Problem (And How to Kill It) The N+1 problem is the #1 performance killer in Django APIs. It happens when you fetch a list of objects and then make a separate database query for each one. The bad way: python# views.py — DON'T DO THIS class PostListView(generics.ListAPIView): queryset = Post.objects.all() serializer_class = PostSerializer

serializers.py — This triggers N+1

class PostSerializer(serializers.ModelSerializer):
author_name = serializers.SerializerMethodField()

def get_author_name(self, obj):
    return obj.author.name  # 1 query per post!

class Meta:
    model = Post
    fields = ['id', 'title', 'author_name']

With 100 posts, this runs 101 queries — 1 to fetch posts, then 1 per post to get the author.
The fix — select_related for ForeignKey:
python# views.py — DO THIS
class PostListView(generics.ListAPIView):
serializer_class = PostSerializer

def get_queryset(self):
    return Post.objects.select_related('author').all()

Now Django fetches everything in 1 SQL JOIN query.
Use prefetch_related for ManyToMany:
pythondef get_queryset(self):
return Post.objects.select_related('author').prefetch_related('tags').all()
This runs 2 queries total (posts + tags), regardless of how many rows are returned.

Filtering with django-filter Install the package: bashpip install django-filter Add to settings: pythonINSTALLED_APPS = [..., 'django_filters']

REST_FRAMEWORK = {
'DEFAULT_FILTER_BACKENDS': ['django_filters.rest_framework.DjangoFilterBackend'],
}
Create a filter class:
python# filters.py
import django_filters
from .models import Post

class PostFilter(django_filters.FilterSet):
author = django_filters.CharFilter(field_name='author_name', lookup_expr='icontains')
tag = django_filters.CharFilter(field_name='tags_name', lookup_expr='iexact')
published = django_filters.BooleanFilter()
created_after = django_filters.DateFilter(field_name='created_at', lookup_expr='gte')
created_before = django_filters.DateFilter(field_name='created_at', lookup_expr='lte')

class Meta:
    model = Post
    fields = ['author', 'tag', 'published', 'created_after', 'created_before']

Wire it up in the view:
pythonfrom .filters import PostFilter

class PostListView(generics.ListAPIView):
serializer_class = PostSerializer
filterset_class = PostFilter

def get_queryset(self):
    return Post.objects.select_related('author').prefetch_related('tags')


Now your API supports queries like:

GET /api/posts/?author=sri&published=true&created_after=2026-01-01

PostgreSQL-Specific Features This is where PostgreSQL really shines over SQLite or MySQL. Full-Text Search pythonfrom django.contrib.postgres.search import SearchVector, SearchQuery, SearchRank

class PostSearchView(generics.ListAPIView):
serializer_class = PostSerializer

def get_queryset(self):
    query = self.request.query_params.get('q', '')
    if not query:
        return Post.objects.none()

    search_query = SearchQuery(query)
    search_vector = SearchVector('title', weight='A') + SearchVector('content', weight='B')

    return (
        Post.objects
        .annotate(rank=SearchRank(search_vector, search_query))
        .filter(rank__gte=0.1)
        .order_by('-rank')
        .select_related('author')
    )

Usage: GET /api/posts/search/?q=django+authentication
PostgreSQL ranks results by relevance — title matches score higher than body matches.
ArrayField for Tags (Alternative Approach)
pythonfrom django.contrib.postgres.fields import ArrayField

class Article(models.Model):
title = models.CharField(max_length=200)
keywords = ArrayField(models.CharField(max_length=50), blank=True, default=list)
Query it:
python# Posts where keywords contain 'django'
Article.objects.filter(keywords__contains=['django'])

Posts where keywords overlap with a list

Article.objects.filter(keywords__overlap=['django', 'python'])
JSONField for Flexible Metadata
pythonclass Post(models.Model):
# ... other fields
metadata = models.JSONField(default=dict, blank=True)

Store anything

post.metadata = {'reading_time': 5, 'difficulty': 'intermediate', 'version': '4.2'}
post.save()

Query into JSON

Post.objects.filter(metadata_difficulty='intermediate')
Post.objects.filter(metadatareading_time_gte=3)

Aggregations & Annotations Annotations let you add computed fields directly in the queryset — pushing work to the database instead of Python. pythonfrom django.db.models import Count, Avg, Sum, F, Q

class AuthorStatsView(generics.ListAPIView):
serializer_class = AuthorStatsSerializer

def get_queryset(self):
    return Author.objects.annotate(
        post_count=Count('posts'),
        published_count=Count('posts', filter=Q(posts__published=True)),
        total_views=Sum('posts__view_count'),
        avg_views=Avg('posts__view_count'),
    ).order_by('-total_views')

The serializer:
pythonclass AuthorStatsSerializer(serializers.ModelSerializer):
post_count = serializers.IntegerField()
published_count = serializers.IntegerField()
total_views = serializers.IntegerField()
avg_views = serializers.FloatField()

class Meta:
    model = Author
    fields = ['id', 'name', 'post_count', 'published_count', 'total_views', 'avg_views']

This is one SQL query that returns all stats — no Python loops needed.

Pagination for Large Datasets Never return unbounded querysets in production. DRF has three built-in strategies: python# settings.py REST_FRAMEWORK = { 'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.CursorPagination', 'PAGE_SIZE': 20, } Cursor pagination is the most efficient for large tables — it uses a database cursor instead of OFFSET, which gets slow on millions of rows. Custom cursor pagination: pythonfrom rest_framework.pagination import CursorPagination

class PostCursorPagination(CursorPagination):
page_size = 20
ordering = '-created_at'
cursor_query_param = 'cursor'

Measuring Query Performance Never guess — always measure. Django Debug Toolbar (Development) bashpip install django-debug-toolbar python# settings.py INSTALLED_APPS = [..., 'debug_toolbar'] MIDDLEWARE = ['debug_toolbar.middleware.DebugToolbarMiddleware', ...] INTERNAL_IPS = ['127.0.0.1'] This shows every SQL query, its duration, and a stack trace in the browser. Query Counting in Tests python# tests.py from django.test import TestCase from django.test.utils import override_settings

class PostListQueryTest(TestCase):
def setUp(self):
# Create test data
author = Author.objects.create(name='Sri', email='sri@example.com')
for i in range(10):
Post.objects.create(title=f'Post {i}', author=author, published=True)

def test_post_list_query_count(self):
    with self.assertNumQueries(2):  # 1 for posts, 1 for tags
        response = self.client.get('/api/posts/')
        self.assertEqual(response.status_code, 200)

If this test fails with 12 queries instead of 2, you know you have an N+1 somewhere.
Explain Analyze (PostgreSQL)
pythonfrom django.db import connection

queryset = Post.objects.select_related('author').filter(published=True)
print(queryset.query) # Raw SQL

Run EXPLAIN ANALYZE in psql

EXPLAIN ANALYZE SELECT * FROM blog_post WHERE published = true;

Look for Seq Scan on large tables — that's a signal you need an index.

Putting It All Together — Optimized ViewSet python# views.py from rest_framework import viewsets, filters from django_filters.rest_framework import DjangoFilterBackend from .models import Post from .serializers import PostSerializer from .filters import PostFilter from .pagination import PostCursorPagination

class PostViewSet(viewsets.ReadOnlyModelViewSet):
serializer_class = PostSerializer
filterset_class = PostFilter
pagination_class = PostCursorPagination
filter_backends = [DjangoFilterBackend, filters.SearchFilter, filters.OrderingFilter]
search_fields = ['title', 'content']
ordering_fields = ['created_at', 'view_count']
ordering = ['-created_at']

def get_queryset(self):
    return (
        Post.objects
        .select_related('author')
        .prefetch_related('tags')
        .filter(published=True)
        .only('id', 'title', 'created_at', 'view_count', 'author__name')
        # .only() fetches just the columns you need — saves bandwidth
    )

The .only() call is the final optimization — it tells PostgreSQL to return only the columns your serializer actually uses, reducing data transfer.

Key Takeaways
TechniqueWhen to Useselect_relatedForeignKey / OneToOne relationshipsprefetch_relatedManyToMany / reverse FK relationshipsannotate()Computed fields — push math to the DBonly() / defer()Large tables where you don't need all columnsFull-text searchSearch bars with relevance rankingCursor paginationLarge datasets (10k+ rows)assertNumQueriesCatch N+1 regressions in CI

What's Next
In Part 4, we'll set up a full CI/CD pipeline for Django using GitHub Actions — automated testing, linting, and deployment on every push.

Part of the Django Production Series. Part 1 — Authentication | Part 2 — Docker Deployment

Django + Docker Deployment: A Complete Production Guide

sribalu — Sat, 21 Mar 2026 23:50:14 +0000

Django + Docker Deployment: A Complete Production Guide

Level: Intermediate | Read Time: 14 min | Author: Sri Balu

Introduction

Deploying Django applications used to mean wrestling with server configurations, dependency conflicts, and "it works on my machine" nightmares. Docker changes all of that.

In this guide, we'll containerize a Django application from scratch, wire it up with PostgreSQL and Nginx, and deploy it to a production server — the right way.

Here's what we'll cover:

Why Docker for Django applications
Writing a production-ready Dockerfile
Docker Compose for multi-container setup (Django + PostgreSQL + Nginx)
Environment variables and secrets management
Static files and media files handling
Running database migrations automatically
Deploying to a Linux server (Ubuntu)
Common pitfalls and how to avoid them

1. Why Docker for Django?

Before we write any code, let's understand why Docker has become the standard for Django deployments.

The Problem Without Docker

Developer A: "It works on my machine!"
Developer B: "But it crashes on mine..."
DevOps:      "It works in staging but not production..."

What Docker Solves

Problem	Docker Solution
Dependency conflicts	Isolated containers per service
Environment differences	Same image runs everywhere
Complex setup	One command: `docker compose up`
Scaling	Spin up multiple containers easily
Rollback	Switch back to previous image instantly

2. Project Structure

Here's the structure we'll build:

myproject/
├── app/
│   ├── manage.py
│   ├── myproject/
│   │   ├── settings/
│   │   │   ├── base.py
│   │   │   ├── development.py
│   │   │   └── production.py
│   │   ├── urls.py
│   │   └── wsgi.py
│   └── requirements/
│       ├── base.txt
│       └── production.txt
├── nginx/
│   └── nginx.conf
├── .env
├── .env.example
├── docker-compose.yml
├── docker-compose.prod.yml
└── Dockerfile

3. Writing a Production-Ready Dockerfile

A good Dockerfile uses multi-stage builds to keep the final image small and secure.

# Dockerfile

# ─── Stage 1: Builder ───────────────────────────────────────
FROM python:3.12-slim AS builder

# Set environment variables
ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PIP_NO_CACHE_DIR=1

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    build-essential \
    libpq-dev \
    && rm -rf /var/lib/apt/lists/*

# Install Python dependencies
COPY requirements/base.txt requirements/production.txt ./requirements/
RUN pip install --upgrade pip \
    && pip install -r requirements/production.txt

# ─── Stage 2: Production Image ──────────────────────────────
FROM python:3.12-slim AS production

ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1

WORKDIR /app

# Install only runtime dependencies
RUN apt-get update && apt-get install -y \
    libpq5 \
    && rm -rf /var/lib/apt/lists/*

# Copy installed packages from builder
COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
COPY --from=builder /usr/local/bin /usr/local/bin

# Copy project files
COPY app/ .

# Create non-root user for security
RUN addgroup --system django \
    && adduser --system --ingroup django django \
    && chown -R django:django /app

USER django

# Expose port
EXPOSE 8000

# Start Gunicorn
CMD ["gunicorn", "myproject.wsgi:application", \
     "--bind", "0.0.0.0:8000", \
     "--workers", "3", \
     "--timeout", "120"]

Key Dockerfile Best Practices

Multi-stage builds — keeps final image lean (no build tools in production)
Non-root user — runs Django as django user, not root (security!)
Gunicorn — production WSGI server, never use runserver in production
PYTHONUNBUFFERED=1 — ensures logs appear in real time

4. Requirements Files

# requirements/base.txt
Django==5.0.4
djangorestframework==3.15.1
psycopg2==2.9.9
python-decouple==3.8
whitenoise==6.6.0

# requirements/production.txt
-r base.txt
gunicorn==21.2.0

5. Django Settings for Docker

Split your settings into base and production:

# app/myproject/settings/base.py
from decouple import config

SECRET_KEY = config('SECRET_KEY')
DEBUG = config('DEBUG', default=False, cast=bool)
ALLOWED_HOSTS = config('ALLOWED_HOSTS', default='').split(',')

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': config('POSTGRES_DB'),
        'USER': config('POSTGRES_USER'),
        'PASSWORD': config('POSTGRES_PASSWORD'),
        'HOST': config('POSTGRES_HOST', default='db'),
        'PORT': config('POSTGRES_PORT', default='5432'),
    }
}

# Static files
STATIC_URL = '/static/'
STATIC_ROOT = '/app/staticfiles'

MEDIA_URL = '/media/'
MEDIA_ROOT = '/app/mediafiles'

# Whitenoise for static files
MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'whitenoise.middleware.WhiteNoiseMiddleware',  # Add this!
    ...
]

STATICFILES_STORAGE = 'whitenoise.storage.CompressedManifestStaticFilesStorage'

6. Environment Variables (.env)

Never hardcode secrets! Use a .env file:

# .env (never commit this to git!)
SECRET_KEY=your-super-secret-key-here
DEBUG=False
ALLOWED_HOSTS=localhost,127.0.0.1,yourdomain.com

# PostgreSQL
POSTGRES_DB=myproject_db
POSTGRES_USER=myproject_user
POSTGRES_PASSWORD=strong_password_here
POSTGRES_HOST=db
POSTGRES_PORT=5432

# .env.example (commit this — no real secrets)
SECRET_KEY=your-secret-key
DEBUG=False
ALLOWED_HOSTS=localhost
POSTGRES_DB=myproject_db
POSTGRES_USER=myproject_user
POSTGRES_PASSWORD=your-password
POSTGRES_HOST=db
POSTGRES_PORT=5432

# .gitignore — CRITICAL!
.env
*.pyc
__pycache__/
staticfiles/
mediafiles/

7. Docker Compose — Development

# docker-compose.yml (development)
version: '3.9'

services:
  db:
    image: postgres:16-alpine
    volumes:
      - postgres_data:/var/lib/postgresql/data/
    env_file:
      - .env
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5

  web:
    build:
      context: .
      target: builder  # Use builder stage for dev (has dev tools)
    command: python manage.py runserver 0.0.0.0:8000
    volumes:
      - ./app:/app  # Live code reloading
    ports:
      - "8000:8000"
    env_file:
      - .env
    depends_on:
      db:
        condition: service_healthy

volumes:
  postgres_data:

8. Docker Compose — Production

# docker-compose.prod.yml (production)
version: '3.9'

services:
  db:
    image: postgres:16-alpine
    volumes:
      - postgres_data:/var/lib/postgresql/data/
    env_file:
      - .env
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5

  web:
    build:
      context: .
      target: production  # Use production stage
    command: >
      sh -c "python manage.py migrate --noinput &&
             python manage.py collectstatic --noinput &&
             gunicorn myproject.wsgi:application
             --bind 0.0.0.0:8000
             --workers 3
             --timeout 120"
    volumes:
      - static_volume:/app/staticfiles
      - media_volume:/app/mediafiles
    env_file:
      - .env
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

  nginx:
    image: nginx:1.25-alpine
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/conf.d/default.conf
      - static_volume:/app/staticfiles
      - media_volume:/app/mediafiles
    ports:
      - "80:80"
    depends_on:
      - web
    restart: unless-stopped

volumes:
  postgres_data:
  static_volume:
  media_volume:

9. Nginx Configuration

Nginx acts as a reverse proxy — it handles static files and forwards API requests to Gunicorn:

# nginx/nginx.conf
upstream django {
    server web:8000;
}

server {
    listen 80;
    server_name yourdomain.com www.yourdomain.com;

    client_max_body_size 20M;

    # Static files — served directly by Nginx (fast!)
    location /static/ {
        alias /app/staticfiles/;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    # Media files
    location /media/ {
        alias /app/mediafiles/;
    }

    # Django app — proxy to Gunicorn
    location / {
        proxy_pass http://django;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_connect_timeout 60s;
        proxy_read_timeout 60s;
    }
}

10. Deploying to Ubuntu Server

Step 1 — Install Docker on Server

# Update system
sudo apt-get update
sudo apt-get upgrade -y

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Install Docker Compose
sudo apt-get install docker-compose-plugin -y

# Add your user to docker group
sudo usermod -aG docker $USER
newgrp docker

# Verify installation
docker --version
docker compose version

Step 2 — Clone Your Project

git clone https://github.com/yourusername/myproject.git
cd myproject

Step 3 — Set Up Environment Variables

cp .env.example .env
nano .env  # Fill in your production values

Step 4 — Build and Start

# Build images
docker compose -f docker-compose.prod.yml build

# Start all services
docker compose -f docker-compose.prod.yml up -d

# Check status
docker compose -f docker-compose.prod.yml ps

Step 5 — Verify Everything Works

# Check logs
docker compose -f docker-compose.prod.yml logs web
docker compose -f docker-compose.prod.yml logs nginx

# Run a command inside the container
docker compose -f docker-compose.prod.yml exec web python manage.py createsuperuser

11. Useful Docker Commands

# View running containers
docker compose ps

# View logs (follow mode)
docker compose logs -f web

# Restart a service
docker compose restart web

# Stop all services
docker compose down

# Stop and remove volumes (WARNING: deletes DB data!)
docker compose down -v

# Rebuild after code changes
docker compose up --build -d

# Run Django management commands
docker compose exec web python manage.py migrate
docker compose exec web python manage.py shell
docker compose exec web python manage.py createsuperuser

# Access PostgreSQL directly
docker compose exec db psql -U myproject_user -d myproject_db

12. Common Pitfalls & Fixes

❌ Issue 1: Database not ready when Django starts

# Fix: Add healthcheck + depends_on condition
depends_on:
  db:
    condition: service_healthy

❌ Issue 2: Static files not showing

# Fix: Run collectstatic
docker compose exec web python manage.py collectstatic --noinput

❌ Issue 3: Migrations not applied

# Fix: Run migrations manually
docker compose exec web python manage.py migrate

❌ Issue 4: Secret key exposed in code

# Fix: Always use environment variables
from decouple import config
SECRET_KEY = config('SECRET_KEY')  # Never hardcode!

❌ Issue 5: Container runs as root

# Fix: Always create non-root user
RUN adduser --system django
USER django

Summary

Here's what we built:

Component	Technology
Web server	Gunicorn + Django
Reverse proxy	Nginx
Database	PostgreSQL 16
Containerization	Docker + Docker Compose
Static files	Whitenoise + Nginx
Secrets	python-decouple + .env
Security	Non-root user, no DEBUG in prod

What's Next?

Part 3: Django REST API with PostgreSQL — Advanced Queries & Optimization
Part 4: CI/CD Pipeline for Django with GitHub Actions
Part 5: Scaling Django with Redis, Celery & Background Tasks

Found this helpful? Share it with your team! Questions? Drop them in the comments.

Tags: django docker python devops postgresql nginx deployment backend

Go beyond Django's built-in auth — learn JWT, custom email login, role-based permissions, and brute-force protection.

sribalu — Sat, 21 Mar 2026 22:41:21 +0000

Django Authentication Deep Dive: JWT, Sessions, and Custom Backends

Go beyond Django's built-in auth — learn JWT, custom email login, role-based permissions, and brute-force protection. Intermediate | Read Time: 12 min | Author: [SRI BALU]

Introduction

Authentication is the backbone of almost every web application. Django ships with a solid built-in auth system — but in real-world projects, you'll quickly outgrow it. Whether you're building a REST API, a multi-tenant SaaS, or a social login platform, understanding Django's authentication internals gives you the power to customize it exactly how you need.

In this deep-dive, we'll cover:

How Django's authentication system works under the hood
Session-based vs JWT-based authentication
Implementing JWT authentication with djangorestframework-simplejwt
Writing a custom authentication backend (e.g., login with email instead of username)
Securing your endpoints with permissions

1. How Django Authentication Works Under the Hood

Before writing any code, it helps to understand what happens when a user logs in.

Django's auth system revolves around three core components:

Component	Role
`User` model	Stores credentials (username, password hash)
`AuthenticationBackend`	Validates credentials
`Session` / `Token`	Maintains state after login

When you call authenticate(request, username=..., password=...), Django loops through all backends listed in AUTHENTICATION_BACKENDS and returns the first User object that matches — or None.

# django/contrib/auth/__init__.py (simplified)
def authenticate(request=None, **credentials):
    for backend_path in settings.AUTHENTICATION_BACKENDS:
        backend = load_backend(backend_path)
        try:
            user = backend.authenticate(request, **credentials)
        except PermissionDenied:
            return None
        if user is None:
            continue
        user.backend = backend_path
        return user
    return None

The default backend is django.contrib.auth.backends.ModelBackend, which checks the database for a matching username + password hash.

2. Session-Based Authentication (The Django Default)

Django's default auth uses server-side sessions. Here's the flow:

User submits login form
    → Django validates credentials
    → Creates a session in the DB (django_session table)
    → Sends a session cookie (sessionid) to the browser
    → On every request, browser sends the cookie
    → Django looks up the session → finds the user

Setting it up (already built-in):

# settings.py
INSTALLED_APPS = [
    'django.contrib.auth',
    'django.contrib.sessions',
    ...
]

MIDDLEWARE = [
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    ...
]

Login/Logout views:

# views.py
from django.contrib.auth import authenticate, login, logout
from django.shortcuts import redirect, render

def login_view(request):
    if request.method == 'POST':
        username = request.POST['username']
        password = request.POST['password']
        user = authenticate(request, username=username, password=password)
        if user is not None:
            login(request, user)
            return redirect('dashboard')
        else:
            return render(request, 'login.html', {'error': 'Invalid credentials'})
    return render(request, 'login.html')

def logout_view(request):
    logout(request)
    return redirect('login')

When to use sessions:

Traditional Django web apps (not APIs)
Server-rendered templates
When you control both frontend and backend

3. JWT Authentication for REST APIs

For Django REST Framework (DRF) APIs — especially those consumed by React, Flutter, or mobile apps — JWT (JSON Web Tokens) is the preferred approach.

Why JWT over sessions for APIs?

	Sessions	JWT
State	Server-side	Stateless
Scalability	Requires shared DB	Works across servers
Mobile support	Cookie issues	Easy via headers
Logout	Simple	Requires token blacklist

Installation:

pip install djangorestframework djangorestframework-simplejwt

# settings.py
INSTALLED_APPS = [
    ...
    'rest_framework',
]

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': (
        'rest_framework_simplejwt.authentication.JWTAuthentication',
    ),
}

from datetime import timedelta

SIMPLE_JWT = {
    'ACCESS_TOKEN_LIFETIME': timedelta(minutes=30),
    'REFRESH_TOKEN_LIFETIME': timedelta(days=7),
    'ROTATE_REFRESH_TOKENS': True,
    'BLACKLIST_AFTER_ROTATION': True,
    'ALGORITHM': 'HS256',
    'AUTH_HEADER_TYPES': ('Bearer',),
}

URL configuration:

# urls.py
from rest_framework_simplejwt.views import (
    TokenObtainPairView,
    TokenRefreshView,
    TokenBlacklistView,
)

urlpatterns = [
    path('api/auth/login/', TokenObtainPairView.as_view(), name='token_obtain_pair'),
    path('api/auth/refresh/', TokenRefreshView.as_view(), name='token_refresh'),
    path('api/auth/logout/', TokenBlacklistView.as_view(), name='token_blacklist'),
]

Protecting API views:

# views.py
from rest_framework.permissions import IsAuthenticated
from rest_framework.decorators import api_view, permission_classes
from rest_framework.response import Response

@api_view(['GET'])
@permission_classes([IsAuthenticated])
def profile_view(request):
    user = request.user
    return Response({
        'id': user.id,
        'username': user.username,
        'email': user.email,
    })

How to call the API:

# Step 1: Get tokens
curl -X POST http://localhost:8000/api/auth/login/ \
  -H "Content-Type: application/json" \
  -d '{"username": "john", "password": "secret123"}'

# Response:
# {"access": "eyJ0eXAiOiJKV...", "refresh": "eyJ0eXAiOiJKV..."}

# Step 2: Call protected endpoint
curl -X GET http://localhost:8000/api/profile/ \
  -H "Authorization: Bearer eyJ0eXAiOiJKV..."

4. Custom Authentication Backend: Login with Email

By default, Django uses username to authenticate. In modern apps, users expect to log in with their email address. Here's how to write a custom backend:

# backends.py
from django.contrib.auth.backends import ModelBackend
from django.contrib.auth import get_user_model

User = get_user_model()

class EmailBackend(ModelBackend):
    """
    Authenticate using email instead of username.
    Falls back to username if email not found.
    """
    def authenticate(self, request, username=None, password=None, **kwargs):
        try:
            # Try to find user by email
            user = User.objects.get(email=username)
        except User.DoesNotExist:
            # Fall back to username lookup
            try:
                user = User.objects.get(username=username)
            except User.DoesNotExist:
                return None

        if user.check_password(password) and self.user_can_authenticate(user):
            return user
        return None

Register the backend:

# settings.py
AUTHENTICATION_BACKENDS = [
    'myapp.backends.EmailBackend',
    'django.contrib.auth.backends.ModelBackend',  # keep as fallback
]

Now authenticate(request, username="john@example.com", password="secret") will work automatically — no other code changes needed!

5. Custom JWT Payload (Add Extra Claims)

By default, JWT tokens contain only user_id. You can add extra data like role, email, or is_staff:

# serializers.py
from rest_framework_simplejwt.serializers import TokenObtainPairSerializer

class CustomTokenObtainPairSerializer(TokenObtainPairSerializer):
    @classmethod
    def get_token(cls, user):
        token = super().get_token(user)

        # Add custom claims
        token['email'] = user.email
        token['username'] = user.username
        token['is_staff'] = user.is_staff
        token['role'] = getattr(user, 'role', 'user')  # if you have a role field

        return token

# views.py
from rest_framework_simplejwt.views import TokenObtainPairView

class CustomTokenObtainPairView(TokenObtainPairView):
    serializer_class = CustomTokenObtainPairSerializer

# urls.py
path('api/auth/login/', CustomTokenObtainPairView.as_view(), name='token_obtain_pair'),

6. Role-Based Permissions

Once authentication is set up, you'll want authorization — controlling what users can do.

Built-in permission classes:

from rest_framework.permissions import (
    IsAuthenticated,       # Must be logged in
    IsAdminUser,           # Must be staff/superuser
    IsAuthenticatedOrReadOnly,  # Read for all, write for authenticated
)

Custom permission class:

# permissions.py
from rest_framework.permissions import BasePermission

class IsOwnerOrAdmin(BasePermission):
    """
    Allow access only to object owners or admin users.
    """
    def has_object_permission(self, request, view, obj):
        if request.user.is_staff:
            return True
        return obj.owner == request.user


# views.py
from rest_framework import generics
from .permissions import IsOwnerOrAdmin
from .models import Post
from .serializers import PostSerializer

class PostDetailView(generics.RetrieveUpdateDestroyAPIView):
    queryset = Post.objects.all()
    serializer_class = PostSerializer
    permission_classes = [IsAuthenticated, IsOwnerOrAdmin]

7. Security Best Practices

✅ Always do this:

# settings.py

# Use HTTPS in production
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True

# Prevent XSS from stealing session cookies
SESSION_COOKIE_HTTPONLY = True

# Limit session age
SESSION_COOKIE_AGE = 1209600  # 2 weeks in seconds

# Password validation
AUTH_PASSWORD_VALIDATORS = [
    {'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator',
     'OPTIONS': {'min_length': 8}},
    {'NAME': 'django.contrib.auth.password_validation.CommonPasswordValidator'},
    {'NAME': 'django.contrib.auth.password_validation.NumericPasswordValidator'},
]

✅ Rate-limit login attempts:

pip install django-axes

# settings.py
INSTALLED_APPS = ['axes', ...]
AUTHENTICATION_BACKENDS = [
    'axes.backends.AxesStandaloneBackend',
    'myapp.backends.EmailBackend',
]
AXES_FAILURE_LIMIT = 5       # Lock after 5 failed attempts
AXES_COOLOFF_TIME = 1        # Unlock after 1 hour

Summary

Here's what we covered:

Topic	Use Case
Session auth	Traditional Django web apps
JWT with simplejwt	REST APIs, mobile apps
Custom EmailBackend	Login with email
Custom JWT claims	Pass role/email in token
Custom permissions	Role-based access control
django-axes	Brute-force protection

Django's auth system is designed to be extended — not replaced. By understanding how backends, sessions, and tokens work together, you can build secure, scalable authentication for any use case.

What's Next?

Part 2: OAuth2 & Social Login with django-allauth (Google, GitHub)
Part 3: Two-Factor Authentication (2FA) with TOTP
Part 4: Multi-tenant authentication with row-level security

Found this helpful? Share it on Twitter and tag me! Have questions? Drop them in the comments below.

Tags: django python authentication jwt django-rest-framework web-development backend