doc/src/sgml/lo.sgml

   1
   2 <sect1 id="lo">
   3  <title>lo</title>
   4
   5  <indexterm zone="lo">
   6   <primary>lo</primary>
   7  </indexterm>
   8
   9  <para>
  10   PostgreSQL type extension for managing Large Objects
  11  </para>
  12
  13  <sect2>
  14   <title>Overview</title>
  15   <para>
  16    One of the problems with the JDBC driver (and this affects the ODBC driver
  17    also), is that the specification assumes that references to BLOBS (Binary
  18    Large OBjectS) are stored within a table, and if that entry is changed, the
  19    associated BLOB is deleted from the database.
  20   </para>
  21   <para>
  22    As PostgreSQL stands, this doesn't occur.  Large objects are treated as
  23    objects in their own right; a table entry can reference a large object by
  24    OID, but there can be multiple table entries referencing the same large
  25    object OID, so the system doesn't delete the large object just because you
  26    change or remove one such entry.
  27   </para>
  28   <para>
  29    Now this is fine for new PostgreSQL-specific applications, but existing ones
  30    using JDBC or ODBC won't delete the objects, resulting in orphaning - objects
  31    that are not referenced by anything, and simply occupy disk space.
  32   </para>
  33  </sect2>
  34
  35  <sect2>
  36   <title>The Fix</title>
  37   <para>
  38    I've fixed this by creating a new data type 'lo', some support functions, and
  39    a Trigger which handles the orphaning problem.  The trigger essentially just
  40    does a 'lo_unlink' whenever you delete or modify a value referencing a large
  41    object.  When you use this trigger, you are assuming that there is only one
  42    database reference to any large object that is referenced in a
  43    trigger-controlled column!
  44   </para>
  45   <para>
  46    The 'lo' type was created because we needed to differentiate between plain
  47    OIDs and Large Objects. Currently the JDBC driver handles this dilemma easily,
  48    but (after talking to Byron), the ODBC driver needed a unique type. They had
  49    created an 'lo' type, but not the solution to orphaning.
  50   </para>
  51   <para>
  52    You don't actually have to use the 'lo' type to use the trigger, but it may be
  53    convenient to use it to keep track of which columns in your database represent
  54    large objects that you are managing with the trigger.
  55   </para>
  56  </sect2>
  57
  58  <sect2>
  59   <title>How to Use</title>
  60   <para>
  61    The easiest way is by an example:
  62   </para>
  63   <programlisting>
  64    CREATE TABLE image (title TEXT, raster lo);
  65    CREATE TRIGGER t_raster BEFORE UPDATE OR DELETE ON image
  66      FOR EACH ROW EXECUTE PROCEDURE lo_manage(raster);
  67   </programlisting>
  68   <para>
  69    Create a trigger for each column that contains a lo type, and give the column
  70    name as the trigger procedure argument.  You can have more than one trigger on
  71    a table if you need multiple lo columns in the same table, but don't forget to
  72    give a different name to each trigger.
  73   </para>
  74  </sect2>
  75
  76  <sect2>
  77   <title>Issues</title>
  78
  79   <itemizedlist>
  80    <listitem>
  81     <para>
  82      Dropping a table will still orphan any objects it contains, as the trigger
  83      is not executed.
  84     </para>
  85     <para>
  86      Avoid this by preceding the 'drop table' with 'delete from {table}'.
  87     </para>
  88     <para>
  89      If you already have, or suspect you have, orphaned large objects, see
  90      the contrib/vacuumlo module to help you clean them up.  It's a good idea
  91      to run contrib/vacuumlo occasionally as a back-stop to the lo_manage
  92      trigger.
  93     </para>
  94    </listitem>
  95    <listitem>
  96     <para>
  97      Some frontends may create their own tables, and will not create the
  98      associated trigger(s). Also, users may not remember (or know) to create
  99      the triggers.
 100     </para>
 101    </listitem>
 102   </itemizedlist>
 103
 104   <para>
 105    As the ODBC driver needs a permanent lo type (& JDBC could be optimised to
 106    use it if it's Oid is fixed), and as the above issues can only be fixed by
 107    some internal changes, I feel it should become a permanent built-in type.
 108   </para>
 109  </sect2>
 110
 111  <sect2>
 112   <title>Author</title>
 113   <para>
 114    Peter Mount <email>peter@retep.org.uk</email> June 13 1998
 115   </para>
 116  </sect2>
 117 </sect1>
 118