<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Explicit Locking</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REV="MADE"
HREF="mailto:pgsql-docs@postgresql.org"><LINK
REL="HOME"
TITLE="PostgreSQL 8.0.11 Documentation"
HREF="index.html"><LINK
REL="UP"
TITLE="Concurrency Control"
HREF="mvcc.html"><LINK
REL="PREVIOUS"
TITLE="Transaction Isolation"
HREF="transaction-iso.html"><LINK
REL="NEXT"
TITLE="Data Consistency Checks at the Application Level"
HREF="applevel-consistency.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="stylesheet.css"><META
HTTP-EQUIV="Content-Type"
CONTENT="text/html; charset=ISO-8859-1"><META
NAME="creation"
CONTENT="2007-02-02T03:57:22"></HEAD
><BODY
CLASS="SECT1"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="5"
ALIGN="center"
VALIGN="bottom"
>PostgreSQL 8.0.11 Documentation</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
HREF="transaction-iso.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
HREF="mvcc.html"
>Fast Backward</A
></TD
><TD
WIDTH="60%"
ALIGN="center"
VALIGN="bottom"
>Chapter 12. Concurrency Control</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="top"
><A
HREF="mvcc.html"
>Fast Forward</A
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="top"
><A
HREF="applevel-consistency.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="EXPLICIT-LOCKING"
>12.3. Explicit Locking</A
></H1
><A
NAME="AEN14507"
></A
><P
> <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> provides various lock modes
to control concurrent access to data in tables. These modes can
be used for application-controlled locking in situations where
<ACRONYM
CLASS="ACRONYM"
>MVCC</ACRONYM
> does not give the desired behavior. Also,
most <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> commands automatically
acquire locks of appropriate modes to ensure that referenced
tables are not dropped or modified in incompatible ways while the
command executes. (For example, <TT
CLASS="COMMAND"
>ALTER TABLE</TT
> cannot be
executed concurrently with other operations on the same table.)
</P
><P
> To examine a list of the currently outstanding locks in a database
server, use the <TT
CLASS="STRUCTNAME"
>pg_locks</TT
> system view
(<A
HREF="view-pg-locks.html"
>Section 41.33</A
>). For more
information on monitoring the status of the lock manager
subsystem, refer to <A
HREF="monitoring.html"
>Chapter 23</A
>.
</P
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="LOCKING-TABLES"
>12.3.1. Table-Level Locks</A
></H2
><A
NAME="AEN14520"
></A
><P
> The list below shows the available lock modes and the contexts in
which they are used automatically by
<SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
>. You can also acquire any
of these locks explicitly with the command <A
HREF="sql-lock.html"
>LOCK</A
>.
Remember that all of these lock modes are table-level locks,
even if the name contains the word
<SPAN
CLASS="QUOTE"
>"row"</SPAN
>; the names of the lock modes are historical.
To some extent the names reflect the typical usage of each lock
mode — but the semantics are all the same. The only real difference
between one lock mode and another is the set of lock modes with
which each conflicts. Two transactions cannot hold locks of conflicting
modes on the same table at the same time. (However, a transaction
never conflicts with itself. For example, it may acquire
<TT
CLASS="LITERAL"
>ACCESS EXCLUSIVE</TT
> lock and later acquire
<TT
CLASS="LITERAL"
>ACCESS SHARE</TT
> lock on the same table.) Non-conflicting
lock modes may be held concurrently by many transactions. Notice in
particular that some lock modes are self-conflicting (for example,
an <TT
CLASS="LITERAL"
>ACCESS EXCLUSIVE</TT
> lock cannot be held by more than one
transaction at a time) while others are not self-conflicting (for example,
an <TT
CLASS="LITERAL"
>ACCESS SHARE</TT
> lock can be held by multiple transactions).
Once acquired, a lock is held till end of transaction.
</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><P
><B
>Table-level lock modes</B
></P
><DL
><DT
><TT
CLASS="LITERAL"
>ACCESS SHARE</TT
></DT
><DD
><P
> Conflicts with the <TT
CLASS="LITERAL"
>ACCESS EXCLUSIVE</TT
> lock
mode only.
</P
><P
> The commands <TT
CLASS="COMMAND"
>SELECT</TT
> and
<TT
CLASS="COMMAND"
>ANALYZE</TT
> acquire a lock of this mode on
referenced tables. In general, any query that only reads a table
and does not modify it will acquire this lock mode.
</P
></DD
><DT
><TT
CLASS="LITERAL"
>ROW SHARE</TT
></DT
><DD
><P
> Conflicts with the <TT
CLASS="LITERAL"
>EXCLUSIVE</TT
> and
<TT
CLASS="LITERAL"
>ACCESS EXCLUSIVE</TT
> lock modes.
</P
><P
> The <TT
CLASS="COMMAND"
>SELECT FOR UPDATE</TT
> command acquires a
lock of this mode on the target table(s) (in addition to
<TT
CLASS="LITERAL"
>ACCESS SHARE</TT
> locks on any other tables
that are referenced but not selected <TT
CLASS="OPTION"
>FOR UPDATE</TT
>).
</P
></DD
><DT
><TT
CLASS="LITERAL"
>ROW EXCLUSIVE</TT
></DT
><DD
><P
> Conflicts with the <TT
CLASS="LITERAL"
>SHARE</TT
>, <TT
CLASS="LITERAL"
>SHARE ROW
EXCLUSIVE</TT
>, <TT
CLASS="LITERAL"
>EXCLUSIVE</TT
>, and
<TT
CLASS="LITERAL"
>ACCESS EXCLUSIVE</TT
> lock modes.
</P
><P
> The commands <TT
CLASS="COMMAND"
>UPDATE</TT
>,
<TT
CLASS="COMMAND"
>DELETE</TT
>, and <TT
CLASS="COMMAND"
>INSERT</TT
>
acquire this lock mode on the target table (in addition to
<TT
CLASS="LITERAL"
>ACCESS SHARE</TT
> locks on any other referenced
tables). In general, this lock mode will be acquired by any
command that modifies the data in a table.
</P
></DD
><DT
><TT
CLASS="LITERAL"
>SHARE UPDATE EXCLUSIVE</TT
></DT
><DD
><P
> Conflicts with the <TT
CLASS="LITERAL"
>SHARE UPDATE EXCLUSIVE</TT
>,
<TT
CLASS="LITERAL"
>SHARE</TT
>, <TT
CLASS="LITERAL"
>SHARE ROW
EXCLUSIVE</TT
>, <TT
CLASS="LITERAL"
>EXCLUSIVE</TT
>, and
<TT
CLASS="LITERAL"
>ACCESS EXCLUSIVE</TT
> lock modes.
This mode protects a table against
concurrent schema changes and <TT
CLASS="COMMAND"
>VACUUM</TT
> runs.
</P
><P
> Acquired by <TT
CLASS="COMMAND"
>VACUUM</TT
> (without <TT
CLASS="OPTION"
>FULL</TT
>).
</P
></DD
><DT
><TT
CLASS="LITERAL"
>SHARE</TT
></DT
><DD
><P
> Conflicts with the <TT
CLASS="LITERAL"
>ROW EXCLUSIVE</TT
>,
<TT
CLASS="LITERAL"
>SHARE UPDATE EXCLUSIVE</TT
>, <TT
CLASS="LITERAL"
>SHARE ROW
EXCLUSIVE</TT
>, <TT
CLASS="LITERAL"
>EXCLUSIVE</TT
>, and
<TT
CLASS="LITERAL"
>ACCESS EXCLUSIVE</TT
> lock modes.
This mode protects a table against concurrent data changes.
</P
><P
> Acquired by <TT
CLASS="COMMAND"
>CREATE INDEX</TT
>.
</P
></DD
><DT
><TT
CLASS="LITERAL"
>SHARE ROW EXCLUSIVE</TT
></DT
><DD
><P
> Conflicts with the <TT
CLASS="LITERAL"
>ROW EXCLUSIVE</TT
>,
<TT
CLASS="LITERAL"
>SHARE UPDATE EXCLUSIVE</TT
>,
<TT
CLASS="LITERAL"
>SHARE</TT
>, <TT
CLASS="LITERAL"
>SHARE ROW
EXCLUSIVE</TT
>, <TT
CLASS="LITERAL"
>EXCLUSIVE</TT
>, and
<TT
CLASS="LITERAL"
>ACCESS EXCLUSIVE</TT
> lock modes.
</P
><P
> This lock mode is not automatically acquired by any
<SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> command.
</P
></DD
><DT
><TT
CLASS="LITERAL"
>EXCLUSIVE</TT
></DT
><DD
><P
> Conflicts with the <TT
CLASS="LITERAL"
>ROW SHARE</TT
>, <TT
CLASS="LITERAL"
>ROW
EXCLUSIVE</TT
>, <TT
CLASS="LITERAL"
>SHARE UPDATE
EXCLUSIVE</TT
>, <TT
CLASS="LITERAL"
>SHARE</TT
>, <TT
CLASS="LITERAL"
>SHARE
ROW EXCLUSIVE</TT
>, <TT
CLASS="LITERAL"
>EXCLUSIVE</TT
>, and
<TT
CLASS="LITERAL"
>ACCESS EXCLUSIVE</TT
> lock modes.
This mode allows only concurrent <TT
CLASS="LITERAL"
>ACCESS SHARE</TT
> locks,
i.e., only reads from the table can proceed in parallel with a
transaction holding this lock mode.
</P
><P
> This lock mode is not automatically acquired by any
<SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> command.
</P
></DD
><DT
><TT
CLASS="LITERAL"
>ACCESS EXCLUSIVE</TT
></DT
><DD
><P
> Conflicts with locks of all modes (<TT
CLASS="LITERAL"
>ACCESS
SHARE</TT
>, <TT
CLASS="LITERAL"
>ROW SHARE</TT
>, <TT
CLASS="LITERAL"
>ROW
EXCLUSIVE</TT
>, <TT
CLASS="LITERAL"
>SHARE UPDATE
EXCLUSIVE</TT
>, <TT
CLASS="LITERAL"
>SHARE</TT
>, <TT
CLASS="LITERAL"
>SHARE
ROW EXCLUSIVE</TT
>, <TT
CLASS="LITERAL"
>EXCLUSIVE</TT
>, and
<TT
CLASS="LITERAL"
>ACCESS EXCLUSIVE</TT
>).
This mode guarantees that the
holder is the only transaction accessing the table in any way.
</P
><P
> Acquired by the <TT
CLASS="COMMAND"
>ALTER TABLE</TT
>, <TT
CLASS="COMMAND"
>DROP
TABLE</TT
>, <TT
CLASS="COMMAND"
>REINDEX</TT
>,
<TT
CLASS="COMMAND"
>CLUSTER</TT
>, and <TT
CLASS="COMMAND"
>VACUUM FULL</TT
>
commands. This is also the default lock mode for <TT
CLASS="COMMAND"
>LOCK
TABLE</TT
> statements that do not specify a mode explicitly.
</P
></DD
></DL
></DIV
><DIV
CLASS="TIP"
><BLOCKQUOTE
CLASS="TIP"
><P
><B
>Tip: </B
> Only an <TT
CLASS="LITERAL"
>ACCESS EXCLUSIVE</TT
> lock blocks a
<TT
CLASS="COMMAND"
>SELECT</TT
> (without <TT
CLASS="OPTION"
>FOR UPDATE</TT
>)
statement.
</P
></BLOCKQUOTE
></DIV
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="LOCKING-ROWS"
>12.3.2. Row-Level Locks</A
></H2
><P
> In addition to table-level locks, there are row-level locks.
A row-level lock on a specific row is automatically acquired when the
row is updated (or deleted or marked for update). The lock is held
until the transaction commits or rolls back.
Row-level locks do not affect data
querying; they block <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>writers to the same row</I
></SPAN
>
only. To acquire a row-level lock on a row without actually
modifying the row, select the row with <TT
CLASS="COMMAND"
>SELECT FOR
UPDATE</TT
>. Note that once a particular row-level lock is
acquired, the transaction may update the row multiple times without
fear of conflicts.
</P
><P
> <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> doesn't remember any
information about modified rows in memory, so it has no limit to
the number of rows locked at one time. However, locking a row
may cause a disk write; thus, for example, <TT
CLASS="COMMAND"
>SELECT FOR
UPDATE</TT
> will modify selected rows to mark them and so
will result in disk writes.
</P
><P
> In addition to table and row locks, page-level share/exclusive locks are
used to control read/write access to table pages in the shared buffer
pool. These locks are released immediately after a row is fetched or
updated. Application developers normally need not be concerned with
page-level locks, but we mention them for completeness.
</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="LOCKING-DEADLOCKS"
>12.3.3. Deadlocks</A
></H2
><A
NAME="AEN14656"
></A
><P
> The use of explicit locking can increase the likelihood of
<I
CLASS="FIRSTTERM"
>deadlocks</I
>, wherein two (or more) transactions each
hold locks that the other wants. For example, if transaction 1
acquires an exclusive lock on table A and then tries to acquire
an exclusive lock on table B, while transaction 2 has already
exclusive-locked table B and now wants an exclusive lock on table
A, then neither one can proceed.
<SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> automatically detects
deadlock situations and resolves them by aborting one of the
transactions involved, allowing the other(s) to complete.
(Exactly which transaction will be aborted is difficult to
predict and should not be relied on.)
</P
><P
> Note that deadlocks can also occur as the result of row-level
locks (and thus, they can occur even if explicit locking is not
used). Consider the case in which there are two concurrent
transactions modifying a table. The first transaction executes:
</P><PRE
CLASS="SCREEN"
>UPDATE accounts SET balance = balance + 100.00 WHERE acctnum = 11111;</PRE
><P>
This acquires a row-level lock on the row with the specified
account number. Then, the second transaction executes:
</P><PRE
CLASS="SCREEN"
>UPDATE accounts SET balance = balance + 100.00 WHERE acctnum = 22222;
UPDATE accounts SET balance = balance - 100.00 WHERE acctnum = 11111;</PRE
><P>
The first <TT
CLASS="COMMAND"
>UPDATE</TT
> statement successfully
acquires a row-level lock on the specified row, so it succeeds in
updating that row. However, the second <TT
CLASS="COMMAND"
>UPDATE</TT
>
statement finds that the row it is attempting to update has
already been locked, so it waits for the transaction that
acquired the lock to complete. Transaction two is now waiting on
transaction one to complete before it continues execution. Now,
transaction one executes:
</P><PRE
CLASS="SCREEN"
>UPDATE accounts SET balance = balance - 100.00 WHERE acctnum = 22222;</PRE
><P>
Transaction one attempts to acquire a row-level lock on the
specified row, but it cannot: transaction two already holds such
a lock. So it waits for transaction two to complete. Thus,
transaction one is blocked on transaction two, and transaction
two is blocked on transaction one: a deadlock
condition. <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> will detect this
situation and abort one of the transactions.
</P
><P
> The best defense against deadlocks is generally to avoid them by
being certain that all applications using a database acquire
locks on multiple objects in a consistent order. In the example
above, if both transactions
had updated the rows in the same order, no deadlock would have
occurred. One should also ensure that the first lock acquired on
an object in a transaction is the highest mode that will be
needed for that object. If it is not feasible to verify this in
advance, then deadlocks may be handled on-the-fly by retrying
transactions that are aborted due to deadlock.
</P
><P
> So long as no deadlock situation is detected, a transaction seeking
either a table-level or row-level lock will wait indefinitely for
conflicting locks to be released. This means it is a bad idea for
applications to hold transactions open for long periods of time
(e.g., while waiting for user input).
</P
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="transaction-iso.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="applevel-consistency.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Transaction Isolation</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="mvcc.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Data Consistency Checks at the Application Level</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
