DEV Community: Will Poulson

Most Django Indexes Are Useless. Here’s How to Fix Them.

Will Poulson — Sun, 04 May 2025 16:19:48 +0000

TL;DR: Most Django developers rely on default indexes (like those on foreign keys), but PostgreSQL (and most RDBMSs) only uses one index per query. If you filter on multiple fields, especially together, a composite index is usually required. Index for how you query, not just how your models look.

1. What Django Gives You by Default

Django will automatically add indexes for:

Primary keys (the id field)
Foreign keys (behind the scenes with db_index=True)

It does not automatically index:

Regular fields you filter on (CharField, BooleanField, etc.)
Fields used in .order_by() or pagination
Fields used together in queries (composite indexes)

Example:

class Invoice(models.Model):
    user = models.ForeignKey(User, on_delete=models.CASCADE) # FK = auto-indexed
    created_at = models.DateTimeField()
    status = models.CharField(max_length=20) # Not indexed by default

This model will have indexes on id and user_id, but not on status.

The presence of ForeignKey fields and Django’s automatic primary keys can give a false sense of security. It’s easy to assume that if a field is indexed, the query will be fast. But indexing isn’t about whether a field can be queried — it’s about how fields are used together in your queries. Relying only on what Django gives you by default often leads to missed performance wins.

2. The More Field Indexes, the Merrier - Right?

It’s often believed that adding db_index=True to all fields you might filter on is enough. But this is where things get counterintuitive:

PostgreSQL only uses one index per table scan.

If your query filters on multiple fields, the planner won’t merge several single-column indexes. It’ll pick the one it believes is most selective and apply the other filters in memory.

Example query:

Invoice.objects.filter(user_id=1, status="paid")

Even with indexes on both user_id and status, Postgres might still do a sequential scan:

Example `.explain()` output:

Seq Scan on invoice (cost=0.00..1204.50 rows=1000 width=48)
  Filter: ((user_id = 1) AND (status = 'paid'))

This means no index was used effectively. For large tables, this becomes a performance bottleneck.

3. How to Index for Composite Queries

You need to design indexes that reflect how your data is used, not just how it’s structured.

Fixing the example:

class Meta:
    indexes = [
        models.Index(fields=["user", "status"]),
    ]

This allows Postgres to filter efficiently when both fields are queried together.

Important: Composite indexes are only used when the leading column(s) in the index are part of the query. An index on ("user", "status") will not help if you're only filtering by status. The query must include user to make use of the index.

Also note: using models.Index(fields=["field"]) provides the same underlying result as db_index=True, but it can be more readable and easier to evolve, especially if you plan to later modify or combine indexes.

4. The Trade-Offs

Indexes come with costs:

They consume disk space
They slow down writes (INSERT, UPDATE, DELETE) because each index must also be updated

Avoid blindly creating composite indexes for every possible combination of fields. Instead, focus on what's frequent, slow, or scaling poorly — and back your decisions with .explain() output and real-world usage.

Indexing is only effective when it aligns with your actual query patterns. Adding indexes for every field often leads to bloat and diminishing returns.

5. Reviewing Indexes in Practice

When reviewing model or migration PRs, we ask:

Is this field part of a common filter?
Are these fields used together in filters?
Are we paginating or sorting by this field?
Does this need a composite or partial index instead of multiple single-field ones?

A common red flag: db_index=True on three different fields — all used together — but no composite index in sight.

Good indexing is less about marking every field as "indexable" and more about being precise, intentional, and aware of how queries behave in the real world.

6. Final Thoughts

Indexes are one of the most powerful tools in your performance toolbox — but only if they’re actually used.

Don’t rely on Django’s defaults. Don’t assume that db_index=True is sufficient. And don’t expect PostgreSQL to combine indexes for you — it won’t.

Index for how your data is used, not just how it’s structured.

Why We Wrote a Code Review Guide. And What Actually Worked.

Will Poulson — Sun, 04 May 2025 16:19:29 +0000

TL;DR: We created a code review guide to align expectations, improve feedback quality, and make reviews feel collaborative instead of gatekeeping. Here’s what worked for us.

The Problem We Saw

We didn’t set out to write a code review guide to be formal or process-heavy. We wrote it because our reviews were inconsistent, unstructured, and sometimes even unhelpful. Developers weren’t sure what was expected of them when reviewing or being reviewed, and the quality of feedback varied wildly. We needed to align not just on how to review code, but on why we were doing it in the first place.

As we dug into the problem, we realized the inconsistency wasn’t just about what was being reviewed- it was also about how feedback was communicated. The way comments were delivered varied so much that it was often hard to tell the difference between a question, a suggestion, or a required change. As a result, each comment thread required extra clarification before it could be acted on, which slowed everything down.

Why We Wrote a Guide

We didn’t just want to solve tactical issues; we wanted to create a shared understanding of what a good review looked like on our team. Without that foundation, even experienced developers were operating with different assumptions.

We also saw the guide as a tool for onboarding new team members faster, reducing review friction , and building a culture where reviews were collaborative, respectful, and consistent. Instead of relying on tribal knowledge or guesswork, we wanted clear expectations that everyone could reference and evolve together.

What’s in the Guide

The guide covers both the philosophy and the practical mechanics of doing a good code review on our team.

We started with the purpose: code reviews are a way to share knowledge, ensure maintainability, and spot architectural issues early- not just to catch typos or enforce style.

From there, we broke things down into:

Reviewer responsibilities : what to look for (e.g. clarity, structure, test coverage), and what to avoid (nitpicking without context).
Author responsibilities : how to write a good PR description, how to request feedback, and how to respond to it.
Tone and communication : always assume good intent, prefer questions to demands, and don’t let disagreement become personal.
Turnaround expectations : how quickly to review, and when it’s okay to defer.
Common pitfalls : bikeshedding, “drive-by” reviews, and over-indexing on personal preference.

The idea was to make the process predictable without being rigid and to empower everyone to participate confidently, regardless of experience level.

The guide itself is a collaborative project. Anyone on the team can propose edits and contribute to it. This approach ensures the document reflects the evolving needs and insights of the team, and continues to improve over time.

Comment Prefixing: The Simple Trick That Changed Everything

To reduce ambiguity in reviews, we introduced a simple but effective prefixing system. Reviewers tag their comments with one of three labels:

REQ – A required change.
OPT – An optional suggestion.
QQ – A clarifying question.

These prefixes helped reviewers communicate intent clearly and made it easier for authors to prioritize responses. It also improved tone and reduced friction, especially in larger PRs. No tools required—just a habit that stuck.

What Actually Changed

The impact was immediate. The overall quality of reviews improved dramatically- feedback became clearer, more actionable, and more consistent. Developers no longer had to guess which comments were blocking and which were suggestions.

For PR authors, it meant faster, more confident iteration. They could quickly identify what needed to be addressed to move forward and what could be reasonably discussed or even dismissed. Reviews became less about judgment and more about collaboration.

The shift in tone also made a difference. By clearly framing feedback, discussions stayed focused and respectful. The process felt more like a conversation between peers, not an audit or gatekeeping step. It encouraged thoughtful dialogue and raised the baseline for what we expect from and contribute to every review.

Advice to Other Teams

Start small and focus on purpose over process. Agree on what a code review is for, not just how to do it. A shared document can go a long way in aligning expectations—and simple habits like prefixing comments can dramatically improve clarity and tone without adding overhead.