Thread: Recently noticed documentation issues

Hi all

I've recently noticed two oversights in the docs that I'd like to fix.


First, in sql-fetch, there's no hint that the cursor name can be the 
quoted value of a refcursor, eg:
    FETCH ALL FROM "<unnamed portal 1>";

This *is* shown in an example in plpgsql-cursors, but only in some 
sample code. If you set out with the question "how do I fetch the 
contents of a refcursor returned from a function" it's a lot harder to 
find the results than it could be.

I'd like to add a short discussion of refcursors and an example to 
sql-fetch, and refer to that from plpgsql-cursors to make it clearer how 
you work with plpgsql cursors from SQL.



Second, in functions-datetime, I wasn't able to find any mention of the 
behaviour of CASTing a DATE to a TIMESTAMP or to a TIMESTAMPTZ. I'd like 
to explicitly state that casting date to timestamp or timestamptz 
produces a date in local time, and show that if you want to cast a date 
to another time zone you can use:
    thedate::timestamp AT TIME ZONE 'UTC'

to produce a timestamptz containing that date at midnight UTC.

Opinions?

--
Criaig Ringer

From: pgsql-hackers-owner@postgresql.org
[mailto:pgsql-hackers-owner@postgresql.org] On Behalf Of Craig Ringer
Sent: Friday, August 24, 2012 7:17 AM

> I've recently noticed two oversights in the docs that I'd like to fix.


> First, in sql-fetch, there's no hint that the cursor name can be the 
> quoted value of a refcursor, eg:

>     FETCH ALL FROM "<unnamed portal 1>";

> This *is* shown in an example in plpgsql-cursors, but only in some 
> sample code. If you set out with the question "how do I fetch the 
> contents of a refcursor returned from a function" it's a lot harder to 
> find the results than it could be.

Isn't what you are telling explained in Returning Cursors section on below
link:
http://www.postgresql.org/docs/9.1/static/plpgsql-cursors.html

On 08/24/2012 12:42 PM, Amit Kapila wrote:

> Isn't what you are telling explained in Returning Cursors section on below
> link:
> http://www.postgresql.org/docs/9.1/static/plpgsql-cursors.html

Yes, but nowhere in:
  http://www.postgresql.org/docs/current/static/sql-fetch.html

and IMO not clearly enough in the PL/PgSQL docs; it only appears in 
sample code.

--
Craig Ringer

From: Craig Ringer [mailto:ringerc@ringerc.id.au] 
Sent: Friday, August 24, 2012 6:59 PM
On 08/24/2012 12:42 PM, Amit Kapila wrote:

>> Isn't what you are telling explained in Returning Cursors section on
below
>> link:
>> http://www.postgresql.org/docs/9.1/static/plpgsql-cursors.html

>Yes, but nowhere in:

>   http://www.postgresql.org/docs/current/static/sql-fetch.html

> and IMO not clearly enough in the PL/PgSQL docs; it only appears in 
> sample code.
 Ref-cursors usage is also along with functions, so mentioning them along
with PL/PgSQL docs looks more logical to me. However in context of SQL statements also Fetch can use internally
generated cursor  names in quoted strings, so about that some description might be useful.
But again I  don't know clearly the usage of it, whether such kind of functionality is
used by  users or PG is expecting to get Fetch used in such contexts. 

With Regards,
Amit Kapila.