From: Kirk Wolak <wolakk@gmail.com>
To: David G. Johnston <david.g.johnston@gmail.com>
Cc: Laurenz Albe <laurenz.albe@cybertec.at>
Cc: Bruce Momjian <bruce@momjian.us>
Cc: ailjushkin@gmail.com
Cc: pgsql-docs@lists.postgresql.org
Subject: Re: nextval parameter is not clear
Date: Thu, 24 Nov 2022 15:50:58 -0500
Message-ID: <CACLU5mRn-xHKP9irkBQvYCQYKNDCcud66zJHHaHNHoOMA4kmVQ@mail.gmail.com> (raw)
In-Reply-To: <CAKFQuwarCJs9bbgJ9_PtsCBJKmSM1UnLx80J5JUJm1eJyYzHXQ@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>
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]
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgmlindex 82fba48d5f..bd17d247e2 100644--- 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); <lineannotation>-- returns 1</lineannotation>+</programlisting>+ </para>+ <para>
This function requires <literal>USAGE</literal>
or <literal>UPDATE</literal> privilege on the sequence.
</para></entry>
@@ -17657,11 +17662,11 @@ $.* ? (@ like_regex "^\\d+$")
Furthermore, the value reported by <function>currval</function> is not
changed in this case. For example,
<programlisting>
-SELECT setval('myseq', 42); <lineannotation>Next <function>nextval</function> will return 43</lineannotation>-SELECT setval('myseq', 42, true); <lineannotation>Same as above</lineannotation>-SELECT setval('myseq', 42, false); <lineannotation>Next <function>nextval</function> will return 42</lineannotation>+SELECT setval('myseq', 42); <lineannotation>-- The next <function>nextval</function>('myseq') will return 43</lineannotation>+SELECT setval('myseq', 42, true); <lineannotation>-- Same as above</lineannotation>+SELECT setval('myseq', 42, false); <lineannotation>-- The next <function>nextval</function>('myseq') will return 42</lineannotation>
</programlisting>
- The result returned by <function>setval</function> is just the value of its+ The result returned by <function>setval</function> is the value of its
second argument.
</para>
<para>
@@ -17686,6 +17691,9 @@ SELECT setval('myseq', 42, false); <lineannotation>Next <function>nextval</fu
returning a session-local value, it gives a predictable answer whether
or not other sessions have executed <function>nextval</function> since
the current session did.
+<programlisting>+SELECT currval('myseq'::regclass);+</programlisting>
</para>
<para>
This function requires <literal>USAGE</literal>
@@ -17707,15 +17715,36 @@ 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>
</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"><para role="example_code">+ Examples</para>+<programlisting>+CREATE TABLE seq_example ( id bigint PRIMARY KEY GENERATED BY DEFAULT AS IDENTITY );+<lineannotation>-- implicit sequence named seq_example_id_seq is created (\ds in psql will show sequences)</lineannotation>++INSERT INTO seq_example RETURNING id; <lineannotation>-- 1</lineannotation>+SELECT currval('seq_example_id_seq'::regclass); <lineannotation>-- 1</lineannotation>++SELECT setval('seq_example_id_seq', 10);+INSERT INTO seq_example (id)+ VALUES (nextval('seq_example_id_seq')) <lineannotation>-- works as-is due to choosing BY DEFAULT for the identity</lineannotation>+ RETURNING id; <lineannotation>-- 11</lineannotation>+ +SELECT lastval(); <lineannotation>-- 11</lineannotation>+</programlisting>+ </entry>+ </row>
</tbody>
</tgroup>
</table>
Attachments:
[image/png] image.png (70.6K, ../CACLU5mRn-xHKP9irkBQvYCQYKNDCcud66zJHHaHNHoOMA4kmVQ@mail.gmail.com/3-image.png)
download | view image
[text/plain] func-examples-4.patch (4.0K, ../CACLU5mRn-xHKP9irkBQvYCQYKNDCcud66zJHHaHNHoOMA4kmVQ@mail.gmail.com/4-func-examples-4.patch)
download | inline diff:diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgmlindex 82fba48d5f..bd17d247e2 100644--- 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); <lineannotation>-- returns 1</lineannotation>+</programlisting>+ </para>+ <para>
This function requires <literal>USAGE</literal>
or <literal>UPDATE</literal> privilege on the sequence.
</para></entry>
@@ -17657,11 +17662,11 @@ $.* ? (@ like_regex "^\\d+$")
Furthermore, the value reported by <function>currval</function> is not
changed in this case. For example,
<programlisting>
-SELECT setval('myseq', 42); <lineannotation>Next <function>nextval</function> will return 43</lineannotation>-SELECT setval('myseq', 42, true); <lineannotation>Same as above</lineannotation>-SELECT setval('myseq', 42, false); <lineannotation>Next <function>nextval</function> will return 42</lineannotation>+SELECT setval('myseq', 42); <lineannotation>-- The next <function>nextval</function>('myseq') will return 43</lineannotation>+SELECT setval('myseq', 42, true); <lineannotation>-- Same as above</lineannotation>+SELECT setval('myseq', 42, false); <lineannotation>-- The next <function>nextval</function>('myseq') will return 42</lineannotation>
</programlisting>
- The result returned by <function>setval</function> is just the value of its+ The result returned by <function>setval</function> is the value of its
second argument.
</para>
<para>
@@ -17686,6 +17691,9 @@ SELECT setval('myseq', 42, false); <lineannotation>Next <function>nextval</fu
returning a session-local value, it gives a predictable answer whether
or not other sessions have executed <function>nextval</function> since
the current session did.
+<programlisting>+SELECT currval('myseq'::regclass);+</programlisting>
</para>
<para>
This function requires <literal>USAGE</literal>
@@ -17707,15 +17715,36 @@ 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>
</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"><para role="example_code">+ Examples</para>+<programlisting>+CREATE TABLE seq_example ( id bigint PRIMARY KEY GENERATED BY DEFAULT AS IDENTITY );+<lineannotation>-- implicit sequence named seq_example_id_seq is created (\ds in psql will show sequences)</lineannotation>++INSERT INTO seq_example RETURNING id; <lineannotation>-- 1</lineannotation>+SELECT currval('seq_example_id_seq'::regclass); <lineannotation>-- 1</lineannotation>++SELECT setval('seq_example_id_seq', 10);+INSERT INTO seq_example (id)+ VALUES (nextval('seq_example_id_seq')) <lineannotation>-- works as-is due to choosing BY DEFAULT for the identity</lineannotation>+ RETURNING id; <lineannotation>-- 11</lineannotation>+ +SELECT lastval(); <lineannotation>-- 11</lineannotation>+</programlisting>+ </entry>+ </row>
</tbody>
</tgroup>
</table>
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: wolakk@gmail.com, david.g.johnston@gmail.com, laurenz.albe@cybertec.at, bruce@momjian.us, ailjushkin@gmail.com, pgsql-docs@lists.postgresql.org
Subject: Re: nextval parameter is not clear
In-Reply-To: <CACLU5mRn-xHKP9irkBQvYCQYKNDCcud66zJHHaHNHoOMA4kmVQ@mail.gmail.com>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox