diff options
| -rw-r--r-- | doc/src/sgml/func.sgml | 31 |
1 files changed, 22 insertions, 9 deletions
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 74d3087a723..0a725a67117 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -17645,24 +17645,37 @@ SELECT setval('myseq', 42, false); <lineannotation>Next <function>nextval</fu <caution> <para> To avoid blocking concurrent transactions that obtain numbers from - the same sequence, a <function>nextval</function> operation is never - rolled back; that is, once a value has been fetched it is considered - used and will not be returned again. This is true even if the - surrounding transaction later aborts, or if the calling query ends - up not using the value. For example an <command>INSERT</command> with + the same sequence, the value obtained by <function>nextval</function> + is not reclaimed for re-use if the calling transaction later aborts. + This means that transaction aborts or database crashes can result in + gaps in the sequence of assigned values. That can happen without a + transaction abort, too. For example an <command>INSERT</command> with an <literal>ON CONFLICT</literal> clause will compute the to-be-inserted tuple, including doing any required <function>nextval</function> calls, before detecting any conflict that would cause it to follow - the <literal>ON CONFLICT</literal> rule instead. Such cases will leave - unused <quote>holes</quote> in the sequence of assigned values. + the <literal>ON CONFLICT</literal> rule instead. Thus, <productname>PostgreSQL</productname> sequence objects <emphasis>cannot be used to obtain <quote>gapless</quote> sequences</emphasis>. </para> <para> - Likewise, any sequence state changes made by <function>setval</function> - are not undone if the transaction rolls back. + Likewise, sequence state changes made by <function>setval</function> + are immediately visible to other transactions, and are not undone if + the calling transaction rolls back. + </para> + + <para> + If the database cluster crashes before committing a transaction + containing a <function>nextval</function> + or <function>setval</function> call, the sequence state change might + not have made its way to persistent storage, so that it is uncertain + whether the sequence will have its original or updated state after the + cluster restarts. This is harmless for usage of the sequence within + the database, since other effects of uncommitted transactions will not + be visible either. However, if you wish to use a sequence value for + persistent outside-the-database purposes, make sure that the + <function>nextval</function> call has been committed before doing so. </para> </caution> |