From 9ddfe034c7d7ee9c4a7dcae1ba37e5e4e5ac2488 Mon Sep 17 00:00:00 2001
From: Tom Lane
Date: Thu, 25 Oct 2007 18:54:03 +0000
Subject: Fix ALTER SEQUENCE so that it does not affect the value of currval()
 for the sequence.  Also, make setval() with is_called = false not affect the
 currval state, either.  Per report from Kris Jurka that an implicit ALTER
 SEQUENCE OWNED BY unexpectedly caused currval() to become valid. Since this
 isn't 100% backwards compatible, it will go into HEAD only; I'll put a more
 limited patch into 8.2.

---
 doc/src/sgml/func.sgml               | 23 ++++++++++++++---------
 doc/src/sgml/ref/alter_sequence.sgml | 13 +++++++++++--
 2 files changed, 25 insertions(+), 11 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index c9d665376e4..5feb572de2d 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.404 2007/10/23 20:46:11 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.405 2007/10/25 18:54:03 tgl Exp $ -->
 
  <chapter id="functions">
   <title>Functions and Operators</title>
@@ -8733,15 +8733,20 @@ nextval('foo'::text)      <lineannotation><literal>foo</literal> is looked up at
       <listitem>
        <para>
         Reset the sequence object's counter value.  The two-parameter
-        form sets the sequence's <literal>last_value</literal> field to the specified
-        value and sets its <literal>is_called</literal> field to <literal>true</literal>,
-        meaning that the next <function>nextval</function> will advance the sequence
-        before returning a value.  In the three-parameter form,
-        <literal>is_called</literal> can be set either <literal>true</literal> or
-        <literal>false</literal>.  If it's set to <literal>false</literal>,
-        the next <function>nextval</function> will return exactly the specified
+        form sets the sequence's <literal>last_value</literal> field to the
+        specified value and sets its <literal>is_called</literal> field to
+        <literal>true</literal>, meaning that the next
+        <function>nextval</function> will advance the sequence before
+        returning a value.  The value reported by <function>currval</> is
+        also set to the specified value.  In the three-parameter form,
+        <literal>is_called</literal> can be set either <literal>true</literal>
+        or <literal>false</literal>.  <literal>true</> has the same effect as
+        the two-parameter form. If it's set to <literal>false</literal>, the
+        next <function>nextval</function> will return exactly the specified
         value, and sequence advancement commences with the following
-        <function>nextval</function>.  For example,
+        <function>nextval</function>.  Furthermore, the value reported by
+        <function>currval</> is not changed in this case (this is a change
+        from pre-8.3 behavior).  For example,
 
 <screen>
 SELECT setval('foo', 42);           <lineannotation>Next <function>nextval</> will return 43</lineannotation>
diff --git a/doc/src/sgml/ref/alter_sequence.sgml b/doc/src/sgml/ref/alter_sequence.sgml
index b515ae46016..3c982eee6f1 100644
--- a/doc/src/sgml/ref/alter_sequence.sgml
+++ b/doc/src/sgml/ref/alter_sequence.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/alter_sequence.sgml,v 1.18 2007/10/03 16:48:43 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/alter_sequence.sgml,v 1.19 2007/10/25 18:54:03 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -114,7 +114,10 @@ ALTER SEQUENCE <replaceable class="parameter">name</replaceable> SET SCHEMA <rep
        <para>
         The optional clause <literal>RESTART WITH <replaceable
         class="parameter">start</replaceable></literal> changes the
-        current value of the sequence.
+        current value of the sequence.  This is equivalent to calling the
+        <function>setval</> function with <literal>is_called</literal> =
+        <literal>false</>: the specified value will be returned by the
+        <emphasis>next</> call of <function>nextval</>.
        </para>
       </listitem>
      </varlistentry>
@@ -226,6 +229,12 @@ ALTER SEQUENCE <replaceable class="parameter">name</replaceable> SET SCHEMA <rep
    immediately.
   </para>
 
+  <para>
+   <command>ALTER SEQUENCE</command> does not affect the <function>currval</>
+   status for the sequence.  (Before <productname>PostgreSQL</productname>
+   8.3, it sometimes did.)
+  </para>
+
   <para>
    Some variants of <command>ALTER TABLE</command> can be used with
    sequences as well; for example, to rename a sequence it is also
-- 
cgit v1.2.3