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

Commit7b96f52

Browse files
committed
doc: add transaction processing chapter with internals info
This also adds references to this new chapter at relevant sections ofour documentation. Previously much of these internal details wereexposed to users, but not explained. This also updates RELEASESAVEPOINT.Discussion:https://postgr.es/m/CANbhV-E_iy9fmrErxrCh8TZTyenpfo72Hf_XD2HLDppva4dUNA@mail.gmail.comAuthor: Simon Riggs, Laurenz AlbeReviewed-by: Bruce MomjianBackpatch-through: 11
1 parent20b796a commit7b96f52

File tree

11 files changed

+266
-36
lines changed

11 files changed

+266
-36
lines changed

‎doc/src/sgml/catalogs.sgml

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9187,16 +9187,17 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
91879187
<entry></entry>
91889188
<entry>
91899189
Virtual ID of the transaction targeted by the lock,
9190-
or null if the target is not a virtual transaction ID
9190+
or null if the target is not a virtual transaction ID; see
9191+
<xref linkend="transactions"/>
91919192
</entry>
91929193
</row>
91939194
<row>
91949195
<entry><structfield>transactionid</structfield></entry>
91959196
<entry><type>xid</type></entry>
91969197
<entry></entry>
91979198
<entry>
9198-
ID of the transaction targeted by the lock,
9199-
or null if the targetis not a transaction ID
9199+
ID of the transaction targeted by the lock, or null if the target
9200+
is not a transaction ID; <xref linkend="transactions"/>
92009201
</entry>
92019202
</row>
92029203
<row>

‎doc/src/sgml/config.sgml

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6566,12 +6566,14 @@ local0.* /var/log/postgresql
65666566
</row>
65676567
<row>
65686568
<entry><literal>%v</literal></entry>
6569-
<entry>Virtual transaction ID (backendID/localXID)</entry>
6569+
<entry>Virtual transaction ID (backendID/localXID); see
6570+
<xref linkend="transaction-id"/></entry>
65706571
<entry>no</entry>
65716572
</row>
65726573
<row>
65736574
<entry><literal>%x</literal></entry>
6574-
<entry>Transaction ID (0 if none is assigned)</entry>
6575+
<entry>Transaction ID (0 if none is assigned); see
6576+
<xref linkend="transaction-id"/></entry>
65756577
<entry>no</entry>
65766578
</row>
65776579
<row>

‎doc/src/sgml/filelist.sgml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,7 @@
101101
<!ENTITY protocol SYSTEM "protocol.sgml">
102102
<!ENTITY sources SYSTEM "sources.sgml">
103103
<!ENTITY storage SYSTEM "storage.sgml">
104+
<!ENTITY transaction SYSTEM "xact.sgml">
104105
<!ENTITY tablesample-method SYSTEM "tablesample-method.sgml">
105106
<!ENTITY generic-wal SYSTEM "generic-wal.sgml">
106107

‎doc/src/sgml/monitoring.sgml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -817,7 +817,8 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
817817
<row>
818818
<entry><structfield>backend_xid</structfield></entry>
819819
<entry><type>xid</type></entry>
820-
<entry>Top-level transaction identifier of this backend, if any.</entry>
820+
<entry>Top-level transaction identifier of this backend, if any; see
821+
<xref linkend="transaction-id"/>.</entry>
821822
</row>
822823
<row>
823824
<entry><structfield>backend_xmin</structfield></entry>

‎doc/src/sgml/pgrowlocks.sgml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,8 @@ pgrowlocks(text) returns setof record
5757
<row>
5858
<entry><structfield>locker</structfield></entry>
5959
<entry><type>xid</type></entry>
60-
<entry>Transaction ID of locker, or multixact ID if multitransaction</entry>
60+
<entry>Transaction ID of locker, or multixact ID if
61+
multitransaction; see <xref linkend="transaction-id"/></entry>
6162
</row>
6263
<row>
6364
<entry><structfield>multi</structfield></entry>

‎doc/src/sgml/postgres.sgml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -260,6 +260,7 @@
260260
&brin;
261261
&hash;
262262
&storage;
263+
&transaction;
263264
&bki;
264265
&planstats;
265266

‎doc/src/sgml/ref/release_savepoint.sgml

Lines changed: 41 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ PostgreSQL documentation
2121

2222
<refnamediv>
2323
<refname>RELEASE SAVEPOINT</refname>
24-
<refpurpose>destroy a previously defined savepoint</refpurpose>
24+
<refpurpose>release a previously defined savepoint</refpurpose>
2525
</refnamediv>
2626

2727
<refsynopsisdiv>
@@ -34,23 +34,13 @@ RELEASE [ SAVEPOINT ] <replaceable>savepoint_name</replaceable>
3434
<title>Description</title>
3535

3636
<para>
37-
<command>RELEASE SAVEPOINT</command> destroys a savepoint previously defined
38-
in the current transaction.
39-
</para>
40-
41-
<para>
42-
Destroying a savepoint makes it unavailable as a rollback point,
43-
but it has no other user visible behavior. It does not undo the
44-
effects of commands executed after the savepoint was established.
45-
(To do that, see <xref linkend="sql-rollback-to"/>.)
46-
Destroying a savepoint when
47-
it is no longer needed allows the system to reclaim some resources
48-
earlier than transaction end.
49-
</para>
50-
51-
<para>
52-
<command>RELEASE SAVEPOINT</command> also destroys all savepoints that were
53-
established after the named savepoint was established.
37+
<command>RELEASE SAVEPOINT</command> releases the named savepoint and
38+
all active savepoints that were created after the named savepoint,
39+
and frees their resources. All changes made since the creation of
40+
the savepoint that didn't already get rolled back are merged into
41+
the transaction or savepoint that was active when the named savepoint
42+
was created. Changes made after <command>RELEASE SAVEPOINT</command>
43+
will also be part of this active transaction or savepoint.
5444
</para>
5545
</refsect1>
5646

@@ -62,7 +52,7 @@ RELEASE [ SAVEPOINT ] <replaceable>savepoint_name</replaceable>
6252
<term><replaceable>savepoint_name</replaceable></term>
6353
<listitem>
6454
<para>
65-
The name of the savepoint todestroy.
55+
The name of the savepoint torelease.
6656
</para>
6757
</listitem>
6858
</varlistentry>
@@ -78,7 +68,7 @@ RELEASE [ SAVEPOINT ] <replaceable>savepoint_name</replaceable>
7868

7969
<para>
8070
It is not possible to release a savepoint when the transaction is in
81-
an aborted state.
71+
an aborted state; to do that, use <xref linkend="sql-rollback-to"/>.
8272
</para>
8373

8474
<para>
@@ -93,7 +83,7 @@ RELEASE [ SAVEPOINT ] <replaceable>savepoint_name</replaceable>
9383
<title>Examples</title>
9484

9585
<para>
96-
To establish and laterdestroy a savepoint:
86+
To establish and laterrelease a savepoint:
9787
<programlisting>
9888
BEGIN;
9989
INSERT INTO table1 VALUES (3);
@@ -104,6 +94,36 @@ COMMIT;
10494
</programlisting>
10595
The above transaction will insert both 3 and 4.
10696
</para>
97+
98+
<para>
99+
A more complex example with multiple nested subtransactions:
100+
<programlisting>
101+
BEGIN;
102+
INSERT INTO table1 VALUES (1);
103+
SAVEPOINT sp1;
104+
INSERT INTO table1 VALUES (2);
105+
SAVEPOINT sp2;
106+
INSERT INTO table1 VALUES (3);
107+
RELEASE SAVEPOINT sp2;
108+
INSERT INTO table1 VALUES (4))); -- generates an error
109+
</programlisting>
110+
In this example, the application requests the release of the savepoint
111+
<literal>sp2</literal>, which inserted 3. This changes the insert's
112+
transaction context to <literal>sp1</literal>. When the statement
113+
attempting to insert value 4 generates an error, the insertion of 2 and
114+
4 are lost because they are in the same, now-rolled back savepoint,
115+
and value 3 is in the same transaction context. The application can
116+
now only choose one of these two commands, since all other commands
117+
will be ignored:
118+
<programlisting>
119+
ROLLBACK;
120+
ROLLBACK TO SAVEPOINT sp1;
121+
</programlisting>
122+
Choosing <command>ROLLBACK</command> will abort everything, including
123+
value 1, whereas <command>ROLLBACK TO SAVEPOINT sp1</command> will retain
124+
value 1 and allow the transaction to continue.
125+
</para>
126+
107127
</refsect1>
108128

109129
<refsect1>

‎doc/src/sgml/ref/rollback.sgml

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -56,10 +56,10 @@ ROLLBACK [ WORK | TRANSACTION ] [ AND [ NO ] CHAIN ]
5656
<term><literal>AND CHAIN</literal></term>
5757
<listitem>
5858
<para>
59-
If <literal>AND CHAIN</literal> is specified, a newtransaction is
60-
immediately started with the same transaction characteristics (see <xref
61-
linkend="sql-set-transaction"/>) as the just finished one. Otherwise,
62-
no new transaction is started.
59+
If <literal>AND CHAIN</literal> is specified, a new(not aborted)
60+
transaction isimmediately started with the same transaction
61+
characteristics (see <xreflinkend="sql-set-transaction"/>) as the
62+
just finished one. Otherwise,no new transaction is started.
6363
</para>
6464
</listitem>
6565
</varlistentry>

‎doc/src/sgml/ref/rollback_to.sgml

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,8 +35,9 @@ ROLLBACK [ WORK | TRANSACTION ] TO [ SAVEPOINT ] <replaceable>savepoint_name</re
3535

3636
<para>
3737
Roll back all commands that were executed after the savepoint was
38-
established. The savepoint remains valid and can be rolled back to
39-
again later, if needed.
38+
established and then start a new subtransaction at the same transaction level.
39+
The savepoint remains valid and can be rolled back to again later,
40+
if needed.
4041
</para>
4142

4243
<para>

‎doc/src/sgml/wal.sgml

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,9 @@
44
<title>Reliability and the Write-Ahead Log</title>
55

66
<para>
7-
This chapter explains how the Write-Ahead Log is used to obtain
8-
efficient, reliable operation.
7+
This chapter explains how to control the reliability of
8+
<productname>PostgreSQL</productname>, including details about the
9+
Write-Ahead Log.
910
</para>
1011

1112
<sect1 id="wal-reliability">
@@ -811,4 +812,5 @@
811812
seem to be a problem in practice.
812813
</para>
813814
</sect1>
815+
814816
</chapter>

0 commit comments

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