pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feednextval parameter is not clear
29+ messages / 7 participants
[nested] [flat]
* nextval parameter is not clear
@ 2022-10-18 08:17 PG Doc comments form <noreply@postgresql.org>
2022-11-22 19:10 ` Re: nextval parameter is not clear Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 29+ messages in thread
From: PG Doc comments form @ 2022-10-18 08:17 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: ailjushkin@gmail.com
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.
Thanks.
^ permalink raw reply [nested|flat] 29+ messages in thread
* Re: nextval parameter is not clear
2022-10-18 08:17 nextval parameter is not clear PG Doc comments form <noreply@postgresql.org>
@ 2022-11-22 19:10 ` Bruce Momjian <bruce@momjian.us>
2022-11-23 03:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
0 siblings, 1 reply; 29+ messages in thread
From: Bruce Momjian @ 2022-11-22 19:10 UTC (permalink / raw)
To: ailjushkin@gmail.com; pgsql-docs@lists.postgresql.org
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
^ permalink raw reply [nested|flat] 29+ messages in thread
* Re: nextval parameter is not clear
2022-10-18 08:17 nextval parameter is not clear PG Doc comments form <noreply@postgresql.org>
2022-11-22 19:10 ` Re: nextval parameter is not clear Bruce Momjian <bruce@momjian.us>
@ 2022-11-23 03:41 ` Kirk Wolak <wolakk@gmail.com>
2022-11-23 04:42 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
0 siblings, 1 reply; 29+ messages in thread
From: Kirk Wolak @ 2022-11-23 03:41 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: ailjushkin@gmail.com; pgsql-docs@lists.postgresql.org
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"
^ permalink raw reply [nested|flat] 29+ messages in thread
* Re: nextval parameter is not clear
2022-10-18 08:17 nextval parameter is not clear PG Doc comments form <noreply@postgresql.org>
2022-11-22 19:10 ` Re: nextval parameter is not clear Bruce Momjian <bruce@momjian.us>
2022-11-23 03:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
@ 2022-11-23 04:42 ` David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 04:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
0 siblings, 1 reply; 29+ messages in thread
From: David G. Johnston @ 2022-11-23 04:42 UTC (permalink / raw)
To: Kirk Wolak <wolakk@gmail.com>; +Cc: Bruce Momjian <bruce@momjian.us>; ailjushkin@gmail.com; pgsql-docs@lists.postgresql.org
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.
^ permalink raw reply [nested|flat] 29+ messages in thread
* Re: nextval parameter is not clear
2022-10-18 08:17 nextval parameter is not clear PG Doc comments form <noreply@postgresql.org>
2022-11-22 19:10 ` Re: nextval parameter is not clear Bruce Momjian <bruce@momjian.us>
2022-11-23 03:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-23 04:42 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
@ 2022-11-24 04:06 ` Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:04 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
0 siblings, 1 reply; 29+ messages in thread
From: Kirk Wolak @ 2022-11-24 04:06 UTC (permalink / raw)
To: David G. Johnston <david.g.johnston@gmail.com>; +Cc: Bruce Momjian <bruce@momjian.us>; ailjushkin@gmail.com; pgsql-docs@lists.postgresql.org
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
Attachments:
[application/octet-stream] func-examples.patch (3.4K, ../../CACLU5mQ1LTz9BnG-bbfCmwzytyUFwej90XBnFtQJKQkubS9Khw@mail.gmail.com/3-func-examples.patch)
download | inline diff:
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 82fba48d5f..2941ec6073 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -17625,6 +17625,12 @@ $.* ? (@ like_regex "^\\d+$")
command.
</para>
<para>
+<programlisting>
+CREATE SEQUENCE myseq;
+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 +17663,12 @@ $.* ? (@ 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>
+CREATE SEQUENCE myseq;
+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 +17693,12 @@ 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>
+CREATE SEQUENCE myseq;
+<lineannotation>-- SELECT currval('myseq'::regclass); -- would throw an error here</lineannotation>
+SELECT nextval('myseq'::regclass); <lineannotation>-- returns 1</lineannotation>
+SELECT currval('myseq'::regclass); <lineannotation>-- returns 1</lineannotation>
+</programlisting>
</para>
<para>
This function requires <literal>USAGE</literal>
@@ -17707,9 +17720,14 @@ 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>
+CREATE SEQUENCE myseq;
+<lineannotation>-- SELECT lastval(); -- would throw an error here</lineannotation>
+SELECT nextval('myseq'::regclass); <lineannotation>-- returns 1</lineannotation>
+SELECT lastval('myseq'::regclass); <lineannotation>-- returns 1</lineannotation>
+</programlisting>
</para>
<para>
This function requires <literal>USAGE</literal>
^ permalink raw reply [nested|flat] 29+ messages in thread
* Re: nextval parameter is not clear
2022-10-18 08:17 nextval parameter is not clear PG Doc comments form <noreply@postgresql.org>
2022-11-22 19:10 ` Re: nextval parameter is not clear Bruce Momjian <bruce@momjian.us>
2022-11-23 03:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-23 04:42 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 04:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
@ 2022-11-24 07:04 ` Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
0 siblings, 1 reply; 29+ messages in thread
From: Kirk Wolak @ 2022-11-24 07:04 UTC (permalink / raw)
To: David G. Johnston <david.g.johnston@gmail.com>; +Cc: Bruce Momjian <bruce@momjian.us>; ailjushkin@gmail.com; pgsql-docs@lists.postgresql.org
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
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 82fba48d5f..ee36ba8690 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -17625,6 +17625,12 @@ $.* ? (@ like_regex "^\\d+$")
command.
</para>
<para>
+<programlisting>
+CREATE SEQUENCE myseq;
+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 +17663,12 @@ $.* ? (@ 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>
+CREATE SEQUENCE myseq;
+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 +17693,12 @@ 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>
+CREATE SEQUENCE myseq;
+<lineannotation>-- SELECT currval('myseq'::regclass); -- would throw an error here</lineannotation>
+SELECT nextval('myseq'::regclass); <lineannotation>-- returns 1</lineannotation>
+SELECT currval('myseq'::regclass); <lineannotation>-- returns 1</lineannotation>
+</programlisting>
</para>
<para>
This function requires <literal>USAGE</literal>
@@ -17707,9 +17720,14 @@ 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>
+CREATE SEQUENCE myseq;
+<lineannotation>-- SELECT lastval(); -- would throw an error here</lineannotation>
+SELECT nextval('myseq'::regclass); <lineannotation>-- returns 1</lineannotation>
+SELECT lastval(); <lineannotation>-- returns 1</lineannotation>
+</programlisting>
</para>
<para>
This function requires <literal>USAGE</literal>
Attachments:
[text/plain] func-examples-2.patch (3.4K, ../../CACLU5mTKsNgWfY9qcsn1fhMRXbfJ0M8bPEwgXbmanxVgdKPQ7A@mail.gmail.com/3-func-examples-2.patch)
download | inline diff:
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 82fba48d5f..ee36ba8690 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -17625,6 +17625,12 @@ $.* ? (@ like_regex "^\\d+$")
command.
</para>
<para>
+<programlisting>
+CREATE SEQUENCE myseq;
+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 +17663,12 @@ $.* ? (@ 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>
+CREATE SEQUENCE myseq;
+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 +17693,12 @@ 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>
+CREATE SEQUENCE myseq;
+<lineannotation>-- SELECT currval('myseq'::regclass); -- would throw an error here</lineannotation>
+SELECT nextval('myseq'::regclass); <lineannotation>-- returns 1</lineannotation>
+SELECT currval('myseq'::regclass); <lineannotation>-- returns 1</lineannotation>
+</programlisting>
</para>
<para>
This function requires <literal>USAGE</literal>
@@ -17707,9 +17720,14 @@ 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>
+CREATE SEQUENCE myseq;
+<lineannotation>-- SELECT lastval(); -- would throw an error here</lineannotation>
+SELECT nextval('myseq'::regclass); <lineannotation>-- returns 1</lineannotation>
+SELECT lastval(); <lineannotation>-- returns 1</lineannotation>
+</programlisting>
</para>
<para>
This function requires <literal>USAGE</literal>
^ permalink raw reply [nested|flat] 29+ messages in thread
* Re: nextval parameter is not clear
2022-10-18 08:17 nextval parameter is not clear PG Doc comments form <noreply@postgresql.org>
2022-11-22 19:10 ` Re: nextval parameter is not clear Bruce Momjian <bruce@momjian.us>
2022-11-23 03:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-23 04:42 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 04:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:04 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
@ 2022-11-24 07:41 ` Kirk Wolak <wolakk@gmail.com>
2022-11-24 10:33 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
0 siblings, 1 reply; 29+ messages in thread
From: Kirk Wolak @ 2022-11-24 07:41 UTC (permalink / raw)
To: David G. Johnston <david.g.johnston@gmail.com>; +Cc: Bruce Momjian <bruce@momjian.us>; ailjushkin@gmail.com; pgsql-docs@lists.postgresql.org
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...
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 82fba48d5f..e730154c0f 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -17625,6 +17625,12 @@ $.* ? (@ like_regex "^\\d+$")
command.
</para>
<para>
+<programlisting>
+CREATE SEQUENCE myseq;
+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 +17663,12 @@ $.* ? (@ 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>
+CREATE SEQUENCE myseq;
+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 +17693,12 @@ 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>
+CREATE SEQUENCE myseq;
+<lineannotation>-- SELECT currval('myseq'::regclass); -- would throw an error here</lineannotation>
+SELECT nextval('myseq'::regclass); <lineannotation>-- returns 1</lineannotation>
+SELECT currval('myseq'::regclass); <lineannotation>-- returns 1</lineannotation>
+</programlisting>
</para>
<para>
This function requires <literal>USAGE</literal>
@@ -17707,9 +17720,14 @@ 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>
+CREATE SEQUENCE myseq;
+<lineannotation>-- SELECT lastval(); -- would throw an error here</lineannotation>
+SELECT nextval('myseq'::regclass); <lineannotation>-- returns 1</lineannotation>
+SELECT lastval(); <lineannotation> -- returns 1</lineannotation>
+</programlisting>
</para>
<para>
This function requires <literal>USAGE</literal>
Attachments:
[text/plain] func-examples-3.patch (3.4K, ../../CACLU5mS4b3xM-tuMpT2oP-pqwwnHJbSeLDBzZSs9Lq_ObgMu7Q@mail.gmail.com/3-func-examples-3.patch)
download | inline diff:
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 82fba48d5f..e730154c0f 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -17625,6 +17625,12 @@ $.* ? (@ like_regex "^\\d+$")
command.
</para>
<para>
+<programlisting>
+CREATE SEQUENCE myseq;
+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 +17663,12 @@ $.* ? (@ 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>
+CREATE SEQUENCE myseq;
+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 +17693,12 @@ 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>
+CREATE SEQUENCE myseq;
+<lineannotation>-- SELECT currval('myseq'::regclass); -- would throw an error here</lineannotation>
+SELECT nextval('myseq'::regclass); <lineannotation>-- returns 1</lineannotation>
+SELECT currval('myseq'::regclass); <lineannotation>-- returns 1</lineannotation>
+</programlisting>
</para>
<para>
This function requires <literal>USAGE</literal>
@@ -17707,9 +17720,14 @@ 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>
+CREATE SEQUENCE myseq;
+<lineannotation>-- SELECT lastval(); -- would throw an error here</lineannotation>
+SELECT nextval('myseq'::regclass); <lineannotation>-- returns 1</lineannotation>
+SELECT lastval(); <lineannotation> -- returns 1</lineannotation>
+</programlisting>
</para>
<para>
This function requires <literal>USAGE</literal>
^ permalink raw reply [nested|flat] 29+ messages in thread
* Re: nextval parameter is not clear
2022-10-18 08:17 nextval parameter is not clear PG Doc comments form <noreply@postgresql.org>
2022-11-22 19:10 ` Re: nextval parameter is not clear Bruce Momjian <bruce@momjian.us>
2022-11-23 03:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-23 04:42 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 04:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:04 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
@ 2022-11-24 10:33 ` Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-24 14:33 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
0 siblings, 1 reply; 29+ messages in thread
From: Laurenz Albe @ 2022-11-24 10:33 UTC (permalink / raw)
To: Kirk Wolak <wolakk@gmail.com>; David G. Johnston <david.g.johnston@gmail.com>; +Cc: Bruce Momjian <bruce@momjian.us>; ailjushkin@gmail.com; pgsql-docs@lists.postgresql.org
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
^ permalink raw reply [nested|flat] 29+ messages in thread
* Re: nextval parameter is not clear
2022-10-18 08:17 nextval parameter is not clear PG Doc comments form <noreply@postgresql.org>
2022-11-22 19:10 ` Re: nextval parameter is not clear Bruce Momjian <bruce@momjian.us>
2022-11-23 03:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-23 04:42 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 04:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:04 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 10:33 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
@ 2022-11-24 14:33 ` Kirk Wolak <wolakk@gmail.com>
2022-11-24 15:44 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
0 siblings, 1 reply; 29+ messages in thread
From: Kirk Wolak @ 2022-11-24 14:33 UTC (permalink / raw)
To: Laurenz Albe <laurenz.albe@cybertec.at>; +Cc: David G. Johnston <david.g.johnston@gmail.com>; Bruce Momjian <bruce@momjian.us>; ailjushkin@gmail.com; pgsql-docs@lists.postgresql.org
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
^ permalink raw reply [nested|flat] 29+ messages in thread
* Re: nextval parameter is not clear
2022-10-18 08:17 nextval parameter is not clear PG Doc comments form <noreply@postgresql.org>
2022-11-22 19:10 ` Re: nextval parameter is not clear Bruce Momjian <bruce@momjian.us>
2022-11-23 03:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-23 04:42 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 04:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:04 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 10:33 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-24 14:33 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
@ 2022-11-24 15:44 ` David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 20:50 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
0 siblings, 1 reply; 29+ messages in thread
From: David G. Johnston @ 2022-11-24 15:44 UTC (permalink / raw)
To: Kirk Wolak <wolakk@gmail.com>; +Cc: Laurenz Albe <laurenz.albe@cybertec.at>; Bruce Momjian <bruce@momjian.us>; ailjushkin@gmail.com; pgsql-docs@lists.postgresql.org
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.
^ permalink raw reply [nested|flat] 29+ messages in thread
* Re: nextval parameter is not clear
2022-10-18 08:17 nextval parameter is not clear PG Doc comments form <noreply@postgresql.org>
2022-11-22 19:10 ` Re: nextval parameter is not clear Bruce Momjian <bruce@momjian.us>
2022-11-23 03:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-23 04:42 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 04:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:04 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 10:33 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-24 14:33 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 15:44 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
@ 2022-11-24 20:50 ` Kirk Wolak <wolakk@gmail.com>
2022-11-25 07:40 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
0 siblings, 1 reply; 29+ messages in thread
From: Kirk Wolak @ 2022-11-24 20:50 UTC (permalink / raw)
To: David G. Johnston <david.g.johnston@gmail.com>; +Cc: Laurenz Albe <laurenz.albe@cybertec.at>; Bruce Momjian <bruce@momjian.us>; ailjushkin@gmail.com; pgsql-docs@lists.postgresql.org
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.sgml
index 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.sgml
index 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>
^ permalink raw reply [nested|flat] 29+ messages in thread
* Re: nextval parameter is not clear
2022-10-18 08:17 nextval parameter is not clear PG Doc comments form <noreply@postgresql.org>
2022-11-22 19:10 ` Re: nextval parameter is not clear Bruce Momjian <bruce@momjian.us>
2022-11-23 03:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-23 04:42 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 04:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:04 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 10:33 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-24 14:33 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 15:44 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 20:50 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
@ 2022-11-25 07:40 ` Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-25 14:58 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
0 siblings, 1 reply; 29+ messages in thread
From: Laurenz Albe @ 2022-11-25 07:40 UTC (permalink / raw)
To: Kirk Wolak <wolakk@gmail.com>; David G. Johnston <david.g.johnston@gmail.com>; +Cc: Bruce Momjian <bruce@momjian.us>; ailjushkin@gmail.com; pgsql-docs@lists.postgresql.org
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
^ permalink raw reply [nested|flat] 29+ messages in thread
* Re: nextval parameter is not clear
2022-10-18 08:17 nextval parameter is not clear PG Doc comments form <noreply@postgresql.org>
2022-11-22 19:10 ` Re: nextval parameter is not clear Bruce Momjian <bruce@momjian.us>
2022-11-23 03:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-23 04:42 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 04:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:04 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 10:33 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-24 14:33 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 15:44 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 20:50 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-25 07:40 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
@ 2022-11-25 14:58 ` David G. Johnston <david.g.johnston@gmail.com>
2022-11-25 19:11 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-26 03:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
0 siblings, 2 replies; 29+ messages in thread
From: David G. Johnston @ 2022-11-25 14:58 UTC (permalink / raw)
To: Laurenz Albe <laurenz.albe@cybertec.at>; +Cc: Kirk Wolak <wolakk@gmail.com>; Bruce Momjian <bruce@momjian.us>; ailjushkin@gmail.com; pgsql-docs@lists.postgresql.org
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.
^ permalink raw reply [nested|flat] 29+ messages in thread
* Re: nextval parameter is not clear
2022-10-18 08:17 nextval parameter is not clear PG Doc comments form <noreply@postgresql.org>
2022-11-22 19:10 ` Re: nextval parameter is not clear Bruce Momjian <bruce@momjian.us>
2022-11-23 03:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-23 04:42 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 04:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:04 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 10:33 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-24 14:33 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 15:44 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 20:50 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-25 07:40 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-25 14:58 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
@ 2022-11-25 19:11 ` Kirk Wolak <wolakk@gmail.com>
1 sibling, 0 replies; 29+ messages in thread
From: Kirk Wolak @ 2022-11-25 19:11 UTC (permalink / raw)
To: David G. Johnston <david.g.johnston@gmail.com>; +Cc: Laurenz Albe <laurenz.albe@cybertec.at>; Bruce Momjian <bruce@momjian.us>; ailjushkin@gmail.com; pgsql-docs@lists.postgresql.org
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!
^ permalink raw reply [nested|flat] 29+ messages in thread
* Re: nextval parameter is not clear
2022-10-18 08:17 nextval parameter is not clear PG Doc comments form <noreply@postgresql.org>
2022-11-22 19:10 ` Re: nextval parameter is not clear Bruce Momjian <bruce@momjian.us>
2022-11-23 03:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-23 04:42 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 04:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:04 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 10:33 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-24 14:33 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 15:44 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 20:50 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-25 07:40 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-25 14:58 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
@ 2022-11-26 03:06 ` Kirk Wolak <wolakk@gmail.com>
2022-11-27 04:22 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
1 sibling, 1 reply; 29+ messages in thread
From: Kirk Wolak @ 2022-11-26 03:06 UTC (permalink / raw)
To: David G. Johnston <david.g.johnston@gmail.com>; +Cc: Laurenz Albe <laurenz.albe@cybertec.at>; Bruce Momjian <bruce@momjian.us>; ailjushkin@gmail.com; pgsql-docs@lists.postgresql.org
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
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 82fba48d5f..360cb48f70 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);
+</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>
@@ -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>
@@ -17686,6 +17690,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,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>
</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>
+ <para>Example
+<programlisting>
+CREATE SCHEMA play; <lineannotation>-- Create a play schema</lineannotation>
+SET search_path = play; <lineannotation>-- Make sure we create this in the play schema</lineannotation>
+
+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>-- If you want to see this sequence in psql</lineannotation>
+\ds test_seq
+<lineannotation>-- If you want to see all sequences in psql</lineannotation>
+\ds
+
+<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>
+INSERT INTO t1 (other_data) VALUES ('Some Data')
+ RETURNING id; <lineannotation>-- Assigns the next ID, and returns it to you!</lineannotation>
+
+INSERT INTO t1 (id, other_data) VALUES (NULL, 'Some Data');
+<lineannotation>-- Oops, you forced the ID to NULL: error violates not-null constraint</lineannotation>
+
+INSERT INTO t1 (id, other_data) VALUES (nextval('test_seq'), 'Some Data')
+ RETURNING id; <lineannotation>-- Redundant, but useful in some ETL</lineannotation>
+
+<lineannotation>-- If you create a table with the GENERATED syntax, a sequence is generated behind the scenes</lineannotation>
+
+CREATE TABLE t2 ( id bigint PRIMARY KEY GENERATED BY DEFAULT AS IDENTITY, other_data text);
+
+<lineannotation>-- An implicit sequence named t2_id_seq is created</lineannotation>
+
+INSERT INTO t2 (other_data) values ('data') RETURNING id; <lineannotation>-- 1</lineannotation>
+SELECT currval('t2_id_seq'::regclass); <lineannotation>-- 1</lineannotation>
+
+SELECT setval('t2_id_seq', 10);
+INSERT INTO t2 (other_data) values (1234) RETURNING id; <lineannotation>-- 11</lineannotation>
+
+SELECT lastval(); <lineannotation>-- 11</lineannotation>
+
+<lineannotation>-- Finally, how can you determine the sequence name used for a GENERATED SEQUENCE?</lineannotation>
+SELECT pg_get_serial_sequence('t2', 'id');
+
+<lineannotation>-- And therefore you can use it with the functions in this section, without knowing it's name</lineannotation>
+SELECT currval(pg_get_serial_sequence('t2', 'id'));
+
+</programlisting>
+ </para>
<caution>
<para>
To avoid blocking concurrent transactions that obtain numbers from
Attachments:
[text/plain] func-examples-6.patch (6.2K, ../../CACLU5mTmEieU-uTF6bNm9T5Y94gd1g_cgz_JDLz6Qw36RjcBHQ@mail.gmail.com/3-func-examples-6.patch)
download | inline diff:
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 82fba48d5f..360cb48f70 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);
+</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>
@@ -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>
@@ -17686,6 +17690,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,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>
</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>
+ <para>Example
+<programlisting>
+CREATE SCHEMA play; <lineannotation>-- Create a play schema</lineannotation>
+SET search_path = play; <lineannotation>-- Make sure we create this in the play schema</lineannotation>
+
+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>-- If you want to see this sequence in psql</lineannotation>
+\ds test_seq
+<lineannotation>-- If you want to see all sequences in psql</lineannotation>
+\ds
+
+<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>
+INSERT INTO t1 (other_data) VALUES ('Some Data')
+ RETURNING id; <lineannotation>-- Assigns the next ID, and returns it to you!</lineannotation>
+
+INSERT INTO t1 (id, other_data) VALUES (NULL, 'Some Data');
+<lineannotation>-- Oops, you forced the ID to NULL: error violates not-null constraint</lineannotation>
+
+INSERT INTO t1 (id, other_data) VALUES (nextval('test_seq'), 'Some Data')
+ RETURNING id; <lineannotation>-- Redundant, but useful in some ETL</lineannotation>
+
+<lineannotation>-- If you create a table with the GENERATED syntax, a sequence is generated behind the scenes</lineannotation>
+
+CREATE TABLE t2 ( id bigint PRIMARY KEY GENERATED BY DEFAULT AS IDENTITY, other_data text);
+
+<lineannotation>-- An implicit sequence named t2_id_seq is created</lineannotation>
+
+INSERT INTO t2 (other_data) values ('data') RETURNING id; <lineannotation>-- 1</lineannotation>
+SELECT currval('t2_id_seq'::regclass); <lineannotation>-- 1</lineannotation>
+
+SELECT setval('t2_id_seq', 10);
+INSERT INTO t2 (other_data) values (1234) RETURNING id; <lineannotation>-- 11</lineannotation>
+
+SELECT lastval(); <lineannotation>-- 11</lineannotation>
+
+<lineannotation>-- Finally, how can you determine the sequence name used for a GENERATED SEQUENCE?</lineannotation>
+SELECT pg_get_serial_sequence('t2', 'id');
+
+<lineannotation>-- And therefore you can use it with the functions in this section, without knowing it's name</lineannotation>
+SELECT currval(pg_get_serial_sequence('t2', 'id'));
+
+</programlisting>
+ </para>
<caution>
<para>
To avoid blocking concurrent transactions that obtain numbers from
^ permalink raw reply [nested|flat] 29+ messages in thread
* Re: nextval parameter is not clear
2022-10-18 08:17 nextval parameter is not clear PG Doc comments form <noreply@postgresql.org>
2022-11-22 19:10 ` Re: nextval parameter is not clear Bruce Momjian <bruce@momjian.us>
2022-11-23 03:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-23 04:42 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 04:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:04 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 10:33 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-24 14:33 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 15:44 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 20:50 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-25 07:40 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-25 14:58 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-26 03:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
@ 2022-11-27 04:22 ` Kirk Wolak <wolakk@gmail.com>
2022-11-28 03:34 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
0 siblings, 1 reply; 29+ messages in thread
From: Kirk Wolak @ 2022-11-27 04:22 UTC (permalink / raw)
To: David G. Johnston <david.g.johnston@gmail.com>; +Cc: Laurenz Albe <laurenz.albe@cybertec.at>; Bruce Momjian <bruce@momjian.us>; ailjushkin@gmail.com; pgsql-docs@lists.postgresql.org
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
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 82fba48d5f..360cb48f70 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);
+</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>
@@ -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>
@@ -17686,6 +17690,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,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>
</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>
+ <para>Example
+<programlisting>
+CREATE SCHEMA play; <lineannotation>-- Create a play schema</lineannotation>
+SET search_path = play; <lineannotation>-- Make sure we create this in the play schema</lineannotation>
+
+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>-- If you want to see this sequence in psql</lineannotation>
+\ds test_seq
+<lineannotation>-- If you want to see all sequences in psql</lineannotation>
+\ds
+
+<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>
+INSERT INTO t1 (other_data) VALUES ('Some Data')
+ RETURNING id; <lineannotation>-- Assigns the next ID, and returns it to you!</lineannotation>
+
+INSERT INTO t1 (id, other_data) VALUES (NULL, 'Some Data');
+<lineannotation>-- Oops, you forced the ID to NULL: error violates not-null constraint</lineannotation>
+
+INSERT INTO t1 (id, other_data) VALUES (nextval('test_seq'), 'Some Data')
+ RETURNING id; <lineannotation>-- Redundant, but useful in some ETL</lineannotation>
+
+<lineannotation>-- If you create a table with the GENERATED syntax, a sequence is generated behind the scenes</lineannotation>
+
+CREATE TABLE t2 ( id bigint PRIMARY KEY GENERATED BY DEFAULT AS IDENTITY, other_data text);
+
+<lineannotation>-- An implicit sequence named t2_id_seq is created</lineannotation>
+
+INSERT INTO t2 (other_data) values ('data') RETURNING id; <lineannotation>-- 1</lineannotation>
+SELECT currval('t2_id_seq'::regclass); <lineannotation>-- 1</lineannotation>
+
+SELECT setval('t2_id_seq', 10);
+INSERT INTO t2 (other_data) values (1234) RETURNING id; <lineannotation>-- 11</lineannotation>
+
+SELECT lastval(); <lineannotation>-- 11</lineannotation>
+
+<lineannotation>-- Finally, how can you determine the sequence name used for a GENERATED SEQUENCE?</lineannotation>
+SELECT pg_get_serial_sequence('t2', 'id');
+
+<lineannotation>-- And therefore you can use it with the functions in this section, without knowing it's name</lineannotation>
+SELECT currval(pg_get_serial_sequence('t2', 'id'));
+
+</programlisting>
+ </para>
<caution>
<para>
To avoid blocking concurrent transactions that obtain numbers from
Attachments:
[text/plain] func-examples-7.patch (6.2K, ../../CACLU5mR7JsrJN6qnz=Gh4Ta-0E1hsL++DLLMeWDMQMCVKbOQvw@mail.gmail.com/3-func-examples-7.patch)
download | inline diff:
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 82fba48d5f..360cb48f70 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);
+</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>
@@ -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>
@@ -17686,6 +17690,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,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>
</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>
+ <para>Example
+<programlisting>
+CREATE SCHEMA play; <lineannotation>-- Create a play schema</lineannotation>
+SET search_path = play; <lineannotation>-- Make sure we create this in the play schema</lineannotation>
+
+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>-- If you want to see this sequence in psql</lineannotation>
+\ds test_seq
+<lineannotation>-- If you want to see all sequences in psql</lineannotation>
+\ds
+
+<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>
+INSERT INTO t1 (other_data) VALUES ('Some Data')
+ RETURNING id; <lineannotation>-- Assigns the next ID, and returns it to you!</lineannotation>
+
+INSERT INTO t1 (id, other_data) VALUES (NULL, 'Some Data');
+<lineannotation>-- Oops, you forced the ID to NULL: error violates not-null constraint</lineannotation>
+
+INSERT INTO t1 (id, other_data) VALUES (nextval('test_seq'), 'Some Data')
+ RETURNING id; <lineannotation>-- Redundant, but useful in some ETL</lineannotation>
+
+<lineannotation>-- If you create a table with the GENERATED syntax, a sequence is generated behind the scenes</lineannotation>
+
+CREATE TABLE t2 ( id bigint PRIMARY KEY GENERATED BY DEFAULT AS IDENTITY, other_data text);
+
+<lineannotation>-- An implicit sequence named t2_id_seq is created</lineannotation>
+
+INSERT INTO t2 (other_data) values ('data') RETURNING id; <lineannotation>-- 1</lineannotation>
+SELECT currval('t2_id_seq'::regclass); <lineannotation>-- 1</lineannotation>
+
+SELECT setval('t2_id_seq', 10);
+INSERT INTO t2 (other_data) values (1234) RETURNING id; <lineannotation>-- 11</lineannotation>
+
+SELECT lastval(); <lineannotation>-- 11</lineannotation>
+
+<lineannotation>-- Finally, how can you determine the sequence name used for a GENERATED SEQUENCE?</lineannotation>
+SELECT pg_get_serial_sequence('t2', 'id');
+
+<lineannotation>-- And therefore you can use it with the functions in this section, without knowing it's name</lineannotation>
+SELECT currval(pg_get_serial_sequence('t2', 'id'));
+
+</programlisting>
+ </para>
<caution>
<para>
To avoid blocking concurrent transactions that obtain numbers from
^ permalink raw reply [nested|flat] 29+ messages in thread
* Re: nextval parameter is not clear
2022-10-18 08:17 nextval parameter is not clear PG Doc comments form <noreply@postgresql.org>
2022-11-22 19:10 ` Re: nextval parameter is not clear Bruce Momjian <bruce@momjian.us>
2022-11-23 03:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-23 04:42 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 04:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:04 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 10:33 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-24 14:33 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 15:44 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 20:50 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-25 07:40 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-25 14:58 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-26 03:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-27 04:22 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
@ 2022-11-28 03:34 ` Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-28 05:45 ` Re: nextval parameter is not clear Tom Lane <tgl@sss.pgh.pa.us>
2022-11-28 17:28 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
0 siblings, 2 replies; 29+ messages in thread
From: Laurenz Albe @ 2022-11-28 03:34 UTC (permalink / raw)
To: Kirk Wolak <wolakk@gmail.com>; David G. Johnston <david.g.johnston@gmail.com>; +Cc: Bruce Momjian <bruce@momjian.us>; ailjushkin@gmail.com; pgsql-docs@lists.postgresql.org
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
^ permalink raw reply [nested|flat] 29+ messages in thread
* Re: nextval parameter is not clear
2022-10-18 08:17 nextval parameter is not clear PG Doc comments form <noreply@postgresql.org>
2022-11-22 19:10 ` Re: nextval parameter is not clear Bruce Momjian <bruce@momjian.us>
2022-11-23 03:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-23 04:42 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 04:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:04 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 10:33 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-24 14:33 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 15:44 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 20:50 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-25 07:40 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-25 14:58 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-26 03:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-27 04:22 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-28 03:34 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
@ 2022-11-28 05:45 ` Tom Lane <tgl@sss.pgh.pa.us>
2022-11-28 17:23 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-29 21:26 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
1 sibling, 2 replies; 29+ messages in thread
From: Tom Lane @ 2022-11-28 05:45 UTC (permalink / raw)
To: Laurenz Albe <laurenz.albe@cybertec.at>; +Cc: Kirk Wolak <wolakk@gmail.com>; David G. Johnston <david.g.johnston@gmail.com>; Bruce Momjian <bruce@momjian.us>; ailjushkin@gmail.com; pgsql-docs@lists.postgresql.org
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
^ permalink raw reply [nested|flat] 29+ messages in thread
* Re: nextval parameter is not clear
2022-10-18 08:17 nextval parameter is not clear PG Doc comments form <noreply@postgresql.org>
2022-11-22 19:10 ` Re: nextval parameter is not clear Bruce Momjian <bruce@momjian.us>
2022-11-23 03:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-23 04:42 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 04:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:04 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 10:33 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-24 14:33 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 15:44 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 20:50 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-25 07:40 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-25 14:58 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-26 03:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-27 04:22 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-28 03:34 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-28 05:45 ` Re: nextval parameter is not clear Tom Lane <tgl@sss.pgh.pa.us>
@ 2022-11-28 17:23 ` Kirk Wolak <wolakk@gmail.com>
2022-11-28 17:47 ` Re: nextval parameter is not clear Tom Lane <tgl@sss.pgh.pa.us>
1 sibling, 1 reply; 29+ messages in thread
From: Kirk Wolak @ 2022-11-28 17:23 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Laurenz Albe <laurenz.albe@cybertec.at>; David G. Johnston <david.g.johnston@gmail.com>; Bruce Momjian <bruce@momjian.us>; ailjushkin@gmail.com; pgsql-docs@lists.postgresql.org
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]
^ permalink raw reply [nested|flat] 29+ messages in thread
* Re: nextval parameter is not clear
2022-10-18 08:17 nextval parameter is not clear PG Doc comments form <noreply@postgresql.org>
2022-11-22 19:10 ` Re: nextval parameter is not clear Bruce Momjian <bruce@momjian.us>
2022-11-23 03:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-23 04:42 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 04:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:04 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 10:33 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-24 14:33 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 15:44 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 20:50 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-25 07:40 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-25 14:58 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-26 03:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-27 04:22 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-28 03:34 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-28 05:45 ` Re: nextval parameter is not clear Tom Lane <tgl@sss.pgh.pa.us>
2022-11-28 17:23 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
@ 2022-11-28 17:47 ` Tom Lane <tgl@sss.pgh.pa.us>
2022-11-28 19:22 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
0 siblings, 1 reply; 29+ messages in thread
From: Tom Lane @ 2022-11-28 17:47 UTC (permalink / raw)
To: Kirk Wolak <wolakk@gmail.com>; +Cc: Laurenz Albe <laurenz.albe@cybertec.at>; David G. Johnston <david.g.johnston@gmail.com>; Bruce Momjian <bruce@momjian.us>; ailjushkin@gmail.com; pgsql-docs@lists.postgresql.org
Kirk Wolak <wolakk@gmail.com> writes:
> 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.
I'm not for that. func.sgml is already massive, and doubling its size
with extensive examples doesn't seem like an improvement. Admittedly,
we probably don't need long examples for many of the functions, so maybe
we wouldn't end up with quite that much bloat; but it still seems like
the wrong approach. In my view, that chapter is more in the nature of
reference material, so extended examples ought to go somewhere else.
I could see adding a section about sequences and identity columns to
chapter 3 in the tutorial.
> Preferably where someone
> can copy/paste the example and see the results.
As far as that goes, there's already an idea that src/tutorial/
should contain SQL scripts that you can step-execute to follow
along with the tutorial docs. This hasn't been followed through
on very well --- chapter 2 is covered, but chapter 3 mostly not.
No time like the present to make it better, though. If your
ambition is to make self-contained working examples, making sure
that they execute as a script is good discipline.
regards, tom lane
^ permalink raw reply [nested|flat] 29+ messages in thread
* Re: nextval parameter is not clear
2022-10-18 08:17 nextval parameter is not clear PG Doc comments form <noreply@postgresql.org>
2022-11-22 19:10 ` Re: nextval parameter is not clear Bruce Momjian <bruce@momjian.us>
2022-11-23 03:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-23 04:42 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 04:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:04 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 10:33 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-24 14:33 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 15:44 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 20:50 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-25 07:40 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-25 14:58 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-26 03:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-27 04:22 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-28 03:34 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-28 05:45 ` Re: nextval parameter is not clear Tom Lane <tgl@sss.pgh.pa.us>
2022-11-28 17:23 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-28 17:47 ` Re: nextval parameter is not clear Tom Lane <tgl@sss.pgh.pa.us>
@ 2022-11-28 19:22 ` Kirk Wolak <wolakk@gmail.com>
2022-11-28 19:50 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
0 siblings, 1 reply; 29+ messages in thread
From: Kirk Wolak @ 2022-11-28 19:22 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Laurenz Albe <laurenz.albe@cybertec.at>; David G. Johnston <david.g.johnston@gmail.com>; Bruce Momjian <bruce@momjian.us>; ailjushkin@gmail.com; pgsql-docs@lists.postgresql.org
On Mon, Nov 28, 2022 at 12:47 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
> Kirk Wolak <wolakk@gmail.com> writes:
> > 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.
>
> I'm not for that. func.sgml is already massive, and doubling its size
...
> reference material, so extended examples ought to go somewhere else.
>
> I could see adding a section about sequences and identity columns to
> chapter 3 in the tutorial.
>
> > Preferably where someone
> > can copy/paste the example and see the results.
>
> As far as that goes, there's already an idea that src/tutorial/
> should contain SQL scripts that you can step-execute to follow
> along with the tutorial docs. This hasn't been followed through
> on very well --- chapter 2 is covered, but chapter 3 mostly not.
> No time like the present to make it better, though. If your
> ambition is to make self-contained working examples, making sure
> that they execute as a script is good discipline.
>
> regards, tom lane
>
Two questions follow from the above:
1) For the novice who finds this page (funcs), how will they know to find
the tutorial?
2) Should each function link to that? or One link per page? [to the
appropriate example section]
I will gladly move my focus to adding to the tutorials... (but I want to
know how even I would know it was available if I hit here first)
And I still believe that each function in the documentation section should
have at least a one-line example usage???
After a quick review of the tutorial section, if you end up on any random
page in the tutorial,
the example code does not stand alone.
[I think this was your point]. I see 2 approaches:
A) Simply expand the current examples so that they include the code to make
them stand alone
or
B) Maybe if we had the ENTIRE Tutorial code in one place, runnable
(copy/paste).
Then the more detailed explanations that explain what the statements do,
like we have now.
We would get the best of both worlds?
Thanks, Kirk
^ permalink raw reply [nested|flat] 29+ messages in thread
* Re: nextval parameter is not clear
2022-10-18 08:17 nextval parameter is not clear PG Doc comments form <noreply@postgresql.org>
2022-11-22 19:10 ` Re: nextval parameter is not clear Bruce Momjian <bruce@momjian.us>
2022-11-23 03:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-23 04:42 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 04:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:04 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 10:33 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-24 14:33 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 15:44 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 20:50 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-25 07:40 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-25 14:58 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-26 03:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-27 04:22 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-28 03:34 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-28 05:45 ` Re: nextval parameter is not clear Tom Lane <tgl@sss.pgh.pa.us>
2022-11-28 17:23 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-28 17:47 ` Re: nextval parameter is not clear Tom Lane <tgl@sss.pgh.pa.us>
2022-11-28 19:22 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
@ 2022-11-28 19:50 ` David G. Johnston <david.g.johnston@gmail.com>
0 siblings, 0 replies; 29+ messages in thread
From: David G. Johnston @ 2022-11-28 19:50 UTC (permalink / raw)
To: Kirk Wolak <wolakk@gmail.com>; +Cc: Tom Lane <tgl@sss.pgh.pa.us>; Laurenz Albe <laurenz.albe@cybertec.at>; Bruce Momjian <bruce@momjian.us>; ailjushkin@gmail.com; pgsql-docs@lists.postgresql.org
On Mon, Nov 28, 2022 at 12:22 PM Kirk Wolak <wolakk@gmail.com> wrote:
> On Mon, Nov 28, 2022 at 12:47 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
>
>> Kirk Wolak <wolakk@gmail.com> writes:
>> > 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.
>>
>> I'm not for that. func.sgml is already massive, and doubling its size
>
> ...
>> reference material, so extended examples ought to go somewhere else.
>>
>> I could see adding a section about sequences and identity columns to
>> chapter 3 in the tutorial.
>>
>> > Preferably where someone
>> > can copy/paste the example and see the results.
>>
>> As far as that goes, there's already an idea that src/tutorial/
>> should contain SQL scripts that you can step-execute to follow
>> along with the tutorial docs. This hasn't been followed through
>> on very well --- chapter 2 is covered, but chapter 3 mostly not.
>> No time like the present to make it better, though. If your
>> ambition is to make self-contained working examples, making sure
>> that they execute as a script is good discipline.
>>
>> regards, tom lane
>>
>
> Two questions follow from the above:
> 1) For the novice who finds this page (funcs), how will they know to find
> the tutorial?
> 2) Should each function link to that? or One link per page? [to the
> appropriate example section]
>
You would add a sentence, as appropriate to the page, pointing the reader
to the tutorial section for further examples. There isn't really a
rule-of-thumb here; use existing examples and context to figure out what
makes the most sense.
>
> I will gladly move my focus to adding to the tutorials... (but I want to
> know how even I would know it was available if I hit here first)
>
> And I still believe that each function in the documentation section should
> have at least a one-line example usage???
>
There already is guaranteed one example - it is the function signature that
begins each row.
On a related point, the word SELECT in table examples is unwanted noise
(this page is not the best example to emulate). The example call
expressions the supplement the function signature also need not be
executable.
The string functions demonstrate good usage examples for the tables.
https://www.postgresql.org/docs/current/functions-string.html
> After a quick review of the tutorial section, if you end up on any random
> page in the tutorial,
> the example code does not stand alone.
>
If you'd like to start a discussion on this I suggest a new email thread,
leaving this one to finishing the patch within the reality of the
documentation as it exists today. That is to say, making decisions based
upon existing prior work and sound arguments about the merits of the
content presentation. This isn't the place to experiment and propose an
example of some new grand design.
David J.
^ permalink raw reply [nested|flat] 29+ messages in thread
* Re: nextval parameter is not clear
2022-10-18 08:17 nextval parameter is not clear PG Doc comments form <noreply@postgresql.org>
2022-11-22 19:10 ` Re: nextval parameter is not clear Bruce Momjian <bruce@momjian.us>
2022-11-23 03:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-23 04:42 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 04:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:04 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 10:33 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-24 14:33 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 15:44 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 20:50 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-25 07:40 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-25 14:58 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-26 03:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-27 04:22 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-28 03:34 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-28 05:45 ` Re: nextval parameter is not clear Tom Lane <tgl@sss.pgh.pa.us>
@ 2022-11-29 21:26 ` Kirk Wolak <wolakk@gmail.com>
2022-12-01 21:21 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
1 sibling, 1 reply; 29+ messages in thread
From: Kirk Wolak @ 2022-11-29 21:26 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Laurenz Albe <laurenz.albe@cybertec.at>; David G. Johnston <david.g.johnston@gmail.com>; Bruce Momjian <bruce@momjian.us>; ailjushkin@gmail.com; pgsql-docs@lists.postgresql.org
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.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
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.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
^ permalink raw reply [nested|flat] 29+ messages in thread
* Re: nextval parameter is not clear
2022-10-18 08:17 nextval parameter is not clear PG Doc comments form <noreply@postgresql.org>
2022-11-22 19:10 ` Re: nextval parameter is not clear Bruce Momjian <bruce@momjian.us>
2022-11-23 03:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-23 04:42 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 04:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:04 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 10:33 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-24 14:33 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 15:44 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 20:50 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-25 07:40 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-25 14:58 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-26 03:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-27 04:22 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-28 03:34 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-28 05:45 ` Re: nextval parameter is not clear Tom Lane <tgl@sss.pgh.pa.us>
2022-11-29 21:26 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
@ 2022-12-01 21:21 ` Laurenz Albe <laurenz.albe@cybertec.at>
2022-12-04 03:02 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
0 siblings, 1 reply; 29+ messages in thread
From: Laurenz Albe @ 2022-12-01 21:21 UTC (permalink / raw)
To: Kirk Wolak <wolakk@gmail.com>; Tom Lane <tgl@sss.pgh.pa.us>; +Cc: David G. Johnston <david.g.johnston@gmail.com>; Bruce Momjian <bruce@momjian.us>; ailjushkin@gmail.com; pgsql-docs@lists.postgresql.org
On Tue, 2022-11-29 at 16:26 -0500, Kirk Wolak wrote:
> 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.
You can have <title> only after the start of a section.
The new examples in the table don't really add anything to the function declaration...
I realized that there already are some examples in the CREATE SEQUENCE documentation,
so what about linking there instead of writing more examples?
The attached patch does that and removes the less useful examples. What do you think?
Yours,
Laurenz Albe
Attachments:
[text/x-patch] 0001-Improve-sequence-manipulation-function-doc.v9.patch (3.7K, ../../075bcf0bf071140c294261d52687fd8d78fb5255.camel@cybertec.at/2-0001-Improve-sequence-manipulation-function-doc.v9.patch)
download | inline diff:
From df836162e88e6ac51d47c26908df64fb122414ce Mon Sep 17 00:00:00 2001
From: Laurenz Albe <laurenz.albe@cybertec.at>
Date: Thu, 1 Dec 2022 22:16:28 +0100
Subject: [PATCH] Improve sequence manipulation function doc
Point to the example section of CREATE SEQUENCE for examples.
Add "--" before comments interleaved with code.
Some slight rewording.
Author: Kirk Wolak
---
doc/src/sgml/func.sgml | 20 ++++++++++++--------
doc/src/sgml/ref/create_sequence.sgml | 2 +-
2 files changed, 13 insertions(+), 9 deletions(-)
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 6e0425cb3d..2391deabea 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -17623,7 +17623,7 @@ $.* ? (@ 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>
This function requires <literal>USAGE</literal>
or <literal>UPDATE</literal> privilege on the sequence.
@@ -17657,11 +17657,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>
@@ -17707,9 +17707,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>
@@ -17720,6 +17719,11 @@ SELECT setval('myseq', 42, false); <lineannotation>Next <function>nextval</fu
</tgroup>
</table>
+ <para>
+ You can see sequence manipulation functions being used in the
+ <xref linkend="sql-createsequence-examples"/>.
+ </para>
+
<caution>
<para>
To avoid blocking concurrent transactions that obtain numbers from
diff --git a/doc/src/sgml/ref/create_sequence.sgml b/doc/src/sgml/ref/create_sequence.sgml
index 34e9084b5c..d417405930 100644
--- a/doc/src/sgml/ref/create_sequence.sgml
+++ b/doc/src/sgml/ref/create_sequence.sgml
@@ -329,7 +329,7 @@ SELECT * FROM <replaceable>name</replaceable>;
</para>
</refsect1>
- <refsect1>
+ <refsect1 id="sql-createsequence-examples" xreflabel="Examples for CREATE SEQUENCE">
<title>Examples</title>
<para>
--
2.38.1
^ permalink raw reply [nested|flat] 29+ messages in thread
* Re: nextval parameter is not clear
2022-10-18 08:17 nextval parameter is not clear PG Doc comments form <noreply@postgresql.org>
2022-11-22 19:10 ` Re: nextval parameter is not clear Bruce Momjian <bruce@momjian.us>
2022-11-23 03:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-23 04:42 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 04:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:04 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 10:33 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-24 14:33 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 15:44 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 20:50 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-25 07:40 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-25 14:58 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-26 03:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-27 04:22 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-28 03:34 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-28 05:45 ` Re: nextval parameter is not clear Tom Lane <tgl@sss.pgh.pa.us>
2022-11-29 21:26 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-12-01 21:21 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
@ 2022-12-04 03:02 ` Kirk Wolak <wolakk@gmail.com>
2022-12-04 04:46 ` Re: nextval parameter is not clear Александр Илюшкин <ailjushkin@gmail.com>
2022-12-07 21:32 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
0 siblings, 2 replies; 29+ messages in thread
From: Kirk Wolak @ 2022-12-04 03:02 UTC (permalink / raw)
To: Laurenz Albe <laurenz.albe@cybertec.at>; +Cc: Tom Lane <tgl@sss.pgh.pa.us>; David G. Johnston <david.g.johnston@gmail.com>; Bruce Momjian <bruce@momjian.us>; ailjushkin@gmail.com; pgsql-docs@lists.postgresql.org
On Thu, Dec 1, 2022 at 4:21 PM Laurenz Albe <laurenz.albe@cybertec.at>
wrote:
> On Tue, 2022-11-29 at 16:26 -0500, Kirk Wolak wrote:
> > 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.
>
> You can have <title> only after the start of a section.
>
> The new examples in the table don't really add anything to the function
> declaration...
>
> I realized that there already are some examples in the CREATE SEQUENCE
> documentation,
> so what about linking there instead of writing more examples?
>
> The attached patch does that and removes the less useful examples. What
> do you think?
>
> Yours,
> Laurenz Albe
>
+1
^ permalink raw reply [nested|flat] 29+ messages in thread
* Re: nextval parameter is not clear
2022-10-18 08:17 nextval parameter is not clear PG Doc comments form <noreply@postgresql.org>
2022-11-22 19:10 ` Re: nextval parameter is not clear Bruce Momjian <bruce@momjian.us>
2022-11-23 03:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-23 04:42 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 04:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:04 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 10:33 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-24 14:33 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 15:44 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 20:50 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-25 07:40 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-25 14:58 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-26 03:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-27 04:22 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-28 03:34 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-28 05:45 ` Re: nextval parameter is not clear Tom Lane <tgl@sss.pgh.pa.us>
2022-11-29 21:26 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-12-01 21:21 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-12-04 03:02 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
@ 2022-12-04 04:46 ` Александр Илюшкин <ailjushkin@gmail.com>
1 sibling, 0 replies; 29+ messages in thread
From: Александр Илюшкин @ 2022-12-04 04:46 UTC (permalink / raw)
To: Kirk Wolak <wolakk@gmail.com>; +Cc: Laurenz Albe <laurenz.albe@cybertec.at>; Tom Lane <tgl@sss.pgh.pa.us>; David G. Johnston <david.g.johnston@gmail.com>; Bruce Momjian <bruce@momjian.us>; pgsql-docs@lists.postgresql.org
That was feedback on my issue I've never seen before. Thanks so much to all
of you.
С уважением, А. И.
вс, 4 дек. 2022 г., 06:03 Kirk Wolak <wolakk@gmail.com>:
> On Thu, Dec 1, 2022 at 4:21 PM Laurenz Albe <laurenz.albe@cybertec.at>
> wrote:
>
>> On Tue, 2022-11-29 at 16:26 -0500, Kirk Wolak wrote:
>> > 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.
>>
>> You can have <title> only after the start of a section.
>>
>> The new examples in the table don't really add anything to the function
>> declaration...
>>
>> I realized that there already are some examples in the CREATE SEQUENCE
>> documentation,
>> so what about linking there instead of writing more examples?
>>
>> The attached patch does that and removes the less useful examples. What
>> do you think?
>>
>> Yours,
>> Laurenz Albe
>>
>
> +1
>
^ permalink raw reply [nested|flat] 29+ messages in thread
* Re: nextval parameter is not clear
2022-10-18 08:17 nextval parameter is not clear PG Doc comments form <noreply@postgresql.org>
2022-11-22 19:10 ` Re: nextval parameter is not clear Bruce Momjian <bruce@momjian.us>
2022-11-23 03:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-23 04:42 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 04:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:04 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 10:33 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-24 14:33 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 15:44 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 20:50 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-25 07:40 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-25 14:58 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-26 03:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-27 04:22 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-28 03:34 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-28 05:45 ` Re: nextval parameter is not clear Tom Lane <tgl@sss.pgh.pa.us>
2022-11-29 21:26 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-12-01 21:21 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-12-04 03:02 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
@ 2022-12-07 21:32 ` David G. Johnston <david.g.johnston@gmail.com>
2022-12-08 14:15 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
1 sibling, 1 reply; 29+ messages in thread
From: David G. Johnston @ 2022-12-07 21:32 UTC (permalink / raw)
To: Kirk Wolak <wolakk@gmail.com>; +Cc: Laurenz Albe <laurenz.albe@cybertec.at>; Tom Lane <tgl@sss.pgh.pa.us>; Bruce Momjian <bruce@momjian.us>; ailjushkin@gmail.com; pgsql-docs@lists.postgresql.org
On Sat, Dec 3, 2022 at 8:03 PM Kirk Wolak <wolakk@gmail.com> wrote:
> On Thu, Dec 1, 2022 at 4:21 PM Laurenz Albe <laurenz.albe@cybertec.at>
> wrote:
>
>> On Tue, 2022-11-29 at 16:26 -0500, Kirk Wolak wrote:
>> > 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.
>>
>> You can have <title> only after the start of a section.
>>
>> The new examples in the table don't really add anything to the function
>> declaration...
>>
>> I realized that there already are some examples in the CREATE SEQUENCE
>> documentation,
>> so what about linking there instead of writing more examples?
>>
>> The attached patch does that and removes the less useful examples. What
>> do you think?
>>
>> Yours,
>> Laurenz Albe
>>
>
> +1
>
While I agree with the conclusion that the function signature is an
example, and having more than one for these is probably overkill, we can
address the OP's complaint quite easily by doing what we do in many other
places, give each parameter in the function signature a name. I've
modified v9 to include those and attach it here as v10. I do think this
suffices as a response to this complaint.
Bikeshedding on the names for setval, and maybe an attempt to incorporate
the parameter name into the prose, can be considered, though.
My thoughts regarding incorporating pg_get_serial_sequence and usage of
these functions in a more common, GENERATED AS IDENTITY environment, can be
considered in a separate thread should I or anyone else wish to do so.
David J.
Attachments:
[application/octet-stream] 0001-Improve-sequence-manipulation-function-doc.v10.patch (4.4K, ../../CAKFQuwZsH4X4E5=Qo2Ebz7FTcTnbdxYn1fGUdZ0TVOSamJyChA@mail.gmail.com/3-0001-Improve-sequence-manipulation-function-doc.v10.patch)
download | inline diff:
From 01db33f785f979bb017b1a15964b432033e2caac Mon Sep 17 00:00:00 2001
From: "David G. Johnston" <David.G.Johnston@Gmail.com>
Date: Wed, 7 Dec 2022 21:20:25 +0000
Subject: [PATCH] Improve sequence manipulation function doc
---
doc/src/sgml/func.sgml | 26 +++++++++++++++-----------
1 file changed, 15 insertions(+), 11 deletions(-)
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 2052d3c844..26f71d864b 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -17614,7 +17614,7 @@ $.* ? (@ like_regex "^\\d+$")
<indexterm>
<primary>nextval</primary>
</indexterm>
- <function>nextval</function> ( <type>regclass</type> )
+ <function>nextval</function> ( <parameter>sequence_name</parameter> <type>regclass</type> )
<returnvalue>bigint</returnvalue>
</para>
<para>
@@ -17627,7 +17627,7 @@ $.* ? (@ 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>
This function requires <literal>USAGE</literal>
or <literal>UPDATE</literal> privilege on the sequence.
@@ -17639,7 +17639,7 @@ $.* ? (@ like_regex "^\\d+$")
<indexterm>
<primary>setval</primary>
</indexterm>
- <function>setval</function> ( <type>regclass</type>, <type>bigint</type> <optional>, <type>boolean</type> </optional> )
+ <function>setval</function> ( <parameter>sequence_name</parameter> <type>regclass</type>, <parameter>new_current_value</parameter> <type>bigint</type> <optional>, <parameter>is_called</parameter> <type>boolean</type> </optional> )
<returnvalue>bigint</returnvalue>
</para>
<para>
@@ -17661,11 +17661,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>
@@ -17679,7 +17679,7 @@ SELECT setval('myseq', 42, false); <lineannotation>Next <function>nextval</fu
<indexterm>
<primary>currval</primary>
</indexterm>
- <function>currval</function> ( <type>regclass</type> )
+ <function>currval</function> ( <parameter>sequence_name</parameter> <type>regclass</type> )
<returnvalue>bigint</returnvalue>
</para>
<para>
@@ -17711,9 +17711,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>
@@ -17724,6 +17723,11 @@ SELECT setval('myseq', 42, false); <lineannotation>Next <function>nextval</fu
</tgroup>
</table>
+ <para>
+ You can see sequence manipulation functions being used in the
+ <xref linkend="sql-createsequence-examples"/>.
+ </para>
+
<caution>
<para>
To avoid blocking concurrent transactions that obtain numbers from
--
2.25.1
^ permalink raw reply [nested|flat] 29+ messages in thread
* Re: nextval parameter is not clear
2022-10-18 08:17 nextval parameter is not clear PG Doc comments form <noreply@postgresql.org>
2022-11-22 19:10 ` Re: nextval parameter is not clear Bruce Momjian <bruce@momjian.us>
2022-11-23 03:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-23 04:42 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 04:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:04 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 10:33 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-24 14:33 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 15:44 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 20:50 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-25 07:40 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-25 14:58 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-26 03:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-27 04:22 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-28 03:34 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-28 05:45 ` Re: nextval parameter is not clear Tom Lane <tgl@sss.pgh.pa.us>
2022-11-29 21:26 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-12-01 21:21 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-12-04 03:02 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-12-07 21:32 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
@ 2022-12-08 14:15 ` Laurenz Albe <laurenz.albe@cybertec.at>
0 siblings, 0 replies; 29+ messages in thread
From: Laurenz Albe @ 2022-12-08 14:15 UTC (permalink / raw)
To: David G. Johnston <david.g.johnston@gmail.com>; Kirk Wolak <wolakk@gmail.com>; +Cc: Tom Lane <tgl@sss.pgh.pa.us>; Bruce Momjian <bruce@momjian.us>; ailjushkin@gmail.com; pgsql-docs@lists.postgresql.org
On Wed, 2022-12-07 at 14:32 -0700, David G. Johnston wrote:
> While I agree with the conclusion that the function signature is an example,
> and having more than one for these is probably overkill, we can address the
> OP's complaint quite easily by doing what we do in many other places, give
> each parameter in the function signature a name. I've modified v9 to include
> those and attach it here as v10. I do think this suffices as a response
> to this complaint.
>
> Bikeshedding on the names for setval, and maybe an attempt to incorporate
> the parameter name into the prose, can be considered, though.
Thanks for looking into that, and parameter names are fully sufficient to
clarify the usage.
Your patch is good, except that you forgot to add the link target on the CREATE
SEQUENCE page.
> My thoughts regarding incorporating pg_get_serial_sequence and usage of these
> functions in a more common, GENERATED AS IDENTITY environment, can be considered
> in a separate thread should I or anyone else wish to do so.
+1
Yours,
Laurenz Albe
^ permalink raw reply [nested|flat] 29+ messages in thread
* Re: nextval parameter is not clear
2022-10-18 08:17 nextval parameter is not clear PG Doc comments form <noreply@postgresql.org>
2022-11-22 19:10 ` Re: nextval parameter is not clear Bruce Momjian <bruce@momjian.us>
2022-11-23 03:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-23 04:42 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 04:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:04 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:41 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 10:33 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-24 14:33 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-24 15:44 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 20:50 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-25 07:40 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-25 14:58 ` Re: nextval parameter is not clear David G. Johnston <david.g.johnston@gmail.com>
2022-11-26 03:06 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-27 04:22 ` Re: nextval parameter is not clear Kirk Wolak <wolakk@gmail.com>
2022-11-28 03:34 ` Re: nextval parameter is not clear Laurenz Albe <laurenz.albe@cybertec.at>
@ 2022-11-28 17:28 ` Kirk Wolak <wolakk@gmail.com>
1 sibling, 0 replies; 29+ messages in thread
From: Kirk Wolak @ 2022-11-28 17:28 UTC (permalink / raw)
To: Laurenz Albe <laurenz.albe@cybertec.at>; +Cc: David G. Johnston <david.g.johnston@gmail.com>; Bruce Momjian <bruce@momjian.us>; ailjushkin@gmail.com; pgsql-docs@lists.postgresql.org
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...
^ permalink raw reply [nested|flat] 29+ messages in thread
end of thread, other threads:[~2022-12-08 14:15 UTC | newest]
Thread overview: 29+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2022-10-18 08:17 nextval parameter is not clear PG Doc comments form <noreply@postgresql.org>
2022-11-22 19:10 ` Bruce Momjian <bruce@momjian.us>
2022-11-23 03:41 ` Kirk Wolak <wolakk@gmail.com>
2022-11-23 04:42 ` David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 04:06 ` Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:04 ` Kirk Wolak <wolakk@gmail.com>
2022-11-24 07:41 ` Kirk Wolak <wolakk@gmail.com>
2022-11-24 10:33 ` Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-24 14:33 ` Kirk Wolak <wolakk@gmail.com>
2022-11-24 15:44 ` David G. Johnston <david.g.johnston@gmail.com>
2022-11-24 20:50 ` Kirk Wolak <wolakk@gmail.com>
2022-11-25 07:40 ` Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-25 14:58 ` David G. Johnston <david.g.johnston@gmail.com>
2022-11-25 19:11 ` Kirk Wolak <wolakk@gmail.com>
2022-11-26 03:06 ` Kirk Wolak <wolakk@gmail.com>
2022-11-27 04:22 ` Kirk Wolak <wolakk@gmail.com>
2022-11-28 03:34 ` Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-28 05:45 ` Tom Lane <tgl@sss.pgh.pa.us>
2022-11-28 17:23 ` Kirk Wolak <wolakk@gmail.com>
2022-11-28 17:47 ` Tom Lane <tgl@sss.pgh.pa.us>
2022-11-28 19:22 ` Kirk Wolak <wolakk@gmail.com>
2022-11-28 19:50 ` David G. Johnston <david.g.johnston@gmail.com>
2022-11-29 21:26 ` Kirk Wolak <wolakk@gmail.com>
2022-12-01 21:21 ` Laurenz Albe <laurenz.albe@cybertec.at>
2022-12-04 03:02 ` Kirk Wolak <wolakk@gmail.com>
2022-12-04 04:46 ` Александр Илюшкин <ailjushkin@gmail.com>
2022-12-07 21:32 ` David G. Johnston <david.g.johnston@gmail.com>
2022-12-08 14:15 ` Laurenz Albe <laurenz.albe@cybertec.at>
2022-11-28 17:28 ` Kirk Wolak <wolakk@gmail.com>
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