On Tue, Dec 7, 2021 at 02:28:09PM +, 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.
>
> 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 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
SET [ SESSION | LOCAL ] configuration_parameter { TO | = } { value | 'value' | DEFAULT }
-SET [ SESSION | LOCAL ] TIME ZONE { timezone | LOCAL | DEFAULT }
+SET [ SESSION | LOCAL ] TIME ZONE { value | 'value' | LOCAL | DEFAULT }
@@ -192,8 +192,8 @@ SELECT setseed(value);
TIME ZONE
- SET TIME ZONE value is an alias
- for SET timezone TO value. The
+ 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:
@@ -254,7 +254,8 @@ SELECT setseed(value);
- See for more information
+ Time zone abbreviations are not supported by SET;
+ see for more information
about time zones.
