Confusing information in sections 8.5 and 9.9 (date and time types, functions and operators)

From: PG Doc comments form <noreply(at)postgresql(dot)org>
To: pgsql-docs(at)lists(dot)postgresql(dot)org
Cc: jindrich(at)vavruska(dot)cz
Subject: Confusing information in sections 8.5 and 9.9 (date and time types, functions and operators)
Date: 2019-04-09 14:50:14
Message-ID: 155482141428.1361.16437659503221856211@wrigleys.postgresql.org
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-docs

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/11/datatype-datetime.html
Description:

Both sections mention syntax TIMESTAMP '2019-01-20 08:00' as valid for input
of timestamp data. This seems to work fine in psql, however, this syntax
causes Syntax error when used in library access to the server (in my case it
is via pg module in NodeJS). After spending half a day looking for error, I
learned from the javascript module developer that the mentioned syntax
cannot be used for programmatic access. Instead, he recommended to use cast
operator form '2019-01-20 08:00'::timestamp.
I tested his suggestion (it works, of course) and was looking for some
mention or confirmation in the documentation, but found nothing. I think
this is a serious issue, especially because the alternative possibility of
using ::timestamp is not even mentioned in chapters 8.5 or 9.9. If someone
(like me) looks for specific information how to handle date & time literals,
they will inevitably fall into the same trap.
Since the experienced Syntax error is contrary to what one would expect
after reading the SQL language manual, could you please at least add some
hyperlink in both sections 8.5 and 9.9 to attract reader's attention to this
specific behavior of the database server? Thank you.

Responses

Browse pgsql-docs by date

  From Date Subject
Next Message PG Doc comments form 2019-04-09 15:08:15 Section 4.1.2.7 contains false information
Previous Message Emanuel Araújo 2019-04-09 13:23:37 Re: Improve documentation about include_dir parameter.