Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit6365e3a

Browse files
committed
Doc: improve documentation about nextval()/setval().
Clarify that the results of nextval and setval are not guaranteedpersistent until the calling transaction commits. Some peopleseem to have drawn the opposite conclusion from the statement thatthese functions are never rolled back, so re-word to avoid sayingit quite that way.Discussion:https://postgr.es/m/CAKU4AWohO=NfM-4KiZWvdc+z3c1C9FrUBR6xnReFJ6sfy0i=Lw@mail.gmail.com
1 parent4a761b7 commit6365e3a

File tree

1 file changed

+36
-25
lines changed

1 file changed

+36
-25
lines changed

‎doc/src/sgml/func.sgml

Lines changed: 36 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -13678,24 +13678,6 @@ nextval('foo'::text) <lineannotation><literal>foo</literal> is looked up at
1367813678
see its command reference page for more information.
1367913679
</para>
1368013680

13681-
<important>
13682-
<para>
13683-
To avoid blocking concurrent transactions that obtain numbers from
13684-
the same sequence, a <function>nextval</function> operation is never
13685-
rolled back; that is, once a value has been fetched it is considered
13686-
used and will not be returned again. This is true even if the
13687-
surrounding transaction later aborts, or if the calling query ends
13688-
up not using the value. For example an <command>INSERT</command> with
13689-
an <literal>ON CONFLICT</literal> clause will compute the to-be-inserted
13690-
tuple, including doing any required <function>nextval</function>
13691-
calls, before detecting any conflict that would cause it to follow
13692-
the <literal>ON CONFLICT</literal> rule instead. Such cases will leave
13693-
unused <quote>holes</quote> in the sequence of assigned values.
13694-
Thus, <productname>PostgreSQL</productname> sequence objects <emphasis>cannot
13695-
be used to obtain <quote>gapless</quote> sequences</emphasis>.
13696-
</para>
13697-
</important>
13698-
1369913681
<para>
1370013682
This function requires <literal>USAGE</literal>
1370113683
or <literal>UPDATE</literal> privilege on the sequence.
@@ -13772,13 +13754,6 @@ SELECT setval('foo', 42, false); <lineannotation>Next <function>nextval</func
1377213754
The result returned by <function>setval</function> is just the value of its
1377313755
second argument.
1377413756
</para>
13775-
<important>
13776-
<para>
13777-
Because sequences are non-transactional, changes made by
13778-
<function>setval</function> are not undone if the transaction rolls
13779-
back.
13780-
</para>
13781-
</important>
1378213757

1378313758
<para>
1378413759
This function requires <literal>UPDATE</literal> privilege on the
@@ -13789,6 +13764,42 @@ SELECT setval('foo', 42, false); <lineannotation>Next <function>nextval</func
1378913764
</variablelist>
1379013765
</para>
1379113766

13767+
<caution>
13768+
<para>
13769+
To avoid blocking concurrent transactions that obtain numbers from
13770+
the same sequence, the value obtained by <function>nextval</function>
13771+
is not reclaimed for re-use if the calling transaction later aborts.
13772+
This means that transaction aborts or database crashes can result in
13773+
gaps in the sequence of assigned values. That can happen without a
13774+
transaction abort, too. For example an <command>INSERT</command> with
13775+
an <literal>ON CONFLICT</literal> clause will compute the to-be-inserted
13776+
tuple, including doing any required <function>nextval</function>
13777+
calls, before detecting any conflict that would cause it to follow
13778+
the <literal>ON CONFLICT</literal> rule instead.
13779+
Thus, <productname>PostgreSQL</productname> sequence
13780+
objects <emphasis>cannot be used to obtain <quote>gapless</quote>
13781+
sequences</emphasis>.
13782+
</para>
13783+
13784+
<para>
13785+
Likewise, sequence state changes made by <function>setval</function>
13786+
are immediately visible to other transactions, and are not undone if
13787+
the calling transaction rolls back.
13788+
</para>
13789+
13790+
<para>
13791+
If the database cluster crashes before committing a transaction
13792+
containing a <function>nextval</function>
13793+
or <function>setval</function> call, the sequence state change might
13794+
not have made its way to persistent storage, so that it is uncertain
13795+
whether the sequence will have its original or updated state after the
13796+
cluster restarts. This is harmless for usage of the sequence within
13797+
the database, since other effects of uncommitted transactions will not
13798+
be visible either. However, if you wish to use a sequence value for
13799+
persistent outside-the-database purposes, make sure that the
13800+
<function>nextval</function> call has been committed before doing so.
13801+
</para>
13802+
</caution>
1379213803
</sect1>
1379313804

1379413805

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp