From d8b5c95ca8a2ce7cd4062d4a12710ca977bac87c Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Tue, 25 Jul 2006 03:51:23 +0000 Subject: Remove hard-wired lists of timezone abbreviations in favor of providing configuration files that can be altered by a DBA. The australian_timezones GUC setting disappears, replaced by a timezone_abbreviations setting (set this to 'Australia' to get the effect of australian_timezones). The list of zone names defined by default has undergone a bit of cleanup, too. Documentation still needs some work --- in particular, should we fix Table B-4, or just get rid of it? Joachim Wieland, with some editorializing by moi. --- doc/src/sgml/catalogs.sgml | 54 +++++++++++- doc/src/sgml/config.sgml | 21 ++--- doc/src/sgml/datetime.sgml | 201 +++++++++++++++++++++++++++++---------------- doc/src/sgml/ref/show.sgml | 3 +- 4 files changed, 193 insertions(+), 86 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index cc42c5906ff..cf5d3f3b855 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -1,4 +1,4 @@ - + @@ -4559,6 +4559,11 @@ tables + + pg_timezonenames + time zone abbreviations + + pg_user database users @@ -5869,6 +5874,53 @@ + + <structname>pg_timezonenames</structname> + + + pg_timezonenames + + + + The view pg_timezonenames provides a list + of time zone abbreviations that are currently recognized by the datetime + input routines. The contents of this view change when the + run-time parameter is modified. + + + + <structname>pg_timezonenames</> Columns + + + + + Name + Type + Description + + + + + name + text + time zone abbreviation + + + utc_offset + interval + offset from UTC (positive means east of Greenwich) + + + is_dst + boolean + true if this is a daylight-savings zone + + + +
+ + + <structname>pg_user</structname> diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index e073148ff9a..e967b235f36 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -1,4 +1,4 @@ - + Server Configuration @@ -3410,19 +3410,20 @@ SELECT * FROM parent WHERE key = 2400; - - australian_timezones (boolean) + + timezone_abbreviations (string) - australian_timezones configuration parameter + timezone_abbreviations configuration parameter - time zoneAustralian + time zone names - If set to on, ACST, - CST, EST, and - SAT are interpreted as Australian time - zones rather than as North/South American time zones and - Saturday. The default is off. + Sets the collection of time zone abbreviations that will be accepted + by the server for datetime input. The default is 'Default', + which is a collection that works in most of the world; there are + also 'Australia' and 'India', and other collections can be defined + for a particular installation. See for more information. diff --git a/doc/src/sgml/datetime.sgml b/doc/src/sgml/datetime.sgml index 2bd42e5e52b..7e7e3278a0a 100644 --- a/doc/src/sgml/datetime.sgml +++ b/doc/src/sgml/datetime.sgml @@ -1,4 +1,4 @@ - + Date/Time Support @@ -361,15 +361,25 @@ - and - show the time zone + shows the time zone abbreviations recognized by PostgreSQL - in date/time input values. Note that these names are not - necessarily used for date/time output — output is driven by the - official timezone abbreviation(s) associated with the currently selected - parameter setting. (It is - likely that future releases will make some use of timezone - for input as well.) + in date/time input values. These abbreviations are not + hard-wired into the server, but are obtained from a configuration + file (see ). Note that these + names are not used for date/time output — all supported + output formats use numeric timezone displays to avoid ambiguity. + + + + In addition to these abbreviations, the full timezone names shown in + can be used + in date/time input values. There is a conceptual and + practical difference between the abbreviations and the full names: + abbreviations always represent a fixed offset from UTC, whereas most + of the full names imply a local daylight-savings time rule and so + have two possible UTC offsets. That's why + you always have to specify a date if you want to use full time zone + names in timetz values. @@ -925,61 +935,6 @@ - - Australian Time Zones - - - There are three naming conflicts between Australian time zone - names and time zone names commonly used in North and South America: - ACST, CST, and - EST. If the run-time option - australian_timezones is set to true then - ACST, CST, - EST, and SAT are interpreted - as Australian time zone names, as shown in . If it is false (which is the - default), then ACST, CST, - and EST are taken as American time zone names, - and SAT is interpreted as a noise word - indicating Saturday. - - - - - Australian Time Zone Abbreviations for Input - - - - Time Zone - Offset from UTC - Description - - - - - ACST - +09:30 - Central Australia Standard Time - - - CST - +10:30 - Australian Central Standard Time - - - EST - +10:00 - Australian Eastern Standard Time - - - SAT - +09:30 - South Australian Standard Time - - - -
- time zone configuration names @@ -988,13 +943,10 @@ shows the time zone names recognized by PostgreSQL as valid - settings for the parameter. Note that - these names are conceptually as well as practically different from - the names shown in : - most of these names imply a local daylight-savings time rule, whereas - the former names each represent just a fixed offset from UTC. That's why - you always have to specify a date if you want to use these time zone - names in timetz values. + settings for the parameter. These names + are not hard-wired into the server, but are in fact names of configuration + files stored under .../share/timezone/ of the installation + directory. @@ -1004,7 +956,7 @@ - Time Zone Names for date/time input values and for setting <varname>timezone</> + Time Zone Names for setting <varname>timezone</> @@ -2230,7 +2182,8 @@ In addition to the names listed in the table, - PostgreSQL will accept time zone names of the + PostgreSQL will accept + values of the form STDoffset or STDoffsetDST, where STD is a zone abbreviation, offset is a @@ -2250,6 +2203,108 @@ + + Date/Time Configuration Files + + + Since timezone abbreviations are not well standardized, + PostgreSQL provides a means to customize + the set of abbreviations accepted by the server. The + run-time parameter + determines the active set of abbreviations. While this parameter + can be altered by any database user, the possible values for it + are under the control of the database administrator — they + are in fact names of configuration files stored in + .../share/timezonesets/ of the installation directory. + By adding or altering files in that directory, the administrator + can set local policy for timezone abbreviations. + + + + timezone_abbreviations can be set to any file name + found in .../share/timezonesets/, if the file's name + is entirely alphabetic. (The prohibition against non-alphabetic + characters in timezone_abbreviations prevents reading + files outside the intended directory, as well as reading editor + backup files and other extraneous files.) + + + + A timezone abbreviation file may contain blank lines and comments + beginning with #. Non-comment lines must have one of + these formats: + + +time_zone_name offset +time_zone_name offset D +@INCLUDE file_name +@OVERRIDE + + + + + A time_zone_name is just the abbreviation + being defined. The offset is the zone's + offset in seconds from UTC, positive being east from Greenwich and + negative being west. For example, -18000 would be five hours west + of Greenwich, or North American east coast standard time. D + indicates that the zone name represents local daylight-savings time + rather than standard time. + + + + The @INCLUDE syntax allows inclusion of another file in the + .../share/timezonesets/ directory. Inclusion can be nested, + to a limited depth. + + + + The @OVERRIDE syntax indicates that subsequent entries in the + file may override previous entries (i.e., entries obtained from included + files). Without this, conflicting definitions of the same timezone + abbreviation are considered an error. + + + + In an unmodified installation, the file Default contains + all the non-conflicting time zone abbreviations for most of the world. + Additional files Australia and India are + provided for those regions: these files first include the + Default file and then add or modify timezones as needed. + + + + For reference purposes, a standard installation also contains files + Africa.txt, America.txt, etc, containing + information about every time zone abbreviation known to be in use + according to the zic timezone database. The zone name + definitions found in these files can be copied and pasted into a custom + configuration file as needed. Note that these files cannot be directly + referenced as timezone_abbreviations settings, because of + the dot embedded in their names. + + + + + Time zone abbreviations defined in the configuration file override + non-timezone meanings built into PostgreSQL. + For example, the Australia configuration file defines + SAT (for South Australian Standard Time). When this + file is active, SAT will not be recognized as an abbreviation + for Saturday. + + + + + + If you modify files in .../share/timezonesets/, + it is up to you to make backups — a normal database dump + will not include this directory. + + + + + History of Units diff --git a/doc/src/sgml/ref/show.sgml b/doc/src/sgml/ref/show.sgml index f6123ba5036..cf92bcec4e8 100644 --- a/doc/src/sgml/ref/show.sgml +++ b/doc/src/sgml/ref/show.sgml @@ -1,5 +1,5 @@ @@ -168,7 +168,6 @@ SHOW ALL; --------------------------------+--------------------------------+---------------------------------------------------------------------------------------------- add_missing_from | off | Automatically adds missing table references to FROM clauses. archive_command | unset | WAL archiving command. - australian_timezones | off | Interprets ACST, CST, EST, and SAT as Australian time zones. . . . -- cgit v1.2.3