Skip to content

Commit d8b5c95

Browse files
tglsfdctglsfdc
committed
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.
1 parent 631ea61 commit d8b5c95

40 files changed

+2988
-519
lines changed

‎doc/src/sgml/catalogs.sgml

Lines changed: 53 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.126 2006/07/10 16:20:49 alvherre Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.127 2006/07/25 03:51:21 tgl Exp $ -->
22
<!--
33
Documentation of the system catalogs, directed toward PostgreSQL developers
44
-->
@@ -4559,6 +4559,11 @@
45594559
<entry>tables</entry>
45604560
</row>
45614561

4562+
<row>
4563+
<entry><link linkend="view-pg-timezonenames"><structname>pg_timezonenames</structname></link></entry>
4564+
<entry>time zone abbreviations</entry>
4565+
</row>
4566+
45624567
<row>
45634568
<entry><link linkend="view-pg-user"><structname>pg_user</structname></link></entry>
45644569
<entry>database users</entry>
@@ -5869,6 +5874,53 @@
58695874

58705875
</sect1>
58715876

5877+
<sect1 id="view-pg-timezonenames">
5878+
<title><structname>pg_timezonenames</structname></title>
5879+
5880+
<indexterm zone="view-pg-timezonenames">
5881+
<primary>pg_timezonenames</primary>
5882+
</indexterm>
5883+
5884+
<para>
5885+
The view <structname>pg_timezonenames</structname> provides a list
5886+
of time zone abbreviations that are currently recognized by the datetime
5887+
input routines. The contents of this view change when the
5888+
<xref linkend="guc-timezone-abbreviations"> run-time parameter is modified.
5889+
</para>
5890+
5891+
<table>
5892+
<title><structname>pg_timezonenames</> Columns</title>
5893+
5894+
<tgroup cols=3>
5895+
<thead>
5896+
<row>
5897+
<entry>Name</entry>
5898+
<entry>Type</entry>
5899+
<entry>Description</entry>
5900+
</row>
5901+
</thead>
5902+
<tbody>
5903+
<row>
5904+
<entry><structfield>name</structfield></entry>
5905+
<entry><type>text</type></entry>
5906+
<entry>time zone abbreviation</entry>
5907+
</row>
5908+
<row>
5909+
<entry><structfield>utc_offset</structfield></entry>
5910+
<entry><type>interval</type></entry>
5911+
<entry>offset from UTC (positive means east of Greenwich)</entry>
5912+
</row>
5913+
<row>
5914+
<entry><structfield>is_dst</structfield></entry>
5915+
<entry><type>boolean</type></entry>
5916+
<entry>true if this is a daylight-savings zone</entry>
5917+
</row>
5918+
</tbody>
5919+
</tgroup>
5920+
</table>
5921+
5922+
</sect1>
5923+
58725924
<sect1 id="view-pg-user">
58735925
<title><structname>pg_user</structname></title>
58745926

‎doc/src/sgml/config.sgml

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.68 2006/06/27 22:16:43 momjian Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.69 2006/07/25 03:51:21 tgl Exp $ -->
22

33
<chapter Id="runtime-config">
44
<title>Server Configuration</title>
@@ -3410,19 +3410,20 @@ SELECT * FROM parent WHERE key = 2400;
34103410
</listitem>
34113411
</varlistentry>
34123412

3413-
<varlistentry id="guc-australian-timezones" xreflabel="australian_timezones">
3414-
<term><varname>australian_timezones</varname> (<type>boolean</type>)</term>
3413+
<varlistentry id="guc-timezone-abbreviations" xreflabel="timezone_abbreviations">
3414+
<term><varname>timezone_abbreviations</varname> (<type>string</type>)</term>
34153415
<indexterm>
3416-
<primary><varname>australian_timezones</> configuration parameter</primary>
3416+
<primary><varname>timezone_abbreviations</> configuration parameter</primary>
34173417
</indexterm>
3418-
<indexterm><primary>time zone</><secondary>Australian</></>
3418+
<indexterm><primary>time zone names</></>
34193419
<listitem>
34203420
<para>
3421-
If set to on, <literal>ACST</literal>,
3422-
<literal>CST</literal>, <literal>EST</literal>, and
3423-
<literal>SAT</literal> are interpreted as Australian time
3424-
zones rather than as North/South American time zones and
3425-
Saturday. The default is <literal>off</>.
3421+
Sets the collection of time zone abbreviations that will be accepted
3422+
by the server for datetime input. The default is 'Default',
3423+
which is a collection that works in most of the world; there are
3424+
also 'Australia' and 'India', and other collections can be defined
3425+
for a particular installation. See <xref
3426+
linkend="datetime-appendix"> for more information.
34263427
</para>
34273428
</listitem>
34283429
</varlistentry>

‎doc/src/sgml/datetime.sgml

Lines changed: 128 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/datetime.sgml,v 2.50 2006/07/06 01:46:37 momjian Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/datetime.sgml,v 2.51 2006/07/25 03:51:21 tgl Exp $ -->
22

33
<appendix id="datetime-appendix">
44
<title>Date/Time Support</title>
@@ -361,15 +361,25 @@
361361
</indexterm>
362362

363363
<para>
364-
<xref linkend="datetime-timezone-input-table"> and
365-
<xref linkend="datetime-timezone-full-names-table"> show the time zone
364+
<xref linkend="datetime-timezone-input-table"> shows the time zone
366365
abbreviations recognized by <productname>PostgreSQL</productname>
367-
in date/time input values. Note that these names are <emphasis>not</>
368-
necessarily used for date/time output &mdash; output is driven by the
369-
official timezone abbreviation(s) associated with the currently selected
370-
<xref linkend="guc-timezone"> parameter setting. (It is
371-
likely that future releases will make some use of <varname>timezone</>
372-
for input as well.)
366+
in date/time input values. These abbreviations are not
367+
hard-wired into the server, but are obtained from a configuration
368+
file (see <xref linkend="datetime-config-files">). Note that these
369+
names are <emphasis>not</> used for date/time output &mdash; all supported
370+
output formats use numeric timezone displays to avoid ambiguity.
371+
</para>
372+
373+
<para>
374+
In addition to these abbreviations, the full timezone names shown in
375+
<xref linkend="datetime-timezone-full-names-table"> can be used
376+
in date/time input values. There is a conceptual and
377+
practical difference between the abbreviations and the full names:
378+
abbreviations always represent a fixed offset from UTC, whereas most
379+
of the full names imply a local daylight-savings time rule and so
380+
have two possible UTC offsets. That's why
381+
you always have to specify a date if you want to use full time zone
382+
names in <type>timetz</> values.
373383
</para>
374384

375385
<para>
@@ -925,61 +935,6 @@
925935
</tgroup>
926936
</table>
927937

928-
<formalpara>
929-
<title>Australian Time Zones</title>
930-
931-
<para>
932-
There are three naming conflicts between Australian time zone
933-
names and time zone names commonly used in North and South America:
934-
<literal>ACST</literal>, <literal>CST</literal>, and
935-
<literal>EST</literal>. If the run-time option
936-
<varname>australian_timezones</varname> is set to true then
937-
<literal>ACST</literal>, <literal>CST</literal>,
938-
<literal>EST</literal>, and <literal>SAT</literal> are interpreted
939-
as Australian time zone names, as shown in <xref
940-
linkend="datetime-oztz-table">. If it is false (which is the
941-
default), then <literal>ACST</literal>, <literal>CST</literal>,
942-
and <literal>EST</literal> are taken as American time zone names,
943-
and <literal>SAT</literal> is interpreted as a noise word
944-
indicating Saturday.
945-
</para>
946-
</formalpara>
947-
948-
<table id="datetime-oztz-table">
949-
<title>Australian Time Zone Abbreviations for Input</title>
950-
<tgroup cols="3">
951-
<thead>
952-
<row>
953-
<entry>Time Zone</entry>
954-
<entry>Offset from UTC</entry>
955-
<entry>Description</entry>
956-
</row>
957-
</thead>
958-
<tbody>
959-
<row>
960-
<entry>ACST</entry>
961-
<entry>+09:30</entry>
962-
<entry>Central Australia Standard Time</entry>
963-
</row>
964-
<row>
965-
<entry>CST</entry>
966-
<entry>+10:30</entry>
967-
<entry>Australian Central Standard Time</entry>
968-
</row>
969-
<row>
970-
<entry>EST</entry>
971-
<entry>+10:00</entry>
972-
<entry>Australian Eastern Standard Time</entry>
973-
</row>
974-
<row>
975-
<entry>SAT</entry>
976-
<entry>+09:30</entry>
977-
<entry>South Australian Standard Time</entry>
978-
</row>
979-
</tbody>
980-
</tgroup>
981-
</table>
982-
983938
<indexterm>
984939
<primary>time zone</primary>
985940
<secondary>configuration names</secondary>
@@ -988,13 +943,10 @@
988943
<para>
989944
<xref linkend="datetime-timezone-full-names-table"> shows the time zone
990945
names recognized by <productname>PostgreSQL</productname> as valid
991-
settings for the <xref linkend="guc-timezone"> parameter. Note that
992-
these names are conceptually as well as practically different from
993-
the names shown in <xref linkend="datetime-timezone-input-table">:
994-
most of these names imply a local daylight-savings time rule, whereas
995-
the former names each represent just a fixed offset from UTC. That's why
996-
you always have to specify a date if you want to use these time zone
997-
names in <type>timetz</> values.
946+
settings for the <xref linkend="guc-timezone"> parameter. These names
947+
are not hard-wired into the server, but are in fact names of configuration
948+
files stored under <filename>.../share/timezone/</> of the installation
949+
directory.
998950
</para>
999951

1000952
<para>
@@ -1004,7 +956,7 @@
1004956
</para>
1005957

1006958
<table id="datetime-timezone-full-names-table">
1007-
<title>Time Zone Names for date/time input values and for setting <varname>timezone</></title>
959+
<title>Time Zone Names for setting <varname>timezone</></title>
1008960
<tgroup cols="1">
1009961
<thead>
1010962
<row>
@@ -2230,7 +2182,8 @@
22302182

22312183
<para>
22322184
In addition to the names listed in the table,
2233-
<productname>PostgreSQL</productname> will accept time zone names of the
2185+
<productname>PostgreSQL</productname> will accept
2186+
<xref linkend="guc-timezone"> values of the
22342187
form <replaceable>STD</><replaceable>offset</> or
22352188
<replaceable>STD</><replaceable>offset</><replaceable>DST</>, where
22362189
<replaceable>STD</> is a zone abbreviation, <replaceable>offset</> is a
@@ -2250,6 +2203,108 @@
22502203

22512204
</sect1>
22522205

2206+
<sect1 id="datetime-config-files">
2207+
<title>Date/Time Configuration Files</title>
2208+
2209+
<para>
2210+
Since timezone abbreviations are not well standardized,
2211+
<productname>PostgreSQL</productname> provides a means to customize
2212+
the set of abbreviations accepted by the server. The
2213+
<xref linkend="guc-timezone-abbreviations"> run-time parameter
2214+
determines the active set of abbreviations. While this parameter
2215+
can be altered by any database user, the possible values for it
2216+
are under the control of the database administrator &mdash; they
2217+
are in fact names of configuration files stored in
2218+
<filename>.../share/timezonesets/</> of the installation directory.
2219+
By adding or altering files in that directory, the administrator
2220+
can set local policy for timezone abbreviations.
2221+
</para>
2222+
2223+
<para>
2224+
<literal>timezone_abbreviations</> can be set to any file name
2225+
found in <filename>.../share/timezonesets/</>, if the file's name
2226+
is entirely alphabetic. (The prohibition against non-alphabetic
2227+
characters in <literal>timezone_abbreviations</> prevents reading
2228+
files outside the intended directory, as well as reading editor
2229+
backup files and other extraneous files.)
2230+
</para>
2231+
2232+
<para>
2233+
A timezone abbreviation file may contain blank lines and comments
2234+
beginning with <literal>#</>. Non-comment lines must have one of
2235+
these formats:
2236+
2237+
<synopsis>
2238+
<replaceable>time_zone_name</replaceable> <replaceable>offset</replaceable>
2239+
<replaceable>time_zone_name</replaceable> <replaceable>offset</replaceable> D
2240+
@INCLUDE <replaceable>file_name</replaceable>
2241+
@OVERRIDE
2242+
</synopsis>
2243+
</para>
2244+
2245+
<para>
2246+
A <replaceable>time_zone_name</replaceable> is just the abbreviation
2247+
being defined. The <replaceable>offset</replaceable> is the zone's
2248+
offset in seconds from UTC, positive being east from Greenwich and
2249+
negative being west. For example, -18000 would be five hours west
2250+
of Greenwich, or North American east coast standard time. <literal>D</>
2251+
indicates that the zone name represents local daylight-savings time
2252+
rather than standard time.
2253+
</para>
2254+
2255+
<para>
2256+
The <literal>@INCLUDE</> syntax allows inclusion of another file in the
2257+
<filename>.../share/timezonesets/</> directory. Inclusion can be nested,
2258+
to a limited depth.
2259+
</para>
2260+
2261+
<para>
2262+
The <literal>@OVERRIDE</> syntax indicates that subsequent entries in the
2263+
file may override previous entries (i.e., entries obtained from included
2264+
files). Without this, conflicting definitions of the same timezone
2265+
abbreviation are considered an error.
2266+
</para>
2267+
2268+
<para>
2269+
In an unmodified installation, the file <filename>Default</> contains
2270+
all the non-conflicting time zone abbreviations for most of the world.
2271+
Additional files <filename>Australia</> and <filename>India</> are
2272+
provided for those regions: these files first include the
2273+
<literal>Default</> file and then add or modify timezones as needed.
2274+
</para>
2275+
2276+
<para>
2277+
For reference purposes, a standard installation also contains files
2278+
<filename>Africa.txt</>, <filename>America.txt</>, etc, containing
2279+
information about every time zone abbreviation known to be in use
2280+
according to the <literal>zic</> timezone database. The zone name
2281+
definitions found in these files can be copied and pasted into a custom
2282+
configuration file as needed. Note that these files cannot be directly
2283+
referenced as <literal>timezone_abbreviations</> settings, because of
2284+
the dot embedded in their names.
2285+
</para>
2286+
2287+
<caution>
2288+
<para>
2289+
Time zone abbreviations defined in the configuration file override
2290+
non-timezone meanings built into <productname>PostgreSQL</productname>.
2291+
For example, the <filename>Australia</> configuration file defines
2292+
<literal>SAT</> (for South Australian Standard Time). When this
2293+
file is active, <literal>SAT</> will not be recognized as an abbreviation
2294+
for Saturday.
2295+
</para>
2296+
</caution>
2297+
2298+
<caution>
2299+
<para>
2300+
If you modify files in <filename>.../share/timezonesets/</>,
2301+
it is up to you to make backups &mdash; a normal database dump
2302+
will not include this directory.
2303+
</para>
2304+
</caution>
2305+
2306+
</sect1>
2307+
22532308
<sect1 id="datetime-units-history">
22542309
<title>History of Units</title>
22552310

‎doc/src/sgml/ref/show.sgml

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/ref/show.sgml,v 1.40 2006/06/18 15:38:36 petere Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/ref/show.sgml,v 1.41 2006/07/25 03:51:21 tgl Exp $
33
PostgreSQL documentation
44
-->
55

@@ -168,7 +168,6 @@ SHOW ALL;
168168
--------------------------------+--------------------------------+----------------------------------------------------------------------------------------------
169169
add_missing_from | off | Automatically adds missing table references to FROM clauses.
170170
archive_command | unset | WAL archiving command.
171-
australian_timezones | off | Interprets ACST, CST, EST, and SAT as Australian time zones.
172171
.
173172
.
174173
.

‎src/backend/catalog/system_views.sql

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
*
44
* Copyright (c) 1996-2006, PostgreSQL Global Development Group
55
*
6-
* $PostgreSQL: pgsql/src/backend/catalog/system_views.sql,v 1.27 2006/05/19 19:08:26 alvherre Exp $
6+
* $PostgreSQL: pgsql/src/backend/catalog/system_views.sql,v 1.28 2006/07/25 03:51:21 tgl Exp $
77
*/
88

99
CREATE VIEW pg_roles AS
@@ -186,6 +186,11 @@ CREATE RULE pg_settings_n AS
186186

187187
GRANT SELECT, UPDATE ON pg_settings TO PUBLIC;
188188

189+
CREATE VIEW pg_timezonenames AS
190+
SELECT *
191+
FROM pg_timezonenames() AS T
192+
(name text, utc_offset interval, is_dst boolean);
193+
189194
-- Statistics views
190195

191196
CREATE VIEW pg_stat_all_tables AS

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy