<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>1998-09-01</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>
       SHARE MODE
      </term>
      <listitem>
       <para>
       </para>
      </listitem>
     </varlistentry>

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

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

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

     <varlistentry>
      <term>
       ACCESS SHARE MODE
      </term>
      <listitem>
       <para>
       </para>
      </listitem>
     </varlistentry>

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

     <varlistentry>
      <term>
       SHARE ROW EXCLUSIVE MODE
      </term>
      <listitem>
       <para>
       </para>
      </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>
   By default, <command>LOCK</command> locks in exclusive mode a table inside
   a transaction. Various options allow shared access, or row-level locking
   control.  The classic use for this is
   the case where you want to select some data, then
   update it inside a transaction.
   If you don't explicit lock a table using LOCK statement, it will be
   implicit locked only at the first
   <command>UPDATE</command>, <command>INSERT</command>,
   or <command>DELETE</command> operation.
   If you don't exclusive lock the table before the select, some
   other user may also read the selected data, and try and do
   their own update, causing a deadlock while you both wait
   for the other to release the select-induced shared lock so
   you can get an exclusive lock to do the update.
  </para>
  <para>
   Another example of deadlock is where one user locks one
   table, and another user locks a second table. While both
   keep their existing locks, the first user tries to lock
   the second user's table, and the second user tries to lock
   the first user's table. Both users deadlock waiting for
   the tables to become available. The only solution to this
   is for both users to lock tables in the same order, so
   user's lock acquisitions and requests to not form a deadlock.
  </para>
  <note>
   <para>
    <productname>Postgres</productname> does detect deadlocks and will
    rollback transactions to resolve the deadlock. Usually, at least one
    of the deadlocked transactions will complete successfully.
   </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>
    <command>LOCK</command> works only inside transactions.
    
    <note>
     <title>Bug</title>
     <para>
      If the locked table is dropped then it will be automatically
      unlocked even if a transaction is still in progress.
     </para>
    </note>
   </para>
  </refsect2>
 </refsect1>
  
 <refsect1 id="R1-SQL-LOCK-2">
  <title>
   Usage
  </title>
  <para>
  </para>
  <programlisting>
    --Explicit locking to prevent deadlock:
    --
    BEGIN WORK;
    LOCK films;
    SELECT * FROM films;
    UPDATE films SET len = INTERVAL '100 minute'
      WHERE len = INTERVAL '117 minute';
    COMMIT WORK;
  </programlisting>
	
 </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:
-->
