Re: nextval parameter is not clear - Mailing list pgsql-docs

On Thu, Nov 24, 2022 at 7:33 AM Kirk Wolak <wolakk@gmail.com> wrote:

On Thu, Nov 24, 2022 at 5:33 AM Laurenz Albe <laurenz.albe@cybertec.at> wrote:

On Thu, 2022-11-24 at 02:41 -0500, Kirk Wolak wrote:
> Alright, as I have the documentation build working, and a slightly better stylesheet,
> the comments on the last block were not aligned.
> They are fixed now.
>...

I dislike having CREATE SEQUENCE in the table examples.  Keep those focused on only the syntax of the call expression.  That requires removing the nextval calls too and not showing the error path.  I'd be fine with not showing examples of code that would produce an error.  (if we are going to show the error path I'd suggest we show the actual error message produced)

At the bottom of the page I would add an extended example of how these sequences can be used in practice.

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

SELECT setval('seq_example_seq', 10);

INSERT INTO seq_example (id)

  VALUES (nextval('seq_example_seq')) -- works as-is due to choosing BY DEFAULT for the identity

  RETURNING id; -- 11

SELECT lastval(); -- 11

I would remove the casting of the sequence name from the table examples and just keep one in the main usage example.  I agree that having both to make the reader stop and think is a good idea.

David J.