begriffs open source - ai-pg/blob - full-docs/txt/sql-lock.txt

   1
   2 LOCK
   3
   4    LOCK — lock a table
   5
   6 Synopsis
   7
   8 LOCK [ TABLE ] [ ONLY ] name [ * ] [, ...] [ IN lockmode MODE ] [ NOWAIT ]
   9
  10 where lockmode is one of:
  11
  12     ACCESS SHARE | ROW SHARE | ROW EXCLUSIVE | SHARE UPDATE EXCLUSIVE
  13     | SHARE | SHARE ROW EXCLUSIVE | EXCLUSIVE | ACCESS EXCLUSIVE
  14
  15 Description
  16
  17    LOCK TABLE obtains a table-level lock, waiting if necessary for any
  18    conflicting locks to be released. If NOWAIT is specified, LOCK TABLE
  19    does not wait to acquire the desired lock: if it cannot be acquired
  20    immediately, the command is aborted and an error is emitted. Once
  21    obtained, the lock is held for the remainder of the current
  22    transaction. (There is no UNLOCK TABLE command; locks are always
  23    released at transaction end.)
  24
  25    When a view is locked, all relations appearing in the view definition
  26    query are also locked recursively with the same lock mode.
  27
  28    When acquiring locks automatically for commands that reference tables,
  29    PostgreSQL always uses the least restrictive lock mode possible. LOCK
  30    TABLE provides for cases when you might need more restrictive locking.
  31    For example, suppose an application runs a transaction at the READ
  32    COMMITTED isolation level and needs to ensure that data in a table
  33    remains stable for the duration of the transaction. To achieve this you
  34    could obtain SHARE lock mode over the table before querying. This will
  35    prevent concurrent data changes and ensure subsequent reads of the
  36    table see a stable view of committed data, because SHARE lock mode
  37    conflicts with the ROW EXCLUSIVE lock acquired by writers, and your
  38    LOCK TABLE name IN SHARE MODE statement will wait until any concurrent
  39    holders of ROW EXCLUSIVE mode locks commit or roll back. Thus, once you
  40    obtain the lock, there are no uncommitted writes outstanding;
  41    furthermore none can begin until you release the lock.
  42
  43    To achieve a similar effect when running a transaction at the
  44    REPEATABLE READ or SERIALIZABLE isolation level, you have to execute
  45    the LOCK TABLE statement before executing any SELECT or data
  46    modification statement. A REPEATABLE READ or SERIALIZABLE transaction's
  47    view of data will be frozen when its first SELECT or data modification
  48    statement begins. A LOCK TABLE later in the transaction will still
  49    prevent concurrent writes — but it won't ensure that what the
  50    transaction reads corresponds to the latest committed values.
  51
  52    If a transaction of this sort is going to change the data in the table,
  53    then it should use SHARE ROW EXCLUSIVE lock mode instead of SHARE mode.
  54    This ensures that only one transaction of this type runs at a time.
  55    Without this, a deadlock is possible: two transactions might both
  56    acquire SHARE mode, and then be unable to also acquire ROW EXCLUSIVE
  57    mode to actually perform their updates. (Note that a transaction's own
  58    locks never conflict, so a transaction can acquire ROW EXCLUSIVE mode
  59    when it holds SHARE mode — but not if anyone else holds SHARE mode.) To
  60    avoid deadlocks, make sure all transactions acquire locks on the same
  61    objects in the same order, and if multiple lock modes are involved for
  62    a single object, then transactions should always acquire the most
  63    restrictive mode first.
  64
  65    More information about the lock modes and locking strategies can be
  66    found in Section 13.3.
  67
  68 Parameters
  69
  70    name
  71           The name (optionally schema-qualified) of an existing table to
  72           lock. If ONLY is specified before the table name, only that
  73           table is locked. If ONLY is not specified, the table and all its
  74           descendant tables (if any) are locked. Optionally, * can be
  75           specified after the table name to explicitly indicate that
  76           descendant tables are included.
  77
  78           The command LOCK TABLE a, b; is equivalent to LOCK TABLE a; LOCK
  79           TABLE b;. The tables are locked one-by-one in the order
  80           specified in the LOCK TABLE command.
  81
  82    lockmode
  83           The lock mode specifies which locks this lock conflicts with.
  84           Lock modes are described in Section 13.3.
  85
  86           If no lock mode is specified, then ACCESS EXCLUSIVE, the most
  87           restrictive mode, is used.
  88
  89    NOWAIT
  90           Specifies that LOCK TABLE should not wait for any conflicting
  91           locks to be released: if the specified lock(s) cannot be
  92           acquired immediately without waiting, the transaction is
  93           aborted.
  94
  95 Notes
  96
  97    To lock a table, the user must have the right privilege for the
  98    specified lockmode. If the user has MAINTAIN, UPDATE, DELETE, or
  99    TRUNCATE privileges on the table, any lockmode is permitted. If the
 100    user has INSERT privileges on the table, ROW EXCLUSIVE MODE (or a
 101    less-conflicting mode as described in Section 13.3) is permitted. If a
 102    user has SELECT privileges on the table, ACCESS SHARE MODE is
 103    permitted.
 104
 105    The user performing the lock on the view must have the corresponding
 106    privilege on the view. In addition, by default, the view's owner must
 107    have the relevant privileges on the underlying base relations, whereas
 108    the user performing the lock does not need any permissions on the
 109    underlying base relations. However, if the view has security_invoker
 110    set to true (see CREATE VIEW), the user performing the lock, rather
 111    than the view owner, must have the relevant privileges on the
 112    underlying base relations.
 113
 114    LOCK TABLE is useless outside a transaction block: the lock would
 115    remain held only to the completion of the statement. Therefore
 116    PostgreSQL reports an error if LOCK is used outside a transaction
 117    block. Use BEGIN and COMMIT (or ROLLBACK) to define a transaction
 118    block.
 119
 120    LOCK TABLE only deals with table-level locks, and so the mode names
 121    involving ROW are all misnomers. These mode names should generally be
 122    read as indicating the intention of the user to acquire row-level locks
 123    within the locked table. Also, ROW EXCLUSIVE mode is a shareable table
 124    lock. Keep in mind that all the lock modes have identical semantics so
 125    far as LOCK TABLE is concerned, differing only in the rules about which
 126    modes conflict with which. For information on how to acquire an actual
 127    row-level lock, see Section 13.3.2 and The Locking Clause in the SELECT
 128    documentation.
 129
 130 Examples
 131
 132    Obtain a SHARE lock on a primary key table when going to perform
 133    inserts into a foreign key table:
 134 BEGIN WORK;
 135 LOCK TABLE films IN SHARE MODE;
 136 SELECT id FROM films
 137     WHERE name = 'Star Wars: Episode I - The Phantom Menace';
 138 -- Do ROLLBACK if record was not returned
 139 INSERT INTO films_user_comments VALUES
 140     (_id_, 'GREAT! I was waiting for it for so long!');
 141 COMMIT WORK;
 142
 143    Take a SHARE ROW EXCLUSIVE lock on a primary key table when going to
 144    perform a delete operation:
 145 BEGIN WORK;
 146 LOCK TABLE films IN SHARE ROW EXCLUSIVE MODE;
 147 DELETE FROM films_user_comments WHERE id IN
 148     (SELECT id FROM films WHERE rating < 5);
 149 DELETE FROM films WHERE rating < 5;
 150 COMMIT WORK;
 151
 152 Compatibility
 153
 154    There is no LOCK TABLE in the SQL standard, which instead uses SET
 155    TRANSACTION to specify concurrency levels on transactions. PostgreSQL
 156    supports that too; see SET TRANSACTION for details.
 157
 158    Except for ACCESS SHARE, ACCESS EXCLUSIVE, and SHARE UPDATE EXCLUSIVE
 159    lock modes, the PostgreSQL lock modes and the LOCK TABLE syntax are
 160    compatible with those present in Oracle.