granicus.if.org Git - postgresql/blob - doc/src/sgml/pgrowlocks.sgml

   1
   2 <sect1 id="pgrowlocks">
   3  <title>pgrowlocks</title>
   4
   5  <indexterm zone="pgrowlocks">
   6   <primary>pgrowlocks</primary>
   7  </indexterm>
   8
   9  <para>
  10   The <literal>pgrowlocks</literal> module provides a function to show row
  11   locking information for a specified table.
  12  </para>
  13
  14  <sect2>
  15   <title>Overview</title>
  16   <programlisting>
  17 pgrowlocks(text) RETURNS pgrowlocks_type
  18   </programlisting>
  19   <para>
  20    The parameter is a name of table. And <literal>pgrowlocks_type</literal> is
  21    defined as:
  22   </para>
  23   <programlisting>
  24 CREATE TYPE pgrowlocks_type AS (
  25         locked_row TID,         -- row TID
  26         lock_type TEXT,         -- lock type
  27         locker XID,             -- locking XID
  28         multi bool,             -- multi XID?
  29         xids xid[],             -- multi XIDs
  30         pids INTEGER[]          -- locker's process id
  31 );
  32   </programlisting>
  33
  34   <table>
  35    <title>pgrowlocks_type</title>
  36    <tgroup cols="2">
  37     <tbody>
  38      <row>
  39       <entry>locked_row</entry>
  40       <entry>tuple ID(TID) of each locked rows</entry>
  41      </row>
  42      <row>
  43       <entry>lock_type</entry>
  44       <entry>"Shared" for shared lock, "Exclusive" for exclusive lock</entry>
  45      </row>
  46      <row>
  47       <entry>locker</entry>
  48       <entry>transaction ID of locker (Note 1)</entry>
  49      </row>
  50      <row>
  51       <entry>multi</entry>
  52       <entry>"t" if locker is a multi transaction, otherwise "f"</entry>
  53      </row>
  54      <row>
  55       <entry>xids</entry>
  56       <entry>XIDs of lockers (Note 2)</entry>
  57      </row>
  58      <row>
  59       <entry>pids</entry>
  60       <entry>process ids of locking backends</entry>
  61      </row>
  62     </tbody>
  63    </tgroup>
  64   </table>
  65   <para>
  66    Note1: If the locker is multi transaction, it represents the multi ID.
  67   </para>
  68   <para>
  69    Note2: If the locker is multi, multiple data are shown.
  70   </para>
  71
  72   <para>
  73    The calling sequence for <literal>pgrowlocks</literal> is as follows:
  74    <literal>pgrowlocks</literal> grabs AccessShareLock for the target table and
  75    reads each row one by one to get the row locking information. You should
  76    notice that:
  77   </para>
  78   <orderedlist>
  79    <listitem>
  80     <para>
  81     if the table is exclusive locked by someone else,
  82     <literal>pgrowlocks</literal> will be blocked.
  83     </para>
  84    </listitem>
  85    <listitem>
  86     <para>
  87      <literal>pgrowlocks</literal> may show incorrect information if there's a
  88      new lock or a lock is freeed while its execution.
  89     </para>
  90    </listitem>
  91   </orderedlist>
  92   <para>
  93    <literal>pgrowlocks</literal> does not show the contents of locked rows. If
  94    you want to take a look at the row contents at the same time, you could do
  95    something like this:
  96   </para>
  97   <programlisting>
  98 SELECT * FROM accounts AS a, pgrowlocks('accounts') AS p WHERE p.locked_ row = a.ctid;
  99   </programlisting>
 100  </sect2>
 101
 102  <sect2>
 103   <title>Example</title>
 104   <para>
 105    <literal>pgrowlocks</literal> returns the following columns:
 106   </para>
 107   <para>
 108    Here is a sample execution of pgrowlocks:
 109   </para>
 110   <programlisting>
 111 test=# SELECT * FROM pgrowlocks('t1');
 112  locked_row | lock_type | locker | multi |   xids    |     pids
 113 ------------+-----------+--------+-------+-----------+---------------
 114       (0,1) | Shared    |     19 | t     | {804,805} | {29066,29068}
 115       (0,2) | Shared    |     19 | t     | {804,805} | {29066,29068}
 116       (0,3) | Exclusive |    804 | f     | {804}     | {29066}
 117       (0,4) | Exclusive |    804 | f     | {804}     | {29066}
 118 (4 rows)
 119   </programlisting>
 120
 121  </sect2>
 122 </sect1>
 123