From 3012061b8653a57a098c85f06f1f80ec9576711b Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter_e@gmx.net>
Date: Fri, 15 Sep 2017 14:04:51 -0400
Subject: Apply pg_get_serial_sequence() to identity column sequences as well

Bug: #14813
---
 doc/src/sgml/func.sgml | 37 ++++++++++++++++++++++---------------
 1 file changed, 22 insertions(+), 15 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 641b3b8f4e4..2f036015cc2 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -17034,8 +17034,7 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
       <row>
        <entry><literal><function>pg_get_serial_sequence(<parameter>table_name</parameter>, <parameter>column_name</parameter>)</function></literal></entry>
        <entry><type>text</type></entry>
-       <entry>get name of the sequence that a <type>serial</type>, <type>smallserial</type> or <type>bigserial</type> column
-       uses</entry>
+       <entry>get name of the sequence that a serial or identity column uses</entry>
       </row>
       <row>
        <entry><literal><function>pg_get_statisticsobjdef(<parameter>statobj_oid</parameter>)</function></literal></entry>
@@ -17223,19 +17222,27 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
   <para>
    <function>pg_get_serial_sequence</function> returns the name of the
    sequence associated with a column, or NULL if no sequence is associated
-   with the column.  The first input parameter is a table name with
-   optional schema, and the second parameter is a column name.  Because
-   the first parameter is potentially a schema and table, it is not treated
-   as a double-quoted identifier, meaning it is lower cased by default,
-   while the second parameter, being just a column name, is treated as
-   double-quoted and has its case preserved.  The function returns a value
-   suitably formatted for passing to sequence functions (see <xref
-   linkend="functions-sequence">).  This association can be modified or
-   removed with <command>ALTER SEQUENCE OWNED BY</>.  (The function
-   probably should have been called
-   <function>pg_get_owned_sequence</function>; its current name reflects the fact
-   that it's typically used with <type>serial</> or <type>bigserial</>
-   columns.)
+   with the column.  If the column is an identity column, the associated
+   sequence is the sequence internally created for the identity column.  For
+   columns created using one of the serial types
+   (<type>serial</type>, <type>smallserial</type>, <type>bigserial</type>), it
+   is the sequence created for that serial column definition.  In the latter
+   case, this association can be modified or removed with <command>ALTER
+   SEQUENCE OWNED BY</>.  (The function probably should have been called
+   <function>pg_get_owned_sequence</function>; its current name reflects the
+   fact that it has typically been used with <type>serial</>
+   or <type>bigserial</> columns.)  The first input parameter is a table name
+   with optional schema, and the second parameter is a column name.  Because
+   the first parameter is potentially a schema and table, it is not treated as
+   a double-quoted identifier, meaning it is lower cased by default, while the
+   second parameter, being just a column name, is treated as double-quoted and
+   has its case preserved.  The function returns a value suitably formatted
+   for passing to sequence functions
+   (see <xref linkend="functions-sequence">).  A typical use is in reading the
+   current value of a sequence for an identity or serial column, for example:
+<programlisting>
+SELECT currval(pg_get_serial_sequence('sometable', 'id'));
+</programlisting>
   </para>
 
   <para>
-- 
cgit v1.2.3