On Wed, Nov 23, 2022 at 11:06 PM Kirk Wolak <wol...@gmail.com> wrote:
> On Tue, Nov 22, 2022 at 11:43 PM David G. Johnston <
> david.g.johns...@gmail.com> wrote:
>
>> On Tue, Nov 22, 2022 at 8:42 PM Kirk Wolak <wol...@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>
