<refentry id="SQL-LOCK">
 <refmeta>
  <refentrytitle>
   LOCK
  </refentrytitle>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>
 <refnamediv>
  <refname>
   LOCK
  </refname>
  <refpurpose>
   Explicit lock of a table inside a transaction
  </refpurpose>
 </refnamediv>
 <refsynopsisdiv>
  <refsynopsisdivinfo>
   <date>1998-09-24</date>
  </refsynopsisdivinfo>
  <synopsis>
LOCK [ TABLE ] <replaceable class="PARAMETER">table</replaceable>
LOCK [ TABLE ] <replaceable class="PARAMETER">table</replaceable> IN [ ROW | ACCESS ] { SHARE | EXCLUSIVE } MODE
LOCK [ TABLE ] <replaceable class="PARAMETER">table</replaceable> IN SHARE ROW EXCLUSIVE MODE
  </synopsis>

  <refsect2 id="R2-SQL-LOCK-1">
   <refsect2info>
    <date>1999-06-09</date>
   </refsect2info>
   <title>
    Inputs
   </title>
   <para>

    <variablelist>
     <varlistentry>
      <term>
       <replaceable class="PARAMETER">table</replaceable>
      </term>
      <listitem>
       <para>
	The name of an existing table to lock.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>
       ACCESS SHARE MODE
      </term>
      <listitem>
       <note>
       <para>
	This lock mode is acquired automatically over tables being queried.
	<productname>Postgres</productname> releases automatically acquired
	ACCESS SHARE locks after statement is done.
	   </para>
	   </note>

	   <para>
	This is the less restrictive lock mode which conflicts with 
	ACCESS EXCLUSIVE mode only. It's intended to protect table being
	queried from concurrent <command>ALTER TABLE</command>, 
	<command>DROP TABLE</command> and <command>VACUUM</command> 
	statements over the same table.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>
       ROW SHARE MODE
      </term>
      <listitem>
       <note>
       <para>
	 Automatically acquired by <command>SELECT FOR UPDATE</command> statement.
	   </para>
       </note>

	   <para>
	 Conflicts with EXCLUSIVE and ACCESS EXCLUSIVE lock modes.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>
       ROW EXCLUSIVE MODE
      </term>
      <listitem>
       <note>
       <para>
	 Automatically acquired by <command>UPDATE</command>, 
	 <command>DELETE</command>, <command>INSERT</command> statements.
	   </para>
	   </note>

	   <para>
	 Conflicts with SHARE, SHARE ROW EXCLUSIVE, EXCLUSIVE and
	 ACCESS EXCLUSIVE modes. Generally means that a transaction
	 updated/inserted some tuples in a table.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>
       SHARE MODE
      </term>
      <listitem>
       <note>
       <para>
	 Automatically acquired by <command>CREATE INDEX</command> statement.
       </para>
       </note>

	   <para>
	 Conflicts with ROW EXCLUSIVE, SHARE ROW EXCLUSIVE, EXCLUSIVE and
	 ACCESS EXCLUSIVE modes. This mode protects a table against
	 concurrent updates.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>
       SHARE ROW EXCLUSIVE MODE
      </term>
      <listitem>

	   <para>
	Conflicts with ROW EXCLUSIVE, SHARE, SHARE ROW EXCLUSIVE,
	EXCLUSIVE and ACCESS EXCLUSIVE modes. This mode is more
	restrictive than SHARE mode because of only one transaction
	at time can hold this lock.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>
       EXCLUSIVE MODE
      </term>
      <listitem>

	   <para>
	Conflicts with ROW SHARE, ROW EXCLUSIVE, SHARE, SHARE ROW EXCLUSIVE,
	EXCLUSIVE and ACCESS EXCLUSIVE modes. This mode is yet more
	restrictive than SHARE ROW EXCLUSIVE one - it blocks concurrent
	SELECT FOR UPDATE queries.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>
       ACCESS EXCLUSIVE MODE
      </term>
      <listitem>
       <note>
       <para>
	Automatically acquired by <command>ALTER TABLE</command>, 
	<command>DROP TABLE</command>, <command>VACUUM</command> statements.
	   </para>
	   </note>

	   <para>
	This is the most restrictive lock mode which conflicts with all other
	lock modes and protects locked table from any concurrent operations.
	   </para>
	   
	   <note>
	   <para>
	This lock mode is also acquired by first form of
	<command>LOCK TABLE</command> (i.e. without explicit
	lock mode option).
	   </para>
	   </note>
      </listitem>
     </varlistentry>

    </variablelist>
   </para>
  </refsect2>

  <refsect2 id="R2-SQL-LOCK-2">
   <refsect2info>
    <date>1998-09-24</date>
   </refsect2info>
   <title>
    Outputs
   </title>
   <para>
    
    <variablelist>
     <varlistentry>
      <term>
       ERROR <replaceable class="PARAMETER">table</replaceable>: Table does not exist.
      </term>
      <listitem>
       <para>
	Message returned if <replaceable class="PARAMETER">table</replaceable>
	does not exist.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </refsect2>
 </refsynopsisdiv>

 <refsect1 id="R1-SQL-LOCK-1">
  <refsect1info>
   <date>1998-09-24</date>
  </refsect1info>
  <title>
   Description
  </title>
  <para>
   <productname>Postgres</productname> always uses less restrictive
   lock modes ever possible. <command>LOCK TABLE</command> statement 
   provided for cases when you might need in more restrictive locking.
  </para>

  <para>
   For example, application run transaction at READ COMMITTED isolation
   level and need to ensure existance data in a table for duration of
   transaction. To achieve this you could use SHARE lock mode over
   table before querying. This will protect data from concurrent changes 
   and provide your further read operations over table with data in their 
   real current state, because of SHARE lock mode conflicts with ROW EXCLUSIVE 
   one, acquired by writers, and your LOCK TABLE table IN SHARE MODE statement 
   will wait untill concurrent write operations (if any) commit/rollback.
   (Note that to read data in their real current state running transaction
   at SERIALIZABLE isolation level you have to execute LOCK TABLE
   statement before execution any DML statement, when transaction defines
   what concurrent changes will be visible to herself).
  </para>
  
  <para>
   If, in addition to requirements above, transaction is going to
   change data in a table then SHARE ROW EXCLUSIVE lock mode should
   be acquired to prevent deadlock conditions when two concurrent
   transactions would lock table in SHARE mode and than would
   try to change data in this table, both (implicitly) acquiring 
   ROW EXCLUSIVE lock mode that conflicts with concurrent SHARE lock.
  </para>
  
  <para>
   Following deadlock issue (when two transaction wait one another)
   touched above, you should follow two general rules to prevent 
   deadlock conditions:
  </para>
  
  <listitem>
   <para>
    Transactions have to acquire locks on the same objects in the same order.
   </para>
   
   <para>
    For example, if one application updates row R1 and than updates 
    row R2 (in the same transaction) then second application shouldn't 
    update row R2 if it's going update row R1 later (in single transaction). 
    Instead, it should update R1 and R2 rows in the same order as first 
    application.
   </para>
  </listitem>

  <listitem>
   <para>
    Transactions should acquire two conflicting lock modes only if
    one of them is self-conflicting (i.e. may be held by one
    transaction at time only) and should acquire most restrictive
    mode first.
   </para>
   
   <para>
    Example for this rule is described above when told about using
    SHARE ROW EXCLUSIVE mode instead of SHARE one.
   </para>
  </listitem>

  <note>
   <para>
    <productname>Postgres</productname> does detect deadlocks and will
    rollback one of waiting transactions to resolve the deadlock. 
   </para>
  </note>

  <refsect2 id="R2-SQL-LOCK-3">
   <refsect2info>
    <date>1998-09-24</date>
   </refsect2info>
   <title>
    Notes
   </title>
   <para>
    <command>LOCK</command> is a <productname>Postgres</productname>
    language extension.
   </para>
   <para>
    Except for ACCESS SHARE/EXCLUSIVE lock modes, all other
    <productname>Postgres</productname> lock modes and 
    <command>LOCK TABLE</command> syntax are compatible with
    <productname>Oracle</productname> ones.
   <para>
    <command>LOCK</command> works only inside transactions.
   </para>
  </refsect2>
 </refsect1>
  
 <refsect1 id="R1-SQL-LOCK-2">
  <title>
   Usage
  </title>

  <para>
  <programlisting>
    --
    -- SHARE lock primary key table when going to perform
    -- insert into foreign key table.
    --
    BEGIN WORK;
    LOCK TABLE films IN SHARE MODE;
    SELECT id FROM films 
      WHERE name = 'Star Wars: Episode I - The Phantom Menace';
    --
    -- Do ROLLBACK if record was not returned
    --
    INSERT INTO films_user_comments VALUES 
      (_id_, 'GREAT! I was waiting it so long!');
    COMMIT WORK;
  </programlisting>
  </para>

  <para>
  <programlisting>
    --
    -- SHARE ROW EXCLUSIVE lock primary key table when going to perform
    -- delete operation.
    --
    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;
  </programlisting>
  </para>
	
 </refsect1>

 <refsect1 id="R1-SQL-LOCK-3">
  <title>
   Compatibility
  </title>
	  
  <refsect2 id="R2-SQL-LOCK-4">
   <refsect2info>
    <date>1998-09-24</date>
   </refsect2info>
   <title>
    SQL92
   </title>
   <para>
    There is no <command>LOCK TABLE</command> in <acronym>SQL92</acronym>,
    which instead uses <command>SET TRANSACTION</command> to specify
    concurrency level on transactions.  We support that too.
   </para>
  </refsect2>
 </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
sgml-local-ecat-files:nil
End:
-->
