1 files changed, 259 insertions, 0 deletions
diff --git a/doc/src/sgml/man7/LOCK.7 b/doc/src/sgml/man7/LOCK.7
new file mode 100644
index 0000000..3e1dbfb
--- /dev/null
+++ b/doc/src/sgml/man7/LOCK.7
@@ -0,0 +1,259 @@
+'\" t
+.\"     Title: LOCK
+.\"    Author: The PostgreSQL Global Development Group
+.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
+.\"      Date: 2024
+.\"    Manual: PostgreSQL 16.2 Documentation
+.\"    Source: PostgreSQL 16.2
+.\"  Language: English
+.\"
+.TH "LOCK" "7" "2024" "PostgreSQL 16.2" "PostgreSQL 16.2 Documentation"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+LOCK \- lock a table
+.SH "SYNOPSIS"
+.sp
+.nf
+LOCK [ TABLE ] [ ONLY ] \fIname\fR [ * ] [, \&.\&.\&.] [ IN \fIlockmode\fR MODE ] [ NOWAIT ]
+
+where \fIlockmode\fR is one of:
+
+    ACCESS SHARE | ROW SHARE | ROW EXCLUSIVE | SHARE UPDATE EXCLUSIVE
+    | SHARE | SHARE ROW EXCLUSIVE | EXCLUSIVE | ACCESS EXCLUSIVE
+.fi
+.SH "DESCRIPTION"
+.PP
+\fBLOCK TABLE\fR
+obtains a table\-level lock, waiting if necessary for any conflicting locks to be released\&. If
+NOWAIT
+is specified,
+\fBLOCK TABLE\fR
+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
+\fBUNLOCK TABLE\fR
+command; locks are always released at transaction end\&.)
+.PP
+When a view is locked, all relations appearing in the view definition query are also locked recursively with the same lock mode\&.
+.PP
+When acquiring locks automatically for commands that reference tables,
+PostgreSQL
+always uses the least restrictive lock mode possible\&.
+\fBLOCK TABLE\fR
+provides for cases when you might need more restrictive locking\&. For example, suppose an application runs a transaction at the
+READ COMMITTED
+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
+SHARE
+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
+SHARE
+lock mode conflicts with the
+ROW EXCLUSIVE
+lock acquired by writers, and your
+\fBLOCK TABLE \fR\fB\fIname\fR\fR\fB IN SHARE MODE\fR
+statement will wait until any concurrent holders of
+ROW EXCLUSIVE
+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\&.
+.PP
+To achieve a similar effect when running a transaction at the
+REPEATABLE READ
+or
+SERIALIZABLE
+isolation level, you have to execute the
+\fBLOCK TABLE\fR
+statement before executing any
+\fBSELECT\fR
+or data modification statement\&. A
+REPEATABLE READ
+or
+SERIALIZABLE
+transaction\*(Aqs view of data will be frozen when its first
+\fBSELECT\fR
+or data modification statement begins\&. A
+\fBLOCK TABLE\fR
+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\&.
+.PP
+If a transaction of this sort is going to change the data in the table, then it should use
+SHARE ROW EXCLUSIVE
+lock mode instead of
+SHARE
+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
+SHARE
+mode, and then be unable to also acquire
+ROW EXCLUSIVE
+mode to actually perform their updates\&. (Note that a transaction\*(Aqs own locks never conflict, so a transaction can acquire
+ROW EXCLUSIVE
+mode when it holds
+SHARE
+mode \(em but not if anyone else holds
+SHARE
+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\&.
+.PP
+More information about the lock modes and locking strategies can be found in
+Section\ \&13.3\&.
+.SH "PARAMETERS"
+.PP
+\fIname\fR
+.RS 4
+The name (optionally schema\-qualified) of an existing table to lock\&. If
+ONLY
+is specified before the table name, only that table is locked\&. If
+ONLY
+is not specified, the table and all its descendant tables (if any) are locked\&. Optionally,
+*
+can be specified after the table name to explicitly indicate that descendant tables are included\&.
+.sp
+The command
+LOCK TABLE a, b;
+is equivalent to
+LOCK TABLE a; LOCK TABLE b;\&. The tables are locked one\-by\-one in the order specified in the
+\fBLOCK TABLE\fR
+command\&.
+.RE
+.PP
+\fIlockmode\fR
+.RS 4
+The lock mode specifies which locks this lock conflicts with\&. Lock modes are described in
+Section\ \&13.3\&.
+.sp
+If no lock mode is specified, then
+ACCESS EXCLUSIVE, the most restrictive mode, is used\&.
+.RE
+.PP
+NOWAIT
+.RS 4
+Specifies that
+\fBLOCK TABLE\fR
+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\&.
+.RE
+.SH "NOTES"
+.PP
+To lock a table, the user must have the right privilege for the specified
+\fIlockmode\fR, or be the table\*(Aqs owner or a superuser\&. If the user has
+UPDATE,
+DELETE, or
+TRUNCATE
+privileges on the table, any
+\fIlockmode\fR
+is permitted\&. If the user has
+INSERT
+privileges on the table,
+ROW EXCLUSIVE MODE
+(or a less\-conflicting mode as described in
+Section\ \&13.3) is permitted\&. If a user has
+SELECT
+privileges on the table,
+ACCESS SHARE MODE
+is permitted\&.
+.PP
+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
+security_invoker
+set to
+true
+(see
+\fBCREATE VIEW\fR), the user performing the lock, rather than the view owner, must have the relevant privileges on the underlying base relations\&.
+.PP
+\fBLOCK TABLE\fR
+is useless outside a transaction block: the lock would remain held only to the completion of the statement\&. Therefore
+PostgreSQL
+reports an error if
+\fBLOCK\fR
+is used outside a transaction block\&. Use
+\fBBEGIN\fR
+and
+\fBCOMMIT\fR
+(or
+\fBROLLBACK\fR) to define a transaction block\&.
+.PP
+\fBLOCK TABLE\fR
+only deals with table\-level locks, and so the mode names involving
+ROW
+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,
+ROW EXCLUSIVE
+mode is a shareable table lock\&. Keep in mind that all the lock modes have identical semantics so far as
+\fBLOCK TABLE\fR
+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
+Section\ \&13.3.2
+and
+The Locking Clause
+in the
+\fBSELECT\fR(7)
+documentation\&.
+.SH "EXAMPLES"
+.PP
+Obtain a
+SHARE
+lock on a primary key table when going to perform inserts into a foreign key table:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+BEGIN WORK;
+LOCK TABLE films IN SHARE MODE;
+SELECT id FROM films
+    WHERE name = \*(AqStar Wars: Episode I \- The Phantom Menace\*(Aq;
+\-\- Do ROLLBACK if record was not returned
+INSERT INTO films_user_comments VALUES
+    (_id_, \*(AqGREAT! I was waiting for it for so long!\*(Aq);
+COMMIT WORK;
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+Take a
+SHARE ROW EXCLUSIVE
+lock on a primary key table when going to perform a delete operation:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+BEGIN WORK;
+LOCK TABLE films IN SHARE ROW EXCLUSIVE MODE;
+DELETE FROM films_user_comments WHERE id IN
+    (SELECT id FROM films WHERE rating < 5);
+DELETE FROM films WHERE rating < 5;
+COMMIT WORK;
+.fi
+.if n \{\
+.RE
+.\}
+.SH "COMPATIBILITY"
+.PP
+There is no
+\fBLOCK TABLE\fR
+in the SQL standard, which instead uses
+\fBSET TRANSACTION\fR
+to specify concurrency levels on transactions\&.
+PostgreSQL
+supports that too; see
+SET TRANSACTION (\fBSET_TRANSACTION\fR(7))
+for details\&.
+.PP
+Except for
+ACCESS SHARE,
+ACCESS EXCLUSIVE, and
+SHARE UPDATE EXCLUSIVE
+lock modes, the
+PostgreSQL
+lock modes and the
+\fBLOCK TABLE\fR
+syntax are compatible with those present in
+Oracle\&.