From: Kirk Wolak <wolakk@gmail.com>
To: Tom Lane <tgl@sss.pgh.pa.us>
Cc: Laurenz Albe <laurenz.albe@cybertec.at>
Cc: David G. Johnston <david.g.johnston@gmail.com>
Cc: Bruce Momjian <bruce@momjian.us>
Cc: ailjushkin@gmail.com
Cc: pgsql-docs@lists.postgresql.org
Subject: Re: nextval parameter is not clear
Date: Tue, 29 Nov 2022 16:26:51 -0500
Message-ID: <CACLU5mRd-xpVfhmDJwGwM33uV4hovGT85DZbd_F4vAS1FVRMSA@mail.gmail.com> (raw)
In-Reply-To: <452493.1669614328@sss.pgh.pa.us>
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>
<0c0eddb287571e72a2df1be8758fbbb0cb7cc378.camel@cybertec.at>
<CAKFQuwYuu_FrZZ=TEdUPdB4c-hbsCHSKD+XSUdDFrGnaDMQ_=A@mail.gmail.com>
<CACLU5mTmEieU-uTF6bNm9T5Y94gd1g_cgz_JDLz6Qw36RjcBHQ@mail.gmail.com>
<f7a51be79a5146740954e0b9b70515529a1d944b.camel@cybertec.at>
<452493.1669614328@sss.pgh.pa.us>
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
>
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.sgmlindex 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
Attachments:
[text/plain] func-examples-8.patch (3.9K, ../CACLU5mRd-xpVfhmDJwGwM33uV4hovGT85DZbd_F4vAS1FVRMSA@mail.gmail.com/3-func-examples-8.patch)
download | inline diff:diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgmlindex 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
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, tgl@sss.pgh.pa.us, laurenz.albe@cybertec.at, david.g.johnston@gmail.com, bruce@momjian.us, ailjushkin@gmail.com, pgsql-docs@lists.postgresql.org
Subject: Re: nextval parameter is not clear
In-Reply-To: <CACLU5mRd-xpVfhmDJwGwM33uV4hovGT85DZbd_F4vAS1FVRMSA@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