Forem: Houssem Reggai

EXPLAIN ANALYZE: The PostgreSQL Command Every Django Developer Should Know

Houssem Reggai — Wed, 29 Apr 2026 11:34:11 +0000

PROFESSIONAL DJANGO ENGINEERING SERIES #6

If you have never read a query execution plan, you are flying blind on database performance. Here is how to read one — and what the warning signs look like.

Django's ORM is excellent at writing SQL. It is not excellent at telling you whether that SQL is fast. For that, you need to go one level deeper — to the database itself, and to the execution plan it generates for every query you run.

EXPLAIN ANALYZE is PostgreSQL's most powerful diagnostic tool. It shows you not just what SQL your query produces, but how the database engine plans to execute it, how long it actually takes, and — most usefully — where it is spending that time.

Most Django performance problems are database problems. Most database problems are index problems. And most index problems are invisible until you look at the query plan.

Running EXPLAIN ANALYZE from Django

Django 3.2 added QuerySet.explain(), which gives you direct access to the database execution plan:

# In the Django shell (python manage.py shell_plus):
qs = Order.objects.filter(status='paid', user_id=42).select_related('user')
print(qs.explain(verbose=True, analyze=True))

# Or with raw SQL for more control:
from django.db import connection
with connection.cursor() as cursor:
    cursor.execute(
        'EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT) '
        'SELECT * FROM orders_order WHERE status = %s AND user_id = %s',
        ['paid', 42]
    )
    for row in cursor.fetchall():
        print(row[0])

Reading the Output

A typical EXPLAIN ANALYZE output looks like this:

Seq Scan on orders_order  (cost=0.00..4821.00 rows=3912 width=52)
                          (actual time=0.05..28.4 rows=3912 loops=1)
  Filter: ((status = 'paid') AND (user_id = 42))
  Rows Removed by Filter: 48231
Planning Time: 0.8 ms
Execution Time: 28.9 ms

Here is what each part means:

Seq Scan — the most important warning sign
A Seq Scan means the database read every row in the table to find the ones matching your filter. It is sometimes unavoidable on very small tables, but on a table with tens of thousands of rows, a Seq Scan on a filtered column almost always means a missing index.

Rows Removed by Filter — measuring inefficiency
In the example above, 48,231 rows were read and discarded to find 3,912 matching rows. The database is reading 12 rows for every 1 it keeps. An index on status and user_id would let the database jump directly to the matching rows without reading the discarded ones.

cost=X..Y — the planner’s estimate
The cost values are the planner's estimates in arbitrary units. The first number is startup cost (getting the first row), the second is total cost. Lower is better, but absolute numbers are less useful than the ratio between different parts of your query plan.

actual time — ground truth
The actual time values are real milliseconds from the execution. If startup time is high, your query is doing expensive initialization. If total time is high but startup time is low, the bottleneck is in processing the rows.

The Warning Signs to Look For

Seq Scan on a large table — almost always means a missing index on the filter column.
High Rows Removed by Filter — large ratio of rows read to rows kept. An index on the filter column would prevent this.
Nested Loop with a large outer side — the SQL-level manifestation of N+1. The inner side is queried once per outer row.
Sort on an un-indexed column — if you order by this column frequently, add an index.

Adding the Right Index

Once you have identified a missing index from the query plan, adding it in Django is straightforward:

# models.py
class Order(models.Model):
    user   = models.ForeignKey(settings.AUTH_USER_MODEL, ...)
    status = models.CharField(max_length=20, ...)

    class Meta:
        indexes = [
            # Composite index: supports queries filtering on both columns
            # Also supports queries on 'status' alone (leftmost prefix rule)
            models.Index(fields=['status', 'user'], name='order_status_user_idx'),

            # Partial index: only index active orders
            # Smaller, faster, more selective than a full-table index
            models.Index(
                fields=['user', 'created_at'],
                condition=Q(status__in=['pending', 'paid']),
                name='order_active_user_created_idx',
            ),
        ]

Building the Habit

The habit worth building: after you write any query that will be called frequently in production, run it through EXPLAIN ANALYZE in the shell. Look for Seq Scans on large tables. Look at the Rows Removed by Filter ratio. Look at the actual time.
This takes two minutes. It catches the performance problems that will take two hours to diagnose in production after users start complaining. The two-minute habit is always worth it.

✓ Use django-debug-toolbar for everyday development: For development workflow, django-debug-toolbar's SQL panel gives you query counts and execution times on every page load without going to the shell. Reserve EXPLAIN ANALYZE for queries that the toolbar has flagged as slow or that appear suspiciously frequently.

Database performance is not a black art. It is a skill built on a small set of fundamentals: understanding what EXPLAIN ANALYZE tells you, knowing when a Seq Scan is a problem, understanding index selection, and measuring before optimizing. EXPLAIN ANALYZE is where all of that starts.

Found this useful? There’s a full book. This article is drawn from Professional Django Engineering (Chapter 7 — Database Performance). The book covers 16 chapters across every major aspect of production Django development: architecture, ORM performance, REST APIs, security, testing, caching, async, and deployment. Every chapter follows the same pattern: real anti-patterns, professional solutions, and a pitfall reference table you can bookmark. ▶ Available on Amazon KDP. Link in comments.

The N+1 Query Problem That's Silently Slowing Your Django App

Houssem Reggai — Fri, 24 Apr 2026 18:37:38 +0000

PROFESSIONAL DJANGO ENGINEERING SERIES #5

100 orders. A loop. A template that accesses order.user.email. Result: 701 database queries. Here is how it happens — and how to fix it in one line.

The N+1 query problem is the most common performance issue in Django applications. It is also the most invisible one in development, because your local database has twenty records. It only becomes visible in production, where it has twenty thousand — and by then, it is an incident.

The ORM does not hide SQL from you. It writes SQL for you. Understanding what SQL it writes — and why — is what separates ORM users from ORM professionals.

How N+1 Happens

Here is a view that looks perfectly innocent:

# views.py — looks clean, causes disaster at scale
def order_list(request):
    orders = Order.objects.all()  # Query 1: SELECT * FROM orders
    return render(request, 'orders/list.html', {'orders': orders})

Then in the template:

{# orders/list.html #}
{% for order in orders %}
    {{ order.user.email }}      {# Query 2,3,...N: SELECT user WHERE id=? #}
    {% for item in order.items.all %}
        {{ item.product.name }} {# Query N+1, N+2... for each item #}
    {% endfor %}
{% endfor %}

For 100 orders with 5 items each, this template fires:

1 query to fetch all orders
100 queries to fetch each order's user
100 queries to fetch each order's items
500 queries to fetch each item's product — total: 701 queries

Every page load. Every visitor. The database CPU climbs. Response times degrade. And because it works fine locally with your 10 test records, no one notices until production slows to a crawl.

The Fix: `select_related` and `prefetch_related`

Django provides two tools for solving N+1, and using the right one matters.

`select_related` — for `ForeignKey` and `OneToOne`

Use select_related when traversing ForeignKey or OneToOneField relationships. It generates a SQL JOIN and fetches everything in one query:

# BAD: 1 + N queries
orders = Order.objects.all()

# GOOD: 1 query with a JOIN
orders = Order.objects.select_related('user', 'shipping_address')

# Multi-level: traverse FK chains
orders = Order.objects.select_related('user__profile')

`prefetch_related` — for reverse FK and `ManyToMany`

Use prefetch_related for reverse ForeignKey relationships and ManyToManyFields — relationships where the related object is a collection. It executes a separate query per relationship and joins the results in Python:

# BAD: 1 query for orders + N queries for items + N*M for products
orders = Order.objects.all()

# GOOD: 3 queries regardless of order count
# Query 1: SELECT * FROM orders
# Query 2: SELECT * FROM order_items WHERE order_id IN (...)
# Query 3: SELECT * FROM products WHERE id IN (...)
orders = Order.objects.prefetch_related('items__product')

# Combine both for the full solution:
orders = (
    Order.objects
    .select_related('user', 'shipping_address')
    .prefetch_related('items__product')
    .filter(status='paid')
    .order_by('-created_at')
)

⚠ A common mistake that defeats prefetch_related
Filtering a prefetched relation inside a loop re-fires a query per object and completely defeats the prefetch. This is the trap:

for order in orders:  # prefetched
    active_items = order.items.filter(is_active=True)  # NEW query each time!

Fix: use a Prefetch object with a custom queryset to apply the filter at prefetch time.

How to Detect N+1: `django-debug-toolbar`

Install django-debug-toolbar in your development environment and make the SQL panel part of your workflow. It shows every query executed during a request, the time each took, and whether any are duplicates.

# requirements/local.txt
django-debug-toolbar==4.3.0

# config/settings/local.py
INSTALLED_APPS += ['debug_toolbar']
MIDDLEWARE.insert(1, 'debug_toolbar.middleware.DebugToolbarMiddleware')
INTERNAL_IPS = ['127.0.0.1']

A healthy page has under 10 queries. A page with 50+ has an N+1 problem. Treat the SQL panel as a mandatory check before every feature is considered done.

Lock it in with Query Count Tests

The best way to prevent N+1 regressions is to assert query counts in your test suite:

from django.test import TestCase

class OrderListViewTest(TestCase):
    def test_query_count_is_bounded(self):
        user = UserFactory()
        OrderFactory.create_batch(20, user=user)

        self.client.force_login(user)
        with self.assertNumQueries(3):  # orders + users + items
            response = self.client.get('/orders/')

        self.assertEqual(response.status_code, 200)

This test will fail the moment someone adds a line to the view that introduces an N+1. That failure, caught in CI before it reaches production, is exactly what the test is for.

The N+1 problem is not unique to Django — it appears in every ORM-based framework. But Django's ORM makes it particularly invisible because querysets are lazy and the query only fires at iteration time, often deep in a template. select_related and prefetch_related are the tools designed to solve it. Learn to reach for them automatically whenever you access a related object.

null=True on CharField Is Always Wrong — Here Is Why

Houssem Reggai — Wed, 22 Apr 2026 11:37:23 +0000

PROFESSIONAL DJANGO ENGINEERING SERIES #4

Two ways to represent 'no value' means every query that checks for empty strings has to handle both. The rule is simple once you know it.

Django provides two separate flags for handling empty values on model fields. They are frequently confused, and conflating them leads to subtle bugs, inconsistent data, and queries that are harder to write than they should be.

Here is the rule stated plainly, and then the reasoning behind it.

null=True is a database directive. blank=True is a validation directive. They are independent. Think about each one separately for every field you define.

The Rule

# String-based fields (CharField, TextField, EmailField, SlugField, URLField)
# ─────────────────────────────────────────────────────────────────────
# Required field:
name = models.CharField(max_length=100)

# Optional field — use blank=True ONLY. Never null=True.
nickname = models.CharField(max_length=100, blank=True)

# WRONG: creates two possible 'empty' values for a string field
nickname = models.CharField(max_length=100, null=True, blank=True)  # BAD

# Non-string fields (IntegerField, DateField, ForeignKey, DecimalField)
# ─────────────────────────────────────────────────────────────────────
# Optional non-string: use null=True. Add blank=True if used in forms.
date_of_birth = models.DateField(null=True, blank=True)
manager = models.ForeignKey(
    settings.AUTH_USER_MODEL,
    null=True, blank=True,
    on_delete=models.SET_NULL,
)

# BooleanField: never null=True unless you genuinely need three states
is_active   = models.BooleanField(default=True)   # correct
is_verified = models.BooleanField(default=False)  # correct

Why null=True on CharField Causes Problems

When you set null=True on a string field, your database can now store two different representations of ‘no value’: the empty string '' and NULL. This forces every query that checks for an empty value to handle both cases:

# With null=True on CharField, you need this everywhere:
User.objects.filter(Q(nickname='') | Q(nickname__isnull=True))

# Without null=True, this simple query is correct and complete:
User.objects.filter(nickname='')

# Or using the cleaner Django convention for 'has a nickname':
User.objects.exclude(nickname='')

Django’s own convention for optional string fields is to store '' for ‘no value’, giving you a single canonical empty representation. null=True creates ambiguity that has to be accounted for in every query, every form, every comparison, and every piece of code that displays or validates the field.

The Full Decision Table

# FIELD TYPE                | REQUIRED           | OPTIONAL
# ─────────────────────────────────────────────────────────────
# CharField / TextField     | (no flags)         | blank=True
# EmailField / SlugField    | (no flags)         | blank=True
# IntegerField              | (no flags)         | null=True, blank=True
# DecimalField              | (no flags)         | null=True, blank=True
# DateField / DateTimeField | (no flags)         | null=True, blank=True
# ForeignKey                | (no flags)         | null=True, blank=True
# OneToOneField             | (no flags)         | null=True, blank=True
# BooleanField              | default=True/False | (no flags, use default)
# JSONField                 | default=dict/list  | blank=True (or null=True)
# ImageField / FileField    | (no flags)         | blank=True

Two More Field Type Mistakes Worth Noting

Never use FloatField for money

Floating point arithmetic is imprecise. 0.1 + 0.2 in Python is not 0.3. For monetary values, always use DecimalField(max_digits=10, decimal_places=2). Or store integer cents: price_cents = models.PositiveIntegerField(). Never use FloatField or CharField for money.

Use TextChoices instead of integer status codes

# BAD: magic integers with no context
class Order(models.Model):
    STATUS_PENDING = 1
    status = models.IntegerField(default=1)

# GOOD: self-documenting, validated, admin-friendly
class Order(models.Model):
    class Status(models.TextChoices):
        PENDING  = 'pending',  'Pending'
        PAID     = 'paid',     'Paid'
        SHIPPED  = 'shipped',  'Shipped'

    status = models.CharField(
        max_length=20,
        choices=Status.choices,
        default=Status.PENDING,
    )

# Your database rows are now self-documenting.
# A raw SQL query shows 'paid', not '2'.
# Invalid values are rejected at the model level.

Field design decisions are among the most expensive to change once a table has data in it. Getting them right at the start — following the null/blank rule, using DecimalField for money, using TextChoices for enumerables — is one of the highest-leverage habits a Django developer can build.

The Custom User Model Mistake 90% of Django Projects Make

Houssem Reggai — Fri, 17 Apr 2026 17:54:09 +0000

PROFESSIONAL DJANGO ENGINEERING SERIES #3

Change your user model after the first migration and you will spend a painful day fixing it. Here is what to do instead — before your first commit.

This is the single piece of Django advice that appears in the official documentation, in every serious Django resource, and from every experienced Django developer who has ever ignored it on an early project and paid the price: create a custom user model before your first migration.

If you are starting a new project today, this article will save you hours. If you are working on an existing project that uses the default user model, this article will help you understand exactly what you are dealing with.

The best time to create a custom user model was before your first commit. The second best time is right now, before you run makemigrations for the first time.

Why the Default User Model Is a Problem?

Django’s default auth.User model makes decisions for you: username is the primary identifier, the field names are fixed, and the model lives in Django’s own package where you cannot modify it. The most common pain point:

Most modern applications want email as the login identifier. The default model has both a username field and an email field, and uses username for authentication. Working around this requires a custom authentication backend — possible, but inelegant.
Every field you want to add to the user (bio, avatar, preferences, organisation) requires either a separate Profile model (an extra database join on every user access) or monkey-patching (an anti-pattern).
Once you have migrations that reference auth.User, changing to a custom model requires either a fresh database or a complex, risky surgical migration.

`AbstractUser` vs `AbstractBaseUser` — Which to Choose

`AbstractUser`: extend the default behaviour

If you are happy with Django’s authentication behaviour and just want to add fields, inherit from AbstractUser. You get everything Django provides, plus the ability to add your own fields:

# apps/users/models.py
from django.contrib.auth.models import AbstractUser
from django.db import models

class User(AbstractUser):
    """
    Custom user model. Add project-specific fields here.
    Even if you add nothing now, this gives you flexibility later.
    """
    bio = models.TextField(blank=True)
    avatar = models.ImageField(upload_to='avatars/', blank=True, null=True)

    def __str__(self):
        return self.email

`AbstractBaseUser`: full control

If you need fundamentally different logic like authentication, inherit from AbstractBaseUser. You build everything yourself, which gives full control at the cost of more setup.

Email-as-username

If you want to create email-based-authentication system (instead of the default username) it's achievable with both AbstractBaseUser and AbstractUser:

# apps/users/managers.py — email-as-username pattern
from django.contrib.auth.hashers import make_password
from django.contrib.auth.models import UserManager
from django.utils.translation import gettext_lazy as _

class EmailBasedUserManager(UserManager):
    """
    Custom user model manager where email is the unique identifier
    for authentication instead of username.
    """

    def create_user(self, email, password, **extra_fields):
        """
        create and save new user with the given email and password
        """
        if not email:
            raise ValueError(_("Email must be set"))
        email = self.normalize_email(email)
        user = self.model(email=email, **extra_fields)
        user.password = make_password(password)
        user.save(using=self._db)
        return user

    def create_superuser(self, email, password, **extra_fields):
        """
        create and save new superuser with the given email and password
        """
        extra_fields.setdefault("is_staff", True)
        extra_fields.setdefault("is_superuser", True)
        extra_fields.setdefault("is_active", True)

        if extra_fields.get("is_staff") is not True:
            raise ValueError(_("Superuser must have is_staff=True."))
        if extra_fields.get("is_superuser") is not True:
            raise ValueError(_("Superuser must have is_superuser=True."))
        return self.create_user(email, password, **extra_fields)

then in models.py:

# apps/users/models.py — email-as-username pattern
# using AbstractUser
from django.contrib.auth.models import AbstractUser
from .managers import EmailBasedUserManager


class User(AbstractUser):
    username    = None
    email       = models.EmailField(unique=True)
    first_name  = models.CharField(max_length=150, blank=True)
    last_name   = models.CharField(max_length=150, blank=True)
    is_active   = models.BooleanField(default=True)
    is_staff    = models.BooleanField(default=False)
    date_joined = models.DateTimeField(auto_now_add=True)

    USERNAME_FIELD  = 'email'   # email is the login identifier
    REQUIRED_FIELDS = []        # email is already required via USERNAME_FIELD

    objects = EmailBasedUserManager()

The Three Things You Must Do

# config/settings/base.py
AUTH_USER_MODEL = 'users.User'

# This one line must be in place BEFORE running the very first makemigrations.
# Everything in Django resolves 'the user model' through this setting.

Reference it correctly in code

# In Python code: use get_user_model()
from django.contrib.auth import get_user_model
User = get_user_model()   # respects AUTH_USER_MODEL

# In model ForeignKey fields: use settings.AUTH_USER_MODEL
from django.conf import settings

class Order(models.Model):
    user = models.ForeignKey(
        settings.AUTH_USER_MODEL,   # string reference, not the class
        on_delete=models.CASCADE,
    )

# NEVER: from django.contrib.auth.models import User
# NEVER: from apps.users.models import User  (in ForeignKey fields)

Update the Admin When you replace the default user model, Django’s built-in UserAdmin breaks because it references the username field. Subclass it and remove the references:

# apps/users/admin.py
from django.contrib import admin
from django.contrib.auth.admin import UserAdmin as BaseUserAdmin
from .models import User

@admin.register(User)
class UserAdmin(BaseUserAdmin):
    list_display  = ('email', 'first_name', 'last_name', 'is_staff')
    search_fields = ('email', 'first_name', 'last_name')
    ordering      = ('-date_joined',)
    fieldsets = (
        (None, {'fields': ('email', 'password')}),
        ('Personal info', {'fields': ('first_name', 'last_name')}),
        ('Permissions', {'fields': ('is_active', 'is_staff', 'is_superuser',
                                    'groups', 'user_permissions')}),
    )
    add_fieldsets = (
        (None, {'classes': ('wide',), 'fields': ('email', 'password1', 'password2')}),
    )

⚠ Already past the first migration?

If your project has existing migrations that reference auth.User, you have two options. In development: drop the database, delete all migration files (not Django's own), set AUTH_USER_MODEL, and run makemigrations and migrate fresh. In production with existing data: this is a documented but complex multi-step migration that requires a maintenance window. Django's official documentation covers it, but it is a significant operation.

The lesson for every future project: AUTH_USER_MODEL before the first makemigrations.

Stop Putting Everything in settings.py

Houssem Reggai — Sun, 12 Apr 2026 17:57:56 +0000

PROFESSIONAL DJANGO ENGINEERING SERIES #2

One settings file for all environments is a production incident waiting to happen. Here is the professional split that prevents it.

Let me guess. Your settings.py has a block that checks os.environ.get('DEBUG'). It has database configuration for two different backends. It has a comment that says # only in production next to something that also runs locally. And somewhere near the top there is a SECRET_KEY that has been in version control since the project started.

This is the natural end state of a single settings file. It is not a failure of discipline, it is the predictable outcome of a structure that was never designed to handle multiple environments. Here is the fix.

The rule is simple and absolute: no secret, credential, or environment-specific value belongs in a file that is committed to version control. Ever. Without exception.

The Four-File Split

Instead of one settings.py, you maintain four files in a config/settings/ directory:
base.py — everything that is the same across all environments: installed apps, middleware, template configuration, authentication backends.

local.py — development overrides: DEBUG=True, SQLite or local Postgres, console email backend, debug toolbar.

production.py — production configuration: HTTPS enforcement, real database URL, S3 storage, structured logging.

test.py — test-specific: in-memory SQLite, MD5 password hasher for speed, local email backend.

base.py — The foundation

The base file contains configuration that never changes between environments. Crucially, it reads secrets from the environment rather than defining them inline. This is where django-environ earns its place:

# config/settings/base.py
import environ
from pathlib import Path

env = environ.Env()

BASE_DIR = Path(__file__).resolve().parent.parent.parent
sys.path.insert(0, str(BASE_DIR / 'apps'))

# Read from environment — never from the file itself
SECRET_KEY = env('DJANGO_SECRET_KEY')
ALLOWED_HOSTS = env.list('DJANGO_ALLOWED_HOSTS', default=[])

# Split INSTALLED_APPS by origin — immediately readable
DJANGO_APPS = ['django.contrib.admin', 'django.contrib.auth', ...]
THIRD_PARTY_APPS = ['rest_framework', 'celery', ...]
LOCAL_APPS = ['users', 'orders', 'products']
INSTALLED_APPS = DJANGO_APPS + THIRD_PARTY_APPS + LOCAL_APPS

AUTH_USER_MODEL = 'users.User'

local.py — Development overrides

# config/settings/local.py
from .base import *  # noqa
from .base import env

DEBUG = True
SECRET_KEY = env('DJANGO_SECRET_KEY', default='local-dev-key-not-for-production')
ALLOWED_HOSTS = ['localhost', '127.0.0.1']

DATABASES = {'default': env.db('DATABASE_URL', default='sqlite:///db.sqlite3')}

# Emails print to the console during development
EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'

# Debug toolbar
INSTALLED_APPS += ['debug_toolbar']
MIDDLEWARE.insert(1, 'debug_toolbar.middleware.DebugToolbarMiddleware')
INTERNAL_IPS = ['127.0.0.1']

production.py — Hardened for real traffic

# config/settings/production.py
from .base import *  # noqa
from .base import env

DEBUG = False
SECRET_KEY = env('DJANGO_SECRET_KEY')  # required — no default
ALLOWED_HOSTS = env.list('DJANGO_ALLOWED_HOSTS')  # required

DATABASES = {'default': env.db('DATABASE_URL')}
DATABASES['default']['CONN_MAX_AGE'] = env.int('CONN_MAX_AGE', default=60)

# HTTPS enforcement
SECURE_SSL_REDIRECT = True
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True
SECURE_HSTS_SECONDS = 31536000
SECURE_HSTS_INCLUDE_SUBDOMAINS = True
SECURE_CONTENT_TYPE_NOSNIFF = True

# Email via SMTP
EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
EMAIL_HOST = env('EMAIL_HOST')
EMAIL_HOST_PASSWORD = env('EMAIL_HOST_PASSWORD')

Secrets Management: the `.env` Pattern

In development, secrets live in a .env file in the project root. This file is in .gitignore and never committed. Instead, you commit a .env.example file with placeholder values that documents every variable the project needs:

# .env.example — commit this file
DJANGO_SECRET_KEY=your-secret-key-here
DJANGO_DEBUG=True
DJANGO_ALLOWED_HOSTS=localhost,127.0.0.1
DATABASE_URL=postgres://user:password@localhost:5432/myproject
REDIS_URL=redis://localhost:6379/0
EMAIL_HOST=smtp.example.com
EMAIL_HOST_PASSWORD=your-password-here

⚠ Your SECRET_KEY is probably in your git history

If you ever committed a real SECRET_KEY to version control, it is compromised regardless of whether you have since removed it. Git history is permanent. Generate a new key immediately using: python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"
Then rotate it in production and ensure every developer generates their own local key rather than sharing one.

One Final Step: Run the Deploy Check

Before every production deployment, run python manage.py check --deploy. Django will verify your settings against a list of known security requirements and flag anything that is misconfigured. It takes ten seconds and has caught real issues in real deployments. Make it part of your CI pipeline.

The split settings pattern is one of those changes that feels like overhead until the first time it prevents a SECRET_KEY leak, an accidental DEBUG=True in production, or an hours-long search for why the staging environment is behaving differently from production. After that, it feels obvious.

Why django-admin startproject Is a Trap

Houssem Reggai — Wed, 08 Apr 2026 20:57:36 +0000

PROFESSIONAL DJANGO ENGINEERING SERIES #1

The default layout Django hands you is a starting point. Most teams treat it as a destination.

Every Django project begins the same way. You type django-admin startproject myproject and in three seconds you have a tidy directory: settings.py, urls.py, wsgi.py. It is clean. It is simple. And for a project that will never grow beyond a prototype, it is perfectly fine.

The problem is that most projects do grow. And when they do, the default layout starts to work against you.

Project structure is not a style preference. It is a load-bearing architectural decision that determines how easily your codebase can be understood, tested, and extended by people who were not there when it was written.

The Three Ways the Default Layout Breaks Down

1. The God Settings File
The default settings.py is a single file. By the time you have added database configuration, static files, installed apps, logging, cache backends, email settings, third-party integrations, and a few environment-specific overrides, that file is six hundred lines long.
More dangerous than the length is the assumption baked in: that your local development environment and your production environment want the same configuration. They do not. The usual solution is to litter settings with conditionals:

# BAD: conditional spaghetti in settings.py
DEBUG = True

if os.environ.get('ENVIRONMENT') == 'production':
    DEBUG = False
    DATABASES = {'default': {'ENGINE': 'django.db.backends.postgresql', ...}}
else:
    DATABASES = {'default': {'ENGINE': 'django.db.backends.sqlite3', ...}}

This works. Until a developer forgets to set the environment variable and deploys debug mode to production. Until you need a staging environment. Until the nesting is three levels deep and nobody is sure which branch is actually active.

2. The Flat App Structure
startapp creates apps in the root directory alongside manage.py. For one app this is fine. For ten, it is a flat list that communicates nothing about your architecture. The deeper problem is apps that are either too large (one giant core app with every model in the project) or too small (one app per database table, with a web of circular imports connecting them).

3. The Missing Business Logic Layer
The default structure gives you models and views. It gives you no guidance on where business logic lives. The result in most codebases: it lives everywhere. Some in models, some in views, some in serializers, some in a file called helpers.py that grows to contain everything that did not fit anywhere else.

What a Professional Layout Looks Like

Here is the structure that fixes all three problems:

myproject/
    .env                      # Environment variables — never commit
    .env.example              # Template — always commit
    requirements/
        base.txt              # Shared dependencies
        local.txt             # Development only
        production.txt        # Production only
    Makefile                  # Common dev commands
    manage.py
    config/                   # Project configuration (renamed from myproject/)
        settings/
            base.py           # Shared settings
            local.py          # Development overrides
            production.py     # Production overrides
            test.py           # Test-specific settings
        urls.py
        wsgi.py
        asgi.py
    apps/                     # All Django applications
        users/
            services.py       # Business logic
            models.py
            views.py
            tests/
        orders/
        ...

Three Changes That Matter Most

1. Rename the inner directory to config/
The inner directory named after your project (myproject/myproject/) tells a new developer nothing. Renaming it config/ communicates its purpose immediately. To do this at project creation time: django-admin startproject config . — note the dot.

2. Group all apps under apps/
Add apps/ to your Python path in settings and your apps can be referenced as 'users' rather than 'apps.users'. Your project root stays clean. New developers can orient themselves in seconds.

3. Split requirements by environment
Three files, not one. local.txt starts with -r base.txt and adds django-debug-toolbar, factory-boy, pytest. production.txt adds gunicorn and sentry-sdk. Your production environment never installs your development tools.

✓ The one rule worth memorizing
The config/ directory contains project-level configuration only. The apps/ directory contains all domain code. Nothing else belongs at the project root.

The Payoff

These are not cosmetic changes. They are the decisions that determine whether, six months from now, a new developer can navigate your project in an afternoon or spend a week getting oriented. Structure is the first thing everyone inherits and the last thing anyone wants to refactor.

If you are starting a new project this week, spend the extra ten minutes getting this right. If you are inheriting an existing project, understanding why it is structured the way it is will tell you most of what you need to know about the decisions made before you arrived.