rdelaage
/
postgresql
mirror of https://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
postgresql/doc/src/sgml/datetime.sgml

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

931 lines
32 KiB
Plaintext
Raw Normal View History

Remove cvs keywords from all files.
2010-09-20 22:08:53 +02:00
<!-- doc/src/sgml/datetime.sgml -->
Rearrange and consolidate the Admin Guide. Add reference pages for utilities and remove standalone chapters for same. Add material for an appendix on date/time properties, but not yet integrated with the User's Guide. Break up the former chapter on pg_options into Admin and Programmer's Guides.
1999-05-20 07:39:29 +02:00
Deprecate 'current' for date/time input. Fix up references to "PostgreSQL" rather than "Postgres". Was roughly evenly split between the two before. ref/ files not yet done.
2001-11-21 06:53:41 +01:00
<appendix id="datetime-appendix">
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<title>Date/Time Support</title>
Rearrange and consolidate the Admin Guide. Add reference pages for utilities and remove standalone chapters for same. Add material for an appendix on date/time properties, but not yet integrated with the User's Guide. Break up the former chapter on pg_options into Admin and Programmer's Guides.
1999-05-20 07:39:29 +02:00
Add more complete details on date/time keywords and parsing rules. Move some tabular information on these from the chapter on data types to the appendix on dates and times.
2002-01-04 18:02:25 +01:00
<para>
<productname>PostgreSQL</productname> uses an internal heuristic
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
parser for all date/time input support. Dates and times are input as
Add more complete details on date/time keywords and parsing rules. Move some tabular information on these from the chapter on data types to the appendix on dates and times.
2002-01-04 18:02:25 +01:00
strings, and are broken up into distinct fields with a preliminary
Update documentation on may/can/might: Standard English uses "may", "can", and "might" in different ways: may - permission, "You may borrow my rake." can - ability, "I can lift that log." might - possibility, "It might rain today." Unfortunately, in conversational English, their use is often mixed, as in, "You may use this variable to do X", when in fact, "can" is a better choice. Similarly, "It may crash" is better stated, "It might crash". Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
determination of what kind of information can be in the
Add more complete details on date/time keywords and parsing rules. Move some tabular information on these from the chapter on data types to the appendix on dates and times.
2002-01-04 18:02:25 +01:00
field. Each field is interpreted and either assigned a numeric
Back out tutorial changes: --------------------------------------------------------------------------- 1. In keeping with the recent discussion that there should be more said about views, stored procedures, and triggers, in the tutorial, I have added a bit of verbiage to that end. 2. Some formatting changes to the datetime discussion, as well as addition of a citation of a relevant book on calendars. Christopher Browne
2004-03-31 18:20:53 +02:00
value, ignored, or rejected.
The parser contains internal lookup tables for all textual fields,
Update documentation to reflect the fact that we now know exactly what time zone names we support.
2004-08-10 02:55:08 +02:00
including months, days of the week, and time zones.
Add more complete details on date/time keywords and parsing rules. Move some tabular information on these from the chapter on data types to the appendix on dates and times.
2002-01-04 18:02:25 +01:00
</para>
<para>
This appendix includes information on the content of these
lookup tables and describes the steps used by the parser to decode
dates and times.
</para>
Ensure that all <sect1> and <refentry> tags have IDs. This is needed to ensure that the resulting webpages have predictable URLs, instead of ever-changing numeric IDs. The new contrib docs were the biggest offender, but some old stuff had the problem too. Also, rename a couple of new contrib sgml files for consistency's sake.
2007-12-02 23:33:20 +01:00
<sect1 id="datetime-input-rules">
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<title>Date/Time Input Interpretation</title>
<para>
Document handling of invalid/ambiguous timestamp input near DST boundaries. The source code comments documented this, but the user-facing docs, not so much. Add a section to Appendix B that discusses it. In passing, improve a couple other things in Appendix B --- notably, a long-obsolete claim that time zone abbreviations are looked up in a fixed table. Per bug #15527 from Michael Davidson. Discussion: https://postgr.es/m/15527-f1be0b4dc99ebbe7@postgresql.org
2018-11-30 00:28:10 +01:00
Date/time input strings are decoded using the following procedure.
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
</para>
<procedure>
<step>
<para>
Break the input string into tokens and categorize each token as
a string, time, time zone, or number.
</para>
<substeps>
<step>
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
If the numeric token contains a colon (<literal>:</literal>), this is
Last batch of updates in response to 7.4 interactive docs comments.
2005-01-09 19:58:10 +01:00
a time string. Include all subsequent digits and colons.
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
</para>
</step>
<step>
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
If the numeric token contains a dash (<literal>-</literal>), slash
(<literal>/</literal>), or two or more dots (<literal>.</literal>), this is
Update documentation on may/can/might: Standard English uses "may", "can", and "might" in different ways: may - permission, "You may borrow my rake." can - ability, "I can lift that log." might - possibility, "It might rain today." Unfortunately, in conversational English, their use is often mixed, as in, "You may use this variable to do X", when in fact, "can" is a better choice. Similarly, "It may crash" is better stated, "It might crash". Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
a date string which might have a text month. If a date token has
Fix up some problems in handling of zic-style time zone names in datetime input routines. Remove the former "DecodePosixTimezone" function in favor of letting the zic code handle POSIX-style zone specs (see tzparse()). In particular this means that "PST+3" now means the same as "-03", whereas it used to mean "-11" --- the zone abbreviation is effectively just a noise word in this syntax. Make sure that all named and POSIX-style zone names will be parsed as a single token. Fix long-standing bogosities in printing and input of fractional-hour timezone offsets (since the tzparse() code will accept these, we'd better make 'em work). Also correct an error in the original coding of the zic-zone-name patch: in "timestamp without time zone" input, zone names are supposed to be allowed but ignored, but the coding was such that the zone changed the interpretation anyway.
2006-10-17 23:03:21 +02:00
already been seen, it is instead interpreted as a time zone
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
name (e.g., <literal>America/New_York</literal>).
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
</para>
</step>
<step>
<para>
Last batch of updates in response to 7.4 interactive docs comments.
2005-01-09 19:58:10 +01:00
If the token is numeric only, then it is either a single field
or an ISO 8601 concatenated date (e.g.,
<literal>19990113</literal> for January 13, 1999) or time
(e.g., <literal>141516</literal> for 14:15:16).
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
</para>
</step>
<step>
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
If the token starts with a plus (<literal>+</literal>) or minus
(<literal>-</literal>), then it is either a numeric time zone or a special
Last batch of updates in response to 7.4 interactive docs comments.
2005-01-09 19:58:10 +01:00
field.
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
</para>
</step>
</substeps>
</step>
<step>
<para>
Document handling of invalid/ambiguous timestamp input near DST boundaries. The source code comments documented this, but the user-facing docs, not so much. Add a section to Appendix B that discusses it. In passing, improve a couple other things in Appendix B --- notably, a long-obsolete claim that time zone abbreviations are looked up in a fixed table. Per bug #15527 from Michael Davidson. Discussion: https://postgr.es/m/15527-f1be0b4dc99ebbe7@postgresql.org
2018-11-30 00:28:10 +01:00
If the token is an alphabetic string, match up with possible strings:
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
</para>
Remove useless whitespace at end of lines
2010-11-23 21:27:50 +01:00
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<substeps>
<step>
<para>
Document handling of invalid/ambiguous timestamp input near DST boundaries. The source code comments documented this, but the user-facing docs, not so much. Add a section to Appendix B that discusses it. In passing, improve a couple other things in Appendix B --- notably, a long-obsolete claim that time zone abbreviations are looked up in a fixed table. Per bug #15527 from Michael Davidson. Discussion: https://postgr.es/m/15527-f1be0b4dc99ebbe7@postgresql.org
2018-11-30 00:28:10 +01:00
See if the token matches any known time zone abbreviation.
These abbreviations are supplied by the configuration file
described in <xref linkend="datetime-config-files"/>.
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
</para>
</step>
Remove useless whitespace at end of lines
2010-11-23 21:27:50 +01:00
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<step>
<para>
Document handling of invalid/ambiguous timestamp input near DST boundaries. The source code comments documented this, but the user-facing docs, not so much. Add a section to Appendix B that discusses it. In passing, improve a couple other things in Appendix B --- notably, a long-obsolete claim that time zone abbreviations are looked up in a fixed table. Per bug #15527 from Michael Davidson. Discussion: https://postgr.es/m/15527-f1be0b4dc99ebbe7@postgresql.org
2018-11-30 00:28:10 +01:00
If not found, search an internal table to match
Fix up some problems in handling of zic-style time zone names in datetime input routines. Remove the former "DecodePosixTimezone" function in favor of letting the zic code handle POSIX-style zone specs (see tzparse()). In particular this means that "PST+3" now means the same as "-03", whereas it used to mean "-11" --- the zone abbreviation is effectively just a noise word in this syntax. Make sure that all named and POSIX-style zone names will be parsed as a single token. Fix long-standing bogosities in printing and input of fractional-hour timezone offsets (since the tzparse() code will accept these, we'd better make 'em work). Also correct an error in the original coding of the zic-zone-name patch: in "timestamp without time zone" input, zone names are supposed to be allowed but ignored, but the coding was such that the zone changed the interpretation anyway.
2006-10-17 23:03:21 +02:00
the token as either a special string (e.g., <literal>today</literal>),
day (e.g., <literal>Thursday</literal>),
month (e.g., <literal>January</literal>),
or noise word (e.g., <literal>at</literal>, <literal>on</literal>).
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
</para>
</step>
<step>
<para>
Last batch of updates in response to 7.4 interactive docs comments.
2005-01-09 19:58:10 +01:00
If still not found, throw an error.
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
</para>
</step>
</substeps>
</step>
Remove useless whitespace at end of lines
2010-11-23 21:27:50 +01:00
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<step>
<para>
Apply (a somewhat revised version of) Greg Mullane's patch to eliminate heuristic determination of day vs month in date/time input. Add the ability to specify that input is interpreted as yy-mm-dd order (which formerly worked, but only for yy greater than 31). DateStyle's input component now has the preferred spellings DMY, MDY, or YMD; the older keywords European and US are now aliases for the first two of these. Per recent discussions on pgsql-general.
2003-07-29 02:03:19 +02:00
When the token is a number or number field:
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
</para>
<substeps>
<step>
<para>
Last batch of updates in response to 7.4 interactive docs comments.
2005-01-09 19:58:10 +01:00
If there are eight or six digits,
Remove useless whitespace at end of lines
2010-11-23 21:27:50 +01:00
and if no other date fields have been previously read, then interpret
Last batch of updates in response to 7.4 interactive docs comments.
2005-01-09 19:58:10 +01:00
as a <quote>concatenated date</quote> (e.g.,
<literal>19990118</literal> or <literal>990118</literal>).
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
The interpretation is <literal>YYYYMMDD</literal> or <literal>YYMMDD</literal>.
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
</para>
</step>
<step>
<para>
Last batch of updates in response to 7.4 interactive docs comments.
2005-01-09 19:58:10 +01:00
If the token is three digits
and a year has already been read, then interpret as day of year.
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
</para>
</step>
Remove useless whitespace at end of lines
2010-11-23 21:27:50 +01:00
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<step>
<para>
Last batch of updates in response to 7.4 interactive docs comments.
2005-01-09 19:58:10 +01:00
If four or six digits and a year has already been read, then
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
interpret as a time (<literal>HHMM</literal> or <literal>HHMMSS</literal>).
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
</para>
</step>
<step>
<para>
Last batch of updates in response to 7.4 interactive docs comments.
2005-01-09 19:58:10 +01:00
If three or more digits and no date fields have yet been found,
interpret as a year (this forces yy-mm-dd ordering of the remaining
date fields).
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
</para>
</step>
<step>
<para>
Apply (a somewhat revised version of) Greg Mullane's patch to eliminate heuristic determination of day vs month in date/time input. Add the ability to specify that input is interpreted as yy-mm-dd order (which formerly worked, but only for yy greater than 31). DateStyle's input component now has the preferred spellings DMY, MDY, or YMD; the older keywords European and US are now aliases for the first two of these. Per recent discussions on pgsql-general.
2003-07-29 02:03:19 +02:00
Otherwise the date field ordering is assumed to follow the
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<varname>DateStyle</varname> setting: mm-dd-yy, dd-mm-yy, or yy-mm-dd.
Last batch of updates in response to 7.4 interactive docs comments.
2005-01-09 19:58:10 +01:00
Throw an error if a month or day field is found to be out of range.
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
</para>
</step>
</substeps>
</step>
<step>
<para>
If BC has been specified, negate the year and add one for
internal storage. (There is no year zero in the Gregorian
Update documentation to reflect the fact that we now know exactly what time zone names we support.
2004-08-10 02:55:08 +02:00
calendar, so numerically 1 BC becomes year zero.)
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
</para>
</step>
<step>
<para>
Update documentation to reflect the fact that we now know exactly what time zone names we support.
2004-08-10 02:55:08 +02:00
If BC was not specified, and if the year field was two digits in length,
then adjust the year to four digits. If the field is less than 70, then
add 2000, otherwise add 1900.
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<tip>
<para>
doc: Use proper em and en dashes
2019-10-25 20:23:44 +02:00
Gregorian years AD 1&ndash;99 can be entered by using 4 digits with leading
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
zeros (e.g., <literal>0099</literal> is AD 99).
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
</para>
</tip>
</para>
</step>
</procedure>
</sect1>
Document handling of invalid/ambiguous timestamp input near DST boundaries. The source code comments documented this, but the user-facing docs, not so much. Add a section to Appendix B that discusses it. In passing, improve a couple other things in Appendix B --- notably, a long-obsolete claim that time zone abbreviations are looked up in a fixed table. Per bug #15527 from Michael Davidson. Discussion: https://postgr.es/m/15527-f1be0b4dc99ebbe7@postgresql.org
2018-11-30 00:28:10 +01:00
<sect1 id="datetime-invalid-input">
<title>Handling of Invalid or Ambiguous Timestamps</title>
<para>
Ordinarily, if a date/time string is syntactically valid but contains
out-of-range field values, an error will be thrown. For example, input
specifying the 31st of February will be rejected.
</para>
<para>
During a daylight-savings-time transition, it is possible for a
seemingly valid timestamp string to represent a nonexistent or ambiguous
timestamp. Such cases are not rejected; the ambiguity is resolved by
determining which UTC offset to apply. For example, supposing that the
<xref linkend="guc-timezone"/> parameter is set
to <literal>America/New_York</literal>, consider
<programlisting>
=&gt; SELECT '2018-03-11 02:30'::timestamptz;
timestamptz
------------------------
2018-03-11 03:30:00-04
(1 row)
</programlisting>
Because that day was a spring-forward transition date in that time zone,
there was no civil time instant 2:30AM; clocks jumped forward from 2AM
EST to 3AM EDT. <productname>PostgreSQL</productname> interprets the
given time as if it were standard time (UTC-5), which then renders as
3:30AM EDT (UTC-4).
</para>
<para>
Conversely, consider the behavior during a fall-back transition:
<programlisting>
Doc: fix bogus example about ambiguous timestamps. I had a brain fade in commit d32899157, and used 2:30AM as the example timestamp for both spring-forward and fall-back cases. But it's not actually ambiguous at all in the fall-back case, because that transition is from 2AM to 1AM under USA rules. Fix the example to use 1:30AM, which *is* ambiguous. Noted while answering a question from Aleksander Alekseev. Back-patch to all supported branches. Discussion: https://postgr.es/m/2191355.1641828552@sss.pgh.pa.us
2022-01-10 17:46:16 +01:00
=&gt; SELECT '2018-11-04 01:30'::timestamptz;
Document handling of invalid/ambiguous timestamp input near DST boundaries. The source code comments documented this, but the user-facing docs, not so much. Add a section to Appendix B that discusses it. In passing, improve a couple other things in Appendix B --- notably, a long-obsolete claim that time zone abbreviations are looked up in a fixed table. Per bug #15527 from Michael Davidson. Discussion: https://postgr.es/m/15527-f1be0b4dc99ebbe7@postgresql.org
2018-11-30 00:28:10 +01:00
timestamptz
------------------------
Doc: fix bogus example about ambiguous timestamps. I had a brain fade in commit d32899157, and used 2:30AM as the example timestamp for both spring-forward and fall-back cases. But it's not actually ambiguous at all in the fall-back case, because that transition is from 2AM to 1AM under USA rules. Fix the example to use 1:30AM, which *is* ambiguous. Noted while answering a question from Aleksander Alekseev. Back-patch to all supported branches. Discussion: https://postgr.es/m/2191355.1641828552@sss.pgh.pa.us
2022-01-10 17:46:16 +01:00
2018-11-04 01:30:00-05
Document handling of invalid/ambiguous timestamp input near DST boundaries. The source code comments documented this, but the user-facing docs, not so much. Add a section to Appendix B that discusses it. In passing, improve a couple other things in Appendix B --- notably, a long-obsolete claim that time zone abbreviations are looked up in a fixed table. Per bug #15527 from Michael Davidson. Discussion: https://postgr.es/m/15527-f1be0b4dc99ebbe7@postgresql.org
2018-11-30 00:28:10 +01:00
(1 row)
</programlisting>
Doc: fix bogus example about ambiguous timestamps. I had a brain fade in commit d32899157, and used 2:30AM as the example timestamp for both spring-forward and fall-back cases. But it's not actually ambiguous at all in the fall-back case, because that transition is from 2AM to 1AM under USA rules. Fix the example to use 1:30AM, which *is* ambiguous. Noted while answering a question from Aleksander Alekseev. Back-patch to all supported branches. Discussion: https://postgr.es/m/2191355.1641828552@sss.pgh.pa.us
2022-01-10 17:46:16 +01:00
On that date, there were two possible interpretations of 1:30AM; there
was 1:30AM EDT, and then an hour later after clocks jumped back from
2AM EDT to 1AM EST, there was 1:30AM EST.
Document handling of invalid/ambiguous timestamp input near DST boundaries. The source code comments documented this, but the user-facing docs, not so much. Add a section to Appendix B that discusses it. In passing, improve a couple other things in Appendix B --- notably, a long-obsolete claim that time zone abbreviations are looked up in a fixed table. Per bug #15527 from Michael Davidson. Discussion: https://postgr.es/m/15527-f1be0b4dc99ebbe7@postgresql.org
2018-11-30 00:28:10 +01:00
Again, <productname>PostgreSQL</productname> interprets the given time
Doc: fix bogus example about ambiguous timestamps. I had a brain fade in commit d32899157, and used 2:30AM as the example timestamp for both spring-forward and fall-back cases. But it's not actually ambiguous at all in the fall-back case, because that transition is from 2AM to 1AM under USA rules. Fix the example to use 1:30AM, which *is* ambiguous. Noted while answering a question from Aleksander Alekseev. Back-patch to all supported branches. Discussion: https://postgr.es/m/2191355.1641828552@sss.pgh.pa.us
2022-01-10 17:46:16 +01:00
as if it were standard time (UTC-5). We can force the other
interpretation by specifying daylight-savings time:
Document handling of invalid/ambiguous timestamp input near DST boundaries. The source code comments documented this, but the user-facing docs, not so much. Add a section to Appendix B that discusses it. In passing, improve a couple other things in Appendix B --- notably, a long-obsolete claim that time zone abbreviations are looked up in a fixed table. Per bug #15527 from Michael Davidson. Discussion: https://postgr.es/m/15527-f1be0b4dc99ebbe7@postgresql.org
2018-11-30 00:28:10 +01:00
<programlisting>
Doc: fix bogus example about ambiguous timestamps. I had a brain fade in commit d32899157, and used 2:30AM as the example timestamp for both spring-forward and fall-back cases. But it's not actually ambiguous at all in the fall-back case, because that transition is from 2AM to 1AM under USA rules. Fix the example to use 1:30AM, which *is* ambiguous. Noted while answering a question from Aleksander Alekseev. Back-patch to all supported branches. Discussion: https://postgr.es/m/2191355.1641828552@sss.pgh.pa.us
2022-01-10 17:46:16 +01:00
=&gt; SELECT '2018-11-04 01:30 EDT'::timestamptz;
Document handling of invalid/ambiguous timestamp input near DST boundaries. The source code comments documented this, but the user-facing docs, not so much. Add a section to Appendix B that discusses it. In passing, improve a couple other things in Appendix B --- notably, a long-obsolete claim that time zone abbreviations are looked up in a fixed table. Per bug #15527 from Michael Davidson. Discussion: https://postgr.es/m/15527-f1be0b4dc99ebbe7@postgresql.org
2018-11-30 00:28:10 +01:00
timestamptz
------------------------
Doc: fix bogus example about ambiguous timestamps. I had a brain fade in commit d32899157, and used 2:30AM as the example timestamp for both spring-forward and fall-back cases. But it's not actually ambiguous at all in the fall-back case, because that transition is from 2AM to 1AM under USA rules. Fix the example to use 1:30AM, which *is* ambiguous. Noted while answering a question from Aleksander Alekseev. Back-patch to all supported branches. Discussion: https://postgr.es/m/2191355.1641828552@sss.pgh.pa.us
2022-01-10 17:46:16 +01:00
2018-11-04 01:30:00-04
Document handling of invalid/ambiguous timestamp input near DST boundaries. The source code comments documented this, but the user-facing docs, not so much. Add a section to Appendix B that discusses it. In passing, improve a couple other things in Appendix B --- notably, a long-obsolete claim that time zone abbreviations are looked up in a fixed table. Per bug #15527 from Michael Davidson. Discussion: https://postgr.es/m/15527-f1be0b4dc99ebbe7@postgresql.org
2018-11-30 00:28:10 +01:00
(1 row)
</programlisting>
</para>
<para>
The precise rule that is applied in such cases is that an invalid
timestamp that appears to fall within a jump-forward daylight savings
transition is assigned the UTC offset that prevailed in the time zone
just before the transition, while an ambiguous timestamp that could fall
on either side of a jump-back transition is assigned the UTC offset that
prevailed just after the transition. In most time zones this is
equivalent to saying that <quote>the standard-time interpretation is
preferred when in doubt</quote>.
</para>
<para>
In all cases, the UTC offset associated with a timestamp can be
specified explicitly, using either a numeric UTC offset or a time zone
abbreviation that corresponds to a fixed UTC offset. The rule just
given applies only when it is necessary to infer a UTC offset for a time
zone in which the offset varies.
</para>
</sect1>
General editing
2003-04-07 03:29:26 +02:00
<sect1 id="datetime-keywords">
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<title>Date/Time Key Words</title>
Add more complete details on date/time keywords and parsing rules. Move some tabular information on these from the chapter on data types to the appendix on dates and times.
2002-01-04 18:02:25 +01:00
<para>
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
<xref linkend="datetime-month-table"/> shows the tokens that are
Last batch of updates in response to 7.4 interactive docs comments.
2005-01-09 19:58:10 +01:00
recognized as names of months.
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
</para>
<table id="datetime-month-table">
Last batch of updates in response to 7.4 interactive docs comments.
2005-01-09 19:58:10 +01:00
<title>Month Names</title>
Add more complete details on date/time keywords and parsing rules. Move some tabular information on these from the chapter on data types to the appendix on dates and times.
2002-01-04 18:02:25 +01:00
<tgroup cols="2">
<thead>
<row>
Last batch of updates in response to 7.4 interactive docs comments.
2005-01-09 19:58:10 +01:00
<entry>Month</entry>
<entry>Abbreviations</entry>
Add more complete details on date/time keywords and parsing rules. Move some tabular information on these from the chapter on data types to the appendix on dates and times.
2002-01-04 18:02:25 +01:00
</row>
</thead>
<tbody>
<row>
Last batch of updates in response to 7.4 interactive docs comments.
2005-01-09 19:58:10 +01:00
<entry>January</entry>
<entry>Jan</entry>
Add more complete details on date/time keywords and parsing rules. Move some tabular information on these from the chapter on data types to the appendix on dates and times.
2002-01-04 18:02:25 +01:00
</row>
<row>
Last batch of updates in response to 7.4 interactive docs comments.
2005-01-09 19:58:10 +01:00
<entry>February</entry>
<entry>Feb</entry>
Add more complete details on date/time keywords and parsing rules. Move some tabular information on these from the chapter on data types to the appendix on dates and times.
2002-01-04 18:02:25 +01:00
</row>
<row>
Last batch of updates in response to 7.4 interactive docs comments.
2005-01-09 19:58:10 +01:00
<entry>March</entry>
<entry>Mar</entry>
Add more complete details on date/time keywords and parsing rules. Move some tabular information on these from the chapter on data types to the appendix on dates and times.
2002-01-04 18:02:25 +01:00
</row>
<row>
Last batch of updates in response to 7.4 interactive docs comments.
2005-01-09 19:58:10 +01:00
<entry>April</entry>
<entry>Apr</entry>
Add more complete details on date/time keywords and parsing rules. Move some tabular information on these from the chapter on data types to the appendix on dates and times.
2002-01-04 18:02:25 +01:00
</row>
<row>
Last batch of updates in response to 7.4 interactive docs comments.
2005-01-09 19:58:10 +01:00
<entry>May</entry>
<entry></entry>
Add more complete details on date/time keywords and parsing rules. Move some tabular information on these from the chapter on data types to the appendix on dates and times.
2002-01-04 18:02:25 +01:00
</row>
<row>
Last batch of updates in response to 7.4 interactive docs comments.
2005-01-09 19:58:10 +01:00
<entry>June</entry>
<entry>Jun</entry>
Add more complete details on date/time keywords and parsing rules. Move some tabular information on these from the chapter on data types to the appendix on dates and times.
2002-01-04 18:02:25 +01:00
</row>
<row>
Last batch of updates in response to 7.4 interactive docs comments.
2005-01-09 19:58:10 +01:00
<entry>July</entry>
<entry>Jul</entry>
Add more complete details on date/time keywords and parsing rules. Move some tabular information on these from the chapter on data types to the appendix on dates and times.
2002-01-04 18:02:25 +01:00
</row>
<row>
Last batch of updates in response to 7.4 interactive docs comments.
2005-01-09 19:58:10 +01:00
<entry>August</entry>
<entry>Aug</entry>
Add more complete details on date/time keywords and parsing rules. Move some tabular information on these from the chapter on data types to the appendix on dates and times.
2002-01-04 18:02:25 +01:00
</row>
<row>
Last batch of updates in response to 7.4 interactive docs comments.
2005-01-09 19:58:10 +01:00
<entry>September</entry>
<entry>Sep, Sept</entry>
Add more complete details on date/time keywords and parsing rules. Move some tabular information on these from the chapter on data types to the appendix on dates and times.
2002-01-04 18:02:25 +01:00
</row>
<row>
Last batch of updates in response to 7.4 interactive docs comments.
2005-01-09 19:58:10 +01:00
<entry>October</entry>
<entry>Oct</entry>
Add more complete details on date/time keywords and parsing rules. Move some tabular information on these from the chapter on data types to the appendix on dates and times.
2002-01-04 18:02:25 +01:00
</row>
<row>
Last batch of updates in response to 7.4 interactive docs comments.
2005-01-09 19:58:10 +01:00
<entry>November</entry>
<entry>Nov</entry>
</row>
<row>
<entry>December</entry>
<entry>Dec</entry>
Add more complete details on date/time keywords and parsing rules. Move some tabular information on these from the chapter on data types to the appendix on dates and times.
2002-01-04 18:02:25 +01:00
</row>
</tbody>
</tgroup>
</table>
<para>
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
<xref linkend="datetime-dow-table"/> shows the tokens that are
Last batch of updates in response to 7.4 interactive docs comments.
2005-01-09 19:58:10 +01:00
recognized as names of days of the week.
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
</para>
<table id="datetime-dow-table">
Last batch of updates in response to 7.4 interactive docs comments.
2005-01-09 19:58:10 +01:00
<title>Day of the Week Names</title>
Add more complete details on date/time keywords and parsing rules. Move some tabular information on these from the chapter on data types to the appendix on dates and times.
2002-01-04 18:02:25 +01:00
<tgroup cols="2">
<thead>
Last batch of updates in response to 7.4 interactive docs comments.
2005-01-09 19:58:10 +01:00
<row>
<entry>Day</entry>
<entry>Abbreviations</entry>
</row>
Add more complete details on date/time keywords and parsing rules. Move some tabular information on these from the chapter on data types to the appendix on dates and times.
2002-01-04 18:02:25 +01:00
</thead>
<tbody>
Last batch of updates in response to 7.4 interactive docs comments.
2005-01-09 19:58:10 +01:00
<row>
<entry>Sunday</entry>
<entry>Sun</entry>
</row>
<row>
<entry>Monday</entry>
<entry>Mon</entry>
</row>
<row>
<entry>Tuesday</entry>
<entry>Tue, Tues</entry>
</row>
<row>
<entry>Wednesday</entry>
<entry>Wed, Weds</entry>
</row>
<row>
<entry>Thursday</entry>
<entry>Thu, Thur, Thurs</entry>
</row>
<row>
<entry>Friday</entry>
<entry>Fri</entry>
</row>
<row>
<entry>Saturday</entry>
<entry>Sat</entry>
</row>
Add more complete details on date/time keywords and parsing rules. Move some tabular information on these from the chapter on data types to the appendix on dates and times.
2002-01-04 18:02:25 +01:00
</tbody>
</tgroup>
</table>
<para>
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
<xref linkend="datetime-mod-table"/> shows the tokens that serve
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
various modifier purposes.
</para>
<table id="datetime-mod-table">
<title>Date/Time Field Modifiers</title>
Add more complete details on date/time keywords and parsing rules. Move some tabular information on these from the chapter on data types to the appendix on dates and times.
2002-01-04 18:02:25 +01:00
<tgroup cols="2">
<thead>
<row>
Last batch of updates in response to 7.4 interactive docs comments.
2005-01-09 19:58:10 +01:00
<entry>Identifier</entry>
<entry>Description</entry>
Add more complete details on date/time keywords and parsing rules. Move some tabular information on these from the chapter on data types to the appendix on dates and times.
2002-01-04 18:02:25 +01:00
</row>
</thead>
<tbody>
<row>
Last batch of updates in response to 7.4 interactive docs comments.
2005-01-09 19:58:10 +01:00
<entry><literal>AM</literal></entry>
<entry>Time is before 12:00</entry>
Add more complete details on date/time keywords and parsing rules. Move some tabular information on these from the chapter on data types to the appendix on dates and times.
2002-01-04 18:02:25 +01:00
</row>
<row>
Last batch of updates in response to 7.4 interactive docs comments.
2005-01-09 19:58:10 +01:00
<entry><literal>AT</literal></entry>
<entry>Ignored</entry>
Add more complete details on date/time keywords and parsing rules. Move some tabular information on these from the chapter on data types to the appendix on dates and times.
2002-01-04 18:02:25 +01:00
</row>
<row>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<entry><literal>JULIAN</literal>, <literal>JD</literal>, <literal>J</literal></entry>
Improve documentation around historical calendar rules. Get rid of section 8.5.6 (Date/Time Internals), which appears to confuse people more than it helps, and anyway discussion of Postgres' internal datetime calculation methods seems pretty out of place here. Instead, make datatype.sgml just say that we follow the Gregorian calendar (a bit of specification not previously present anywhere in that chapter :-() and link to the History of Units appendix for more info. Do some mild editorialization on that appendix, too, to make it clearer that we are following proleptic Gregorian calendar rules rather than anything more historically accurate. Per a question from Florence Cousin and subsequent discussion in pgsql-docs.
2012-04-27 00:28:52 +02:00
<entry>Next field is Julian Date</entry>
Add more complete details on date/time keywords and parsing rules. Move some tabular information on these from the chapter on data types to the appendix on dates and times.
2002-01-04 18:02:25 +01:00
</row>
<row>
Last batch of updates in response to 7.4 interactive docs comments.
2005-01-09 19:58:10 +01:00
<entry><literal>ON</literal></entry>
<entry>Ignored</entry>
Add more complete details on date/time keywords and parsing rules. Move some tabular information on these from the chapter on data types to the appendix on dates and times.
2002-01-04 18:02:25 +01:00
</row>
<row>
Last batch of updates in response to 7.4 interactive docs comments.
2005-01-09 19:58:10 +01:00
<entry><literal>PM</literal></entry>
<entry>Time is on or after 12:00</entry>
Add more complete details on date/time keywords and parsing rules. Move some tabular information on these from the chapter on data types to the appendix on dates and times.
2002-01-04 18:02:25 +01:00
</row>
<row>
Last batch of updates in response to 7.4 interactive docs comments.
2005-01-09 19:58:10 +01:00
<entry><literal>T</literal></entry>
<entry>Next field is time</entry>
Add more complete details on date/time keywords and parsing rules. Move some tabular information on these from the chapter on data types to the appendix on dates and times.
2002-01-04 18:02:25 +01:00
</row>
</tbody>
</tgroup>
</table>
Move incorrectly-located indexterm entry.
2006-09-22 18:35:55 +02:00
</sect1>
<sect1 id="datetime-config-files">
<title>Date/Time Configuration Files</title>
Add more complete details on date/time keywords and parsing rules. Move some tabular information on these from the chapter on data types to the appendix on dates and times.
2002-01-04 18:02:25 +01:00
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<indexterm>
Add/edit index entries.
2003-08-31 19:32:24 +02:00
<primary>time zone</primary>
Update documentation to reflect the fact that we now know exactly what time zone names we support.
2004-08-10 02:55:08 +02:00
<secondary>input abbreviations</secondary>
Deprecate 'current' for date/time input. Fix up references to "PostgreSQL" rather than "Postgres". Was roughly evenly split between the two before. ref/ files not yet done.
2001-11-21 06:53:41 +01:00
</indexterm>
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.
2006-07-25 05:51:23 +02:00
<para>
Since timezone abbreviations are not well standardized,
<productname>PostgreSQL</productname> provides a means to customize
the set of abbreviations accepted by the server. The
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
<xref linkend="guc-timezone-abbreviations"/> run-time parameter
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.
2006-07-25 05:51:23 +02:00
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 &mdash; they
are in fact names of configuration files stored in
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<filename>.../share/timezonesets/</filename> of the installation directory.
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.
2006-07-25 05:51:23 +02:00
By adding or altering files in that directory, the administrator
can set local policy for timezone abbreviations.
</para>
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<varname>timezone_abbreviations</varname> can be set to any file name
found in <filename>.../share/timezonesets/</filename>, if the file's name
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.
2006-07-25 05:51:23 +02:00
is entirely alphabetic. (The prohibition against non-alphabetic
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
characters in <varname>timezone_abbreviations</varname> prevents reading
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.
2006-07-25 05:51:23 +02:00
files outside the intended directory, as well as reading editor
backup files and other extraneous files.)
</para>
<para>
Update documentation on may/can/might: Standard English uses "may", "can", and "might" in different ways: may - permission, "You may borrow my rake." can - ability, "I can lift that log." might - possibility, "It might rain today." Unfortunately, in conversational English, their use is often mixed, as in, "You may use this variable to do X", when in fact, "can" is a better choice. Similarly, "It may crash" is better stated, "It might crash". Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
A timezone abbreviation file can contain blank lines and comments
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
beginning with <literal>#</literal>. Non-comment lines must have one of
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.
2006-07-25 05:51:23 +02:00
these formats:
<synopsis>
Support timezone abbreviations that sometimes change. Up to now, PG has assumed that any given timezone abbreviation (such as "EDT") represents a constant GMT offset in the usage of any particular region; we had a way to configure what that offset was, but not for it to be changeable over time. But, as with most things horological, this view of the world is too simplistic: there are numerous regions that have at one time or another switched to a different GMT offset but kept using the same timezone abbreviation. Almost the entire Russian Federation did that a few years ago, and later this month they're going to do it again. And there are similar examples all over the world. To cope with this, invent the notion of a "dynamic timezone abbreviation", which is one that is referenced to a particular underlying timezone (as defined in the IANA timezone database) and means whatever it currently means in that zone. For zones that use or have used daylight-savings time, the standard and DST abbreviations continue to have the property that you can specify standard or DST time and get that time offset whether or not DST was theoretically in effect at the time. However, the abbreviations mean what they meant at the time in question (or most recently before that time) rather than being absolutely fixed. The standard abbreviation-list files have been changed to use this behavior for abbreviations that have actually varied in meaning since 1970. The old simple-numeric definitions are kept for abbreviations that have not changed, since they are a bit faster to resolve. While this is clearly a new feature, it seems necessary to back-patch it into all active branches, because otherwise use of Russian zone abbreviations is going to become even more problematic than it already was. This change supersedes the changes in commit 513d06ded et al to modify the fixed meanings of the Russian abbreviations; since we've not shipped that yet, this will avoid an undesirably incompatible (not to mention incorrect) change in behavior for timestamps between 2011 and 2014. This patch makes some cosmetic changes in ecpglib to keep its usage of datetime lookup tables as similar as possible to the backend code, but doesn't do anything about the increasingly obsolete set of timezone abbreviation definitions that are hard-wired into ecpglib. Whatever we do about that will likely not be appropriate material for back-patching. Also, a potential free() of a garbage pointer after an out-of-memory failure in ecpglib has been fixed. This patch also fixes pre-existing bugs in DetermineTimeZoneOffset() that caused it to produce unexpected results near a timezone transition, if both the "before" and "after" states are marked as standard time. We'd only ever thought about or tested transitions between standard and DST time, but that's not what's happening when a zone simply redefines their base GMT offset. In passing, update the SGML documentation to refer to the Olson/zoneinfo/ zic timezone database as the "IANA" database, since it's now being maintained under the auspices of IANA.
2014-10-16 21:22:10 +02:00
<replaceable>zone_abbreviation</replaceable> <replaceable>offset</replaceable>
<replaceable>zone_abbreviation</replaceable> <replaceable>offset</replaceable> D
<replaceable>zone_abbreviation</replaceable> <replaceable>time_zone_name</replaceable>
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.
2006-07-25 05:51:23 +02:00
@INCLUDE <replaceable>file_name</replaceable>
@OVERRIDE
</synopsis>
</para>
<para>
Support timezone abbreviations that sometimes change. Up to now, PG has assumed that any given timezone abbreviation (such as "EDT") represents a constant GMT offset in the usage of any particular region; we had a way to configure what that offset was, but not for it to be changeable over time. But, as with most things horological, this view of the world is too simplistic: there are numerous regions that have at one time or another switched to a different GMT offset but kept using the same timezone abbreviation. Almost the entire Russian Federation did that a few years ago, and later this month they're going to do it again. And there are similar examples all over the world. To cope with this, invent the notion of a "dynamic timezone abbreviation", which is one that is referenced to a particular underlying timezone (as defined in the IANA timezone database) and means whatever it currently means in that zone. For zones that use or have used daylight-savings time, the standard and DST abbreviations continue to have the property that you can specify standard or DST time and get that time offset whether or not DST was theoretically in effect at the time. However, the abbreviations mean what they meant at the time in question (or most recently before that time) rather than being absolutely fixed. The standard abbreviation-list files have been changed to use this behavior for abbreviations that have actually varied in meaning since 1970. The old simple-numeric definitions are kept for abbreviations that have not changed, since they are a bit faster to resolve. While this is clearly a new feature, it seems necessary to back-patch it into all active branches, because otherwise use of Russian zone abbreviations is going to become even more problematic than it already was. This change supersedes the changes in commit 513d06ded et al to modify the fixed meanings of the Russian abbreviations; since we've not shipped that yet, this will avoid an undesirably incompatible (not to mention incorrect) change in behavior for timestamps between 2011 and 2014. This patch makes some cosmetic changes in ecpglib to keep its usage of datetime lookup tables as similar as possible to the backend code, but doesn't do anything about the increasingly obsolete set of timezone abbreviation definitions that are hard-wired into ecpglib. Whatever we do about that will likely not be appropriate material for back-patching. Also, a potential free() of a garbage pointer after an out-of-memory failure in ecpglib has been fixed. This patch also fixes pre-existing bugs in DetermineTimeZoneOffset() that caused it to produce unexpected results near a timezone transition, if both the "before" and "after" states are marked as standard time. We'd only ever thought about or tested transitions between standard and DST time, but that's not what's happening when a zone simply redefines their base GMT offset. In passing, update the SGML documentation to refer to the Olson/zoneinfo/ zic timezone database as the "IANA" database, since it's now being maintained under the auspices of IANA.
2014-10-16 21:22:10 +02:00
A <replaceable>zone_abbreviation</replaceable> is just the abbreviation
Don't require dynamic timezone abbreviations to match underlying time zone. Previously, we threw an error if a dynamic timezone abbreviation did not match any abbreviation recorded in the referenced IANA time zone entry. That seemed like a good consistency check at the time, but it turns out that a number of the abbreviations in the IANA database are things that Olson and crew made up out of whole cloth. Their current policy is to remove such names in favor of using simple numeric offsets. Perhaps unsurprisingly, a lot of these made-up abbreviations have varied in meaning over time, which meant that our commit b2cbced9e and later changes made them into dynamic abbreviations. So with newer IANA database versions that don't mention these abbreviations at all, we fail, as reported in bug #14307 from Neil Anderson. It's worse than just a few unused-in-the-wild abbreviations not working, because the pg_timezone_abbrevs view stops working altogether (since its underlying function tries to compute the whole view result in one call). We considered deleting these abbreviations from our abbreviations list, but the problem with that is that we can't stay ahead of possible future IANA changes. Instead, let's leave the abbreviations list alone, and treat any "orphaned" dynamic abbreviation as just meaning the referenced time zone. It will behave a bit differently than it used to, in that you can't any longer override the zone's standard vs. daylight rule by using the "wrong" abbreviation of a pair, but that's better than failing entirely. (Also, this solution can be interpreted as adding a small new feature, which is that any abbreviation a user wants can be defined as referencing a time zone name.) Back-patch to all supported branches, since this problem affects all of them when using tzdata 2016f or newer. Report: <20160902031551.15674.67337@wrigleys.postgresql.org> Discussion: <6189.1472820913@sss.pgh.pa.us>
2016-09-02 23:29:31 +02:00
being defined. An <replaceable>offset</replaceable> is an integer giving
the equivalent 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.
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<literal>D</literal> indicates that the zone name represents local
Don't require dynamic timezone abbreviations to match underlying time zone. Previously, we threw an error if a dynamic timezone abbreviation did not match any abbreviation recorded in the referenced IANA time zone entry. That seemed like a good consistency check at the time, but it turns out that a number of the abbreviations in the IANA database are things that Olson and crew made up out of whole cloth. Their current policy is to remove such names in favor of using simple numeric offsets. Perhaps unsurprisingly, a lot of these made-up abbreviations have varied in meaning over time, which meant that our commit b2cbced9e and later changes made them into dynamic abbreviations. So with newer IANA database versions that don't mention these abbreviations at all, we fail, as reported in bug #14307 from Neil Anderson. It's worse than just a few unused-in-the-wild abbreviations not working, because the pg_timezone_abbrevs view stops working altogether (since its underlying function tries to compute the whole view result in one call). We considered deleting these abbreviations from our abbreviations list, but the problem with that is that we can't stay ahead of possible future IANA changes. Instead, let's leave the abbreviations list alone, and treat any "orphaned" dynamic abbreviation as just meaning the referenced time zone. It will behave a bit differently than it used to, in that you can't any longer override the zone's standard vs. daylight rule by using the "wrong" abbreviation of a pair, but that's better than failing entirely. (Also, this solution can be interpreted as adding a small new feature, which is that any abbreviation a user wants can be defined as referencing a time zone name.) Back-patch to all supported branches, since this problem affects all of them when using tzdata 2016f or newer. Report: <20160902031551.15674.67337@wrigleys.postgresql.org> Discussion: <6189.1472820913@sss.pgh.pa.us>
2016-09-02 23:29:31 +02:00
daylight-savings time rather than standard time.
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.
2006-07-25 05:51:23 +02:00
</para>
Don't require dynamic timezone abbreviations to match underlying time zone. Previously, we threw an error if a dynamic timezone abbreviation did not match any abbreviation recorded in the referenced IANA time zone entry. That seemed like a good consistency check at the time, but it turns out that a number of the abbreviations in the IANA database are things that Olson and crew made up out of whole cloth. Their current policy is to remove such names in favor of using simple numeric offsets. Perhaps unsurprisingly, a lot of these made-up abbreviations have varied in meaning over time, which meant that our commit b2cbced9e and later changes made them into dynamic abbreviations. So with newer IANA database versions that don't mention these abbreviations at all, we fail, as reported in bug #14307 from Neil Anderson. It's worse than just a few unused-in-the-wild abbreviations not working, because the pg_timezone_abbrevs view stops working altogether (since its underlying function tries to compute the whole view result in one call). We considered deleting these abbreviations from our abbreviations list, but the problem with that is that we can't stay ahead of possible future IANA changes. Instead, let's leave the abbreviations list alone, and treat any "orphaned" dynamic abbreviation as just meaning the referenced time zone. It will behave a bit differently than it used to, in that you can't any longer override the zone's standard vs. daylight rule by using the "wrong" abbreviation of a pair, but that's better than failing entirely. (Also, this solution can be interpreted as adding a small new feature, which is that any abbreviation a user wants can be defined as referencing a time zone name.) Back-patch to all supported branches, since this problem affects all of them when using tzdata 2016f or newer. Report: <20160902031551.15674.67337@wrigleys.postgresql.org> Discussion: <6189.1472820913@sss.pgh.pa.us>
2016-09-02 23:29:31 +02:00
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
Alternatively, a <replaceable>time_zone_name</replaceable> can be given, referencing
Don't require dynamic timezone abbreviations to match underlying time zone. Previously, we threw an error if a dynamic timezone abbreviation did not match any abbreviation recorded in the referenced IANA time zone entry. That seemed like a good consistency check at the time, but it turns out that a number of the abbreviations in the IANA database are things that Olson and crew made up out of whole cloth. Their current policy is to remove such names in favor of using simple numeric offsets. Perhaps unsurprisingly, a lot of these made-up abbreviations have varied in meaning over time, which meant that our commit b2cbced9e and later changes made them into dynamic abbreviations. So with newer IANA database versions that don't mention these abbreviations at all, we fail, as reported in bug #14307 from Neil Anderson. It's worse than just a few unused-in-the-wild abbreviations not working, because the pg_timezone_abbrevs view stops working altogether (since its underlying function tries to compute the whole view result in one call). We considered deleting these abbreviations from our abbreviations list, but the problem with that is that we can't stay ahead of possible future IANA changes. Instead, let's leave the abbreviations list alone, and treat any "orphaned" dynamic abbreviation as just meaning the referenced time zone. It will behave a bit differently than it used to, in that you can't any longer override the zone's standard vs. daylight rule by using the "wrong" abbreviation of a pair, but that's better than failing entirely. (Also, this solution can be interpreted as adding a small new feature, which is that any abbreviation a user wants can be defined as referencing a time zone name.) Back-patch to all supported branches, since this problem affects all of them when using tzdata 2016f or newer. Report: <20160902031551.15674.67337@wrigleys.postgresql.org> Discussion: <6189.1472820913@sss.pgh.pa.us>
2016-09-02 23:29:31 +02:00
a zone name defined in the IANA timezone database. The zone's definition
is consulted to see whether the abbreviation is or has been in use in
that zone, and if so, the appropriate meaning is used &mdash; that is,
the meaning that was currently in use at the timestamp whose value is
being determined, or the meaning in use immediately before that if it
wasn't current at that time, or the oldest meaning if it was used only
after that time. This behavior is essential for dealing with
abbreviations whose meaning has historically varied. It is also allowed
to define an abbreviation in terms of a zone name in which that
abbreviation does not appear; then using the abbreviation is just
equivalent to writing out the zone name.
</para>
<tip>
<para>
Using a simple integer <replaceable>offset</replaceable> is preferred
when defining an abbreviation whose offset from UTC has never changed,
as such abbreviations are much cheaper to process than those that
require consulting a time zone definition.
</para>
</tip>
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.
2006-07-25 05:51:23 +02:00
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
The <literal>@INCLUDE</literal> syntax allows inclusion of another file in the
<filename>.../share/timezonesets/</filename> directory. Inclusion can be nested,
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.
2006-07-25 05:51:23 +02:00
to a limited depth.
</para>
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
The <literal>@OVERRIDE</literal> syntax indicates that subsequent entries in the
Support timezone abbreviations that sometimes change. Up to now, PG has assumed that any given timezone abbreviation (such as "EDT") represents a constant GMT offset in the usage of any particular region; we had a way to configure what that offset was, but not for it to be changeable over time. But, as with most things horological, this view of the world is too simplistic: there are numerous regions that have at one time or another switched to a different GMT offset but kept using the same timezone abbreviation. Almost the entire Russian Federation did that a few years ago, and later this month they're going to do it again. And there are similar examples all over the world. To cope with this, invent the notion of a "dynamic timezone abbreviation", which is one that is referenced to a particular underlying timezone (as defined in the IANA timezone database) and means whatever it currently means in that zone. For zones that use or have used daylight-savings time, the standard and DST abbreviations continue to have the property that you can specify standard or DST time and get that time offset whether or not DST was theoretically in effect at the time. However, the abbreviations mean what they meant at the time in question (or most recently before that time) rather than being absolutely fixed. The standard abbreviation-list files have been changed to use this behavior for abbreviations that have actually varied in meaning since 1970. The old simple-numeric definitions are kept for abbreviations that have not changed, since they are a bit faster to resolve. While this is clearly a new feature, it seems necessary to back-patch it into all active branches, because otherwise use of Russian zone abbreviations is going to become even more problematic than it already was. This change supersedes the changes in commit 513d06ded et al to modify the fixed meanings of the Russian abbreviations; since we've not shipped that yet, this will avoid an undesirably incompatible (not to mention incorrect) change in behavior for timestamps between 2011 and 2014. This patch makes some cosmetic changes in ecpglib to keep its usage of datetime lookup tables as similar as possible to the backend code, but doesn't do anything about the increasingly obsolete set of timezone abbreviation definitions that are hard-wired into ecpglib. Whatever we do about that will likely not be appropriate material for back-patching. Also, a potential free() of a garbage pointer after an out-of-memory failure in ecpglib has been fixed. This patch also fixes pre-existing bugs in DetermineTimeZoneOffset() that caused it to produce unexpected results near a timezone transition, if both the "before" and "after" states are marked as standard time. We'd only ever thought about or tested transitions between standard and DST time, but that's not what's happening when a zone simply redefines their base GMT offset. In passing, update the SGML documentation to refer to the Olson/zoneinfo/ zic timezone database as the "IANA" database, since it's now being maintained under the auspices of IANA.
2014-10-16 21:22:10 +02:00
file can override previous entries (typically, entries obtained from
included files). Without this, conflicting definitions of the same
timezone abbreviation are considered an error.
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.
2006-07-25 05:51:23 +02:00
</para>
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
In an unmodified installation, the file <filename>Default</filename> contains
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.
2006-07-25 05:51:23 +02:00
all the non-conflicting time zone abbreviations for most of the world.
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
Additional files <filename>Australia</filename> and <filename>India</filename> are
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.
2006-07-25 05:51:23 +02:00
provided for those regions: these files first include the
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<literal>Default</literal> file and then add or modify abbreviations as needed.
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.
2006-07-25 05:51:23 +02:00
</para>
<para>
For reference purposes, a standard installation also contains files
doc: Properly punctuate "etc."
2022-05-19 09:27:34 +02:00
<filename>Africa.txt</filename>, <filename>America.txt</filename>, etc., containing
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.
2006-07-25 05:51:23 +02:00
information about every time zone abbreviation known to be in use
Support timezone abbreviations that sometimes change. Up to now, PG has assumed that any given timezone abbreviation (such as "EDT") represents a constant GMT offset in the usage of any particular region; we had a way to configure what that offset was, but not for it to be changeable over time. But, as with most things horological, this view of the world is too simplistic: there are numerous regions that have at one time or another switched to a different GMT offset but kept using the same timezone abbreviation. Almost the entire Russian Federation did that a few years ago, and later this month they're going to do it again. And there are similar examples all over the world. To cope with this, invent the notion of a "dynamic timezone abbreviation", which is one that is referenced to a particular underlying timezone (as defined in the IANA timezone database) and means whatever it currently means in that zone. For zones that use or have used daylight-savings time, the standard and DST abbreviations continue to have the property that you can specify standard or DST time and get that time offset whether or not DST was theoretically in effect at the time. However, the abbreviations mean what they meant at the time in question (or most recently before that time) rather than being absolutely fixed. The standard abbreviation-list files have been changed to use this behavior for abbreviations that have actually varied in meaning since 1970. The old simple-numeric definitions are kept for abbreviations that have not changed, since they are a bit faster to resolve. While this is clearly a new feature, it seems necessary to back-patch it into all active branches, because otherwise use of Russian zone abbreviations is going to become even more problematic than it already was. This change supersedes the changes in commit 513d06ded et al to modify the fixed meanings of the Russian abbreviations; since we've not shipped that yet, this will avoid an undesirably incompatible (not to mention incorrect) change in behavior for timestamps between 2011 and 2014. This patch makes some cosmetic changes in ecpglib to keep its usage of datetime lookup tables as similar as possible to the backend code, but doesn't do anything about the increasingly obsolete set of timezone abbreviation definitions that are hard-wired into ecpglib. Whatever we do about that will likely not be appropriate material for back-patching. Also, a potential free() of a garbage pointer after an out-of-memory failure in ecpglib has been fixed. This patch also fixes pre-existing bugs in DetermineTimeZoneOffset() that caused it to produce unexpected results near a timezone transition, if both the "before" and "after" states are marked as standard time. We'd only ever thought about or tested transitions between standard and DST time, but that's not what's happening when a zone simply redefines their base GMT offset. In passing, update the SGML documentation to refer to the Olson/zoneinfo/ zic timezone database as the "IANA" database, since it's now being maintained under the auspices of IANA.
2014-10-16 21:22:10 +02:00
according to the IANA timezone database. The zone name
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.
2006-07-25 05:51:23 +02:00
definitions found in these files can be copied and pasted into a custom
configuration file as needed. Note that these files cannot be directly
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
referenced as <varname>timezone_abbreviations</varname> settings, because of
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.
2006-07-25 05:51:23 +02:00
the dot embedded in their names.
</para>
Update timezone documentation to reflect current reality: instead of giving tables of known timezone names, refer the user to the system views. Joachim Wieland
2006-09-22 18:20:00 +02:00
<note>
<para>
Support timezone abbreviations that sometimes change. Up to now, PG has assumed that any given timezone abbreviation (such as "EDT") represents a constant GMT offset in the usage of any particular region; we had a way to configure what that offset was, but not for it to be changeable over time. But, as with most things horological, this view of the world is too simplistic: there are numerous regions that have at one time or another switched to a different GMT offset but kept using the same timezone abbreviation. Almost the entire Russian Federation did that a few years ago, and later this month they're going to do it again. And there are similar examples all over the world. To cope with this, invent the notion of a "dynamic timezone abbreviation", which is one that is referenced to a particular underlying timezone (as defined in the IANA timezone database) and means whatever it currently means in that zone. For zones that use or have used daylight-savings time, the standard and DST abbreviations continue to have the property that you can specify standard or DST time and get that time offset whether or not DST was theoretically in effect at the time. However, the abbreviations mean what they meant at the time in question (or most recently before that time) rather than being absolutely fixed. The standard abbreviation-list files have been changed to use this behavior for abbreviations that have actually varied in meaning since 1970. The old simple-numeric definitions are kept for abbreviations that have not changed, since they are a bit faster to resolve. While this is clearly a new feature, it seems necessary to back-patch it into all active branches, because otherwise use of Russian zone abbreviations is going to become even more problematic than it already was. This change supersedes the changes in commit 513d06ded et al to modify the fixed meanings of the Russian abbreviations; since we've not shipped that yet, this will avoid an undesirably incompatible (not to mention incorrect) change in behavior for timestamps between 2011 and 2014. This patch makes some cosmetic changes in ecpglib to keep its usage of datetime lookup tables as similar as possible to the backend code, but doesn't do anything about the increasingly obsolete set of timezone abbreviation definitions that are hard-wired into ecpglib. Whatever we do about that will likely not be appropriate material for back-patching. Also, a potential free() of a garbage pointer after an out-of-memory failure in ecpglib has been fixed. This patch also fixes pre-existing bugs in DetermineTimeZoneOffset() that caused it to produce unexpected results near a timezone transition, if both the "before" and "after" states are marked as standard time. We'd only ever thought about or tested transitions between standard and DST time, but that's not what's happening when a zone simply redefines their base GMT offset. In passing, update the SGML documentation to refer to the Olson/zoneinfo/ zic timezone database as the "IANA" database, since it's now being maintained under the auspices of IANA.
2014-10-16 21:22:10 +02:00
If an error occurs while reading the time zone abbreviation set, no new
value is applied and the old set is kept. If the error occurs while
starting the database, startup fails.
Update timezone documentation to reflect current reality: instead of giving tables of known timezone names, refer the user to the system views. Joachim Wieland
2006-09-22 18:20:00 +02:00
</para>
</note>
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.
2006-07-25 05:51:23 +02:00
<caution>
<para>
Time zone abbreviations defined in the configuration file override
non-timezone meanings built into <productname>PostgreSQL</productname>.
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
For example, the <filename>Australia</filename> configuration file defines
<literal>SAT</literal> (for South Australian Standard Time). When this
file is active, <literal>SAT</literal> will not be recognized as an abbreviation
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.
2006-07-25 05:51:23 +02:00
for Saturday.
</para>
</caution>
<caution>
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
If you modify files in <filename>.../share/timezonesets/</filename>,
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.
2006-07-25 05:51:23 +02:00
it is up to you to make backups &mdash; a normal database dump
will not include this directory.
</para>
</caution>
</sect1>
Doc: document POSIX-style time zone specifications in full. We'd glossed over most of this complexity for years, but it's hard to avoid writing it all down now, so that we can explain what happens when there's no "posixrules" file in the IANA time zone database. That was at best a tiny minority situation till now, but it's likely to become quite common in the future, so we'd better explain it. Nonetheless, we don't really encourage people to use POSIX zone specs; picking a named zone is almost always what you really want, unless perhaps you're stuck with an out-of-date zone database. Therefore, let's shove all this detail into an appendix. Patch by me; thanks to Robert Haas for help with some awkward wording. Discussion: https://postgr.es/m/1390.1562258309@sss.pgh.pa.us
2020-06-18 22:27:18 +02:00
<sect1 id="datetime-posix-timezone-specs">
<title><acronym>POSIX</acronym> Time Zone Specifications</title>
<indexterm zone="datetime-posix-timezone-specs">
<primary>time zone</primary>
<secondary><acronym>POSIX</acronym>-style specification</secondary>
</indexterm>
<para>
doc: Fix format, incorrect structure names and markup inconsistencies Author: Alexander Lakhin Discussion: https://postgr.es/m/a2345841-10a5-4eef-257c-02302347cf39@gmail.com Backpatch-through: 13
2020-08-22 15:26:10 +02:00
<productname>PostgreSQL</productname> can accept time zone specifications
that are written according to the <acronym>POSIX</acronym> standard's rules
Doc: document POSIX-style time zone specifications in full. We'd glossed over most of this complexity for years, but it's hard to avoid writing it all down now, so that we can explain what happens when there's no "posixrules" file in the IANA time zone database. That was at best a tiny minority situation till now, but it's likely to become quite common in the future, so we'd better explain it. Nonetheless, we don't really encourage people to use POSIX zone specs; picking a named zone is almost always what you really want, unless perhaps you're stuck with an out-of-date zone database. Therefore, let's shove all this detail into an appendix. Patch by me; thanks to Robert Haas for help with some awkward wording. Discussion: https://postgr.es/m/1390.1562258309@sss.pgh.pa.us
2020-06-18 22:27:18 +02:00
for the <varname>TZ</varname> environment
variable. <acronym>POSIX</acronym> time zone specifications are
inadequate to deal with the complexity of real-world time zone history,
but there are sometimes reasons to use them.
</para>
<para>
A POSIX time zone specification has the form
<synopsis>
<replaceable>STD</replaceable> <replaceable>offset</replaceable> <optional> <replaceable>DST</replaceable> <optional> <replaceable>dstoffset</replaceable> </optional> <optional> , <replaceable>rule</replaceable> </optional> </optional>
</synopsis>
(For readability, we show spaces between the fields, but spaces should
not be used in practice.) The fields are:
<itemizedlist>
<listitem>
<para>
<replaceable>STD</replaceable> is the zone abbreviation to be used
for standard time.
</para>
</listitem>
<listitem>
<para>
<replaceable>offset</replaceable> is the zone's standard-time offset
from UTC.
</para>
</listitem>
<listitem>
<para>
<replaceable>DST</replaceable> is the zone abbreviation to be used
for daylight-savings time. If this field and the following ones are
omitted, the zone uses a fixed UTC offset with no daylight-savings
rule.
</para>
</listitem>
<listitem>
<para>
<replaceable>dstoffset</replaceable> is the daylight-savings offset
from UTC. This field is typically omitted, since it defaults to one
hour less than the standard-time <replaceable>offset</replaceable>,
which is usually the right thing.
</para>
</listitem>
<listitem>
<para>
<replaceable>rule</replaceable> defines the rule for when daylight
savings is in effect, as described below.
</para>
</listitem>
</itemizedlist>
</para>
<para>
In this syntax, a zone abbreviation can be a string of letters, such
as <literal>EST</literal>, or an arbitrary string surrounded by angle
brackets, such as <literal>&lt;UTC-05&gt;</literal>.
Note that the zone abbreviations given here are only used for output,
and even then only in some timestamp output formats. The zone
abbreviations recognized in timestamp input are determined as explained
in <xref linkend="datetime-config-files"/>.
</para>
<para>
The offset fields specify the hours, and optionally minutes and seconds,
difference from UTC. They have the format
<replaceable>hh</replaceable><optional><literal>:</literal><replaceable>mm</replaceable><optional><literal>:</literal><replaceable>ss</replaceable></optional></optional>
optionally with a leading sign (<literal>+</literal>
or <literal>-</literal>). The positive sign is used for
zones <emphasis>west</emphasis> of Greenwich. (Note that this is the
opposite of the ISO-8601 sign convention used elsewhere in
doc: Fix format, incorrect structure names and markup inconsistencies Author: Alexander Lakhin Discussion: https://postgr.es/m/a2345841-10a5-4eef-257c-02302347cf39@gmail.com Backpatch-through: 13
2020-08-22 15:26:10 +02:00
<productname>PostgreSQL</productname>.) <replaceable>hh</replaceable>
can have one or two digits; <replaceable>mm</replaceable>
Doc: document POSIX-style time zone specifications in full. We'd glossed over most of this complexity for years, but it's hard to avoid writing it all down now, so that we can explain what happens when there's no "posixrules" file in the IANA time zone database. That was at best a tiny minority situation till now, but it's likely to become quite common in the future, so we'd better explain it. Nonetheless, we don't really encourage people to use POSIX zone specs; picking a named zone is almost always what you really want, unless perhaps you're stuck with an out-of-date zone database. Therefore, let's shove all this detail into an appendix. Patch by me; thanks to Robert Haas for help with some awkward wording. Discussion: https://postgr.es/m/1390.1562258309@sss.pgh.pa.us
2020-06-18 22:27:18 +02:00
and <replaceable>ss</replaceable> (if used) must have two.
</para>
<para>
The daylight-savings transition <replaceable>rule</replaceable> has the
format
<synopsis>
<replaceable>dstdate</replaceable> <optional> <literal>/</literal> <replaceable>dsttime</replaceable> </optional> <literal>,</literal> <replaceable>stddate</replaceable> <optional> <literal>/</literal> <replaceable>stdtime</replaceable> </optional>
</synopsis>
(As before, spaces should not be included in practice.)
The <replaceable>dstdate</replaceable>
and <replaceable>dsttime</replaceable> fields define when daylight-savings
time starts, while <replaceable>stddate</replaceable>
and <replaceable>stdtime</replaceable> define when standard time
starts. (In some cases, notably in zones south of the equator, the
former might be later in the year than the latter.) The date fields
have one of these formats:
<variablelist>
<varlistentry>
<term><replaceable>n</replaceable></term>
<listitem>
<para>
A plain integer denotes a day of the year, counting from zero to
364, or to 365 in leap years.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>J</literal><replaceable>n</replaceable></term>
<listitem>
<para>
In this form, <replaceable>n</replaceable> counts from 1 to 365,
and February 29 is not counted even if it is present. (Thus, a
transition occurring on February 29 could not be specified this
way. However, days after February have the same numbers whether
it's a leap year or not, so that this form is usually more useful
than the plain-integer form for transitions on fixed dates.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>M</literal><replaceable>m</replaceable><literal>.</literal><replaceable>n</replaceable><literal>.</literal><replaceable>d</replaceable></term>
<listitem>
<para>
This form specifies a transition that always happens during the same
month and on the same day of the week. <replaceable>m</replaceable>
identifies the month, from 1 to 12. <replaceable>n</replaceable>
specifies the <replaceable>n</replaceable>'th occurrence of the
weekday identified by <replaceable>d</replaceable>.
<replaceable>n</replaceable> is a number between 1 and 4, or 5
meaning the last occurrence of that weekday in the month (which
could be the fourth or the fifth). <replaceable>d</replaceable> is
a number between 0 and 6, with 0 indicating Sunday.
For example, <literal>M3.2.0</literal> means <quote>the second
Sunday in March</quote>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<note>
<para>
The <literal>M</literal> format is sufficient to describe many common
daylight-savings transition laws. But note that none of these variants
can deal with daylight-savings law changes, so in practice the
historical data stored for named time zones (in the IANA time zone
database) is necessary to interpret past time stamps correctly.
</para>
</note>
<para>
The time fields in a transition rule have the same format as the offset
fields described previously, except that they cannot contain signs.
They define the current local time at which the change to the other
time occurs. If omitted, they default to <literal>02:00:00</literal>.
</para>
<para>
If a daylight-savings abbreviation is given but the
transition <replaceable>rule</replaceable> field is omitted,
the fallback behavior is to use the
rule <literal>M3.2.0,M11.1.0</literal>, which corresponds to USA
practice as of 2020 (that is, spring forward on the second Sunday of
March, fall back on the first Sunday of November, both transitions
Remove support for timezone "posixrules" file. The IANA tzcode library has a feature to read a time zone file named "posixrules" and apply the daylight-savings transition dates and times therein, when it is given a POSIX-style time zone specification that lacks an explicit transition rule. However, there's a problem with that code: it doesn't work for dates past the Y2038 time_t rollover. (Effectively, all times beyond that point are treated as standard time.) The IANA crew regard this feature as legacy, so their plan is to remove it not fix it. The time frame in which that will happen is unclear, but presumably it'll happen well before 2038. Moreover, effective with the next IANA data update (probably this fall), the recommended default will be to not install a "posixrules" file in the first place. The time frame in which tzdata packagers might adopt that suggestion is likewise unclear, but at least some platforms will probably do it in the next year or so. While we could ignore that recommendation so far as PG-supplied tzdata trees are concerned, builds using --with-system-tzdata will be subject to whatever the platform's tzdata packager decides to do. Thus, whether or not we do anything, some increasing fraction of Postgres users will be exposed to the behavior observed when there is no "posixrules" file; and if we do nothing, we'll have essentially no control over the timing of that change. The best thing to do to ameliorate the uncertainty seems to be to proactively remove the posixrules-reading feature. If we do that in a scheduled release then at least we can release-note the behavioral change, rather than having users be surprised by it after a routine tzdata update. The change in question is fairly minor anyway: to be affected, you have to be using a POSIX-style timezone spec, it has to not have an explicit rule, and it has to not be one of the four traditional continental-USA zone names (EST5EDT, CST6CDT, MST7MDT, or PST8PDT), as those are special-cased. Since the default "posixrules" file provides USA DST rules, the number of people who are likely to find such a zone spec useful is probably quite small. Moreover, the fallback behavior with no explicit rule and no "posixrules" file is to apply current USA rules, so the only thing that really breaks is the DST transitions in years before 2007 (and you get the countervailing fix that transitions after 2038 will be applied). Now, some installations might have replaced the "posixrules" file, allowing e.g. EU rules to be applied to a POSIX-style timezone spec. That won't work anymore. But it's not exactly clear why this solution would be preferable to using a regular named zone. In any case, given the Y2038 issue, we need to be pushing users to stop depending on this. Back-patch into v13; it hasn't been released yet, so it seems OK to change its behavior. (Personally I think we ought to back-patch further, but I've been outvoted.) Discussion: https://postgr.es/m/1390.1562258309@sss.pgh.pa.us Discussion: https://postgr.es/m/20200621211855.6211-1-eggert@cs.ucla.edu
2020-06-30 00:55:01 +02:00
occurring at 2AM prevailing time). Note that this rule does not
give correct USA transition dates for years before 2007.
Doc: document POSIX-style time zone specifications in full. We'd glossed over most of this complexity for years, but it's hard to avoid writing it all down now, so that we can explain what happens when there's no "posixrules" file in the IANA time zone database. That was at best a tiny minority situation till now, but it's likely to become quite common in the future, so we'd better explain it. Nonetheless, we don't really encourage people to use POSIX zone specs; picking a named zone is almost always what you really want, unless perhaps you're stuck with an out-of-date zone database. Therefore, let's shove all this detail into an appendix. Patch by me; thanks to Robert Haas for help with some awkward wording. Discussion: https://postgr.es/m/1390.1562258309@sss.pgh.pa.us
2020-06-18 22:27:18 +02:00
</para>
<para>
As an example, <literal>CET-1CEST,M3.5.0,M10.5.0/3</literal> describes
current (as of 2020) timekeeping practice in Paris. This specification
says that standard time has the abbreviation <literal>CET</literal> and
is one hour ahead (east) of UTC; daylight savings time has the
abbreviation <literal>CEST</literal> and is implicitly two hours ahead
of UTC; daylight savings time begins on the last Sunday in March at 2AM
CET and ends on the last Sunday in October at 3AM CEST.
</para>
Future-proof regression tests against possibly-missing posixrules file. The IANA time zone folk have deprecated use of a "posixrules" file in the tz database. While for now it's our choice whether to keep supplying one in our own builds, installations built with --with-system-tzdata will soon be needing to cope with that file not being present, at least on some platforms. This causes a problem for the horology test, which expected the nonstandard POSIX zone spec "CST7CDT" to apply pre-2007 US daylight savings rules. That does happen if the posixrules file supplies such information, but otherwise the test produces undesired results. To fix, add an explicit transition date rule that matches 2005 practice. (We could alternatively have switched the test to use some real time zone, but it seems useful to have coverage of this type of zone spec.) While at it, update a documentation example that also relied on "CST7CDT"; use a real-world zone name instead. Also, document why the zone names EST5EDT, CST6CDT, MST7MDT, PST8PDT aren't subject to similar failures when "posixrules" is missing. Back-patch to all supported branches, since the hazard is the same for all. Discussion: https://postgr.es/m/1665379.1592581287@sss.pgh.pa.us
2020-06-19 19:55:21 +02:00
<para>
The four timezone names <literal>EST5EDT</literal>,
<literal>CST6CDT</literal>, <literal>MST7MDT</literal>,
and <literal>PST8PDT</literal> look like they are POSIX zone
specifications. However, they actually are treated as named time zones
because (for historical reasons) there are files by those names in the
IANA time zone database. The practical implication of this is that
these zone names will produce valid historical USA daylight-savings
Remove support for timezone "posixrules" file. The IANA tzcode library has a feature to read a time zone file named "posixrules" and apply the daylight-savings transition dates and times therein, when it is given a POSIX-style time zone specification that lacks an explicit transition rule. However, there's a problem with that code: it doesn't work for dates past the Y2038 time_t rollover. (Effectively, all times beyond that point are treated as standard time.) The IANA crew regard this feature as legacy, so their plan is to remove it not fix it. The time frame in which that will happen is unclear, but presumably it'll happen well before 2038. Moreover, effective with the next IANA data update (probably this fall), the recommended default will be to not install a "posixrules" file in the first place. The time frame in which tzdata packagers might adopt that suggestion is likewise unclear, but at least some platforms will probably do it in the next year or so. While we could ignore that recommendation so far as PG-supplied tzdata trees are concerned, builds using --with-system-tzdata will be subject to whatever the platform's tzdata packager decides to do. Thus, whether or not we do anything, some increasing fraction of Postgres users will be exposed to the behavior observed when there is no "posixrules" file; and if we do nothing, we'll have essentially no control over the timing of that change. The best thing to do to ameliorate the uncertainty seems to be to proactively remove the posixrules-reading feature. If we do that in a scheduled release then at least we can release-note the behavioral change, rather than having users be surprised by it after a routine tzdata update. The change in question is fairly minor anyway: to be affected, you have to be using a POSIX-style timezone spec, it has to not have an explicit rule, and it has to not be one of the four traditional continental-USA zone names (EST5EDT, CST6CDT, MST7MDT, or PST8PDT), as those are special-cased. Since the default "posixrules" file provides USA DST rules, the number of people who are likely to find such a zone spec useful is probably quite small. Moreover, the fallback behavior with no explicit rule and no "posixrules" file is to apply current USA rules, so the only thing that really breaks is the DST transitions in years before 2007 (and you get the countervailing fix that transitions after 2038 will be applied). Now, some installations might have replaced the "posixrules" file, allowing e.g. EU rules to be applied to a POSIX-style timezone spec. That won't work anymore. But it's not exactly clear why this solution would be preferable to using a regular named zone. In any case, given the Y2038 issue, we need to be pushing users to stop depending on this. Back-patch into v13; it hasn't been released yet, so it seems OK to change its behavior. (Personally I think we ought to back-patch further, but I've been outvoted.) Discussion: https://postgr.es/m/1390.1562258309@sss.pgh.pa.us Discussion: https://postgr.es/m/20200621211855.6211-1-eggert@cs.ucla.edu
2020-06-30 00:55:01 +02:00
transitions, even when a plain POSIX specification would not.
Future-proof regression tests against possibly-missing posixrules file. The IANA time zone folk have deprecated use of a "posixrules" file in the tz database. While for now it's our choice whether to keep supplying one in our own builds, installations built with --with-system-tzdata will soon be needing to cope with that file not being present, at least on some platforms. This causes a problem for the horology test, which expected the nonstandard POSIX zone spec "CST7CDT" to apply pre-2007 US daylight savings rules. That does happen if the posixrules file supplies such information, but otherwise the test produces undesired results. To fix, add an explicit transition date rule that matches 2005 practice. (We could alternatively have switched the test to use some real time zone, but it seems useful to have coverage of this type of zone spec.) While at it, update a documentation example that also relied on "CST7CDT"; use a real-world zone name instead. Also, document why the zone names EST5EDT, CST6CDT, MST7MDT, PST8PDT aren't subject to similar failures when "posixrules" is missing. Back-patch to all supported branches, since the hazard is the same for all. Discussion: https://postgr.es/m/1665379.1592581287@sss.pgh.pa.us
2020-06-19 19:55:21 +02:00
</para>
Doc: document POSIX-style time zone specifications in full. We'd glossed over most of this complexity for years, but it's hard to avoid writing it all down now, so that we can explain what happens when there's no "posixrules" file in the IANA time zone database. That was at best a tiny minority situation till now, but it's likely to become quite common in the future, so we'd better explain it. Nonetheless, we don't really encourage people to use POSIX zone specs; picking a named zone is almost always what you really want, unless perhaps you're stuck with an out-of-date zone database. Therefore, let's shove all this detail into an appendix. Patch by me; thanks to Robert Haas for help with some awkward wording. Discussion: https://postgr.es/m/1390.1562258309@sss.pgh.pa.us
2020-06-18 22:27:18 +02:00
<para>
One should be wary that it is easy to misspell a POSIX-style time zone
specification, since there is no check on the reasonableness of the
zone abbreviation(s). For example, <literal>SET TIMEZONE TO
FOOBAR0</literal> will work, leaving the system effectively using a
rather peculiar abbreviation for UTC.
</para>
</sect1>
Big editing for consistent content and presentation.
2003-03-13 02:30:29 +01:00
<sect1 id="datetime-units-history">
Improve section heading for date/time history.
2000-05-02 22:36:21 +02:00
<title>History of Units</title>
Rearrange and consolidate the Admin Guide. Add reference pages for utilities and remove standalone chapters for same. Add material for an appendix on date/time properties, but not yet integrated with the User's Guide. Break up the former chapter on pg_options into Admin and Programmer's Guides.
1999-05-20 07:39:29 +02:00
Improve documentation around historical calendar rules. Get rid of section 8.5.6 (Date/Time Internals), which appears to confuse people more than it helps, and anyway discussion of Postgres' internal datetime calculation methods seems pretty out of place here. Instead, make datatype.sgml just say that we follow the Gregorian calendar (a bit of specification not previously present anywhere in that chapter :-() and link to the History of Units appendix for more info. Do some mild editorialization on that appendix, too, to make it clearer that we are following proleptic Gregorian calendar rules rather than anything more historically accurate. Per a question from Florence Cousin and subsequent discussion in pgsql-docs.
2012-04-27 00:28:52 +02:00
<indexterm zone="datetime-units-history">
<primary>Gregorian calendar</primary>
</indexterm>
<para>
The SQL standard states that <quote>Within the definition of a
<quote>datetime literal</quote>, the <quote>datetime
values</quote> are constrained by the natural rules for dates and
times according to the Gregorian calendar</quote>.
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<productname>PostgreSQL</productname> follows the SQL
Improve documentation around historical calendar rules. Get rid of section 8.5.6 (Date/Time Internals), which appears to confuse people more than it helps, and anyway discussion of Postgres' internal datetime calculation methods seems pretty out of place here. Instead, make datatype.sgml just say that we follow the Gregorian calendar (a bit of specification not previously present anywhere in that chapter :-() and link to the History of Units appendix for more info. Do some mild editorialization on that appendix, too, to make it clearer that we are following proleptic Gregorian calendar rules rather than anything more historically accurate. Per a question from Florence Cousin and subsequent discussion in pgsql-docs.
2012-04-27 00:28:52 +02:00
standard's lead by counting dates exclusively in the Gregorian
calendar, even for years before that calendar was in use.
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
This rule is known as the <firstterm>proleptic Gregorian calendar</firstterm>.
Improve documentation around historical calendar rules. Get rid of section 8.5.6 (Date/Time Internals), which appears to confuse people more than it helps, and anyway discussion of Postgres' internal datetime calculation methods seems pretty out of place here. Instead, make datatype.sgml just say that we follow the Gregorian calendar (a bit of specification not previously present anywhere in that chapter :-() and link to the History of Units appendix for more info. Do some mild editorialization on that appendix, too, to make it clearer that we are following proleptic Gregorian calendar rules rather than anything more historically accurate. Per a question from Florence Cousin and subsequent discussion in pgsql-docs.
2012-04-27 00:28:52 +02:00
</para>
Finish initial markup of cvs.sgml, and include it in the programmer's guide and the integrated doc. Clean up other markup.
1999-05-22 04:27:25 +02:00
<para>
Improve documentation about Julian dates; in particular, point out the difference between Julian and Gregorian reckoning of when JD 0 was.
2007-12-15 02:18:34 +01:00
The Julian calendar was introduced by Julius Caesar in 45 BC.
It was in common use in the Western world
Minor copy-editing.
2003-11-06 23:21:47 +01:00
until the year 1582, when countries started changing to the Gregorian
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
calendar. In the Julian calendar, the tropical year is
approximated as 365 1/4 days = 365.25 days. This gives an error of
about 1 day in 128 years.
Finish initial markup of cvs.sgml, and include it in the programmer's guide and the integrated doc. Clean up other markup.
1999-05-22 04:27:25 +02:00
</para>
Remove useless whitespace at end of lines
2010-11-23 21:27:50 +01:00
<para>
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
The accumulating calendar error prompted
Pope Gregory XIII to reform the calendar in accordance with
instructions from the Council of Trent.
Finish initial markup of cvs.sgml, and include it in the programmer's guide and the integrated doc. Clean up other markup.
1999-05-22 04:27:25 +02:00
In the Gregorian calendar, the tropical year is approximated as
365 + 97 / 400 days = 365.2425 days. Thus it takes approximately 3300
years for the tropical year to shift one day with respect to the
Gregorian calendar.
</para>
<para>
The approximation 365+97/400 is achieved by having 97 leap years
every 400 years, using the following rules:
<simplelist>
<member>
Clarify input/output timezone information. Add detail on exact interpretation of "concatenated date" for various lengths.
1999-06-23 08:17:51 +02:00
Every year divisible by 4 is a leap year.
Finish initial markup of cvs.sgml, and include it in the programmer's guide and the integrated doc. Clean up other markup.
1999-05-22 04:27:25 +02:00
</member>
<member>
Clarify input/output timezone information. Add detail on exact interpretation of "concatenated date" for various lengths.
1999-06-23 08:17:51 +02:00
However, every year divisible by 100 is not a leap year.
Finish initial markup of cvs.sgml, and include it in the programmer's guide and the integrated doc. Clean up other markup.
1999-05-22 04:27:25 +02:00
</member>
<member>
Clarify input/output timezone information. Add detail on exact interpretation of "concatenated date" for various lengths.
1999-06-23 08:17:51 +02:00
However, every year divisible by 400 is a leap year after all.
Finish initial markup of cvs.sgml, and include it in the programmer's guide and the integrated doc. Clean up other markup.
1999-05-22 04:27:25 +02:00
</member>
</simplelist>
So, 1700, 1800, 1900, 2100, and 2200 are not leap years. But 1600,
2000, and 2400 are leap years.
Minor copy-editing.
2003-11-06 23:21:47 +01:00
By contrast, in the older Julian calendar all years divisible by 4 are leap
years.
Finish initial markup of cvs.sgml, and include it in the programmer's guide and the integrated doc. Clean up other markup.
1999-05-22 04:27:25 +02:00
</para>
Back out tutorial changes: --------------------------------------------------------------------------- 1. In keeping with the recent discussion that there should be more said about views, stored procedures, and triggers, in the tutorial, I have added a bit of verbiage to that end. 2. Some formatting changes to the datetime discussion, as well as addition of a citation of a relevant book on calendars. Christopher Browne
2004-03-31 18:20:53 +02:00
<para>
The papal bull of February 1582 decreed that 10 days should be dropped
from October 1582 so that 15 October should follow immediately after
4 October.
This was observed in Italy, Poland, Portugal, and Spain. Other Catholic
countries followed shortly after, but Protestant countries were
Improve documentation about Julian dates; in particular, point out the difference between Julian and Gregorian reckoning of when JD 0 was.
2007-12-15 02:18:34 +01:00
reluctant to change, and the Greek Orthodox countries didn't change
Back out tutorial changes: --------------------------------------------------------------------------- 1. In keeping with the recent discussion that there should be more said about views, stored procedures, and triggers, in the tutorial, I have added a bit of verbiage to that end. 2. Some formatting changes to the datetime discussion, as well as addition of a citation of a relevant book on calendars. Christopher Browne
2004-03-31 18:20:53 +02:00
until the start of the 20th century.
Finish initial markup of cvs.sgml, and include it in the programmer's guide and the integrated doc. Clean up other markup.
1999-05-22 04:27:25 +02:00
Improve documentation around historical calendar rules. Get rid of section 8.5.6 (Date/Time Internals), which appears to confuse people more than it helps, and anyway discussion of Postgres' internal datetime calculation methods seems pretty out of place here. Instead, make datatype.sgml just say that we follow the Gregorian calendar (a bit of specification not previously present anywhere in that chapter :-() and link to the History of Units appendix for more info. Do some mild editorialization on that appendix, too, to make it clearer that we are following proleptic Gregorian calendar rules rather than anything more historically accurate. Per a question from Florence Cousin and subsequent discussion in pgsql-docs.
2012-04-27 00:28:52 +02:00
The reform was observed by Great Britain and its dominions (including what
is now the USA) in 1752.
Back out tutorial changes: --------------------------------------------------------------------------- 1. In keeping with the recent discussion that there should be more said about views, stored procedures, and triggers, in the tutorial, I have added a bit of verbiage to that end. 2. Some formatting changes to the datetime discussion, as well as addition of a citation of a relevant book on calendars. Christopher Browne
2004-03-31 18:20:53 +02:00
Thus 2 September 1752 was followed by 14 September 1752.
Finish initial markup of cvs.sgml, and include it in the programmer's guide and the integrated doc. Clean up other markup.
1999-05-22 04:27:25 +02:00
Document handling of invalid/ambiguous timestamp input near DST boundaries. The source code comments documented this, but the user-facing docs, not so much. Add a section to Appendix B that discusses it. In passing, improve a couple other things in Appendix B --- notably, a long-obsolete claim that time zone abbreviations are looked up in a fixed table. Per bug #15527 from Michael Davidson. Discussion: https://postgr.es/m/15527-f1be0b4dc99ebbe7@postgresql.org
2018-11-30 00:28:10 +01:00
This is why Unix systems that have the <command>cal</command> program
Back out tutorial changes: --------------------------------------------------------------------------- 1. In keeping with the recent discussion that there should be more said about views, stored procedures, and triggers, in the tutorial, I have added a bit of verbiage to that end. 2. Some formatting changes to the datetime discussion, as well as addition of a citation of a relevant book on calendars. Christopher Browne
2004-03-31 18:20:53 +02:00
produce the following:
Finish initial markup of cvs.sgml, and include it in the programmer's guide and the integrated doc. Clean up other markup.
1999-05-22 04:27:25 +02:00
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
<screen>
$ <userinput>cal 9 1752</userinput>
Finish initial markup of cvs.sgml, and include it in the programmer's guide and the integrated doc. Clean up other markup.
1999-05-22 04:27:25 +02:00
September 1752
S M Tu W Th F S
1 2 14 15 16
17 18 19 20 21 22 23
24 25 26 27 28 29 30
Merge documentation updates from 7.3 branch.
2002-11-11 21:14:04 +01:00
</screen>
Rearrange and consolidate the Admin Guide. Add reference pages for utilities and remove standalone chapters for same. Add material for an appendix on date/time properties, but not yet integrated with the User's Guide. Break up the former chapter on pg_options into Admin and Programmer's Guides.
1999-05-20 07:39:29 +02:00
Improve documentation around historical calendar rules. Get rid of section 8.5.6 (Date/Time Internals), which appears to confuse people more than it helps, and anyway discussion of Postgres' internal datetime calculation methods seems pretty out of place here. Instead, make datatype.sgml just say that we follow the Gregorian calendar (a bit of specification not previously present anywhere in that chapter :-() and link to the History of Units appendix for more info. Do some mild editorialization on that appendix, too, to make it clearer that we are following proleptic Gregorian calendar rules rather than anything more historically accurate. Per a question from Florence Cousin and subsequent discussion in pgsql-docs.
2012-04-27 00:28:52 +02:00
But, of course, this calendar is only valid for Great Britain and
dominions, not other places.
Since it would be difficult and confusing to try to track the actual
calendars that were in use in various places at various times,
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<productname>PostgreSQL</productname> does not try, but rather follows the Gregorian
Improve documentation around historical calendar rules. Get rid of section 8.5.6 (Date/Time Internals), which appears to confuse people more than it helps, and anyway discussion of Postgres' internal datetime calculation methods seems pretty out of place here. Instead, make datatype.sgml just say that we follow the Gregorian calendar (a bit of specification not previously present anywhere in that chapter :-() and link to the History of Units appendix for more info. Do some mild editorialization on that appendix, too, to make it clearer that we are following proleptic Gregorian calendar rules rather than anything more historically accurate. Per a question from Florence Cousin and subsequent discussion in pgsql-docs.
2012-04-27 00:28:52 +02:00
calendar rules for all dates, even though this method is not historically
accurate.
Improve documentation about Julian dates; in particular, point out the difference between Julian and Gregorian reckoning of when JD 0 was.
2007-12-15 02:18:34 +01:00
</para>
Rearrange and consolidate the Admin Guide. Add reference pages for utilities and remove standalone chapters for same. Add material for an appendix on date/time properties, but not yet integrated with the User's Guide. Break up the former chapter on pg_options into Admin and Programmer's Guides.
1999-05-20 07:39:29 +02:00
Back out tutorial changes: --------------------------------------------------------------------------- 1. In keeping with the recent discussion that there should be more said about views, stored procedures, and triggers, in the tutorial, I have added a bit of verbiage to that end. 2. Some formatting changes to the datetime discussion, as well as addition of a citation of a relevant book on calendars. Christopher Browne
2004-03-31 18:20:53 +02:00
<para>
Different calendars have been developed in various parts of the
world, many predating the Gregorian system.
Rearrange and consolidate the Admin Guide. Add reference pages for utilities and remove standalone chapters for same. Add material for an appendix on date/time properties, but not yet integrated with the User's Guide. Break up the former chapter on pg_options into Admin and Programmer's Guides.
1999-05-20 07:39:29 +02:00
Back out tutorial changes: --------------------------------------------------------------------------- 1. In keeping with the recent discussion that there should be more said about views, stored procedures, and triggers, in the tutorial, I have added a bit of verbiage to that end. 2. Some formatting changes to the datetime discussion, as well as addition of a citation of a relevant book on calendars. Christopher Browne
2004-03-31 18:20:53 +02:00
For example,
the beginnings of the Chinese calendar can be traced back to the 14th
Improve documentation about Julian dates; in particular, point out the difference between Julian and Gregorian reckoning of when JD 0 was.
2007-12-15 02:18:34 +01:00
century BC. Legend has it that the Emperor Huangdi invented that
Back out tutorial changes: --------------------------------------------------------------------------- 1. In keeping with the recent discussion that there should be more said about views, stored procedures, and triggers, in the tutorial, I have added a bit of verbiage to that end. 2. Some formatting changes to the datetime discussion, as well as addition of a citation of a relevant book on calendars. Christopher Browne
2004-03-31 18:20:53 +02:00
calendar in 2637 BC.
Remove useless whitespace at end of lines
2010-11-23 21:27:50 +01:00
Back out tutorial changes: --------------------------------------------------------------------------- 1. In keeping with the recent discussion that there should be more said about views, stored procedures, and triggers, in the tutorial, I have added a bit of verbiage to that end. 2. Some formatting changes to the datetime discussion, as well as addition of a citation of a relevant book on calendars. Christopher Browne
2004-03-31 18:20:53 +02:00
The People's Republic of China uses the Gregorian calendar
for civil purposes. The Chinese calendar is used for determining
festivals.
Finish initial markup of cvs.sgml, and include it in the programmer's guide and the integrated doc. Clean up other markup.
1999-05-22 04:27:25 +02:00
</para>
Improve documentation about Julian dates; in particular, point out the difference between Julian and Gregorian reckoning of when JD 0 was.
2007-12-15 02:18:34 +01:00
Doc: document EXTRACT(JULIAN ...), improve Julian Date explanation. For some reason, the "julian" option for extract()/date_part() has never gotten listed in the manual. Also, while Appendix B mentioned in passing that we don't conform to the usual astronomical definition that a Julian date starts at noon UTC, it was kind of vague about what we do instead. Clarify that, and add an example showing how to get the astronomical definition if you want it. It's been like this for ages, so back-patch to all supported branches. Discussion: https://postgr.es/m/1197050.1619123213@sss.pgh.pa.us
2021-04-26 17:50:35 +02:00
</sect1>
<sect1 id="datetime-julian-dates">
<title>Julian Dates</title>
<indexterm zone="datetime-julian-dates">
<primary>Julian date</primary>
</indexterm>
Improve documentation about Julian dates; in particular, point out the difference between Julian and Gregorian reckoning of when JD 0 was.
2007-12-15 02:18:34 +01:00
<para>
Doc: document EXTRACT(JULIAN ...), improve Julian Date explanation. For some reason, the "julian" option for extract()/date_part() has never gotten listed in the manual. Also, while Appendix B mentioned in passing that we don't conform to the usual astronomical definition that a Julian date starts at noon UTC, it was kind of vague about what we do instead. Clarify that, and add an example showing how to get the astronomical definition if you want it. It's been like this for ages, so back-patch to all supported branches. Discussion: https://postgr.es/m/1197050.1619123213@sss.pgh.pa.us
2021-04-26 17:50:35 +02:00
The <firstterm>Julian Date</firstterm> system is a method for
numbering days. It is
unrelated to the Julian calendar, though it is confusingly
Improve documentation around historical calendar rules. Get rid of section 8.5.6 (Date/Time Internals), which appears to confuse people more than it helps, and anyway discussion of Postgres' internal datetime calculation methods seems pretty out of place here. Instead, make datatype.sgml just say that we follow the Gregorian calendar (a bit of specification not previously present anywhere in that chapter :-() and link to the History of Units appendix for more info. Do some mild editorialization on that appendix, too, to make it clearer that we are following proleptic Gregorian calendar rules rather than anything more historically accurate. Per a question from Florence Cousin and subsequent discussion in pgsql-docs.
2012-04-27 00:28:52 +02:00
named similarly to that calendar.
Improve documentation about Julian dates; in particular, point out the difference between Julian and Gregorian reckoning of when JD 0 was.
2007-12-15 02:18:34 +01:00
The Julian Date system was invented by the French scholar
doc: Use proper em and en dashes
2019-10-25 20:23:44 +02:00
Joseph Justus Scaliger (1540&ndash;1609)
Improve documentation about Julian dates; in particular, point out the difference between Julian and Gregorian reckoning of when JD 0 was.
2007-12-15 02:18:34 +01:00
and probably takes its name from Scaliger's father,
doc: Use proper em and en dashes
2019-10-25 20:23:44 +02:00
the Italian scholar Julius Caesar Scaliger (1484&ndash;1558).
Doc: document EXTRACT(JULIAN ...), improve Julian Date explanation. For some reason, the "julian" option for extract()/date_part() has never gotten listed in the manual. Also, while Appendix B mentioned in passing that we don't conform to the usual astronomical definition that a Julian date starts at noon UTC, it was kind of vague about what we do instead. Clarify that, and add an example showing how to get the astronomical definition if you want it. It's been like this for ages, so back-patch to all supported branches. Discussion: https://postgr.es/m/1197050.1619123213@sss.pgh.pa.us
2021-04-26 17:50:35 +02:00
</para>
<para>
Improve documentation about Julian dates; in particular, point out the difference between Julian and Gregorian reckoning of when JD 0 was.
2007-12-15 02:18:34 +01:00
In the Julian Date system, each day has a sequential number, starting
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
from JD 0 (which is sometimes called <emphasis>the</emphasis> Julian Date).
Improve documentation about Julian dates; in particular, point out the difference between Julian and Gregorian reckoning of when JD 0 was.
2007-12-15 02:18:34 +01:00
JD 0 corresponds to 1 January 4713 BC in the Julian calendar, or
24 November 4714 BC in the Gregorian calendar. Julian Date counting
is most often used by astronomers for labeling their nightly observations,
and therefore a date runs from noon UTC to the next noon UTC, rather than
from midnight to midnight: JD 0 designates the 24 hours from noon UTC on
Improve documentation around historical calendar rules. Get rid of section 8.5.6 (Date/Time Internals), which appears to confuse people more than it helps, and anyway discussion of Postgres' internal datetime calculation methods seems pretty out of place here. Instead, make datatype.sgml just say that we follow the Gregorian calendar (a bit of specification not previously present anywhere in that chapter :-() and link to the History of Units appendix for more info. Do some mild editorialization on that appendix, too, to make it clearer that we are following proleptic Gregorian calendar rules rather than anything more historically accurate. Per a question from Florence Cousin and subsequent discussion in pgsql-docs.
2012-04-27 00:28:52 +02:00
24 November 4714 BC to noon UTC on 25 November 4714 BC.
Improve documentation about Julian dates; in particular, point out the difference between Julian and Gregorian reckoning of when JD 0 was.
2007-12-15 02:18:34 +01:00
</para>
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
Although <productname>PostgreSQL</productname> supports Julian Date notation for
Improve documentation around historical calendar rules. Get rid of section 8.5.6 (Date/Time Internals), which appears to confuse people more than it helps, and anyway discussion of Postgres' internal datetime calculation methods seems pretty out of place here. Instead, make datatype.sgml just say that we follow the Gregorian calendar (a bit of specification not previously present anywhere in that chapter :-() and link to the History of Units appendix for more info. Do some mild editorialization on that appendix, too, to make it clearer that we are following proleptic Gregorian calendar rules rather than anything more historically accurate. Per a question from Florence Cousin and subsequent discussion in pgsql-docs.
2012-04-27 00:28:52 +02:00
input and output of dates (and also uses Julian dates for some internal
datetime calculations), it does not observe the nicety of having dates
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
run from noon to noon. <productname>PostgreSQL</productname> treats a Julian Date
Doc: document EXTRACT(JULIAN ...), improve Julian Date explanation. For some reason, the "julian" option for extract()/date_part() has never gotten listed in the manual. Also, while Appendix B mentioned in passing that we don't conform to the usual astronomical definition that a Julian date starts at noon UTC, it was kind of vague about what we do instead. Clarify that, and add an example showing how to get the astronomical definition if you want it. It's been like this for ages, so back-patch to all supported branches. Discussion: https://postgr.es/m/1197050.1619123213@sss.pgh.pa.us
2021-04-26 17:50:35 +02:00
as running from local midnight to local midnight, the same as a normal
date.
</para>
<para>
This definition does, however, provide a way to obtain the astronomical
definition when you need it: do the arithmetic in time
Doc: fix discussion of how to get real Julian Dates. Somehow I'd convinced myself that rotating to UTC-12 was the way to do this, but upon further review, it's definitely UTC+12. Discussion: https://postgr.es/m/1197050.1619123213@sss.pgh.pa.us
2021-04-28 16:03:28 +02:00
zone <literal>UTC+12</literal>. For example,
Doc: document EXTRACT(JULIAN ...), improve Julian Date explanation. For some reason, the "julian" option for extract()/date_part() has never gotten listed in the manual. Also, while Appendix B mentioned in passing that we don't conform to the usual astronomical definition that a Julian date starts at noon UTC, it was kind of vague about what we do instead. Clarify that, and add an example showing how to get the astronomical definition if you want it. It's been like this for ages, so back-patch to all supported branches. Discussion: https://postgr.es/m/1197050.1619123213@sss.pgh.pa.us
2021-04-26 17:50:35 +02:00
<programlisting>
Doc: fix discussion of how to get real Julian Dates. Somehow I'd convinced myself that rotating to UTC-12 was the way to do this, but upon further review, it's definitely UTC+12. Discussion: https://postgr.es/m/1197050.1619123213@sss.pgh.pa.us
2021-04-28 16:03:28 +02:00
=&gt; SELECT extract(julian from '2021-06-23 7:00:00-04'::timestamptz at time zone 'UTC+12');
Doc: document EXTRACT(JULIAN ...), improve Julian Date explanation. For some reason, the "julian" option for extract()/date_part() has never gotten listed in the manual. Also, while Appendix B mentioned in passing that we don't conform to the usual astronomical definition that a Julian date starts at noon UTC, it was kind of vague about what we do instead. Clarify that, and add an example showing how to get the astronomical definition if you want it. It's been like this for ages, so back-patch to all supported branches. Discussion: https://postgr.es/m/1197050.1619123213@sss.pgh.pa.us
2021-04-26 17:50:35 +02:00
extract
------------------------------
Doc: fix discussion of how to get real Julian Dates. Somehow I'd convinced myself that rotating to UTC-12 was the way to do this, but upon further review, it's definitely UTC+12. Discussion: https://postgr.es/m/1197050.1619123213@sss.pgh.pa.us
2021-04-28 16:03:28 +02:00
2459388.95833333333333333333
Doc: document EXTRACT(JULIAN ...), improve Julian Date explanation. For some reason, the "julian" option for extract()/date_part() has never gotten listed in the manual. Also, while Appendix B mentioned in passing that we don't conform to the usual astronomical definition that a Julian date starts at noon UTC, it was kind of vague about what we do instead. Clarify that, and add an example showing how to get the astronomical definition if you want it. It's been like this for ages, so back-patch to all supported branches. Discussion: https://postgr.es/m/1197050.1619123213@sss.pgh.pa.us
2021-04-26 17:50:35 +02:00
(1 row)
Doc: fix discussion of how to get real Julian Dates. Somehow I'd convinced myself that rotating to UTC-12 was the way to do this, but upon further review, it's definitely UTC+12. Discussion: https://postgr.es/m/1197050.1619123213@sss.pgh.pa.us
2021-04-28 16:03:28 +02:00
=&gt; SELECT extract(julian from '2021-06-23 8:00:00-04'::timestamptz at time zone 'UTC+12');
Doc: document EXTRACT(JULIAN ...), improve Julian Date explanation. For some reason, the "julian" option for extract()/date_part() has never gotten listed in the manual. Also, while Appendix B mentioned in passing that we don't conform to the usual astronomical definition that a Julian date starts at noon UTC, it was kind of vague about what we do instead. Clarify that, and add an example showing how to get the astronomical definition if you want it. It's been like this for ages, so back-patch to all supported branches. Discussion: https://postgr.es/m/1197050.1619123213@sss.pgh.pa.us
2021-04-26 17:50:35 +02:00
extract
--------------------------------------
Doc: fix discussion of how to get real Julian Dates. Somehow I'd convinced myself that rotating to UTC-12 was the way to do this, but upon further review, it's definitely UTC+12. Discussion: https://postgr.es/m/1197050.1619123213@sss.pgh.pa.us
2021-04-28 16:03:28 +02:00
2459389.0000000000000000000000000000
Doc: document EXTRACT(JULIAN ...), improve Julian Date explanation. For some reason, the "julian" option for extract()/date_part() has never gotten listed in the manual. Also, while Appendix B mentioned in passing that we don't conform to the usual astronomical definition that a Julian date starts at noon UTC, it was kind of vague about what we do instead. Clarify that, and add an example showing how to get the astronomical definition if you want it. It's been like this for ages, so back-patch to all supported branches. Discussion: https://postgr.es/m/1197050.1619123213@sss.pgh.pa.us
2021-04-26 17:50:35 +02:00
(1 row)
Doc: fix discussion of how to get real Julian Dates. Somehow I'd convinced myself that rotating to UTC-12 was the way to do this, but upon further review, it's definitely UTC+12. Discussion: https://postgr.es/m/1197050.1619123213@sss.pgh.pa.us
2021-04-28 16:03:28 +02:00
=&gt; SELECT extract(julian from date '2021-06-23');
Doc: document EXTRACT(JULIAN ...), improve Julian Date explanation. For some reason, the "julian" option for extract()/date_part() has never gotten listed in the manual. Also, while Appendix B mentioned in passing that we don't conform to the usual astronomical definition that a Julian date starts at noon UTC, it was kind of vague about what we do instead. Clarify that, and add an example showing how to get the astronomical definition if you want it. It's been like this for ages, so back-patch to all supported branches. Discussion: https://postgr.es/m/1197050.1619123213@sss.pgh.pa.us
2021-04-26 17:50:35 +02:00
extract
---------
Doc: fix discussion of how to get real Julian Dates. Somehow I'd convinced myself that rotating to UTC-12 was the way to do this, but upon further review, it's definitely UTC+12. Discussion: https://postgr.es/m/1197050.1619123213@sss.pgh.pa.us
2021-04-28 16:03:28 +02:00
2459389
Doc: document EXTRACT(JULIAN ...), improve Julian Date explanation. For some reason, the "julian" option for extract()/date_part() has never gotten listed in the manual. Also, while Appendix B mentioned in passing that we don't conform to the usual astronomical definition that a Julian date starts at noon UTC, it was kind of vague about what we do instead. Clarify that, and add an example showing how to get the astronomical definition if you want it. It's been like this for ages, so back-patch to all supported branches. Discussion: https://postgr.es/m/1197050.1619123213@sss.pgh.pa.us
2021-04-26 17:50:35 +02:00
(1 row)
</programlisting>
Improve documentation about Julian dates; in particular, point out the difference between Julian and Gregorian reckoning of when JD 0 was.
2007-12-15 02:18:34 +01:00
</para>
Finish initial markup of cvs.sgml, and include it in the programmer's guide and the integrated doc. Clean up other markup.
1999-05-22 04:27:25 +02:00
</sect1>
</appendix>