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 <br...@momjian.us> https://momjian.us EDB https://enterprisedb.com Indecision is a decision. Inaction is an action. Mark Batterson
diff --git a/doc/src/sgml/ref/set.sgml b/doc/src/sgml/ref/set.sgml index 5878c61f9b..5459b29525 100644 --- a/doc/src/sgml/ref/set.sgml +++ b/doc/src/sgml/ref/set.sgml @@ -22,7 +22,7 @@ PostgreSQL documentation <refsynopsisdiv> <synopsis> SET [ SESSION | LOCAL ] <replaceable class="parameter">configuration_parameter</replaceable> { TO | = } { <replaceable class="parameter">value</replaceable> | '<replaceable class="parameter">value</replaceable>' | DEFAULT } -SET [ SESSION | LOCAL ] TIME ZONE { <replaceable class="parameter">timezone</replaceable> | LOCAL | DEFAULT } +SET [ SESSION | LOCAL ] TIME ZONE { <replaceable class="parameter">value</replaceable> | '<replaceable class="parameter">value</replaceable>' | LOCAL | DEFAULT } </synopsis> </refsynopsisdiv> @@ -192,8 +192,8 @@ SELECT setseed(<replaceable>value</replaceable>); <varlistentry> <term><literal>TIME ZONE</literal></term> <listitem> - <para><literal>SET TIME ZONE <replaceable>value</replaceable></literal> is an alias - for <literal>SET timezone TO <replaceable>value</replaceable></literal>. The + <para><literal>SET TIME ZONE '<replaceable>value</replaceable>'</literal> is an alias + for <literal>SET timezone TO '<replaceable>value</replaceable>'</literal>. The syntax <literal>SET TIME ZONE</literal> allows special syntax for the time zone specification. Here are examples of valid values: @@ -254,7 +254,8 @@ SELECT setseed(<replaceable>value</replaceable>); </para> <para> - See <xref linkend="datatype-timezones"/> for more information + Time zone abbreviations are not supported by <command>SET</command>; + see <xref linkend="datatype-timezones"/> for more information about time zones. </para> </listitem>