Django 6.1 release notes - UNDER DEVELOPMENT¶

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.

• The DatabaseIntrospection.get_relations() should now return a dictionary with 3-tuples containing (field_name_other_table, other_table, db_on_delete) as values. db_on_delete is one of the database-level delete options e.g. DB_CASCADE.

django.contrib.gis¶

• Support for PostGIS 3.1 is removed.

• Support for GEOS 3.8 is removed.

• Support for GDAL 3.1 and 3.2 is removed.

django.contrib.postgres¶

• Top-level elements set to None in an ArrayField with a JSONField base field are now saved as SQL NULL instead of the JSON null primitive. This matches the behavior of a standalone JSONField when storing None values.

System checks¶

• The check management command now supplies all databases if not specified. Callers should be prepared for databases to be accessed.

Dropped support for PostgreSQL 14¶

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

Dropped support for MySQL < 8.4¶

Upstream support for MySQL 8.0 ends in April 2026, and MySQL 8.1-8.3 are short-term innovation releases. Django 6.1 supports MySQL 8.4 and higher.

Miscellaneous¶

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

• The minimum supported version of SQLite is increased from 3.31.0 to 3.37.0.

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).

• The use of None to represent a top-level JSON scalar null when querying JSONField is now deprecated in favor of the new JSONNull expression. At the end of the deprecation period, None values compile to SQL IS NULL when used as the top-level value. Key and index lookups are unaffected by this deprecation.