Model field fetch modes¶

The on-demand fetching behavior of model fields is now configurable with fetch modes. These modes allow you to control how Django fetches data from the database when an unfetched field is accessed.

Django provides three fetch modes:

1. FETCH_ONE, the default, fetches the missing field for the current instance only. This mode represents Django’s existing behavior.

2. FETCH_PEERS fetches a missing field for all instances that came from the same QuerySet.

   This mode works like an on-demand prefetch_related(). It can reduce most cases of the “N+1 queries problem” to two queries without any work to maintain a list of fields to prefetch.

3. RAISE raises a FieldFetchBlocked exception.

   This mode can prevent unintentional queries in performance-critical sections of code.

Use the new method QuerySet.fetch_mode() to set the fetch mode for model instances fetched by the QuerySet:

from django.db import models

books = Book.objects.fetch_mode(models.FETCH_PEERS)
for book in books:
    print(book.author.name)

Despite the loop accessing the author foreign key on each instance, the FETCH_PEERS fetch mode will make the above example perform only two queries:

1. Fetch all books.

2. Fetch associated authors.

See fetch modes for more details.

Database-level delete options for ForeignKey.on_delete¶

ForeignKey.on_delete now supports database-level delete options:

• DB_CASCADE

• DB_SET_NULL

• DB_SET_DEFAULT

These options handle deletion logic entirely within the database, using the SQL ON DELETE clause. They are thus more efficient than the existing Python-level options, as Django does not need to load objects before deleting them. As a consequence, the DB_CASCADE option does not trigger the pre_delete or post_delete signals.

Minor features¶

Database backend API¶

This section describes changes that may be needed in third-party database backends.

• The DatabaseOperations.adapt_durationfield_value() hook is added. If the database has native support for DurationField, override this method to simply return the value.

django.contrib.gis¶

• Support for PostGIS 3.1 is removed.

Dropped support for PostgreSQL 14¶

Upstream support for PostgreSQL 14 ends in November 2026. Django 6.1 supports PostgreSQL 15 and higher.

Miscellaneous¶

• GenericForeignKey now uses a separate descriptor class: the private GenericForeignKeyDescriptor.

Miscellaneous¶

• Calling QuerySet.values_list() with flat=True and no field name is deprecated. Pass an explicit field name, like values_list("pk", flat=True).