doc: Clarify pg_get_sequence_data() NULL-return cases

The documentation previously said that pg_get_sequence_data() returns
a row of NULL values if the sequence does not exist or if the current
user lacks privileges on it. This was incomplete and could be misleading.
A nonexistent relation name is rejected during regclass input conversion,
while the function returns NULLs for a nonexistent relation OID and
several other cases.

This commit clarifies that the function returns NULLs when the specified
relation OID does not exist, the relation is not a sequence, the current
user lacks SELECT privilege on the sequence, the sequence belongs to
another session's temporary schema, or it is an unlogged sequence on
a standby server.

Author: Amit Kapila <amit.kapila16@gmail.com>
Reviewed-by: Fujii Masao <masao.fujii@gmail.com>
Discussion: https://postgr.es/m/CAA4eK1JOo0aJRhFHNWpj3hMwaTtNOopY34f1Lh_QD=z=+DrzWQ@mail.gmail.com
Backpatch-through: 19

diff --git a/doc/src/sgml/func/func-sequence.sgml b/doc/src/sgml/func/func-sequence.sgml
index de266c36296cf2c1d376fa2d0fefaa0b6e7f0dbe..9301faa67d247c39a376e79c070b3049e5a29961 100644 (file)
--- a/doc/src/sgml/func/func-sequence.sgml
+++ b/doc/src/sgml/func/func-sequence.sgml
@@ -163,13 +163,15 @@ SELECT setval('myseq', 42, false);    <lineannotation>Next <function>nextval</fu
         <structfield>is_called</structfield> indicates whether the sequence has
         been used. <structfield>page_lsn</structfield> is the LSN corresponding
         to the most recent WAL record that modified this sequence relation.
-        This function returns a row of NULL values if the sequence does not
-        exist or if the current user lacks privileges on it.
+        This function returns a row of NULL values if the specified relation
+        OID does not exist, if it is not a sequence, if the current user lacks
+        <literal>SELECT</literal> privilege on the sequence, if the sequence
+        is another session's temporary sequence, or if it is an unlogged
+        sequence on a standby server.
        </para>
        <para>
         This function is primarily intended for internal use by pg_dump and by
-        logical replication to synchronize sequences. It requires
-        <literal>SELECT</literal> privilege on the sequence.
+        logical replication to synchronize sequences.
        </para></entry>
       </row>
      </tbody>