MIME-Version: 1.0
References: <CAAaqYe-wQPbchCUE7pocPNEQ3PMY8a98Txmxc7q0+FvXtk1vvg@mail.gmail.com>
 <1362410.1719349169@sss.pgh.pa.us> <CAAaqYe9_RE2WximHuYRpyfU-H2G+W--49e_8GDqS-vHLOzPvmg@mail.gmail.com>
 <1390099.1719357084@sss.pgh.pa.us> <CAKFQuwZkgm0yqHhf05thqu1gzUK__gXBL5tyBuFvKoOe7Dd6=A@mail.gmail.com>
In-Reply-To: <CAKFQuwZkgm0yqHhf05thqu1gzUK__gXBL5tyBuFvKoOe7Dd6=A@mail.gmail.com>
From: David Rowley <dgrowleyml@gmail.com>
Date: Wed, 26 Jun 2024 16:50:00 +1200
Message-ID: <CAApHDvoiHYxM2VQYZeiF7JAdP7Y0JxEr86NZpUjoZ9AA4cpzYw@mail.gmail.com>
Subject: Re: Should we document how column DEFAULT expressions work?
To: "David G. Johnston" <david.g.johnston@gmail.com>
Cc: Tom Lane <tgl@sss.pgh.pa.us>, James Coleman <jtc331@gmail.com>, 
	pgsql-hackers <pgsql-hackers@postgresql.org>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
Archived-At: <https://www.postgresql.org/message-id/CAApHDvoiHYxM2VQYZeiF7JAdP7Y0JxEr86NZpUjoZ9AA4cpzYw%40mail.gmail.com>
Precedence: bulk

On Wed, 26 Jun 2024 at 13:31, David G. Johnston
<david.g.johnston@gmail.com> wrote:
> I'd suggest adding to:
>
> DEFAULT default_expr
> The DEFAULT clause assigns a default data value for the column whose colu=
mn definition it appears within. The value is any variable-free expression =
(in particular, cross-references to other columns in the current table are =
not allowed). Subqueries are not allowed either. The data type of the defau=
lt expression must match the data type of the column.
>
> 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.
>
> + Be aware that the [special timestamp values 1] are resolved immediately=
, not upon insert.  Use the [date/time constructor functions 2] to produce =
a time relative to the future insertion.

FWIW, I disagree that we need to write anything about that in this
part of the documentation.  I think any argument for doing this could
equally be applied to something like re-iterating what the operator
precedence rules for arithmetic are, and I don't think that should be
mentioned. Also, what about all the other places where someone could
use one of the special timestamp input values? Should CREATE VIEW get
a memo too?  How about PREPARE?

If people don't properly understand these special timestamp input
values, then maybe the documentation in [1] needs to be improved.  At
the moment the details are within parentheses. Namely "(In particular,
now and related strings are converted to a specific time value as soon
as they are read.)".  Maybe it would be better to be more explicit
there and mention that these are special values that the input
function understands which are translated to actual timestamp values
when the type's input function is called.  That could maybe be tied
into the DEFAULT clause documentation to mention that the input
function for constant values is called at DML time rather than DDL
time.  That way, we're not adding these (unsustainable) special cases
to the documentation.

David

[1] https://www.postgresql.org/docs/current/datatype-datetime.html#DATATYPE=
-DATETIME-SPECIAL-VALUES