Fixed #23524 -- Allowed DATABASES['TIME_ZONE'] option on PostgreSQL.

3 files changed, 50 insertions, 15 deletions

diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt
index 8f1de4c283..b4c190bafd 100644
--- a/docs/ref/databases.txt
+++ b/docs/ref/databases.txt
@@ -121,8 +121,11 @@ Django needs the following parameters for its database connections:
 - ``client_encoding``: ``'UTF8'``,
 - ``default_transaction_isolation``: ``'read committed'`` by default,
   or the value set in the connection options (see below),
-- ``timezone``: ``'UTC'`` when :setting:`USE_TZ` is ``True``, value of
-  :setting:`TIME_ZONE` otherwise.
+- ``timezone``:
+    - when :setting:`USE_TZ` is ``True``, ``'UTC'`` by default, or the
+      :setting:`TIME_ZONE <DATABASE-TIME_ZONE>` value set for the connection,
+    - when :setting:`USE_TZ` is ``False``, the value of the global
+      :setting:`TIME_ZONE` setting.
 
 If these parameters already have the correct values, Django won't set them for
 every new connection, which improves performance slightly. You can configure
diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index e04d211885..6c8ea9b762 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -632,23 +632,52 @@ default port. Not used with SQLite.
 
 Default: ``None``
 
-A string representing the time zone for datetimes stored in this database
-(assuming that it doesn't support time zones) or ``None``. This inner option of
-the :setting:`DATABASES` setting accepts the same values as the general
-:setting:`TIME_ZONE` setting.
+A string representing the time zone for this database connection or ``None``.
+This inner option of the :setting:`DATABASES` setting accepts the same values
+as the general :setting:`TIME_ZONE` setting.
 
-This allows interacting with third-party databases that store datetimes in
-local time rather than UTC. To avoid issues around DST changes, you shouldn't
-set this option for databases managed by Django.
+When :setting:`USE_TZ` is ``True`` and this option is set, reading datetimes
+from the database returns aware datetimes in this time zone instead of UTC.
+When :setting:`USE_TZ` is ``False``, it is an error to set this option.
 
-When :setting:`USE_TZ` is ``True`` and the database doesn't support time zones
-(e.g. SQLite, MySQL, Oracle), Django reads and writes datetimes in local time
-according to this option if it is set and in UTC if it isn't.
+* If the database backend doesn't support time zones (e.g. SQLite, MySQL,
+  Oracle), Django reads and writes datetimes in local time according to this
+  option if it is set and in UTC if it isn't.
 
-When :setting:`USE_TZ` is ``True`` and the database supports time zones (e.g.
-PostgreSQL), it is an error to set this option.
+  Changing the connection time zone changes how datetimes are read from and
+  written to the database.
 
-When :setting:`USE_TZ` is ``False``, it is an error to set this option.
+  * If Django manages the database and you don't have a strong reason to do
+    otherwise, you should leave this option unset. It's best to store datetimes
+    in UTC because it avoids ambiguous or nonexistent datetimes during daylight
+    saving time changes. Also, receiving datetimes in UTC keeps datetime
+    arithmetic simple — there's no need for the ``normalize()`` method provided
+    by pytz.
+
+  * If you're connecting to a third-party database that stores datetimes in a
+    local time rather than UTC, then you must set this option to the
+    appropriate time zone. Likewise, if Django manages the database but
+    third-party systems connect to the same database and expect to find
+    datetimes in local time, then you must set this option.
+
+* If the database backend supports time zones (e.g. PostgreSQL), the
+  ``TIME_ZONE`` option is very rarely needed. It can be changed at any time;
+  the database takes care of converting datetimes to the desired time zone.
+
+  Setting the time zone of the database connection may be useful for running
+  raw SQL queries involving date/time functions provided by the database, such
+  as ``date_trunc``, because their results depend on the time zone.
+
+  However, this has a downside: receiving all datetimes in local time makes
+  datetime arithmetic more tricky — you must call the ``normalize()`` method
+  provided by pytz after each operation.
+
+  Consider converting to local time explicitly with ``AT TIME ZONE`` in raw SQL
+  queries instead of setting the ``TIME_ZONE`` option.
+
+.. versionchanged:: 3.1
+
+  Using this option when the database backend supports time zones was allowed.
 
 .. setting:: DATABASE-DISABLE_SERVER_SIDE_CURSORS
 
diff --git a/docs/releases/3.1.txt b/docs/releases/3.1.txt
index 58f14e172d..4c8cc56797 100644
--- a/docs/releases/3.1.txt
+++ b/docs/releases/3.1.txt
@@ -283,6 +283,9 @@ Miscellaneous
   :class:`pathlib.Path` instead of :mod:`os.path` for building filesystem
   paths.
 
+* The :setting:`TIME_ZONE <DATABASE-TIME_ZONE>` setting is now allowed on
+  databases that support time zones.
+
 .. _backwards-incompatible-3.1:
 
 Backwards incompatible changes in 3.1