Django 2.2 release notes¶
April 1, 2019
Welcome to Django 2.2!
These release notes cover the new features, as well as some backwards incompatible changes you’ll want to be aware of when upgrading from Django 2.1 or earlier. We’ve begun the deprecation process for some features.
See the Upgrading Django to a newer version guide if you’re updating an existing project.
Django 2.2 is designated as a long-term support release. It will receive security updates for at least three years after its release. Support for the previous LTS, Django 1.11, will end in April 2020.
Django 2.2 supports Python 3.5, 3.6, 3.7, and 3.8 (as of 2.2.8). We highly recommend and only officially support the latest release of each series.
What’s new in Django 2.2¶
HttpRequestis now passed as the first positional argument to
RemoteUserBackend.configure_user(), if it accepts it.
- The new
StringAggdetermines the ordering of the aggregated elements.
- The new
SpGistIndexclasses allow creating
SP-GiSTindexes in the database.
BrinIndexnow has the
- The new
SearchQueryallows searching for a phrase or raw expression.
- Added path matching to the
collectstatic --ignoreoption so that patterns like
/vendor/*.jscan be used.
- Added support and translations for the Armenian language.
- The new
--force-coloroption forces colorization of the command output.
inspectdbnow creates models for foreign tables on PostgreSQL.
inspectdb --include-viewsnow creates models for materialized views on Oracle and PostgreSQL.
- The new
inspectdb --include-partitionsoption allows creating models for partition tables on PostgreSQL. In older versions, models are created child tables instead the parent.
DurationFieldfor Oracle and PostgreSQL, and
- On Oracle,
dbshellis wrapped with
rlwrap, if available.
rlwrapprovides a command history and editing of keyboard input.
- The new
makemigrations --no-headeroption avoids writing header comments in generated migration file(s). This option is also available for
runservercan now use Watchman to improve the performance of watching a large number of files for changes.
- Added support for PostgreSQL operator classes (
- Added support for partial indexes (
- Added the
Reversedatabase functions, as well as many math database functions.
- Setting the new
Truetells the database to ignore failure to insert rows that fail uniqueness constraints or other checks.
- The new
ExtractIsoYearfunction extracts ISO-8601 week-numbering years from
DateTimeField, and the new
iso_yearlookup allows querying by an ISO-8601 week-numbering year.
- The new
QuerySet.bulk_update()method allows efficiently updating specific fields on multiple model instances.
- Django no longer always starts a transaction when a single query is being
performed, such as
Model.delete(). This improves the performance of autocommit by reducing the number of database round trips.
- Added SQLite support for the
- The handling of
DISTINCTaggregation is added to the
allow_distinct = Trueas a class attribute on
Aggregatesubclasses allows a
distinctkeyword argument to be specified on initialization to ensure that the aggregate function is only called for each distinct value of
update_or_create()methods are now allowed on many-to-many relationships with intermediate models. The new
through_defaultsargument is used to specify values for new intermediate model instance(s).
- The new
SimpleTestCase.assertURLEqual()assertion checks for a given URL, ignoring the ordering of the query string.
assertRedirects()uses the new assertion.
- The test
Clientnow supports automatic JSON serialization of list and tuple
- The new
ORACLE_MANAGED_FILEStest database setting allows using Oracle Managed Files (OMF) tablespaces.
- Deferrable database constraints are now checked at the end of each
TestCasetest on SQLite 3.20+, just like on other backends that support deferrable constraints. These checks aren’t implemented for older versions of SQLite because they would require expensive table introspection there.
DiscoverRunnernow skips the setup of databases not referenced by tests.
Backwards incompatible changes in 2.2¶
Database backend API¶
This section describes changes that may be needed in third-party database backends.
- Third-party database backends must implement support for table check
constraints or set
- Third party database backends must implement support for ignoring
constraints or uniqueness errors while inserting or set
- Third party database backends must implement introspection for
DatabaseFeatures.uses_savepointsnow defaults to
- Third party database backends must implement support for partial indexes or
column_name_converter()are removed. Third party database backends may need to instead implement
DatabaseIntrospection.identifier_converter(). In that case, the constraint names that
DatabaseIntrospection.get_constraints()returns must be normalized by
- SQL generation for indexes is moved from
SchemaEditormethods are added:
_delete_index_sql()(to pair with
_delete_unique_sql(to pair with
_delete_fk_sql()(to pair with
- The third argument of
allow_thread_sharing, is removed.
Admin actions are no longer collected from base
For example, in older versions of Django:
from django.contrib import admin class BaseAdmin(admin.ModelAdmin): actions = ['a'] class SubAdmin(BaseAdmin): actions = ['b']
SubAdmin would have actions
actions follows standard Python inheritance. To get the same result as
class SubAdmin(BaseAdmin): actions = BaseAdmin.actions + ['b']
TransactionTestCase serialized data loading¶
Initial data migrations are now loaded in
TransactionTestCase at the end of the test, after the
database flush. In older versions, this data was loaded at the beginning of the
test, but this prevents the
test --keepdb option from working
properly (the database was empty at the end of the whole test suite). This
change shouldn’t have an impact on your tests unless you’ve customized
sqlparse is required dependency¶
To simplify a few parts of Django’s database handling, sqlparse is now a required dependency. It’s automatically installed along with Django.
In usage like:
from django.utils.functional import cached_property class A: @cached_property def base(self): return ... alias = base
alias is not cached. Where the problem can be detected (Python 3.6 and
later), such usage now raises
TypeError: Cannot assign the same
cached_property to two different names ('base' and 'alias').
Use this instead:
import operator class A: ... alias = property(operator.attrgetter('base'))
Permissions for proxy models¶
Permissions for proxy models are now
created using the content type of the proxy model rather than the content type
of the concrete model. A migration will update existing permissions when you
In the admin, the change is transparent for proxy models having the same
app_label as their concrete model. However, in older versions, users with
permissions for a proxy model with a different
app_label than its
concrete model couldn’t access the model in the admin. That’s now fixed, but
you might want to audit the permissions assignments for such proxy models
[add|view|change|delete]_myproxy) prior to upgrading to ensure the new
access is appropriate.
Finally, proxy model permission strings must be updated to use their own
app_label. For example, for
app.MyProxyModel inheriting from
Merging of form
Media assets are now merged using a topological sort algorithm, as the
old pairwise merging algorithm is insufficient for some cases. CSS and
incorrectly (where the old algorithm produced results correctly by
Media classes for any missing dependencies. For example,
widgets depending on
django.jQuery must specify
js=['admin/js/jquery.init.js', ...] when declaring form media assets.
- To improve readability, the
UUIDFieldform field now displays values with dashes, e.g.
- On SQLite,
PositiveSmallIntegerFieldnow include a check constraint to prevent negative values in the database. If you have existing invalid data and run a migration that recreates a table, you’ll see
CHECK constraint failed.
- For consistency with WSGI servers, the test client now sets the
Content-Lengthheader to a string rather than an integer.
- The return value of
django.utils.text.slugify()is no longer marked as HTML safe.
- The default truncation character used by the
truncatewords_htmltemplate filters is now the real ellipsis character (
…) instead of 3 dots. You may have to adapt some test output comparisons.
- Support for bytestring paths in the template filesystem loader is removed.
django.utils.http.urlsafe_base64_encode()now returns a string instead of a bytestring, and
django.utils.http.urlsafe_base64_decode()may no longer be passed a bytestring.
- Support for
cx_Oracle< 6.0 is removed.
- The minimum supported version of
mysqlclientis increased from 1.3.7 to 1.3.13.
- The minimum supported version of SQLite is increased from 3.7.15 to 3.8.3.
- In an attempt to provide more semantic query data,
3. For backwards compatibility, the old values are still accepted as data.
max_lengthis increased from 80 to 150 characters.
- Tests that violate deferrable database constraints now error when run on SQLite 3.20+, just like on other backends that support such constraints.
- To catch usage mistakes, the test
Noneis passed as a value to encode because
Nonecan’t be encoded in GET and POST data. Either pass an empty string or omit the value.
ping_googlemanagement command now defaults to
httpfor the sitemap’s URL. If your site uses http, use the new
ping_google --sitemap-uses-httpoption. If you use the
ping_google()function, set the new
runserverno longer supports pyinotify (replaced by Watchman).
Varianceaggregate functions now return a
Decimalinstead of a
floatwhen the input is
- Tests will fail on SQLite if apps without migrations have relations to apps
with migrations. This has been a documented restriction since migrations were
added in Django 1.7, but it fails more reliably now. You’ll see tests failing
with errors like
no such table: <app_label>_<model>. This was observed with several third-party apps that had models in tests without migrations. You must add migrations for such models.
Features deprecated in 2.2¶
Meta.ordering will no longer affect
GROUP BY queries¶
GROUP BY queries (such as
.annotate().values()) is a common source of confusion. Such queries now
issue a deprecation warning with the advice to add an
order_by() to retain
the current query.
Meta.ordering will be ignored in such queries starting
in Django 3.1.
django.utils.timezone.FixedOffsetis deprecated in favor of
- The undocumented
FloatRangeFieldmodel and form fields in
django.contrib.postgresare deprecated in favor of a new name,
DecimalRangeField, to match the underlying
numrangedata type used in the database.
FILE_CHARSETsetting is deprecated. Starting with Django 3.1, files read from disk must be UTF-8 encoded.
django.contrib.staticfiles.storage.CachedStaticFilesStorageis deprecated due to the intractable problems that it has. Use
ManifestStaticFilesStorageor a third-party cloud storage instead.
RemoteUserBackend.configure_user()is now passed
requestas the first positional argument, if it accepts it. Support for overrides that don’t accept it will be removed in Django 3.1.
TestCase.multi_dbattributes are deprecated in favor of
TestCase.databases. These new attributes allow databases dependencies to be declared in order to prevent unexpected queries against non-default databases to leak state between tests. The previous behavior of
multi_db=Truecan be achieved by setting