From 133d06f7bbf5fcf24f1fdbf0e013e30446f61abd Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Sat, 17 Oct 2020 16:02:47 -0400 Subject: [PATCH] Doc: caution against misuse of 'now' and related datetime literals. Section 8.5.1.4, which defines these literals, made only a vague reference to the fact that they might be evaluated too soon to be safe in non-interactive contexts. Provide a more explicit caution against misuse. Also, generalize the wording in the related tip in section 9.9.4: while it clearly described this problem, it implied (or really, stated outright) that the problem only applies to table DEFAULT clauses. Per gripe from Tijs van Dam. Back-patch to all supported branches. Discussion: https://postgr.es/m/c2LuRv9BiRT3bqIo5mMQiVraEXey_25B4vUn0kDqVqilwOEu_iVF1tbtvLnyQK7yDG3PFaz_GxLLPil2SDkj1MCObNRVaac-7j1dVdFERk8=@thalex.com --- doc/src/sgml/datatype.sgml | 20 +++++++++++++++++--- doc/src/sgml/func.sgml | 8 +++++--- 2 files changed, 22 insertions(+), 6 deletions(-) diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml index 0d38bee182..44d85d81af 100644 --- a/doc/src/sgml/datatype.sgml +++ b/doc/src/sgml/datatype.sgml @@ -2103,7 +2103,7 @@ January 8 04:05:06 1999 PST - + Special Values @@ -2191,12 +2191,26 @@ January 8 04:05:06 1999 PST type: CURRENT_DATE, CURRENT_TIME, CURRENT_TIMESTAMP, LOCALTIME, - LOCALTIMESTAMP. The latter four accept an - optional subsecond precision specification. (See LOCALTIMESTAMP. (See .) Note that these are SQL functions and are not recognized in data input strings. + + + While the input strings now, + today, tomorrow, + and yesterday are fine to use in interactive SQL + commands, they can have surprising behavior when the command is + saved to be executed later, for example in prepared statements, + views, and function definitions. The string can be converted to a + specific time value that continues to be used long after it becomes + stale. Use one of the SQL functions instead in such contexts. + For example, CURRENT_DATE + 1 is safer than + 'tomorrow'::date. + + + diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 4313dc5a1e..0028e53ef1 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -8340,20 +8340,22 @@ now() SELECT CURRENT_TIMESTAMP; SELECT now(); -SELECT TIMESTAMP 'now'; -- incorrect for use with DEFAULT +SELECT TIMESTAMP 'now'; -- but see tip below - You do not want to use the third form when specifying a DEFAULT - clause while creating a table. The system will convert now + Do not use the third form when specifying a value to be evaluated later, + for example in a DEFAULT clause for a table column. + The system will convert now to a timestamp as soon as the constant is parsed, so that when the default value is needed, the time of the table creation would be used! The first two forms will not be evaluated until the default value is used, because they are function calls. Thus they will give the desired behavior of defaulting to the time of row insertion. + (See also .)