13.3. Explicit Locking
PostgreSQL provides various lock modes to control concurrent access to data in tables. These modes can be used for application-controlled locking in situations whereMVCC does not give the desired behavior. Also, mostPostgreSQL 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, To examine a list of the currently outstanding locks in a database server, use the The list below shows the available lock modes and the contexts in which they are used automatically byPostgreSQL. You can also acquire any of these locks explicitly with the commandLOCK. Remember that all of these lock modes are table-level locks, even if the name contains the word“row”; 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 (seeTable 13.2). 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 might acquire Table-Level Lock Modes Conflicts with the The Conflicts with the The Conflicts with the The commands Conflicts with the Acquired by Conflicts with the Acquired by Conflicts with the Acquired by Conflicts with the Acquired by Conflicts with locks of all modes ( Acquired by the Only an Once acquired, a lock is normally held until the end of the transaction. But if a lock is acquired after establishing a savepoint, the lock is released immediately if the savepoint is rolled back to. This is consistent with the principle that Table 13.2. Conflicting Lock Modes In addition to table-level locks, there are row-level locks, which are listed as below with the contexts in which they are used automatically byPostgreSQL. SeeTable 13.3 for a complete table of row-level lock conflicts. Note that a transaction can hold conflicting locks on the same row, even in different subtransactions; but other than that, two transactions can never hold conflicting locks on the same row. Row-level locks do not affect data querying; they block onlywriters and lockers to the same row. Row-level locks are released at transaction end or during savepoint rollback, just like table-level locks. Row-Level Lock Modes The Behaves similarly to Behaves similarly to Behaves similarly to PostgreSQL doesn't remember any information about modified rows in memory, so there is no limit on the number of rows locked at one time. However, locking a row might cause a disk write, e.g., Table 13.3. Conflicting Row-Level Locks 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 they are mentioned here for completeness. The use of explicit locking can increase the likelihood ofdeadlocks, 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.PostgreSQL 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 upon.) 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 two concurrent transactions modify a table. The first transaction executes: This acquires a row-level lock on the row with the specified account number. Then, the second transaction executes: The first 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.PostgreSQL will detect this situation and abort one of the transactions. 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 most restrictive mode that will be needed for that object. If it is not feasible to verify this in advance, then deadlocks can be handled on-the-fly by retrying transactions that abort due to deadlocks. 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). PostgreSQL provides a means for creating locks that have application-defined meanings. These are calledadvisory locks, because the system does not enforce their use — it is up to the application to use them correctly. Advisory locks can be useful for locking strategies that are an awkward fit for the MVCC model. For example, a common use of advisory locks is to emulate pessimistic locking strategies typical of so-called“flat file” data management systems. While a flag stored in a table could be used for the same purpose, advisory locks are faster, avoid table bloat, and are automatically cleaned up by the server at the end of the session. There are two ways to acquire an advisory lock inPostgreSQL: at session level or at transaction level. Once acquired at session level, an advisory lock is held until explicitly released or the session ends. Unlike standard lock requests, session-level advisory lock requests do not honor transaction semantics: a lock acquired during a transaction that is later rolled back will still be held following the rollback, and likewise an unlock is effective even if the calling transaction fails later. A lock can be acquired multiple times by its owning process; for each completed lock request there must be a corresponding unlock request before the lock is actually released. Transaction-level lock requests, on the other hand, behave more like regular lock requests: they are automatically released at the end of the transaction, and there is no explicit unlock operation. This behavior is often more convenient than the session-level behavior for short-term usage of an advisory lock. Session-level and transaction-level lock requests for the same advisory lock identifier will block each other in the expected way. If a session already holds a given advisory lock, additional requests by it will always succeed, even if other sessions are awaiting the lock; this statement is true regardless of whether the existing lock hold and new request are at session level or transaction level. Like all locks inPostgreSQL, a complete list of advisory locks currently held by any session can be found in the Both advisory locks and regular locks are stored in a shared memory pool whose size is defined by the configuration variablesmax_locks_per_transaction andmax_connections. Care must be taken not to exhaust this memory or the server will be unable to grant any locks at all. This imposes an upper limit on the number of advisory locks grantable by the server, typically in the tens to hundreds of thousands depending on how the server is configured. In certain cases using advisory locking methods, especially in queries involving explicit ordering and In the above queries, the second form is dangerous because the The functions provided to manipulate advisory locks are described inSection 9.26.10.TRUNCATE
cannot safely be executed concurrently with other operations on the same table, so it obtains anACCESS EXCLUSIVE
lock on the table to enforce that.)pg_locks
system view. For more information on monitoring the status of the lock manager subsystem, refer toChapter 27.13.3.1. Table-Level Locks
ACCESS EXCLUSIVE
lock and later acquireACCESS SHARE
lock on the same table.) Non-conflicting lock modes can be held concurrently by many transactions. Notice in particular that some lock modes are self-conflicting (for example, anACCESS EXCLUSIVE
lock cannot be held by more than one transaction at a time) while others are not self-conflicting (for example, anACCESS SHARE
lock can be held by multiple transactions).ACCESS SHARE
(AccessShareLock
)ACCESS EXCLUSIVE
lock mode only.SELECT
command acquires a lock of this mode on referenced tables. In general, any query that onlyreads a table and does not modify it will acquire this lock mode.ROW SHARE
(RowShareLock
)EXCLUSIVE
andACCESS EXCLUSIVE
lock modes.SELECT FOR UPDATE
andSELECT FOR SHARE
commands acquire a lock of this mode on the target table(s) (in addition toACCESS SHARE
locks on any other tables that are referenced but not selectedFOR UPDATE/FOR SHARE
).ROW EXCLUSIVE
(RowExclusiveLock
)SHARE
,SHARE ROW EXCLUSIVE
,EXCLUSIVE
, andACCESS EXCLUSIVE
lock modes.UPDATE
,DELETE
, andINSERT
acquire this lock mode on the target table (in addition toACCESS SHARE
locks on any other referenced tables). In general, this lock mode will be acquired by any command thatmodifies data in a table.SHARE UPDATE EXCLUSIVE
(ShareUpdateExclusiveLock
)SHARE UPDATE EXCLUSIVE
,SHARE
,SHARE ROW EXCLUSIVE
,EXCLUSIVE
, andACCESS EXCLUSIVE
lock modes. This mode protects a table against concurrent schema changes andVACUUM
runs.VACUUM
(withoutFULL
),ANALYZE
,CREATE INDEX CONCURRENTLY
,CREATE STATISTICS
,COMMENT ON
,REINDEX CONCURRENTLY
, and certainALTER INDEX
andALTER TABLE
variants (for full details seeALTER INDEX andALTER TABLE).SHARE
(ShareLock
)ROW EXCLUSIVE
,SHARE UPDATE EXCLUSIVE
,SHARE ROW EXCLUSIVE
,EXCLUSIVE
, andACCESS EXCLUSIVE
lock modes. This mode protects a table against concurrent data changes.CREATE INDEX
(withoutCONCURRENTLY
).SHARE ROW EXCLUSIVE
(ShareRowExclusiveLock
)ROW EXCLUSIVE
,SHARE UPDATE EXCLUSIVE
,SHARE
,SHARE ROW EXCLUSIVE
,EXCLUSIVE
, andACCESS EXCLUSIVE
lock modes. This mode protects a table against concurrent data changes, and is self-exclusive so that only one session can hold it at a time.CREATE TRIGGER
and some forms ofALTER TABLE
(seeALTER TABLE).EXCLUSIVE
(ExclusiveLock
)ROW SHARE
,ROW EXCLUSIVE
,SHARE UPDATE EXCLUSIVE
,SHARE
,SHARE ROW EXCLUSIVE
,EXCLUSIVE
, andACCESS EXCLUSIVE
lock modes. This mode allows only concurrentACCESS SHARE
locks, i.e., only reads from the table can proceed in parallel with a transaction holding this lock mode.REFRESH MATERIALIZED VIEW CONCURRENTLY
.ACCESS EXCLUSIVE
(AccessExclusiveLock
)ACCESS SHARE
,ROW SHARE
,ROW EXCLUSIVE
,SHARE UPDATE EXCLUSIVE
,SHARE
,SHARE ROW EXCLUSIVE
,EXCLUSIVE
, andACCESS EXCLUSIVE
). This mode guarantees that the holder is the only transaction accessing the table in any way.DROP TABLE
,TRUNCATE
,REINDEX
,CLUSTER
,VACUUM FULL
, andREFRESH MATERIALIZED VIEW
(withoutCONCURRENTLY
) commands. Many forms ofALTER INDEX
andALTER TABLE
also acquire a lock at this level. This is also the default lock mode forLOCK TABLE
statements that do not specify a mode explicitly.Tip
ACCESS EXCLUSIVE
lock blocks aSELECT
(withoutFOR UPDATE/SHARE
) statement.ROLLBACK
cancels all effects of the commands since the savepoint. The same holds for locks acquired within aPL/pgSQL exception block: an error escape from the block releases locks acquired within it.Requested Lock Mode Current Lock Mode ACCESS SHARE ROW SHARE ROW EXCLUSIVE SHARE UPDATE EXCLUSIVE SHARE SHARE ROW EXCLUSIVE EXCLUSIVE ACCESS EXCLUSIVE ACCESS SHARE X ROW SHARE X X ROW EXCLUSIVE X X X X SHARE UPDATE EXCLUSIVE X X X X X SHARE X X X X X SHARE ROW EXCLUSIVE X X X X X X EXCLUSIVE X X X X X X X ACCESS EXCLUSIVE X X X X X X X X 13.3.2. Row-Level Locks
FOR UPDATE
FOR UPDATE
causes the rows retrieved by theSELECT
statement to be locked as though for update. This prevents them from being locked, modified or deleted by other transactions until the current transaction ends. That is, other transactions that attemptUPDATE
,DELETE
,SELECT FOR UPDATE
,SELECT FOR NO KEY UPDATE
,SELECT FOR SHARE
orSELECT FOR KEY SHARE
of these rows will be blocked until the current transaction ends; conversely,SELECT FOR UPDATE
will wait for a concurrent transaction that has run any of those commands on the same row, and will then lock and return the updated row (or no row, if the row was deleted). Within aREPEATABLE READ
orSERIALIZABLE
transaction, however, an error will be thrown if a row to be locked has changed since the transaction started. For further discussion seeSection 13.4.FOR UPDATE
lock mode is also acquired by anyDELETE
on a row, and also by anUPDATE
that modifies the values of certain columns. Currently, the set of columns considered for theUPDATE
case are those that have a unique index on them that can be used in a foreign key (so partial indexes and expressional indexes are not considered), but this may change in the future.FOR NO KEY UPDATE
FOR UPDATE
, except that the lock acquired is weaker: this lock will not blockSELECT FOR KEY SHARE
commands that attempt to acquire a lock on the same rows. This lock mode is also acquired by anyUPDATE
that does not acquire aFOR UPDATE
lock.FOR SHARE
FOR NO KEY UPDATE
, except that it acquires a shared lock rather than exclusive lock on each retrieved row. A shared lock blocks other transactions from performingUPDATE
,DELETE
,SELECT FOR UPDATE
orSELECT FOR NO KEY UPDATE
on these rows, but it does not prevent them from performingSELECT FOR SHARE
orSELECT FOR KEY SHARE
.FOR KEY SHARE
FOR SHARE
, except that the lock is weaker:SELECT FOR UPDATE
is blocked, but notSELECT FOR NO KEY UPDATE
. A key-shared lock blocks other transactions from performingDELETE
or anyUPDATE
that changes the key values, but not otherUPDATE
, and neither does it preventSELECT FOR NO KEY UPDATE
,SELECT FOR SHARE
, orSELECT FOR KEY SHARE
.SELECT FOR UPDATE
modifies selected rows to mark them locked, and so will result in disk writes.Requested Lock Mode Current Lock Mode FOR KEY SHARE FOR SHARE FOR NO KEY UPDATE FOR UPDATE FOR KEY SHARE X FOR SHARE X X FOR NO KEY UPDATE X X X FOR UPDATE X X X X 13.3.3. Page-Level Locks
13.3.4. Deadlocks
UPDATE accounts SET balance = balance + 100.00 WHERE acctnum = 11111;
UPDATE accounts SET balance = balance + 100.00 WHERE acctnum = 22222;UPDATE accounts SET balance = balance - 100.00 WHERE acctnum = 11111;
UPDATE
statement successfully acquires a row-level lock on the specified row, so it succeeds in updating that row. However, the secondUPDATE
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:UPDATE accounts SET balance = balance - 100.00 WHERE acctnum = 22222;
13.3.5. Advisory Locks
pg_locks
system view.LIMIT
clauses, care must be taken to control the locks acquired because of the order in which SQL expressions are evaluated. For example:SELECT pg_advisory_lock(id) FROM foo WHERE id = 12345; -- okSELECT pg_advisory_lock(id) FROM foo WHERE id > 12345 LIMIT 100; -- danger!SELECT pg_advisory_lock(q.id) FROM( SELECT id FROM foo WHERE id > 12345 LIMIT 100) q; -- ok
LIMIT
is not guaranteed to be applied before the locking function is executed. This might cause some locks to be acquired that the application was not expecting, and hence would fail to release (until it ends the session). From the point of view of the application, such locks would be dangling, although still viewable inpg_locks
.