mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

doc: Clarify use of ACCESS EXCLUSIVE lock in various sections

Browse Source 
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
This commit is contained in:
Michael Paquier 2021-04-01 15:29:01 +09:00
parent 625f5aae7e
commit dd5d04e5da
9 changed files with 29 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
doc/src/sgml/ddl.sgml
View File

@ -2031,7 +2031,8 @@ SELECT * FROM information WHERE group_id = 2 FOR UPDATE;
definer function.) Also, heavy concurrent use of row share locks on the
referenced table could pose a performance problem, especially if updates
of it are frequent. Another solution, practical if updates of the
referenced table are infrequent, is to take an exclusive lock on the
referenced table are infrequent, is to take an
<literal>ACCESS EXCLUSIVE</literal> lock on the
referenced table when updating it, so that no concurrent transactions
could be examining old row values. Or one could just wait for all
concurrent transactions to end after committing an update of the

3
doc/src/sgml/hstore.sgml
View File

@ -610,7 +610,8 @@ UPDATE tablename SET hstorecol = hstorecol || '';
<programlisting>
ALTER TABLE tablename ALTER hstorecol TYPE hstore USING hstorecol || '';
</programlisting>
The <command>ALTER TABLE</command> method requires an exclusive lock on the table,
The <command>ALTER TABLE</command> method requires an
<literal>ACCESS EXCLUSIVE</literal> lock on the table,
but does not result in bloating the table with old row versions.
</para>

4
doc/src/sgml/indexam.sgml
View File

@ -897,8 +897,8 @@ amparallelrescan (IndexScanDesc scan);
<literal>RowExclusiveLock</literal> when updating the index (including plain
<command>VACUUM</command>). Since these lock types do not conflict, the access
method is responsible for handling any fine-grained locking it might need.
An exclusive lock on the index as a whole will be taken only during index
creation, destruction, or <command>REINDEX</command>.
An <literal>ACCESS EXCLUSIVE</literal> lock on the index as a whole will be
taken only during index creation, destruction, or <command>REINDEX</command>.
</para>
<para>

6
doc/src/sgml/maintenance.sgml
View File

@ -128,7 +128,8 @@
<command>DELETE</command> will continue to function normally, though you
will not be able to modify the definition of a table with commands such as
<command>ALTER TABLE</command> while it is being vacuumed.)
<command>VACUUM FULL</command> requires exclusive lock on the table it is
<command>VACUUM FULL</command> requires an
<literal>ACCESS EXCLUSIVE</literal> lock on the table it is
working on, and therefore cannot be done in parallel with other use
of the table. Generally, therefore,
administrators should strive to use standard <command>VACUUM</command> and
@ -231,7 +232,8 @@
or one of the table-rewriting variants of
<xref linkend="sql-altertable"/>.
These commands rewrite an entire new copy of the table and build
new indexes for it. All these options require exclusive lock. Note that
new indexes for it. All these options require an
<literal>ACCESS EXCLUSIVE</literal> lock. Note that
they also temporarily use extra disk space approximately equal to the size
of the table, since the old copies of the table and indexes can't be
released until the new ones are complete.

3
doc/src/sgml/mvcc.sgml
View File

@ -826,7 +826,8 @@ ERROR: could not serialize access due to read/write dependencies among transact
tables are not dropped or modified in incompatible ways while the
command executes. (For example, <command>TRUNCATE</command> cannot safely be
executed concurrently with other operations on the same table, so it
obtains an exclusive lock on the table to enforce that.)
obtains an <literal>ACCESS EXCLUSIVE</literal> lock on the table to
enforce that.)
</para>
<para>

4
doc/src/sgml/pgrowlocks.sgml
View File

@ -97,8 +97,8 @@ pgrowlocks(text) returns setof record
<orderedlist>
<listitem>
<para>
If the table as a whole is exclusive-locked by someone else,
<function>pgrowlocks</function> will be blocked.
If an <literal>ACCESS EXCLUSIVE</literal> lock is taken on the table,
<function>pgrowlocks</function> will be blocked.
</para>
</listitem>
<listitem>

7
doc/src/sgml/ref/drop_index.sgml
View File

@ -45,9 +45,10 @@ DROP INDEX [ CONCURRENTLY ] [ IF EXISTS ] <replaceable class="parameter">name</r
<para>
Drop the index without locking out concurrent selects, inserts, updates,
and deletes on the index's table. A normal <command>DROP INDEX</command>
acquires an exclusive lock on the table, blocking other accesses until the
index drop can be completed. With this option, the command instead
waits until conflicting transactions have completed.
acquires an <literal>ACCESS EXCLUSIVE</literal> lock on the table,
blocking other accesses until the index drop can be completed. With
this option, the command instead waits until conflicting transactions
have completed.
</para>
<para>
There are several caveats to be aware of when using this option.

17
doc/src/sgml/ref/reindex.sgml
View File

@ -213,14 +213,15 @@ REINDEX [ ( VERBOSE ) ] { INDEX | TABLE | SCHEMA | DATABASE | SYSTEM } <replacea
<command>REINDEX</command> is similar to a drop and recreate of the index
in that the index contents are rebuilt from scratch. However, the locking
considerations are rather different. <command>REINDEX</command> locks out writes
but not reads of the index's parent table. It also takes an exclusive lock
on the specific index being processed, which will block reads that attempt
to use that index. In contrast, <command>DROP INDEX</command> momentarily takes
an exclusive lock on the parent table, blocking both writes and reads. The
subsequent <command>CREATE INDEX</command> locks out writes but not reads; since
the index is not there, no read will attempt to use it, meaning that there
will be no blocking but reads might be forced into expensive sequential
scans.
but not reads of the index's parent table. It also takes an
<literal>ACCESS EXCLUSIVE</literal> lock on the specific index being processed,
which will block reads that attempt to use that index. In contrast,
<command>DROP INDEX</command> momentarily takes an
<literal>ACCESS EXCLUSIVE</literal> lock on the parent table, blocking both
writes and reads. The subsequent <command>CREATE INDEX</command> locks out
writes but not reads; since the index is not there, no read will attempt to
use it, meaning that there will be no blocking but reads might be forced
into expensive sequential scans.
</para>
<para>

3
doc/src/sgml/ref/vacuum.sgml
View File

@ -75,7 +75,8 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ <replaceable class="paramet
same table. <command>VACUUM FULL</command> rewrites the entire contents
of the table into a new disk file with no extra space, allowing unused
space to be returned to the operating system. This form is much slower and
requires an exclusive lock on each table while it is being processed.
requires an <literal>ACCESS EXCLUSIVE</literal> lock on each table while
it is being processed.
</para>
<para>