Skip to content

Commit cf9bcb0

Browse files
bmomjianbmomjian
committed
revert: add transaction processing chapter with internals info
This doc patch (master hash 66bc9d2) was decided to be too significant for backpatching, so reverted in all but master. Also fix SGML file header comment in master. Reported-by: Peter Eisentraut Discussion: https://postgr.es/m/c6304b19-6ff7-f3af-0148-cf7aa7e2fbfd@enterprisedb.com Backpatch-through: 11
1 parent a949b73 commit cf9bcb0

14 files changed

+44
-292
lines changed

‎doc/src/sgml/catalogs.sgml

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10594,8 +10594,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
1059410594
</para>
1059510595
<para>
1059610596
Virtual ID of the transaction targeted by the lock,
10597-
or null if the target is not a virtual transaction ID; see
10598-
<xref linkend="transactions"/>
10597+
or null if the target is not a virtual transaction ID
1059910598
</para></entry>
1060010599
</row>
1060110600

@@ -10604,8 +10603,8 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
1060410603
<structfield>transactionid</structfield> <type>xid</type>
1060510604
</para>
1060610605
<para>
10607-
ID of the transaction targeted by the lock, or null if the target
10608-
is not a transaction ID; <xref linkend="transactions"/>
10606+
ID of the transaction targeted by the lock,
10607+
or null if the target is not a transaction ID
1060910608
</para></entry>
1061010609
</row>
1061110610

‎doc/src/sgml/config.sgml

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7017,14 +7017,12 @@ local0.* /var/log/postgresql
70177017
</row>
70187018
<row>
70197019
<entry><literal>%v</literal></entry>
7020-
<entry>Virtual transaction ID (backendID/localXID); see
7021-
<xref linkend="transaction-id"/></entry>
7020+
<entry>Virtual transaction ID (backendID/localXID)</entry>
70227021
<entry>no</entry>
70237022
</row>
70247023
<row>
70257024
<entry><literal>%x</literal></entry>
7026-
<entry>Transaction ID (0 if none is assigned); see
7027-
<xref linkend="transaction-id"/></entry>
7025+
<entry>Transaction ID (0 if none is assigned)</entry>
70287026
<entry>no</entry>
70297027
</row>
70307028
<row>

‎doc/src/sgml/datatype.sgml

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4936,8 +4936,7 @@ WHERE ...
49364936
<structfield>xmin</structfield> and <structfield>xmax</structfield>. Transaction identifiers are 32-bit quantities.
49374937
In some contexts, a 64-bit variant <type>xid8</type> is used. Unlike
49384938
<type>xid</type> values, <type>xid8</type> values increase strictly
4939-
monotonically and cannot be reused in the lifetime of a database
4940-
cluster. See <xref linkend="transaction-id"/> for more details.
4939+
monotonically and cannot be reused in the lifetime of a database cluster.
49414940
</para>
49424941

49434942
<para>

‎doc/src/sgml/filelist.sgml

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,6 @@
102102
<!ENTITY protocol SYSTEM "protocol.sgml">
103103
<!ENTITY sources SYSTEM "sources.sgml">
104104
<!ENTITY storage SYSTEM "storage.sgml">
105-
<!ENTITY transaction SYSTEM "xact.sgml">
106105
<!ENTITY tablesample-method SYSTEM "tablesample-method.sgml">
107106
<!ENTITY generic-wal SYSTEM "generic-wal.sgml">
108107
<!ENTITY backup-manifest SYSTEM "backup-manifest.sgml">

‎doc/src/sgml/func.sgml

Lines changed: 5 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -24100,10 +24100,7 @@ SELECT collation for ('foo' COLLATE "de_DE");
2410024100
<para>
2410124101
Returns the current transaction's ID. It will assign a new one if the
2410224102
current transaction does not have one already (because it has not
24103-
performed any database updates); see <xref
24104-
linkend="transaction-id"/> for details. If executed in a
24105-
subtransaction, this will return the top-level transaction ID;
24106-
see <xref linkend="subxacts"/> for details.
24103+
performed any database updates).
2410724104
</para></entry>
2410824105
</row>
2410924106

@@ -24120,8 +24117,6 @@ SELECT collation for ('foo' COLLATE "de_DE");
2412024117
ID is assigned yet. (It's best to use this variant if the transaction
2412124118
might otherwise be read-only, to avoid unnecessary consumption of an
2412224119
XID.)
24123-
If executed in a subtransaction, this will return the top-level
24124-
transaction ID.
2412524120
</para></entry>
2412624121
</row>
2412724122

@@ -24165,9 +24160,6 @@ SELECT collation for ('foo' COLLATE "de_DE");
2416524160
<para>
2416624161
Returns a current <firstterm>snapshot</firstterm>, a data structure
2416724162
showing which transaction IDs are now in-progress.
24168-
Only top-level transaction IDs are included in the snapshot;
24169-
subtransaction IDs are not shown; see <xref linkend="subxacts"/>
24170-
for details.
2417124163
</para></entry>
2417224164
</row>
2417324165

@@ -24222,8 +24214,7 @@ SELECT collation for ('foo' COLLATE "de_DE");
2422224214
Is the given transaction ID <firstterm>visible</firstterm> according
2422324215
to this snapshot (that is, was it completed before the snapshot was
2422424216
taken)? Note that this function will not give the correct answer for
24225-
a subtransaction ID (subxid); see <xref linkend="subxacts"/> for
24226-
details.
24217+
a subtransaction ID.
2422724218
</para></entry>
2422824219
</row>
2422924220
</tbody>
@@ -24235,9 +24226,8 @@ SELECT collation for ('foo' COLLATE "de_DE");
2423524226
wraps around every 4 billion transactions. However,
2423624227
the functions shown in <xref linkend="functions-pg-snapshot"/> use a
2423724228
64-bit type <type>xid8</type> that does not wrap around during the life
24238-
of an installation and can be converted to <type>xid</type> by casting if
24239-
required; see <xref linkend="transaction-id"/> for details.
24240-
The data type <type>pg_snapshot</type> stores information about
24229+
of an installation, and can be converted to <type>xid</type> by casting if
24230+
required. The data type <type>pg_snapshot</type> stores information about
2424124231
transaction ID visibility at a particular moment in time. Its components
2424224232
are described in <xref linkend="functions-pg-snapshot-parts"/>.
2424324233
<type>pg_snapshot</type>'s textual representation is
@@ -24283,7 +24273,7 @@ SELECT collation for ('foo' COLLATE "de_DE");
2428324273
xmax</literal> and not in this list was already completed at the time
2428424274
of the snapshot, and thus is either visible or dead according to its
2428524275
commit status. This list does not include the transaction IDs of
24286-
subtransactions (subxids).
24276+
subtransactions.
2428724277
</entry>
2428824278
</row>
2428924279
</tbody>

‎doc/src/sgml/glossary.sgml

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1644,8 +1644,7 @@
16441644
<literal>3</literal> (values under that are reserved) and the
16451645
epoch value is incremented by one.
16461646
In some contexts, the epoch and xid values are
1647-
considered together as a single 64-bit value; see <xref
1648-
linkend="transaction-id"/> for more details.
1647+
considered together as a single 64-bit value.
16491648
</para>
16501649
<para>
16511650
For more information, see

‎doc/src/sgml/monitoring.sgml

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -897,8 +897,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
897897
<structfield>backend_xid</structfield> <type>xid</type>
898898
</para>
899899
<para>
900-
Top-level transaction identifier of this backend, if any; see
901-
<xref linkend="transaction-id"/>.
900+
Top-level transaction identifier of this backend, if any.
902901
</para></entry>
903902
</row>
904903

@@ -1861,8 +1860,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
18611860
</row>
18621861
<row>
18631862
<entry><literal>virtualxid</literal></entry>
1864-
<entry>Waiting to acquire a virtual transaction ID lock; see
1865-
<xref linkend="transaction-id"/>.</entry>
1863+
<entry>Waiting to acquire a virtual transaction ID lock.</entry>
18661864
</row>
18671865
</tbody>
18681866
</tgroup>

‎doc/src/sgml/pgrowlocks.sgml

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -57,8 +57,7 @@ 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
61-
multitransaction; see <xref linkend="transaction-id"/></entry>
60+
<entry>Transaction ID of locker, or multixact ID if multitransaction</entry>
6261
</row>
6362
<row>
6463
<entry><structfield>multi</structfield></entry>

‎doc/src/sgml/postgres.sgml

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -268,7 +268,6 @@ break is not needed in a wider output rendering.
268268
&brin;
269269
&hash;
270270
&storage;
271-
&transaction;
272271
&bki;
273272
&planstats;
274273
&backup-manifest;

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

Lines changed: 21 additions & 41 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>release a previously defined savepoint</refpurpose>
24+
<refpurpose>destroy a previously defined savepoint</refpurpose>
2525
</refnamediv>
2626

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

3636
<para>
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.
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.
4454
</para>
4555
</refsect1>
4656

@@ -52,7 +62,7 @@ RELEASE [ SAVEPOINT ] <replaceable>savepoint_name</replaceable>
5262
<term><replaceable>savepoint_name</replaceable></term>
5363
<listitem>
5464
<para>
55-
The name of the savepoint to release.
65+
The name of the savepoint to destroy.
5666
</para>
5767
</listitem>
5868
</varlistentry>
@@ -68,7 +78,7 @@ RELEASE [ SAVEPOINT ] <replaceable>savepoint_name</replaceable>
6878

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

7484
<para>
@@ -83,7 +93,7 @@ RELEASE [ SAVEPOINT ] <replaceable>savepoint_name</replaceable>
8393
<title>Examples</title>
8494

8595
<para>
86-
To establish and later release a savepoint:
96+
To establish and later destroy a savepoint:
8797
<programlisting>
8898
BEGIN;
8999
INSERT INTO table1 VALUES (3);
@@ -94,36 +104,6 @@ COMMIT;
94104
</programlisting>
95105
The above transaction will insert both 3 and 4.
96106
</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-
127107
</refsect1>
128108

129109
<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 new (not aborted)
60-
transaction is immediately started with the same transaction
61-
characteristics (see <xref linkend="sql-set-transaction"/>) as the
62-
just finished one. Otherwise, no new transaction is started.
59+
If <literal>AND CHAIN</literal> is specified, a new transaction 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.
6363
</para>
6464
</listitem>
6565
</varlistentry>

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

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -35,9 +35,8 @@ 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 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.
38+
established. The savepoint remains valid and can be rolled back to
39+
again later, if needed.
4140
</para>
4241

4342
<para>

‎doc/src/sgml/wal.sgml

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

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

1211
<sect1 id="wal-reliability">
@@ -896,5 +895,4 @@
896895
seem to be a problem in practice.
897896
</para>
898897
</sect1>
899-
900898
</chapter>

0 commit comments

Comments
 (0)