Opened 3 weeks ago

Last modified 8 days ago

#37137 assigned Cleanup/optimization

Replace raw SQL suggestion in TIME_ZONE docs

Reported by: Jacob Walls Owned by: Vishy
Component: Documentation Version: dev
Severity: Normal Keywords: postgresql, timezone
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

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 timezone() to accomplish the same thing:

Current text:

  Consider converting to local time explicitly with ``AT TIME ZONE`` in raw SQL
  queries instead of setting the ``TIME_ZONE`` option.

Change History (4)

comment:1 by Vishy, 3 weeks ago

Owner: set to Vishy
Status: newassigned

comment:2 by Natalia Bidart, 3 weeks ago

Triage Stage: UnreviewedAccepted

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

    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.

comment:3 by Jacob Walls, 3 weeks ago

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.

comment:4 by Vishy, 8 days ago

Has patch: set
Note: See TracTickets for help on using tickets.
Back to Top