Re: nextval parameter is not clear

On Fri, Nov 25, 2022 at 9:58 AM David G. Johnston <
david(dot)g(dot)johnston(at)gmail(dot)com> wrote:

> 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.
>
>
David,
Wow, it's hard to clip this email and keep the flow. Apologies.
I love the feedback. I will pull that function (pg_get_serial_sequence) in
here (do I leave it where it is? (probably not))???

And make the other changes. Since I have a "whole" area to put the
sample in, and I did not like the flow of the sample that much.
(I was focused on the make/patch process so I can become useful)... Let me
now craft it up a bit and apply all of this good feedback.

Let me create a better flow... True beginner (CREATE SEQUENCE ...), then
More advanced, like your example, then using this last function,
which qualifies as advanced... relative to someone looking at "nextval", et
al.

Thanks!