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