On Mon, Nov 28, 2022 at 12:45 AM Tom Lane <t...@sss.pgh.pa.us> wrote:
> Laurenz Albe <laurenz.a...@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
>
All changes specified have been addressed.
The Example is significantly reduced, but readable.
The extra "SELECT "'s have been removed off of the inline examples,
excluding the existing paragraph.
This is the smallest possible change, that still has an example.
The "Example" is not <title> as every attempt to make it such fails the
LINT process.
regards, Kirk
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 82fba48d5f..3be2c5ef97 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -17623,7 +17623,12 @@ $.* ? (@ like_regex "^\\d+$")
values beginning with 1. Other behaviors can be obtained by using
appropriate parameters in the <xref linkend="sql-createsequence"/>
command.
- </para>
+ </para>
+ <para>
+<programlisting>
+nextval('myseq');
+</programlisting>
+ </para>
<para>
This function requires <literal>USAGE</literal>
or <literal>UPDATE</literal> privilege on the sequence.
@@ -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>
+currval('myseq');
+</programlisting>
</para>
<para>
This function requires <literal>USAGE</literal>
@@ -17707,9 +17715,8 @@ 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.)
</para>
<para>
This function requires <literal>USAGE</literal>
@@ -17719,7 +17726,21 @@ SELECT setval('myseq', 42, false);
<lineannotation>Next <function>nextval</fu
</tbody>
</tgroup>
</table>
+ <para>Example
+<programlisting>
+CREATE SEQUENCE test_seq;
+
+SELECT nextval('test_seq'::regclass); <lineannotation>--
1</lineannotation>
+SELECT currval('test_seq'); <lineannotation>--
1</lineannotation>
+SELECT lastval(); <lineannotation>--
1</lineannotation>
+
+<lineannotation>-- Using the DEFAULT value you can assign this SEQUENCE to be
used when the field is not assigned a value</lineannotation>
+CREATE TABLE t1 (id bigint NOT NULL DEFAULT nextval('test_seq'), other_data
text); <lineannotation>-- links column/sequence</lineannotation>
+
+INSERT INTO t1 (other_data) VALUES ('Some Data'); <lineannotation>-- Assigns
the next ID automatically</lineannotation>
+</programlisting>
+ </para>
<caution>
<para>
To avoid blocking concurrent transactions that obtain numbers from
