Thread: set time zone
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.
On Tue, Dec 7, 2021 at 02:28:09PM +0000, PG Doc comments form wrote: > 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). Actually, both pg_timezone_names values and POSIX-style time zone specifications are supported by SET. In the attached patch I mention that time zone abbreviations are not supported, and then reference the chapter. I think that should help. > 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. I ended up changing the syntax from 'timezone' to 'value' and added quoted and non-quoted syntax options, again in the attached patch. Did I miss anything? -- Bruce Momjian <bruce@momjian.us> https://momjian.us EDB https://enterprisedb.com Indecision is a decision. Inaction is an action. Mark Batterson
Attachment
On Tue, Aug 16, 2022 at 08:41:05PM -0400, Bruce Momjian wrote: > On Tue, Dec 7, 2021 at 02:28:09PM +0000, PG Doc comments form wrote: > > TIME ZONE > > SET TIME ZONE timezone_name is an alias for SET timezone TO timezone_name. > > I ended up changing the syntax from 'timezone' to 'value' and added > quoted and non-quoted syntax options, again in the attached patch. Patch applied back to PG 10. -- Bruce Momjian <bruce@momjian.us> https://momjian.us EDB https://enterprisedb.com Indecision is a decision. Inaction is an action. Mark Batterson