From acfc7e3a735ffa41dcd9ad7f4f8fef97c1a2c3c6 Mon Sep 17 00:00:00 2001 From: David Sanders <shang.xiao.sanders@gmail.com> Date: Fri, 15 Dec 2023 04:35:04 +1100 Subject: [PATCH] Added clarifications about the DATABASES.TIME_ZONE setting in docs. These include: - Doc'd which is the default used when DATABASES.TIME_ZONE is None. - Doc'd that the database connection's time zone setting is set for PostgreSQL and clarified that it may be necessary to set it to the same value as TIME_ZONE. Co-authored-by: David Smith <39445562+smithdc1@users.noreply.github.com> Co-authored-by: Natalia Bidart <124304+nessita@users.noreply.github.com> --- docs/ref/settings.txt | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index 2aa2beb1becf..089c8897e544 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -663,8 +663,10 @@ 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. -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 ``True``, reading datetimes from the database +returns aware datetimes with the timezone set to this option's value if not +``None``, or to UTC otherwise. + When :setting:`USE_TZ` is ``False``, it is an error to set this option. * If the database backend doesn't support time zones (e.g. SQLite, MySQL, @@ -687,13 +689,18 @@ When :setting:`USE_TZ` is ``False``, it is an error to set this option. 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. +* If the database backend supports time zones (e.g., PostgreSQL), then the + database connection's time zone is set to this value. + + Although setting the ``TIME_ZONE`` option is very rarely needed, there are + situations where it becomes necessary. Specifically, it's recommended to + match the general :setting:`TIME_ZONE` setting when dealing with raw queries + involving date/time functions like PostgreSQL's ``date_trunc()`` or + ``generate_series()``, especially when generating time-based series that + transition daylight savings. - 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. + This value can be changed at any time, the database will handle the + conversion of datetimes to the configured time zone. However, this has a downside: receiving all datetimes in local time makes datetime arithmetic more tricky — you must account for possible offset