doc/src/sgml/lo.sgml

   1 <!-- $PostgreSQL$ -->
   2
   3 <sect1 id="lo">
   4  <title>lo</title>
   5
   6  <indexterm zone="lo">
   7   <primary>lo</primary>
   8  </indexterm>
   9
  10  <para>
  11   The <filename>lo</> module provides support for managing Large Objects
  12   (also called LOs or BLOBs).  This includes a data type <type>lo</>
  13   and a trigger <function>lo_manage</>.
  14  </para>
  15
  16  <sect2>
  17   <title>Rationale</title>
  18
  19   <para>
  20    One of the problems with the JDBC driver (and this affects the ODBC driver
  21    also), is that the specification assumes that references to BLOBs (Binary
  22    Large OBjects) are stored within a table, and if that entry is changed, the
  23    associated BLOB is deleted from the database.
  24   </para>
  25
  26   <para>
  27    As <productname>PostgreSQL</> stands, this doesn't occur.  Large objects
  28    are treated as objects in their own right; a table entry can reference a
  29    large object by OID, but there can be multiple table entries referencing
  30    the same large object OID, so the system doesn't delete the large object
  31    just because you change or remove one such entry.
  32   </para>
  33
  34   <para>
  35    Now this is fine for <productname>PostgreSQL</>-specific applications, but
  36    standard code using JDBC or ODBC won't delete the objects, resulting in
  37    orphan objects &mdash; objects that are not referenced by anything, and
  38    simply occupy disk space.
  39   </para>
  40
  41   <para>
  42    The <filename>lo</> module allows fixing this by attaching a trigger
  43    to tables that contain LO reference columns.  The trigger essentially just
  44    does a <function>lo_unlink</> whenever you delete or modify a value
  45    referencing a large object.  When you use this trigger, you are assuming
  46    that there is only one database reference to any large object that is
  47    referenced in a trigger-controlled column!
  48   </para>
  49
  50   <para>
  51    The module also provides a data type <type>lo</>, which is really just
  52    a domain of the <type>oid</> type.  This is useful for differentiating
  53    database columns that hold large object references from those that are
  54    OIDs of other things.  You don't have to use the <type>lo</> type to
  55    use the trigger, but it may be convenient to use it to keep track of which
  56    columns in your database represent large objects that you are managing with
  57    the trigger.  It is also rumored that the ODBC driver gets confused if you
  58    don't use <type>lo</> for BLOB columns.
  59   </para>
  60  </sect2>
  61
  62  <sect2>
  63   <title>How to Use It</title>
  64
  65   <para>
  66    Here's a simple example of usage:
  67   </para>
  68
  69   <programlisting>
  70    CREATE TABLE image (title TEXT, raster lo);
  71
  72    CREATE TRIGGER t_raster BEFORE UPDATE OR DELETE ON image
  73      FOR EACH ROW EXECUTE PROCEDURE lo_manage(raster);
  74   </programlisting>
  75
  76   <para>
  77    For each column that will contain unique references to large objects,
  78    create a <literal>BEFORE UPDATE OR DELETE</> trigger, and give the column
  79    name as the sole trigger argument.  If you need multiple <type>lo</>
  80    columns in the same table, create a separate trigger for each one,
  81    remembering to give a different name to each trigger on the same table.
  82   </para>
  83  </sect2>
  84
  85  <sect2>
  86   <title>Limitations</title>
  87
  88   <itemizedlist>
  89    <listitem>
  90     <para>
  91      Dropping a table will still orphan any objects it contains, as the trigger
  92      is not executed.  You can avoid this by preceding the <command>DROP
  93      TABLE</> with <command>DELETE FROM <replaceable>table</></command>.
  94     </para>
  95
  96     <para>
  97      <command>TRUNCATE</> has the same hazard.
  98     </para>
  99
 100     <para>
 101      If you already have, or suspect you have, orphaned large objects, see the
 102      <filename>contrib/vacuumlo</> module (<xref linkend="vacuumlo">) to help
 103      you clean them up.  It's a good idea to run <application>vacuumlo</>
 104      occasionally as a back-stop to the <function>lo_manage</> trigger.
 105     </para>
 106    </listitem>
 107
 108    <listitem>
 109     <para>
 110      Some frontends may create their own tables, and will not create the
 111      associated trigger(s).  Also, users may not remember (or know) to create
 112      the triggers.
 113     </para>
 114    </listitem>
 115   </itemizedlist>
 116  </sect2>
 117
 118  <sect2>
 119   <title>Author</title>
 120
 121   <para>
 122    Peter Mount <email>peter@retep.org.uk</email>
 123   </para>
 124  </sect2>
 125
 126 </sect1>