Re: nextval parameter is not clear

On Fri, Nov 25, 2022 at 12:40 AM Laurenz Albe <laurenz(dot)albe(at)cybertec(dot)at>
wrote:

> On Thu, 2022-11-24 at 15:50 -0500, Kirk Wolak wrote:
> >
> > David, let me see how that looks. From an approach standpoint, I am
> hearing:
> > 1) Keep the example near the definition minimal [just this function]
> > 2) It's okay to create an extra "row" [each function is in a <row>],
> right after the last function, with a detailed example, like you put below!
>
> The detailed example should not be another row in the table. The table is
> only for
> the description of individual functions. The functions "nextval",
> "setval", "currval"
> and "lastval" each have their own row.
>
> I think the elaborate example should be at the bottom of the page, similar
> to
> the "Examples" section in the reference pages. See for example
> https://www.postgresql.org/docs/current/sql-createstatistics.html

+1

>
> > >
> > > CREATE TABLE seq_example ( id bigint PRIMARY KEY GENERATED BY DEFAULT
> AS IDENTITY ) -- implicit sequence named seq_example_seq is created (or
> whatever is generated...)
> > > INSERT INTO seq_example RETURNING id; -- 1
> > > SELECT currval('seq_example_seq'::regclass); -- 1
>
> I don't think that is a good example to explain sequences to a beginner.
> The sequence behind an identity column is an implementation detail, and
> I wouldn't burden the reader with all that.
>

If you are using these functions it is most commonly in a situation where
serial/identity is involved. I don't see much benefit to having the example
be sanitized to the point of not reflecting realistic usage.

> I think it would be better to create the sequence explicitly and use
> it in the DEFAULT clause of a column definition.
>

I wasn't too happy with that comment when I wrote it either.

I would probably do without the DEFAULT if going the explicit route (but it
isn't a deal breaker).

However, I remembered that we have:

pg_get_serial_sequence ( table text, column text ) → text

I'd be inclined to stay with the GENERATED example but incorporate that
function call into the other examples.

Regardless of the above choice for the example, it seems appropriate for
this page, somewhere, to mention this function and link to its page.

I'd even argue for moving that function definition here.

David J.