Re: Should we document how column DEFAULT expressions work?

On Fri, Jul 5, 2024 at 2:11 PM Bruce Momjian <bruce(at)momjian(dot)us> wrote:

>
> If I remove the 'now()' mention in the docs, patch attached, I am
> concerned people will be confused whether it is the removal of the
> single quotes or the use of "()" which causes insert-time evaluation,
> and they might try 'now()'.
>
>
Literals are DDL-time because of parsing, functions are insert-time because
of execution. IMO this is presently confusing because we are focused on
characters, not concepts.

diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index c55fa607e8..ac661958fd 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -2391,6 +2391,17 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02'
</para>
</caution>

+ <caution>
+ <para>
+ The input parser for timestamp values is forgiving: it ignores
+ trailing invalid characters. This poses a hazard in
+ the case of the <literal>'now'</literal> special date/time input.
+ The constant <literal>'now()'</literal> is the same special
date/time input;
+ not the <function>now()</function> function, which like all function
+ call expressions, is not single-quoted. Writing
<literal>'now()'</literal>
+ is considered deprecated and may become an error in future versions.
+ </para>
+ </caution>
+
</sect3>
</sect2>

diff --git a/doc/src/sgml/ref/create_table.sgml
b/doc/src/sgml/ref/create_table.sgml
index f19306e776..4cecab011a 100644
--- a/doc/src/sgml/ref/create_table.sgml
+++ b/doc/src/sgml/ref/create_table.sgml
@@ -889,9 +889,10 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
</para>

<para>
- The default expression will be used in any insert operation that
- does not specify a value for the column. If there is no default
- for a column, then the default is null.
+ The default expression is immediately parsed, which causes
evaluation of any literals, notably
+ <link linkend="datatype-datetime-special-table">special date/time
inputs</link>.
+ Execution happens during insert for any row that does not specify a
value for the column.
+ If there is no explicit default constraint for a column, the default
is a null value.
</para>
</listitem>
</varlistentry>

David J.