Message-ID: <0c0eddb287571e72a2df1be8758fbbb0cb7cc378.camel@cybertec.at>
Subject: Re: nextval parameter is not clear
From: Laurenz Albe <laurenz.albe@cybertec.at>
To: Kirk Wolak <wolakk@gmail.com>, "David G. Johnston"
	 <david.g.johnston@gmail.com>
Cc: Bruce Momjian <bruce@momjian.us>, ailjushkin@gmail.com,
	pgsql-docs@lists.postgresql.org
Date: Fri, 25 Nov 2022 08:40:25 +0100
In-Reply-To: 
 <CACLU5mRn-xHKP9irkBQvYCQYKNDCcud66zJHHaHNHoOMA4kmVQ@mail.gmail.com>
References: 
	<166608103231.2042183.13992576112735261253@wrigleys.postgresql.org>
	 <Y30ekxQpiIaG9eSl@momjian.us>
	 <CACLU5mQBVn+cyeAAbs7O6c8h14MBurhuxpp7z+TXWo2+vQcO+w@mail.gmail.com>
	 <CAKFQuwau7CpY+TLufpU1RPPzyLzjS0mvrXnSLf+eGSUJS-_pRQ@mail.gmail.com>
	 <CACLU5mQ1LTz9BnG-bbfCmwzytyUFwej90XBnFtQJKQkubS9Khw@mail.gmail.com>
	 <CACLU5mTKsNgWfY9qcsn1fhMRXbfJ0M8bPEwgXbmanxVgdKPQ7A@mail.gmail.com>
	 <CACLU5mS4b3xM-tuMpT2oP-pqwwnHJbSeLDBzZSs9Lq_ObgMu7Q@mail.gmail.com>
	 <21e017222199f3ca397fa70549140d226236e4b6.camel@cybertec.at>
	 <CACLU5mShHGjroH=Cp_k6i-T+357_Fhxahc5NqpNPoJnN56GyFg@mail.gmail.com>
	 <CAKFQuwarCJs9bbgJ9_PtsCBJKmSM1UnLx80J5JUJm1eJyYzHXQ@mail.gmail.com>
	 <CACLU5mRn-xHKP9irkBQvYCQYKNDCcud66zJHHaHNHoOMA4kmVQ@mail.gmail.com>
Content-Type: text/plain; charset="UTF-8"
User-Agent: Evolution 3.42.4 (3.42.4-2.fc35) 
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Archived-At: 
 <https://www.postgresql.org/message-id/0c0eddb287571e72a2df1be8758fbbb0cb7cc378.camel%40cybertec.at>
Precedence: bulk

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

> David G. Johnston <david.g.johnston@gmail.com> wrote:

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

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.

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

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

I think that is a good idea, and you should go with that.

Yours,
Laurenz Albe