begriffs open source - ai-pg/blob - full-docs/txt/view-pg-locks.txt

   1
   2 53.13. pg_locks #
   3
   4    The view pg_locks provides access to information about the locks held
   5    by active processes within the database server. See Chapter 13 for more
   6    discussion of locking.
   7
   8    pg_locks contains one row per active lockable object, requested lock
   9    mode, and relevant process. Thus, the same lockable object might appear
  10    many times, if multiple processes are holding or waiting for locks on
  11    it. However, an object that currently has no locks on it will not
  12    appear at all.
  13
  14    There are several distinct types of lockable objects: whole relations
  15    (e.g., tables), individual pages of relations, individual tuples of
  16    relations, transaction IDs (both virtual and permanent IDs), and
  17    general database objects (identified by class OID and object OID, in
  18    the same way as in pg_description or pg_depend). Also, the right to
  19    extend a relation is represented as a separate lockable object, as is
  20    the right to update pg_database.datfrozenxid. Also, “advisory” locks
  21    can be taken on numbers that have user-defined meanings.
  22
  23    Table 53.13. pg_locks Columns
  24
  25    Column Type
  26
  27    Description
  28
  29    locktype text
  30
  31    Type of the lockable object: relation, extend, frozenid, page, tuple,
  32    transactionid, virtualxid, spectoken, object, userlock, advisory, or
  33    applytransaction. (See also Table 27.11.)
  34
  35    database oid (references pg_database.oid)
  36
  37    OID of the database in which the lock target exists, or zero if the
  38    target is a shared object, or null if the target is a transaction ID
  39
  40    relation oid (references pg_class.oid)
  41
  42    OID of the relation targeted by the lock, or null if the target is not
  43    a relation or part of a relation
  44
  45    page int4
  46
  47    Page number targeted by the lock within the relation, or null if the
  48    target is not a relation page or tuple
  49
  50    tuple int2
  51
  52    Tuple number targeted by the lock within the page, or null if the
  53    target is not a tuple
  54
  55    virtualxid text
  56
  57    Virtual ID of the transaction targeted by the lock, or null if the
  58    target is not a virtual transaction ID; see Chapter 67
  59
  60    transactionid xid
  61
  62    ID of the transaction targeted by the lock, or null if the target is
  63    not a transaction ID; Chapter 67
  64
  65    classid oid (references pg_class.oid)
  66
  67    OID of the system catalog containing the lock target, or null if the
  68    target is not a general database object
  69
  70    objid oid (references any OID column)
  71
  72    OID of the lock target within its system catalog, or null if the target
  73    is not a general database object
  74
  75    objsubid int2
  76
  77    Column number targeted by the lock (the classid and objid refer to the
  78    table itself), or zero if the target is some other general database
  79    object, or null if the target is not a general database object
  80
  81    virtualtransaction text
  82
  83    Virtual ID of the transaction that is holding or awaiting this lock
  84
  85    pid int4
  86
  87    Process ID of the server process holding or awaiting this lock, or null
  88    if the lock is held by a prepared transaction
  89
  90    mode text
  91
  92    Name of the lock mode held or desired by this process (see
  93    Section 13.3.1 and Section 13.2.3)
  94
  95    granted bool
  96
  97    True if lock is held, false if lock is awaited
  98
  99    fastpath bool
 100
 101    True if lock was taken via fast path, false if taken via main lock
 102    table
 103
 104    waitstart timestamptz
 105
 106    Time when the server process started waiting for this lock, or null if
 107    the lock is held. Note that this can be null for a very short period of
 108    time after the wait started even though granted is false.
 109
 110    granted is true in a row representing a lock held by the indicated
 111    process. False indicates that this process is currently waiting to
 112    acquire this lock, which implies that at least one other process is
 113    holding or waiting for a conflicting lock mode on the same lockable
 114    object. The waiting process will sleep until the other lock is released
 115    (or a deadlock situation is detected). A single process can be waiting
 116    to acquire at most one lock at a time.
 117
 118    Throughout running a transaction, a server process holds an exclusive
 119    lock on the transaction's virtual transaction ID. If a permanent ID is
 120    assigned to the transaction (which normally happens only if the
 121    transaction changes the state of the database), it also holds an
 122    exclusive lock on the transaction's permanent transaction ID until it
 123    ends. When a process finds it necessary to wait specifically for
 124    another transaction to end, it does so by attempting to acquire share
 125    lock on the other transaction's ID (either virtual or permanent ID
 126    depending on the situation). That will succeed only when the other
 127    transaction terminates and releases its locks.
 128
 129    Although tuples are a lockable type of object, information about
 130    row-level locks is stored on disk, not in memory, and therefore
 131    row-level locks normally do not appear in this view. If a process is
 132    waiting for a row-level lock, it will usually appear in the view as
 133    waiting for the permanent transaction ID of the current holder of that
 134    row lock.
 135
 136    A speculative insertion lock consists of a transaction ID and a
 137    speculative insertion token. The speculative insertion token is
 138    displayed in the objid column.
 139
 140    Advisory locks can be acquired on keys consisting of either a single
 141    bigint value or two integer values. A bigint key is displayed with its
 142    high-order half in the classid column, its low-order half in the objid
 143    column, and objsubid equal to 1. The original bigint value can be
 144    reassembled with the expression (classid::bigint << 32) |
 145    objid::bigint. Integer keys are displayed with the first key in the
 146    classid column, the second key in the objid column, and objsubid equal
 147    to 2. The actual meaning of the keys is up to the user. Advisory locks
 148    are local to each database, so the database column is meaningful for an
 149    advisory lock.
 150
 151    Apply transaction locks are used in parallel mode to apply the
 152    transaction in logical replication. The remote transaction ID is
 153    displayed in the transactionid column. The objsubid displays the lock
 154    subtype which is 0 for the lock used to synchronize the set of changes,
 155    and 1 for the lock used to wait for the transaction to finish to ensure
 156    commit order.
 157
 158    pg_locks provides a global view of all locks in the database cluster,
 159    not only those relevant to the current database. Although its relation
 160    column can be joined against pg_class.oid to identify locked relations,
 161    this will only work correctly for relations in the current database
 162    (those for which the database column is either the current database's
 163    OID or zero).
 164
 165    The pid column can be joined to the pid column of the pg_stat_activity
 166    view to get more information on the session holding or awaiting each
 167    lock, for example
 168 SELECT * FROM pg_locks pl LEFT JOIN pg_stat_activity psa
 169     ON pl.pid = psa.pid;
 170
 171    Also, if you are using prepared transactions, the virtualtransaction
 172    column can be joined to the transaction column of the pg_prepared_xacts
 173    view to get more information on prepared transactions that hold locks.
 174    (A prepared transaction can never be waiting for a lock, but it
 175    continues to hold the locks it acquired while running.) For example:
 176 SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
 177     ON pl.virtualtransaction = '-1/' || ppx.transaction;
 178
 179    While it is possible to obtain information about which processes block
 180    which other processes by joining pg_locks against itself, this is very
 181    difficult to get right in detail. Such a query would have to encode
 182    knowledge about which lock modes conflict with which others. Worse, the
 183    pg_locks view does not expose information about which processes are
 184    ahead of which others in lock wait queues, nor information about which
 185    processes are parallel workers running on behalf of which other client
 186    sessions. It is better to use the pg_blocking_pids() function (see
 187    Table 9.71) to identify which process(es) a waiting process is blocked
 188    behind.
 189
 190    The pg_locks view displays data from both the regular lock manager and
 191    the predicate lock manager, which are separate systems; in addition,
 192    the regular lock manager subdivides its locks into regular and
 193    fast-path locks. This data is not guaranteed to be entirely consistent.
 194    When the view is queried, data on fast-path locks (with fastpath =
 195    true) is gathered from each backend one at a time, without freezing the
 196    state of the entire lock manager, so it is possible for locks to be
 197    taken or released while information is gathered. Note, however, that
 198    these locks are known not to conflict with any other lock currently in
 199    place. After all backends have been queried for fast-path locks, the
 200    remainder of the regular lock manager is locked as a unit, and a
 201    consistent snapshot of all remaining locks is collected as an atomic
 202    action. After unlocking the regular lock manager, the predicate lock
 203    manager is similarly locked and all predicate locks are collected as an
 204    atomic action. Thus, with the exception of fast-path locks, each lock
 205    manager will deliver a consistent set of results, but as we do not lock
 206    both lock managers simultaneously, it is possible for locks to be taken
 207    or released after we interrogate the regular lock manager and before we
 208    interrogate the predicate lock manager.
 209
 210    Locking the regular and/or predicate lock manager could have some
 211    impact on database performance if this view is very frequently
 212    accessed. The locks are held only for the minimum amount of time
 213    necessary to obtain data from the lock managers, but this does not
 214    completely eliminate the possibility of a performance impact.