From: PG Doc comments form <noreply@postgresql.org>
To: pgsql-docs@lists.postgresql.org
Cc: philippe.godfrin@nov.com
Subject: set time zone
Date: Tue, 07 Dec 2021 14:28:09 +0000
Message-ID: <163888728952.1269.5167822676466793158@wrigleys.postgresql.org> (raw)
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/13/sql-set.html
Description:
Documentation for the set time zone command can be clearer. What it says for
v13:
TIME ZONE
SET TIME ZONE value is an alias for SET timezone TO value. The syntax SET
TIME ZONE allows special syntax for the time zone specification. Here are
examples of valid values:
'PST8PDT'
The time zone for Berkeley, California.
<snip>
See Section 8.5.3 for more information about time zones.
Issue #1.
There is an example of 'PST8PDT' but there is no explanation as to how to
build that string to set the time zone. If you follow the recommendation to
see Section 8.5.3, you encounter Issue #2...
Issue #2.
Yes you can find more information about time zones in section 8.5.3, but you
have to read carefully for this paragraph in Section 8.5.3, which explains
how NOT to set the Time Zone
A time zone abbreviation, for example PST. Such a specification merely
defines a particular offset from UTC, in contrast to full time zone names
which can imply a set of daylight savings transition rules as well. The
recognized abbreviations are listed in the pg_timezone_abbrevs view (see
Section 51.91). You cannot set the configuration parameters TimeZone or
log_timezone to a time zone abbreviation, but you can use abbreviations in
date/time input values and with the AT TIME ZONE operator.
However the prior paragraph says this:
A full time zone name, for example America/New_York. The recognized time
zone names are listed in the pg_timezone_names view (see Section 51.92).
PostgreSQL uses the widely-used IANA time zone data for this purpose, so the
same time zone names are also recognized by other software.
This is where you can find the correct name to use in the set time zone
command.
SUGGESTION:
Change the documentation for the SET (SQL) command to read as follows, under
the TIME ZONE section:
TIME ZONE
... syntax for the time zone specification. The time zone specification can
be found in the pg_timezone_names view (see Section 51.92).
Issue #3
The syntax diagram shows this:
SET [ SESSION | LOCAL ] configuration_parameter { TO | = } { value | 'value'
| DEFAULT }
SET [ SESSION | LOCAL ] TIME ZONE { timezone | LOCAL | DEFAULT }
Good job, but - the "{ timezone" entry is not referred to. Below in the TIME
ZONE Section it says this:
TIME ZONE
SET TIME ZONE value is an alias for SET timezone TO value.
The word "value" is highlighted but is not applicable to the syntax diagram
above.
SUGGESTION
Change the syntax diagram to read:
SET [ SESSION | LOCAL ] configuration_parameter { TO | = } { value | 'value'
| DEFAULT }
SET [ SESSION | LOCAL ] TIME ZONE { timezone_name | LOCAL | DEFAULT }
and the lower section to read:
TIME ZONE
SET TIME ZONE timezone_name is an alias for SET timezone TO timezone_name.
All this would really make it easier to understand how to change the time
zone. The documents must stop relying solely on examples to convey
information. The syntax must be explicitly and clearly written down and only
then are examples useful.
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: noreply@postgresql.org, pgsql-docs@lists.postgresql.org, philippe.godfrin@nov.com
Subject: Re: set time zone
In-Reply-To: <163888728952.1269.5167822676466793158@wrigleys.postgresql.org>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox