From eaf8f312c754d6b4bcc9d0ff07c14b3b8990ed91 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Mon, 19 Jun 2006 16:13:01 +0000 Subject: [PATCH] Some editorial work on the documentation of the current-date/time functions. --- doc/src/sgml/func.sgml | 118 +++++++++++++++++++++++++---------------- 1 file changed, 73 insertions(+), 45 deletions(-) diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 9e6f332e5b..506fd816ca 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -1,4 +1,4 @@ - + Functions and Operators @@ -5357,7 +5357,8 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); current_date date - Today's date; see + Current date; + see @@ -5366,7 +5367,8 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); current_time time with time zone - Time of day; see + Current time of day; + see @@ -5375,7 +5377,8 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); current_timestamp timestamp with time zone - Date and time of start of current transaction; see + Current date and time (start of current transaction); + see @@ -5384,8 +5387,8 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); date_part(text, timestamp) double precision - Get subfield (equivalent to - extract); see + Get subfield (equivalent to extract); + see date_part('hour', timestamp '2001-02-16 20:38:40') 20 @@ -5473,7 +5476,8 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); localtime time - Time of day; see + Current time of day; + see @@ -5482,7 +5486,8 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); localtimestamp timestamp - Date and time; see + Current date and time (start of current transaction); + see @@ -5491,8 +5496,8 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); now() timestamp with time zone - Date and time of start of current transaction (equivalent to - CURRENT_TIMESTAMP); see + Current date and time (start of current transaction); + see @@ -5501,8 +5506,8 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); transaction_timestamp() timestamp with time zone - Date and time of start of current transaction (equivalent to - CURRENT_TIMESTAMP); see + Current date and time (start of current transaction); + see @@ -5511,7 +5516,8 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); statement_timestamp() timestamp with time zone - Date and time of start of current statement; see + Current date and time (start of current statement); + see @@ -5520,7 +5526,8 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); clock_timestamp() timestamp with time zone - Current date and time (changes during statement execution); see + Current date and time (changes during statement execution); + see @@ -5529,8 +5536,9 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); timeofday() text - Current date and time (like clock_timestamp), but as a Unix-style text value; - see + Current date and time + (like clock_timestamp, but as a text string); + see @@ -6118,7 +6126,7 @@ SELECT TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-05' AT TIME ZONE 'MST'; - Date/Time of Transaction Start + Current Date/Time date @@ -6131,8 +6139,10 @@ SELECT TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-05' AT TIME ZONE 'MST'; - The following functions are available to obtain the date and/or - time of the start of the current transaction: + PostgreSQL provides a number of functions + that return values related to the current date and time. These + SQL-standard functions all return values based on the start time of + the current transaction: CURRENT_DATE CURRENT_TIME @@ -6185,43 +6195,61 @@ SELECT LOCALTIMESTAMP; - It is important to know that - CURRENT_TIMESTAMP and related functions return - the start time of the current transaction; their values do not + Since these functions return + the start time of the current transaction, their values do not change during the transaction. This is considered a feature: the intent is to allow a single transaction to have a consistent notion of the current time, so that multiple modifications within the same transaction bear the same - time stamp. Consider using statement_timestamp or - clock_timestamp if you need something that changes - more frequently. + time stamp. + + + + + Other database systems may advance these values more + frequently. + + + + + PostgreSQL also provides functions that + return the start time of the current statement, as well as the actual + current time at the instant the function is called. The complete list + of non-SQL-standard time functions is: + +now() +transaction_timestamp() +statement_timestamp() +clock_timestamp() +timeofday() + - CURRENT_TIMESTAMP might not be the - transaction start time on other database systems. - For this reason, and for completeness, - transaction_timestamp is provided. - The function now() is the traditional - PostgreSQL equivalent to - the SQL-standard CURRENT_TIMESTAMP. - - - - STATEMENT_TIMESTAMP is the time the statement - arrived at the server from the client. It is not the time - the command started execution. If multiple commands were - sent as a single query string to the server, each command - has the same STATEMENT_TIMESTAMP because they - all arrived at the same time. Also, commands executed - by server-side functions have a STATEMENT_TIMESTAMP - based on the time the client sent the query that triggered - the function, not the time the function was executed. + now() is a traditional PostgreSQL + equivalent to CURRENT_TIMESTAMP. + transaction_timestamp() is likewise equivalent to + CURRENT_TIMESTAMP, but is named to clearly reflect + what it returns. + statement_timestamp() returns the start time of the current + statement (more specifically, the time of receipt of the latest command + message from the client). + statement_timestamp() and transaction_timestamp() + return the same value during the first command of a transaction, but may + differ during subsequent commands. + clock_timestamp() returns the actual current time, and + therefore its value changes even within a single SQL command. + timeofday() is a historical + PostgreSQL function. Like + clock_timestamp(), it returns the actual current time, + but as a formatted text string rather than a timestamp + with time zone value. All the date/time data types also accept the special literal value - now to specify the current date and time. Thus, + now to specify the current date and time (again, + interpreted as the transaction start time). Thus, the following three all return the same result: SELECT CURRENT_TIMESTAMP;