Correct TIME_ZONE setting reference in time zone topic.

[Josh Smeaton]

​https://docs.djangoproject.com/en/4.2/topics/i18n/timezones/#postgresql

The PostgreSQL backend stores datetimes as timestamp with time zone. In practice, this means it converts datetimes from the connection’s time zone to UTC on storage, and from UTC to the connection’s time zone on retrieval.

This wording seems to suggest that Django DateTimeField will return datetimes with the tzinfo set to settings.TIME_ZONE, but that's not what I observe. All data returned is in utc.

Am I mistaking the blurb on the timezone support docs?

​https://github.com/django/django/blob/f5ed4306bbfd2e5543dd02cf5a22326a29253cdf/django/db/models/fields/__init__.py#L1594 defines a to_python which will make a datetime aware, but that's only used by the serialization framework.

I would expect a from_db_value to convert the returned value from utc to the timezone defined by settings.TIME_ZONE.

[Mariusz Felisiak]

This is not a strict duplicate of #21214, but the discussion there should shed some light on the current behavior.

[Josh Smeaton]

Thank you!

I think the docs are ambiguous. It sounds like the configured time zone will be used for the connection from the docs I linked, but in practice the connection uses UTC unless a query is executed on the session? Or is there another connection parameter that controls the session timezone?

Might be worth a docs update to clarify the current behaviour?

[Mariusz Felisiak]

Replying to Josh Smeaton:

Thank you!

I think the docs are ambiguous. It sounds like the configured time zone will be used for the connection from the docs I linked, but in practice the connection uses UTC unless a query is executed on the session? Or is there another connection parameter that controls the session timezone?

Might be worth a docs update to clarify the current behaviour?

Doc clarifications are always welcome. I hope that Aymeric will chime in ;)

[Josh Smeaton]

The database connection settings have their own TIME_ZONE setting: ​https://docs.djangoproject.com/en/5.0/ref/settings/#time-zone, which is what the previous docs I was referring to must have been referencing: ​https://docs.djangoproject.com/en/4.2/topics/i18n/timezones/#postgresql

It makes sense to me now.

[Natalia Bidart]

Replying to Josh Smeaton:

The database connection settings have their own TIME_ZONE setting: ​https://docs.djangoproject.com/en/5.0/ref/settings/#time-zone, which is what the previous docs I was referring to must have been referencing: ​https://docs.djangoproject.com/en/4.2/topics/i18n/timezones/#postgresql

It makes sense to me now.

Amazing, thank you for letting us know. Do you think the first docs you read still need adjustment? I'm thinking that the TIME_ZONE setting link in the paragraph would be better pointed to this instead: ​https://docs.djangoproject.com/en/dev/ref/settings/#time-zone

[Mariusz Felisiak]

Replying to Josh Smeaton:

The database connection settings have their own TIME_ZONE setting: ​https://docs.djangoproject.com/en/5.0/ref/settings/#time-zone, which is what the previous docs I was referring to must have been referencing: ​https://docs.djangoproject.com/en/4.2/topics/i18n/timezones/#postgresql

It makes sense to me now.

Thanks Josh. Assigned to you, I hope you don't mind fixing it ;)

[Josh Smeaton]

​https://github.com/django/django/pull/17938

[Mariusz Felisiak <felisiak.mariusz@…>]

In 6e195b8:

Fixed #35267 -- Clarified time zone topic for PostgreSQL in docs.

The timezone documentation for Postgres mentions the behavior of
time zone conversion, but links to the wrong setting that controls the
behavior.

Postgres will not return datetimes in the time zone set by the
TIME_ZONE setting, but rather the time zone of the database connection,
which is defined by DATABASES.TIME_ZONE setting falling back to UTC.

This corrects the link in the documentation and adds note that there
are two distinct TIME_ZONE settings and the one most are familiar with
is not considered for PostgreSQL time zone conversion.

[Mariusz Felisiak <felisiak.mariusz@…>]

In e45ee72:

[5.0.x] Fixed #35267 -- Clarified time zone topic for PostgreSQL in docs.

The timezone documentation for Postgres mentions the behavior of
time zone conversion, but links to the wrong setting that controls the
behavior.

Postgres will not return datetimes in the time zone set by the
TIME_ZONE setting, but rather the time zone of the database connection,
which is defined by DATABASES.TIME_ZONE setting falling back to UTC.

This corrects the link in the documentation and adds note that there
are two distinct TIME_ZONE settings and the one most are familiar with
is not considered for PostgreSQL time zone conversion.

Backport of 6e195b800aed7d6a0d2a4c073d8f3507f6beb126 from main