nextval parameter is not clear

On Tue, Oct 18, 2022 at 08:17:12AM +0000, PG Doc comments form wrote:

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/14/functions-sequence.html
Description:

https://www.postgresql.org/docs/14/functions-sequence.html

I don't see here any hints about how to use this function, and what the
regclass means.
How should I understand that sequence_name should be passed as string in
nextval('sequence_name') ?

Maybe add some links to other topics or clarify examples for nextval here.

Uh, the last sentence in that section says:

The sequence to be operated on by a sequence function is specified by a
regclass argument, which is simply the OID of the sequence in the
pg_class system catalog. You do not have to look up the OID by hand,
however, since the regclass data type's input converter will do the work
for you. See Section 8.19 for details.

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com

Indecision is a decision. Inaction is an action. Mark Batterson

On Tue, Nov 22, 2022 at 2:10 PM Bruce Momjian <bruce@momjian.us> wrote:

On Tue, Oct 18, 2022 at 08:17:12AM +0000, PG Doc comments form wrote:

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/14/functions-sequence.html
Description:

https://www.postgresql.org/docs/14/functions-sequence.html

I don't see here any hints about how to use this function, and what the
Maybe add some links to other topics or clarify examples for nextval

here.

Uh, the last sentence in that section says:

The sequence to be operated on by a sequence function is specified
by a
regclass argument, which is simply the OID of the sequence in the
pg_class system catalog. You do not have to look up the OID by
hand,
however, since the regclass data type's input converter will do
the work
for you. See Section 8.19 for details.

As someone who is "newer", I'd like to point out that a "clarifying

example" as
simple as *SELECT nextval("your_seq"::regclass); *
is about 100 times more CLEAR about the essence than that paragraph.

And, yes, I read the page, and I've seen the examples just one paragraph
lower.
A huge majority of us are hyper-visual, and learn by example. But that
example
below does not translate to this example... Unless you already know it!

I've been frustrated many times to find the documentation, and then struggle
trying to envision how the ultimate code/syntax truly reads.

I've thought about this, and I believe having a GIGANTIC page of PG SQL
code,
that could be referenced and linked, would be a WONDERFUL thing.
Then a page like this could literally have a link: "see example".

Everyone who NORMALLY reads these emails are not typically struggling
with the syntax. But the people going to documentation often are!

Regards
PS: I am willing to help create that gigantic page, if we can standardize a
way to link to it.
PPS: Even to the point of successive refinement. Over time, we may add "do
this / not this"

On Tue, Nov 22, 2022 at 8:42 PM Kirk Wolak <wolakk@gmail.com> wrote:

On Tue, Nov 22, 2022 at 2:10 PM Bruce Momjian <bruce@momjian.us> wrote:

On Tue, Oct 18, 2022 at 08:17:12AM +0000, PG Doc comments form wrote:

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/14/functions-sequence.html
Description:

https://www.postgresql.org/docs/14/functions-sequence.html

I don't see here any hints about how to use this function, and what the
Maybe add some links to other topics or clarify examples for nextval

here.

Uh, the last sentence in that section says:

The sequence to be operated on by a sequence function is
specified by a
regclass argument, which is simply the OID of the sequence in the
pg_class system catalog. You do not have to look up the OID by
hand,
however, since the regclass data type's input converter will do
the work
for you. See Section 8.19 for details.

As someone who is "newer", I'd like to point out that a "clarifying

example" as
simple as *SELECT nextval("your_seq"::regclass); *
is about 100 times more CLEAR about the essence than that paragraph.

We've only fairly recently made incorporating useful and expansive examples
into the reference part of the documentation generally doable. I agree
that this particular one warrants such an example. If you are willing to
do the harder work you describe below, submit a patch for this. It's
specific, small, an improvement, and nothing Bruce said indicates it isn't
wanted, he just focused on a different aspect of the complaint.

And, yes, I read the page, and I've seen the examples just one paragraph
lower.
A huge majority of us are hyper-visual, and learn by example. But that
example
below does not translate to this example... Unless you already know it!

Sure, and the decades old documentation written for the book era, not
YouTube and interactive tutorials, doesn't cater for that audience. That
isn't going to change at this point, and that is a good thing. But that
doesn't mean specific improvements cannot be made.

Regards
PS: I am willing to help create that gigantic page, if we can standardize
a way to link to it.
PPS: Even to the point of successive refinement. Over time, we may add
"do this / not this"

The wiki is an excellent place to prototype and coordinate. Beyond that,
this idea falls outside what should be discussed on this thread. Here,
let's either patch the docs with some examples, or not.

David J.

On Tue, Nov 22, 2022 at 11:43 PM David G. Johnston <
david.g.johnston@gmail.com> wrote:

On Tue, Nov 22, 2022 at 8:42 PM Kirk Wolak <wolakk@gmail.com> wrote:

On Tue, Nov 22, 2022 at 2:10 PM Bruce Momjian <bruce@momjian.us> wrote:

On Tue, Oct 18, 2022 at 08:17:12AM +0000, PG Doc comments form wrote:

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/14/functions-sequence.html
Description:

https://www.postgresql.org/docs/14/functions-sequence.html

I don't see here any hints about how to use this function, and what the
Maybe add some links to other topics or clarify examples for nextval

here.

We've only fairly recently made incorporating useful and expansive

examples into the reference part of the documentation generally doable. I
agree that this particular one warrants such an example. If you are
willing to do the harder work you describe below, submit a patch for this.
It's specific, small, an improvement, and nothing Bruce said indicates it
isn't wanted, he just focused on a different aspect of the complaint.
..
The wiki is an excellent place to prototype and coordinate. Beyond that,
this idea falls outside what should be discussed on this thread. Here,
let's either patch the docs with some examples, or not.

David J.

David, as requested. I took this page, and created examples in each row of
each function.
I took a little liberty to normalize the warning about the error message
between the last 2 functions (currval()/lastval()).
I also decorated the comments with -- prefix (because I HATE not being able
to quickly copy code and paste and use it).
Also, I added a CREATE SEQUENCE in each block, so that the resulting code
will work if you cut/paste it in.
[Who knows, eventually we could add CSS that adds the copy and maybe an
Open in PGFiddle someday]

Now I edited this as pure sgml. I have no idea how to make this into html
to view. Do you guys use specific tooling?

Have a look. Cut it to shreds. But I believe this is functional and
informative.

Regards Kirk

On Wed, Nov 23, 2022 at 11:06 PM Kirk Wolak <wolakk@gmail.com> wrote:

On Tue, Nov 22, 2022 at 11:43 PM David G. Johnston <
david.g.johnston@gmail.com> wrote:

On Tue, Nov 22, 2022 at 8:42 PM Kirk Wolak <wolakk@gmail.com> wrote:

..

The wiki is an excellent place to prototype and coordinate. Beyond that,
this idea falls outside what should be discussed on this thread. Here,
let's either patch the docs with some examples, or not.

David J.

David, as requested. I took this page, and created examples in each row
of each function.
I took a little liberty to normalize the warning about the error message
between the last 2 functions (currval()/lastval()).
I also decorated the comments with -- prefix (because I HATE not being
able to quickly copy code and paste and use it).
Also, I added a CREATE SEQUENCE in each block, so that the resulting code
will work if you cut/paste it in.
[Who knows, eventually we could add CSS that adds the copy and maybe an
Open in PGFiddle someday]

Now I edited this as pure sgml. I have no idea how to make this into html
to view. Do you guys use specific tooling?

Have a look. Cut it to shreds. But I believe this is functional and
informative.

Regards Kirk

Apologies, I am new to the tools and this approach. I just got the
makefile working for the documentation.
When I got it working, I tested copying/pasting each chunk. And caught an
error.

Here is the updated version.

Regards Kirk

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

On Wed, Nov 23, 2022 at 11:06 PM Kirk Wolak <wolakk@gmail.com> wrote:

On Tue, Nov 22, 2022 at 11:43 PM David G. Johnston <
david.g.johnston@gmail.com> wrote:

On Tue, Nov 22, 2022 at 8:42 PM Kirk Wolak <wolakk@gmail.com> wrote:

Here is the updated version.

Regards Kirk

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.

Apologies for spamming this in... My first patch turned into 3 emails...

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.

Apologies for spamming this in...  My first patch turned into 3 emails... 

That is no problem.

I think the patch is fine. I like the addition of the "--" comments.
The one think that should be unified is that you include an explicit
cast to "regclass" everywhere, but the pre-existing example does not.

I would omit that cast. It might confuse beginners (who are probably
satisfied to know that you have to use the sequence name as a string),
and it is explained in the last paragraph of the page anyway.

Yours,
Laurenz Albe

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.

Apologies for spamming this in... My first patch turned into 3

emails...

That is no problem.

I think the patch is fine. I like the addition of the "--" comments.
The one think that should be unified is that you include an explicit
cast to "regclass" everywhere, but the pre-existing example does not.

I would omit that cast. It might confuse beginners (who are probably
satisfied to know that you have to use the sequence name as a string),
and it is explained in the last paragraph of the page anyway.

Yours,
Laurenz Albe

Laurenz,
First, thanks for the support..

It's funny you mention that (with and without ::regclass). I went both
ways on it.
The reason I did not address it, was that I liked the variety because it
sticks out.
I thought about adding a comment like
-- while you can omit the ::regclass casting, it is preferred

The fact that it is different engages the brain of the reader whose
pattern matching
just got challenged. It almost begs them to test it out.

I think it might deserve a comment, but I would really prefer to keep it
in there.

Regards Kirk

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.

Apologies for spamming this in... My first patch turned into 3

emails...

That is no problem.

I think the patch is fine. I like the addition of the "--" comments.
The one think that should be unified is that you include an explicit
cast to "regclass" everywhere, but the pre-existing example does not.

I would omit that cast. It might confuse beginners (who are probably
satisfied to know that you have to use the sequence name as a string),
and it is explained in the last paragraph of the page anyway.

Yours,
Laurenz Albe

Laurenz,
First, thanks for the support..

It's funny you mention that (with and without ::regclass). I went both
ways on it.
The reason I did not address it, was that I liked the variety because it
sticks out.
I thought about adding a comment like
-- while you can omit the ::regclass casting, it is preferred

The fact that it is different engages the brain of the reader whose
pattern matching
just got challenged. It almost begs them to test it out.

I think it might deserve a comment, but I would really prefer to keep it
in there.

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.

On Thu, Nov 24, 2022 at 10:44 AM David G. Johnston <
david.g.johnston@gmail.com> wrote:

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)

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!
3) It's okay in the example area to introduce a few ideas [I really like
this: RETURNING, etc]
What I LIKE about this... It reminds me of the PHP manual online, where
they have TONS of user posted examples (ours will be more moderated, but
this opens us up to better and better and even alternative examples).

Let me play with this. I think I want to try a progression of the examples.

I used role="example_code", for the paragraph style, and I think it looks
better de-dented to the same level as the functions.
But I have NO IDEA where that css detail would be stored for make..

#docContent table.table p.func_signature, p.example_code {}

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.

I also tested, and cleaned up the results from your example. Sorry it took
me so long, I am very new. Laurenz helped me out with:
make STYLE=website

Let me know what you think now...
(and I removed all but the single embedded SQL. Even when it is trivial,
I would prefer to put one in there.)

Here is a screen shot: (is it preferred to use a link to screencast?)
https://app.screencast.com/hDW9ma2aPsdQy
[image: image.png]

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

On Fri, Nov 25, 2022 at 12:40 AM Laurenz Albe <laurenz.albe@cybertec.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.

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

On Fri, Nov 25, 2022 at 12:40 AM Laurenz Albe <laurenz.albe@cybertec.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!

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

On Fri, Nov 25, 2022 at 12:40 AM Laurenz Albe <laurenz.albe@cybertec.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:

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.

Okay, I've really reworked the example, and it all tests out.
I took the advice of Laurenz about the separate section outside the table.
I did not move the function, it seemed alphabetical where it was (easy
enough to move), but I did use that function twice!

Break out the RED ink and let me know what you think!

Kirk

On Fri, Nov 25, 2022 at 10:06 PM Kirk Wolak <wolakk@gmail.com> wrote:

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

On Fri, Nov 25, 2022 at 12:40 AM Laurenz Albe <laurenz.albe@cybertec.at>
wrote:

On Thu, 2022-11-24 at 15:50 -0500, Kirk Wolak wrote:

..

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.

Okay, I've really reworked the example, and it all tests out.
I took the advice of Laurenz about the separate section outside the table.
I did not move the function, it seemed alphabetical where it was (easy
enough to move), but I did use that function twice!

Break out the RED ink and let me know what you think!

Kirk

Okay, forgive me again. I've figured out how to rebase against the latest
master. There are no changes from the previous post.
But the diff file contains updated references (I have no idea if this
helps, but I was unable to "view" someone elses file with diffs without
that).

Laurenz,
Your feedback would be appreciated. If we keep the "play" schema, I
think a comment at the end of the section reminding them to DROP that
schema would be nice.

Kirk

On Sat, 2022-11-26 at 23:22 -0500, Kirk Wolak wrote:

Your feedback would be appreciated.

--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -17625,6 +17625,11 @@ $.* ? (@ like_regex "^\\d+$")
command.
</para>
<para>
+<programlisting>
+SELECT nextval('myseq'::regclass);
+</programlisting>
+      </para>
+       <para>

The indentation of the <para> tags should be the same everywhere.
True, the misalignment was pre-existing here, but it would be better to
fix it than to repeat the mistake.

I think the cast to "regclass" should be only in the more elaborate
example at the end

@@ -17669,7 +17674,6 @@ SELECT setval('myseq', 42, false); <lineannotation>Next <function>nextval</fu
sequence.
</para></entry>
</row>
-
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>

I think the empty line is intentional and should stay. We have it
everywhere else, and it helps to read the source.

@@ -17707,19 +17714,75 @@ SELECT setval('myseq', 42, false);    <lineannotation>Next <function>nextval</fu
identical to <function>currval</function>, except that instead
of taking the sequence name as an argument it refers to whichever
sequence <function>nextval</function> was most recently applied to
-        in the current session. It is an error to call
-        <function>lastval</function> if <function>nextval</function>
-        has not yet been called in the current session.
+        in the current session. (An error is reported if <function>nextval</function> has
+        never been called in this session.) 
+<programlisting> 
+SELECT lastval();
+</programlisting>

I have no problem with changing the sentence to a parenthetical remark, although
I thing the original wording was fine. However, there is a trailing blank at the
end of the line (and in the <programlisting> line as well). Please avoid these.
"git diff" highlights such training blanks.

I would not add a code sample in this case. The function has no arguments, so what
cat we really learn from that? We don't have to have a code sample here just because
we had one with all the other functions.

</para>
<para>
This function requires <literal>USAGE</literal>
or <literal>SELECT</literal> privilege on the last used sequence.
</para></entry>
</row>
+ <row>
+ <entry role="func_table_entry">
+ </entry>
+ </row>
</tbody>
</tgroup>
</table>

This empty row should definitely go.

+ <para>Example

I think you should use the <title> tag to render that more conspicuous.

+<programlisting>
+CREATE SCHEMA play;                            <lineannotation>-- Create a play schema</lineannotation>
[...]

Now I think that is taking it too far. Your code sample would be great for a tutorial,
but it is too elaborate for the technical documentation. The example should focus on
the sequence functions, but more than half of the code describes other parts of
PostgreSQL:

- schema and search_path
- psql commands
- INSERT ... RETURNING
- pg_get_serial_sequence()

I am not saying that this is bad material, but if anything, it should go to
chapter 3 (Advanced Features) of the tutorial (and then it could be even more
elaborate).

I am alright with having a CREATE TABLE with a DEFAULT and an INSERT or two;
whatever it takes to show the functions in a realistic scenario.
For example, you could INSERT a row that overrides the DEFAULT, then call
"setval()" to readjust the sequence.

Yours,
Laurenz Albe

Laurenz Albe <laurenz.albe@cybertec.at> writes:

Now I think that is taking it too far. Your code sample would be great
for a tutorial, but it is too elaborate for the technical documentation.
The example should focus on the sequence functions, but more than half
of the code describes other parts of PostgreSQL:

Yeah, that stuff seems quite out of place here.

I am alright with having a CREATE TABLE with a DEFAULT and an INSERT or two;
whatever it takes to show the functions in a realistic scenario.
For example, you could INSERT a row that overrides the DEFAULT, then call
"setval()" to readjust the sequence.

I don't believe we have such detail around very many, if indeed any,
of our other functions' documentation.

regards, tom lane

On Mon, Nov 28, 2022 at 12:45 AM Tom Lane <tgl@sss.pgh.pa.us> wrote:

Laurenz Albe <laurenz.albe@cybertec.at> writes:

Now I think that is taking it too far. Your code sample would be great
for a tutorial, but it is too elaborate for the technical documentation.
The example should focus on the sequence functions, but more than half
of the code describes other parts of PostgreSQL:

Yeah, that stuff seems quite out of place here.

I am alright with having a CREATE TABLE with a DEFAULT and an INSERT or

two;

whatever it takes to show the functions in a realistic scenario.
For example, you could INSERT a row that overrides the DEFAULT, then call
"setval()" to readjust the sequence.

I don't believe we have such detail around very many, if indeed any,
of our other functions' documentation.

regards, tom lane

my goal is to get an "approach" accepted, this is the first. Ultimately, I
would love to see
the documentation of functions with examples like this everywhere.
Preferably where someone
can copy/paste the example and see the results. *And I fully intend to
create them all myself,*
*if that's what it takes. *But I would prefer the hard work now, and then I
can stream-line the process.

The driver was my own frustration when I first started learning PG and the
lack of concrete examples.
How are these things used, in context? [I learn through reading code]

On Sun, Nov 27, 2022 at 10:34 PM Laurenz Albe <laurenz.albe@cybertec.at>
wrote:

On Sat, 2022-11-26 at 23:22 -0500, Kirk Wolak wrote:

Your feedback would be appreciated.

+ <para>Example

I think you should use the <title> tag to render that more conspicuous.

I tried. it does not MAKE. It is not allowed in that position. I don't

know how to allow it there!
Help would be appreciated.

I am not saying that this is bad material, but if anything, it should go to
chapter 3 (Advanced Features) of the tutorial (and then it could be even
more
elaborate).

Let me review that section. If we have a place where we can have examples
of ALL functions in actual usage
That would be great.

Yours,
Laurenz Albe

I will make the next version based on ALL of your comments. As well as
reviewing chapter 3, and feedback on the <title>Example</title>
tag working there...