begriffs open source - ai-pg/blob - full-docs/man7/LOCK.7

   1 '\" t
   2 .\"     Title: LOCK
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "LOCK" "7" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 LOCK \- lock a table
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 LOCK [ TABLE ] [ ONLY ] \fIname\fR [ * ] [, \&.\&.\&.] [ IN \fIlockmode\fR MODE ] [ NOWAIT ]
  36
  37 where \fIlockmode\fR is one of:
  38
  39     ACCESS SHARE | ROW SHARE | ROW EXCLUSIVE | SHARE UPDATE EXCLUSIVE
  40     | SHARE | SHARE ROW EXCLUSIVE | EXCLUSIVE | ACCESS EXCLUSIVE
  41 .fi
  42 .SH "DESCRIPTION"
  43 .PP
  44 \fBLOCK TABLE\fR
  45 obtains a table\-level lock, waiting if necessary for any conflicting locks to be released\&. If
  46 NOWAIT
  47 is specified,
  48 \fBLOCK TABLE\fR
  49 does not wait to acquire the desired lock: if it cannot be acquired immediately, the command is aborted and an error is emitted\&. Once obtained, the lock is held for the remainder of the current transaction\&. (There is no
  50 \fBUNLOCK TABLE\fR
  51 command; locks are always released at transaction end\&.)
  52 .PP
  53 When a view is locked, all relations appearing in the view definition query are also locked recursively with the same lock mode\&.
  54 .PP
  55 When acquiring locks automatically for commands that reference tables,
  56 PostgreSQL
  57 always uses the least restrictive lock mode possible\&.
  58 \fBLOCK TABLE\fR
  59 provides for cases when you might need more restrictive locking\&. For example, suppose an application runs a transaction at the
  60 READ COMMITTED
  61 isolation level and needs to ensure that data in a table remains stable for the duration of the transaction\&. To achieve this you could obtain
  62 SHARE
  63 lock mode over the table before querying\&. This will prevent concurrent data changes and ensure subsequent reads of the table see a stable view of committed data, because
  64 SHARE
  65 lock mode conflicts with the
  66 ROW EXCLUSIVE
  67 lock acquired by writers, and your
  68 \fBLOCK TABLE \fR\fB\fIname\fR\fR\fB IN SHARE MODE\fR
  69 statement will wait until any concurrent holders of
  70 ROW EXCLUSIVE
  71 mode locks commit or roll back\&. Thus, once you obtain the lock, there are no uncommitted writes outstanding; furthermore none can begin until you release the lock\&.
  72 .PP
  73 To achieve a similar effect when running a transaction at the
  74 REPEATABLE READ
  75 or
  76 SERIALIZABLE
  77 isolation level, you have to execute the
  78 \fBLOCK TABLE\fR
  79 statement before executing any
  80 \fBSELECT\fR
  81 or data modification statement\&. A
  82 REPEATABLE READ
  83 or
  84 SERIALIZABLE
  85 transaction\*(Aqs view of data will be frozen when its first
  86 \fBSELECT\fR
  87 or data modification statement begins\&. A
  88 \fBLOCK TABLE\fR
  89 later in the transaction will still prevent concurrent writes \(em but it won\*(Aqt ensure that what the transaction reads corresponds to the latest committed values\&.
  90 .PP
  91 If a transaction of this sort is going to change the data in the table, then it should use
  92 SHARE ROW EXCLUSIVE
  93 lock mode instead of
  94 SHARE
  95 mode\&. This ensures that only one transaction of this type runs at a time\&. Without this, a deadlock is possible: two transactions might both acquire
  96 SHARE
  97 mode, and then be unable to also acquire
  98 ROW EXCLUSIVE
  99 mode to actually perform their updates\&. (Note that a transaction\*(Aqs own locks never conflict, so a transaction can acquire
 100 ROW EXCLUSIVE
 101 mode when it holds
 102 SHARE
 103 mode \(em but not if anyone else holds
 104 SHARE
 105 mode\&.) To avoid deadlocks, make sure all transactions acquire locks on the same objects in the same order, and if multiple lock modes are involved for a single object, then transactions should always acquire the most restrictive mode first\&.
 106 .PP
 107 More information about the lock modes and locking strategies can be found in
 108 Section\ \&13.3\&.
 109 .SH "PARAMETERS"
 110 .PP
 111 \fIname\fR
 112 .RS 4
 113 The name (optionally schema\-qualified) of an existing table to lock\&. If
 114 ONLY
 115 is specified before the table name, only that table is locked\&. If
 116 ONLY
 117 is not specified, the table and all its descendant tables (if any) are locked\&. Optionally,
 118 *
 119 can be specified after the table name to explicitly indicate that descendant tables are included\&.
 120 .sp
 121 The command
 122 LOCK TABLE a, b;
 123 is equivalent to
 124 LOCK TABLE a; LOCK TABLE b;\&. The tables are locked one\-by\-one in the order specified in the
 125 \fBLOCK TABLE\fR
 126 command\&.
 127 .RE
 128 .PP
 129 \fIlockmode\fR
 130 .RS 4
 131 The lock mode specifies which locks this lock conflicts with\&. Lock modes are described in
 132 Section\ \&13.3\&.
 133 .sp
 134 If no lock mode is specified, then
 135 ACCESS EXCLUSIVE, the most restrictive mode, is used\&.
 136 .RE
 137 .PP
 138 NOWAIT
 139 .RS 4
 140 Specifies that
 141 \fBLOCK TABLE\fR
 142 should not wait for any conflicting locks to be released: if the specified lock(s) cannot be acquired immediately without waiting, the transaction is aborted\&.
 143 .RE
 144 .SH "NOTES"
 145 .PP
 146 To lock a table, the user must have the right privilege for the specified
 147 \fIlockmode\fR\&. If the user has
 148 MAINTAIN,
 149 UPDATE,
 150 DELETE, or
 151 TRUNCATE
 152 privileges on the table, any
 153 \fIlockmode\fR
 154 is permitted\&. If the user has
 155 INSERT
 156 privileges on the table,
 157 ROW EXCLUSIVE MODE
 158 (or a less\-conflicting mode as described in
 159 Section\ \&13.3) is permitted\&. If a user has
 160 SELECT
 161 privileges on the table,
 162 ACCESS SHARE MODE
 163 is permitted\&.
 164 .PP
 165 The user performing the lock on the view must have the corresponding privilege on the view\&. In addition, by default, the view\*(Aqs owner must have the relevant privileges on the underlying base relations, whereas the user performing the lock does not need any permissions on the underlying base relations\&. However, if the view has
 166 security_invoker
 167 set to
 168 true
 169 (see
 170 \fBCREATE VIEW\fR), the user performing the lock, rather than the view owner, must have the relevant privileges on the underlying base relations\&.
 171 .PP
 172 \fBLOCK TABLE\fR
 173 is useless outside a transaction block: the lock would remain held only to the completion of the statement\&. Therefore
 174 PostgreSQL
 175 reports an error if
 176 \fBLOCK\fR
 177 is used outside a transaction block\&. Use
 178 \fBBEGIN\fR
 179 and
 180 \fBCOMMIT\fR
 181 (or
 182 \fBROLLBACK\fR) to define a transaction block\&.
 183 .PP
 184 \fBLOCK TABLE\fR
 185 only deals with table\-level locks, and so the mode names involving
 186 ROW
 187 are all misnomers\&. These mode names should generally be read as indicating the intention of the user to acquire row\-level locks within the locked table\&. Also,
 188 ROW EXCLUSIVE
 189 mode is a shareable table lock\&. Keep in mind that all the lock modes have identical semantics so far as
 190 \fBLOCK TABLE\fR
 191 is concerned, differing only in the rules about which modes conflict with which\&. For information on how to acquire an actual row\-level lock, see
 192 Section\ \&13.3.2
 193 and
 194 The Locking Clause
 195 in the
 196 \fBSELECT\fR(7)
 197 documentation\&.
 198 .SH "EXAMPLES"
 199 .PP
 200 Obtain a
 201 SHARE
 202 lock on a primary key table when going to perform inserts into a foreign key table:
 203 .sp
 204 .if n \{\
 205 .RS 4
 206 .\}
 207 .nf
 208 BEGIN WORK;
 209 LOCK TABLE films IN SHARE MODE;
 210 SELECT id FROM films
 211     WHERE name = \*(AqStar Wars: Episode I \- The Phantom Menace\*(Aq;
 212 \-\- Do ROLLBACK if record was not returned
 213 INSERT INTO films_user_comments VALUES
 214     (_id_, \*(AqGREAT! I was waiting for it for so long!\*(Aq);
 215 COMMIT WORK;
 216 .fi
 217 .if n \{\
 218 .RE
 219 .\}
 220 .PP
 221 Take a
 222 SHARE ROW EXCLUSIVE
 223 lock on a primary key table when going to perform a delete operation:
 224 .sp
 225 .if n \{\
 226 .RS 4
 227 .\}
 228 .nf
 229 BEGIN WORK;
 230 LOCK TABLE films IN SHARE ROW EXCLUSIVE MODE;
 231 DELETE FROM films_user_comments WHERE id IN
 232     (SELECT id FROM films WHERE rating < 5);
 233 DELETE FROM films WHERE rating < 5;
 234 COMMIT WORK;
 235 .fi
 236 .if n \{\
 237 .RE
 238 .\}
 239 .SH "COMPATIBILITY"
 240 .PP
 241 There is no
 242 \fBLOCK TABLE\fR
 243 in the SQL standard, which instead uses
 244 \fBSET TRANSACTION\fR
 245 to specify concurrency levels on transactions\&.
 246 PostgreSQL
 247 supports that too; see
 248 SET TRANSACTION (\fBSET_TRANSACTION\fR(7))
 249 for details\&.
 250 .PP
 251 Except for
 252 ACCESS SHARE,
 253 ACCESS EXCLUSIVE, and
 254 SHARE UPDATE EXCLUSIVE
 255 lock modes, the
 256 PostgreSQL
 257 lock modes and the
 258 \fBLOCK TABLE\fR
 259 syntax are compatible with those present in
 260 Oracle\&.