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
Appearance settings

Commit 876ecfb

Browse filesBrowse files
michaelpqmichaelpq
committed
doc: Clarify use of ACCESS EXCLUSIVE lock in various sections
Some sections of the documentation used "exclusive lock" to describe that an ACCESS EXCLUSIVE lock is taken during a given operation. This can be confusing to the reader as ACCESS SHARE is allowed with an EXCLUSIVE lock is used, but that would not be the case with what is described on those parts of the documentation. Author: Greg Rychlewski Discussion: https://postgr.es/m/CAKemG7VptD=7fNWckFMsMVZL_zzvgDO6v2yVmQ+ZiBfc_06kCQ@mail.gmail.com Backpatch-through: 9.6
1 parent 89e383b commit 876ecfb
Copy full SHA for 876ecfb

File tree

Expand file treeCollapse file tree

9 files changed

+31
-22
lines changed
Filter options
Expand file treeCollapse file tree

9 files changed

+31
-22
lines changed

‎doc/src/sgml/ddl.sgml

Copy file name to clipboardExpand all lines: doc/src/sgml/ddl.sgml
+2-1Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2635,7 +2635,8 @@ SELECT * FROM information WHERE group_id = 2 FOR UPDATE;
26352635
definer function.) Also, heavy concurrent use of row share locks on the
26362636
referenced table could pose a performance problem, especially if updates
26372637
of it are frequent. Another solution, practical if updates of the
2638-
referenced table are infrequent, is to take an exclusive lock on the
2638+
referenced table are infrequent, is to take an
2639+
<literal>ACCESS EXCLUSIVE</literal> lock on the
26392640
referenced table when updating it, so that no concurrent transactions
26402641
could be examining old row values. Or one could just wait for all
26412642
concurrent transactions to end after committing an update of the

‎doc/src/sgml/hstore.sgml

Copy file name to clipboardExpand all lines: doc/src/sgml/hstore.sgml
+2-1Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -894,7 +894,8 @@ UPDATE tablename SET hstorecol = hstorecol || '';
894894
<programlisting>
895895
ALTER TABLE tablename ALTER hstorecol TYPE hstore USING hstorecol || '';
896896
</programlisting>
897-
The <command>ALTER TABLE</command> method requires an exclusive lock on the table,
897+
The <command>ALTER TABLE</command> method requires an
898+
<literal>ACCESS EXCLUSIVE</literal> lock on the table,
898899
but does not result in bloating the table with old row versions.
899900
</para>
900901

‎doc/src/sgml/indexam.sgml

Copy file name to clipboardExpand all lines: doc/src/sgml/indexam.sgml
+4-2Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -924,8 +924,10 @@ amparallelrescan (IndexScanDesc scan);
924924
<literal>RowExclusiveLock</literal> when updating the index (including plain
925925
<command>VACUUM</command>). Since these lock types do not conflict, the access
926926
method is responsible for handling any fine-grained locking it might need.
927-
An exclusive lock on the index as a whole will be taken only during index
928-
creation, destruction, or <command>REINDEX</command>.
927+
An <literal>ACCESS EXCLUSIVE</literal> lock on the index as a whole will be
928+
taken only during index creation, destruction, or <command>REINDEX</command>
929+
(<literal>SHARE UPDATE EXCLUSIVE</literal> is taken instead with
930+
<literal>CONCURRENTLY</literal>).
929931
</para>
930932

931933
<para>

‎doc/src/sgml/maintenance.sgml

Copy file name to clipboardExpand all lines: doc/src/sgml/maintenance.sgml
+4-2Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -128,7 +128,8 @@
128128
<command>DELETE</command> will continue to function normally, though you
129129
will not be able to modify the definition of a table with commands such as
130130
<command>ALTER TABLE</command> while it is being vacuumed.)
131-
<command>VACUUM FULL</command> requires exclusive lock on the table it is
131+
<command>VACUUM FULL</command> requires an
132+
<literal>ACCESS EXCLUSIVE</literal> lock on the table it is
132133
working on, and therefore cannot be done in parallel with other use
133134
of the table. Generally, therefore,
134135
administrators should strive to use standard <command>VACUUM</command> and
@@ -231,7 +232,8 @@
231232
or one of the table-rewriting variants of
232233
<xref linkend="sql-altertable"/>.
233234
These commands rewrite an entire new copy of the table and build
234-
new indexes for it. All these options require exclusive lock. Note that
235+
new indexes for it. All these options require an
236+
<literal>ACCESS EXCLUSIVE</literal> lock. Note that
235237
they also temporarily use extra disk space approximately equal to the size
236238
of the table, since the old copies of the table and indexes can't be
237239
released until the new ones are complete.

‎doc/src/sgml/mvcc.sgml

Copy file name to clipboardExpand all lines: doc/src/sgml/mvcc.sgml
+2-1Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -826,7 +826,8 @@ ERROR: could not serialize access due to read/write dependencies among transact
826826
tables are not dropped or modified in incompatible ways while the
827827
command executes. (For example, <command>TRUNCATE</command> cannot safely be
828828
executed concurrently with other operations on the same table, so it
829-
obtains an exclusive lock on the table to enforce that.)
829+
obtains an <literal>ACCESS EXCLUSIVE</literal> lock on the table to
830+
enforce that.)
830831
</para>
831832

832833
<para>

‎doc/src/sgml/pgrowlocks.sgml

Copy file name to clipboardExpand all lines: doc/src/sgml/pgrowlocks.sgml
+2-2Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -97,8 +97,8 @@ pgrowlocks(text) returns setof record
9797
<orderedlist>
9898
<listitem>
9999
<para>
100-
If the table as a whole is exclusive-locked by someone else,
101-
<function>pgrowlocks</function> will be blocked.
100+
If an <literal>ACCESS EXCLUSIVE</literal> lock is taken on the table,
101+
<function>pgrowlocks</function> will be blocked.
102102
</para>
103103
</listitem>
104104
<listitem>

‎doc/src/sgml/ref/drop_index.sgml

Copy file name to clipboardExpand all lines: doc/src/sgml/ref/drop_index.sgml
+4-3Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -45,9 +45,10 @@ DROP INDEX [ CONCURRENTLY ] [ IF EXISTS ] <replaceable class="parameter">name</r
4545
<para>
4646
Drop the index without locking out concurrent selects, inserts, updates,
4747
and deletes on the index's table. A normal <command>DROP INDEX</command>
48-
acquires an exclusive lock on the table, blocking other accesses until the
49-
index drop can be completed. With this option, the command instead
50-
waits until conflicting transactions have completed.
48+
acquires an <literal>ACCESS EXCLUSIVE</literal> lock on the table,
49+
blocking other accesses until the index drop can be completed. With
50+
this option, the command instead waits until conflicting transactions
51+
have completed.
5152
</para>
5253
<para>
5354
There are several caveats to be aware of when using this option.

‎doc/src/sgml/ref/reindex.sgml

Copy file name to clipboardExpand all lines: doc/src/sgml/ref/reindex.sgml
+9-8Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -235,14 +235,15 @@ REINDEX [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] { IN
235235
<command>REINDEX</command> is similar to a drop and recreate of the index
236236
in that the index contents are rebuilt from scratch. However, the locking
237237
considerations are rather different. <command>REINDEX</command> locks out writes
238-
but not reads of the index's parent table. It also takes an exclusive lock
239-
on the specific index being processed, which will block reads that attempt
240-
to use that index. In contrast, <command>DROP INDEX</command> momentarily takes
241-
an exclusive lock on the parent table, blocking both writes and reads. The
242-
subsequent <command>CREATE INDEX</command> locks out writes but not reads; since
243-
the index is not there, no read will attempt to use it, meaning that there
244-
will be no blocking but reads might be forced into expensive sequential
245-
scans.
238+
but not reads of the index's parent table. It also takes an
239+
<literal>ACCESS EXCLUSIVE</literal> lock on the specific index being processed,
240+
which will block reads that attempt to use that index. In contrast,
241+
<command>DROP INDEX</command> momentarily takes an
242+
<literal>ACCESS EXCLUSIVE</literal> lock on the parent table, blocking both
243+
writes and reads. The subsequent <command>CREATE INDEX</command> locks out
244+
writes but not reads; since the index is not there, no read will attempt to
245+
use it, meaning that there will be no blocking but reads might be forced
246+
into expensive sequential scans.
246247
</para>
247248

248249
<para>

‎doc/src/sgml/ref/vacuum.sgml

Copy file name to clipboardExpand all lines: doc/src/sgml/ref/vacuum.sgml
+2-2Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -82,8 +82,8 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ <replaceable class="paramet
8282
specify parallel workers as zero. <command>VACUUM FULL</command> rewrites
8383
the entire contents of the table into a new disk file with no extra space,
8484
allowing unused space to be returned to the operating system. This form is
85-
much slower and requires an exclusive lock on each table while it is being
86-
processed.
85+
much slower and requires an <literal>ACCESS EXCLUSIVE</literal> lock on
86+
each table while it is being processed.
8787
</para>
8888

8989
<para>

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.