PG docs - Sequence CYCLE clause
Started by Peter Smithover 1 year ago4 messages
Hi hackers.
While reviewing another thread I had cause to be looking more
carefully at the SEQUENCE documentation.
I found it curious that, unlike other clauses, the syntax of the CYCLE
clause was not displayed on a line by itself.
I have changed that, and at the same time I have moved the CYCLE
syntax (plus its description) to be adjacent to MINVALUE/MAXVALUE,
which IMO is where it naturally belongs.
Please see the attached patch.
Thoughts?
======
Kind Regards,
Peter Smith.
Fujitsu Australia
Attachments:
docs_sequence_cycle.diffapplication/octet-stream; name=docs_sequence_cycle.diffDownload
diff --git a/doc/src/sgml/ref/alter_sequence.sgml b/doc/src/sgml/ref/alter_sequence.sgml
index 7be36cf..a998ccc 100644
--- a/doc/src/sgml/ref/alter_sequence.sgml
+++ b/doc/src/sgml/ref/alter_sequence.sgml
@@ -27,9 +27,10 @@ ALTER SEQUENCE [ IF EXISTS ] <replaceable class="parameter">name</replaceable>
[ AS <replaceable class="parameter">data_type</replaceable> ]
[ INCREMENT [ BY ] <replaceable class="parameter">increment</replaceable> ]
[ MINVALUE <replaceable class="parameter">minvalue</replaceable> | NO MINVALUE ] [ MAXVALUE <replaceable class="parameter">maxvalue</replaceable> | NO MAXVALUE ]
+ [ [ NO ] CYCLE ]
[ START [ WITH ] <replaceable class="parameter">start</replaceable> ]
[ RESTART [ [ WITH ] <replaceable class="parameter">restart</replaceable> ] ]
- [ CACHE <replaceable class="parameter">cache</replaceable> ] [ [ NO ] CYCLE ]
+ [ CACHE <replaceable class="parameter">cache</replaceable> ]
[ OWNED BY { <replaceable class="parameter">table_name</replaceable>.<replaceable class="parameter">column_name</replaceable> | NONE } ]
ALTER SEQUENCE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> SET { LOGGED | UNLOGGED }
ALTER SEQUENCE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> OWNER TO { <replaceable class="parameter">new_owner</replaceable> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
@@ -155,6 +156,38 @@ ALTER SEQUENCE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> S
</varlistentry>
<varlistentry>
+ <term><literal>CYCLE</literal></term>
+ <listitem>
+ <para>
+ The optional <literal>CYCLE</literal> key word can be used to enable
+ the sequence to wrap around when the
+ <replaceable class="parameter">maxvalue</replaceable> or
+ <replaceable class="parameter">minvalue</replaceable> has been
+ reached by
+ an ascending or descending sequence respectively. If the limit is
+ reached, the next number generated will be the
+ <replaceable class="parameter">minvalue</replaceable> or
+ <replaceable class="parameter">maxvalue</replaceable>,
+ respectively.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>NO CYCLE</literal></term>
+ <listitem>
+ <para>
+ If the optional <literal>NO CYCLE</literal> key word is
+ specified, any calls to <function>nextval</function> after the
+ sequence has reached its maximum value will return an error.
+ If neither <literal>CYCLE</literal> or <literal>NO
+ CYCLE</literal> are specified, the old cycle behavior will be
+ maintained.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><replaceable class="parameter">start</replaceable></term>
<listitem>
<para>
@@ -208,38 +241,6 @@ ALTER SEQUENCE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> S
</varlistentry>
<varlistentry>
- <term><literal>CYCLE</literal></term>
- <listitem>
- <para>
- The optional <literal>CYCLE</literal> key word can be used to enable
- the sequence to wrap around when the
- <replaceable class="parameter">maxvalue</replaceable> or
- <replaceable class="parameter">minvalue</replaceable> has been
- reached by
- an ascending or descending sequence respectively. If the limit is
- reached, the next number generated will be the
- <replaceable class="parameter">minvalue</replaceable> or
- <replaceable class="parameter">maxvalue</replaceable>,
- respectively.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>NO CYCLE</literal></term>
- <listitem>
- <para>
- If the optional <literal>NO CYCLE</literal> key word is
- specified, any calls to <function>nextval</function> after the
- sequence has reached its maximum value will return an error.
- If neither <literal>CYCLE</literal> or <literal>NO
- CYCLE</literal> are specified, the old cycle behavior will be
- maintained.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
<term><literal>SET { LOGGED | UNLOGGED }</literal></term>
<listitem>
<para>
diff --git a/doc/src/sgml/ref/create_sequence.sgml b/doc/src/sgml/ref/create_sequence.sgml
index 34e9084..1e283f1 100644
--- a/doc/src/sgml/ref/create_sequence.sgml
+++ b/doc/src/sgml/ref/create_sequence.sgml
@@ -25,7 +25,9 @@ CREATE [ { TEMPORARY | TEMP } | UNLOGGED ] SEQUENCE [ IF NOT EXISTS ] <replaceab
[ AS <replaceable class="parameter">data_type</replaceable> ]
[ INCREMENT [ BY ] <replaceable class="parameter">increment</replaceable> ]
[ MINVALUE <replaceable class="parameter">minvalue</replaceable> | NO MINVALUE ] [ MAXVALUE <replaceable class="parameter">maxvalue</replaceable> | NO MAXVALUE ]
- [ START [ WITH ] <replaceable class="parameter">start</replaceable> ] [ CACHE <replaceable class="parameter">cache</replaceable> ] [ [ NO ] CYCLE ]
+ [ [ NO ] CYCLE ]
+ [ START [ WITH ] <replaceable class="parameter">start</replaceable> ]
+ [ CACHE <replaceable class="parameter">cache</replaceable> ]
[ OWNED BY { <replaceable class="parameter">table_name</replaceable>.<replaceable class="parameter">column_name</replaceable> | NONE } ]
</synopsis>
</refsynopsisdiv>
@@ -194,6 +196,31 @@ SELECT * FROM <replaceable>name</replaceable>;
</varlistentry>
<varlistentry>
+ <term><literal>CYCLE</literal></term>
+ <term><literal>NO CYCLE</literal></term>
+ <listitem>
+ <para>
+ The <literal>CYCLE</literal> option allows the sequence to wrap
+ around when the <replaceable
+ class="parameter">maxvalue</replaceable> or <replaceable
+ class="parameter">minvalue</replaceable> has been reached by an
+ ascending or descending sequence respectively. If the limit is
+ reached, the next number generated will be the <replaceable
+ class="parameter">minvalue</replaceable> or <replaceable
+ class="parameter">maxvalue</replaceable>, respectively.
+ </para>
+
+ <para>
+ If <literal>NO CYCLE</literal> is specified, any calls to
+ <function>nextval</function> after the sequence has reached its
+ maximum value will return an error. If neither
+ <literal>CYCLE</literal> or <literal>NO CYCLE</literal> are
+ specified, <literal>NO CYCLE</literal> is the default.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><replaceable class="parameter">start</replaceable></term>
<listitem>
<para>
@@ -222,31 +249,6 @@ SELECT * FROM <replaceable>name</replaceable>;
</varlistentry>
<varlistentry>
- <term><literal>CYCLE</literal></term>
- <term><literal>NO CYCLE</literal></term>
- <listitem>
- <para>
- The <literal>CYCLE</literal> option allows the sequence to wrap
- around when the <replaceable
- class="parameter">maxvalue</replaceable> or <replaceable
- class="parameter">minvalue</replaceable> has been reached by an
- ascending or descending sequence respectively. If the limit is
- reached, the next number generated will be the <replaceable
- class="parameter">minvalue</replaceable> or <replaceable
- class="parameter">maxvalue</replaceable>, respectively.
- </para>
-
- <para>
- If <literal>NO CYCLE</literal> is specified, any calls to
- <function>nextval</function> after the sequence has reached its
- maximum value will return an error. If neither
- <literal>CYCLE</literal> or <literal>NO CYCLE</literal> are
- specified, <literal>NO CYCLE</literal> is the default.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
<term><literal>OWNED BY</literal> <replaceable class="parameter">table_name</replaceable>.<replaceable class="parameter">column_name</replaceable></term>
<term><literal>OWNED BY NONE</literal></term>
<listitem>
Re: PG docs - Sequence CYCLE clause
On 13.08.24 07:46, Peter Smith wrote:
While reviewing another thread I had cause to be looking more
carefully at the SEQUENCE documentation.I found it curious that, unlike other clauses, the syntax of the CYCLE
clause was not displayed on a line by itself.I have changed that, and at the same time I have moved the CYCLE
syntax (plus its description) to be adjacent to MINVALUE/MAXVALUE,
which IMO is where it naturally belongs.Please see the attached patch.
I agree, it makes a bit more sense with your patches.
Re: PG docs - Sequence CYCLE clause
On Wed, Aug 14, 2024 at 01:46:23PM +0200, Peter Eisentraut wrote:
On 13.08.24 07:46, Peter Smith wrote:
While reviewing another thread I had cause to be looking more
carefully at the SEQUENCE documentation.I found it curious that, unlike other clauses, the syntax of the CYCLE
clause was not displayed on a line by itself.I have changed that, and at the same time I have moved the CYCLE
syntax (plus its description) to be adjacent to MINVALUE/MAXVALUE,
which IMO is where it naturally belongs.Please see the attached patch.
I agree, it makes a bit more sense with your patches.
Great, patch applied to master.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Only you can decide what is important to you.