[Django] #37137: Replace raw SQL suggestion in TIME_ZONE docs

[Django]

#37137: Replace raw SQL suggestion in TIME_ZONE docs
-------------------------------------+-------------------------------------
Reporter: Jacob Walls | Type:
| Cleanup/optimization
Status: new | Component:
| Documentation
Version: dev | Severity: Normal
Keywords: postgresql, | Triage Stage:
timezone | Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Our docs counsel avoiding raw SQL usage where the ORM can do. We have old
advice in the `TIME_ZONE` setting advising to use "raw SQL" when local
time conversions are needed. I think instead we should suggest using a
lightweight `Func` wrapping [https://www.postgresql.org/docs/current
/functions-datetime.html#FUNCTIONS-DATETIME-
ZONECONVERT:~:text=The%20function-,timezone,-(zone%2C%20timestamp
timezone()] to accomplish the same thing:

[https://docs.djangoproject.com/en/dev/ref/settings/#:~:text=raw%20SQL
Current text]:

{{{
Consider converting to local time explicitly with ``AT TIME ZONE`` in
raw SQL
queries instead of setting the ``TIME_ZONE`` option.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/37137>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#37137: Replace raw SQL suggestion in TIME_ZONE docs
-------------------------------------+-------------------------------------

Reporter: Jacob Walls | Owner: Vishy
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: dev
Severity: Normal | Resolution:

Keywords: postgresql, | Triage Stage:
timezone | Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Vishy):

* owner: (none) => Vishy
* status: new => assigned

--
Ticket URL: <https://code.djangoproject.com/ticket/37137#comment:1>

[Django]

#37137: Replace raw SQL suggestion in TIME_ZONE docs

--------------------------------------+------------------------------------

Reporter: Jacob Walls | Owner: Vishy

Type: Cleanup/optimization | Status: assigned

Component: Documentation | Version: dev
Severity: Normal | Resolution:

Keywords: postgresql, timezone | Triage Stage: Accepted

Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

--------------------------------------+------------------------------------
Changes (by Natalia Bidart):

* stage: Unreviewed => Accepted

Comment:

Spot on Jacob, thank you! Are we targeting something like this:

{{{#!python
class TimeZone(Func):
function = "timezone"
output_field = DateTimeField()
}}}

Ideally we would also include a minimal usage example and have a cross-
reference to the `Func` docs and a note that this is PostgreSQL-specific.
--
Ticket URL: <https://code.djangoproject.com/ticket/37137#comment:2>

[Django]

#37137: Replace raw SQL suggestion in TIME_ZONE docs
--------------------------------------+------------------------------------
Reporter: Jacob Walls | Owner: Vishy
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: postgresql, timezone | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------

Comment (by Jacob Walls):

Exactly, assuming a contributor validates that it works. The context for
this remark about the setting is postgres-specific anyway, but totally
agree about mentioning the snippet is PostgreSQL-specific.
--
Ticket URL: <https://code.djangoproject.com/ticket/37137#comment:3>

[Django]

#37137: Replace raw SQL suggestion in TIME_ZONE docs
--------------------------------------+------------------------------------
Reporter: Jacob Walls | Owner: Vishy
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: postgresql, timezone | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------

Changes (by Vishy):

* has_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/37137#comment:4>