Re: Should we document how column DEFAULT expressions work?

On Fri, Jul 5, 2024 at 05:11:22PM -0400, Bruce Momjian wrote:
> Wow, I see that now:
>
> test=> SELECT 'now('::timestamptz;
> timestamptz
> -------------------------------
> 2024-07-05 17:04:33.457915-04
>
> 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()'.

> diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml
> index f19306e7760..4d47248fccf 100644
> --- a/doc/src/sgml/ref/create_table.sgml
> +++ b/doc/src/sgml/ref/create_table.sgml
> @@ -888,6 +888,13 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
> match the data type of the column.
> </para>
>
> + <para>
> + Note, a string that returns a volatile result once cast to a data
> + type, like <literal>'now'::timestamptz</literal>, is evaluated at
> + table creation time, while <literal>now()::timestamptz</literal>
> + (without quotes) is evaluated at data insertion time.
> + </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

It seems we never came to an agreed-upon documentation addition to warn
users about this.

--
Bruce Momjian <bruce(at)momjian(dot)us> https://momjian.us
EDB https://enterprisedb.com

When a patient asks the doctor, "Am I going to die?", he means
"Am I going to die soon?"