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

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

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

PG Bug reporting form
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.
Reply | Threaded
Open this post in threaded view
|

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

Bruce Momjian
On Tue, Apr  9, 2019 at 02:50:14PM +0000, PG Doc comments form wrote:

> 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.

We don't get this question very often.  I wonder if you didn't look at
the error message we generated, or if you could share the exact error
you saw.

--
  Bruce Momjian  <[hidden email]>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +


Reply | Threaded
Open this post in threaded view
|

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

David G Johnston
On Friday, April 12, 2019, Bruce Momjian <[hidden email]> wrote:
On Tue, Apr  9, 2019 at 02:50:14PM +0000, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
>
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.

We don't get this question very often.  I wonder if you didn't look at
the error message we generated, or if you could share the exact error
you saw.


See also:


The docs maybe aren’t great at covering this but they do, and correctly.  Though maybe a note saying “this works but you probably should use actual casts” would be warranted.  I personally have not found a need to use the “type” ‘literal’ syntax.

David J.
Reply | Threaded
Open this post in threaded view
|

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

Jind?ich Vavru?ka

Hello,

I thought about it once more.

I think I fell into trap of my own experience. I do not work with PG very often, that’s why I went into the manual to make sure what is the actual syntax. Second, in most cases in my professional use of any rdbms, we work with scripts (or PL/SQL procedures) and never use database API (my specialization are data warehouses). That’s probably why I never really cared if there were any differences in SQL between script execution and API call.

This was a use case that went out of my usual experience and that’s why I made a mistake that very few active developers or users of PostgreSQL can understand 😊

You guys decide if this single case requires any fixes in docs. If this has never happened in the last ten years, probably not.

Regards,

Jindra

 

From: David G. Johnston <[hidden email]>
Sent: Saturday, April 13, 2019 9:31 AM
To: Bruce Momjian <[hidden email]>
Cc: [hidden email]; [hidden email]
Subject: Re: Confusing information in sections 8.5 and 9.9 (date and time types, functions and operators)

 

On Friday, April 12, 2019, Bruce Momjian <[hidden email]> wrote:

On Tue, Apr  9, 2019 at 02:50:14PM +0000, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
>
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.

We don't get this question very often.  I wonder if you didn't look at
the error message we generated, or if you could share the exact error
you saw.

 

See also:

 

 

The docs maybe aren’t great at covering this but they do, and correctly.  Though maybe a note saying “this works but you probably should use actual casts” would be warranted.  I personally have not found a need to use the “type” ‘literal’ syntax.

 

David J.