<!-- doc/src/sgml/lo.sgml -->

<sect1 id="lo" xreflabel="lo">
 <title>lo &mdash; manage large objects</title>

 <indexterm zone="lo">
  <primary>lo</primary>
 </indexterm>

 <para>
  The <filename>lo</filename> module provides support for managing Large Objects
  (also called LOs or BLOBs).  This includes a data type <type>lo</type>
  and a trigger <function>lo_manage</function>.
 </para>

 <para>
  This module is considered <quote>trusted</quote>, that is, it can be
  installed by non-superusers who have <literal>CREATE</literal> privilege
  on the current database.
 </para>

 <sect2 id="lo-rationale">
  <title>Rationale</title>

  <para>
   One of the problems with the JDBC driver (and this affects the ODBC driver
   also), is that the specification assumes that references to BLOBs (Binary
   Large OBjects) are stored within a table, and if that entry is changed, the
   associated BLOB is deleted from the database.
  </para>

  <para>
   As <productname>PostgreSQL</productname> stands, this doesn't occur.  Large objects
   are treated as objects in their own right; a table entry can reference a
   large object by OID, but there can be multiple table entries referencing
   the same large object OID, so the system doesn't delete the large object
   just because you change or remove one such entry.
  </para>

  <para>
   Now this is fine for <productname>PostgreSQL</productname>-specific applications, but
   standard code using JDBC or ODBC won't delete the objects, resulting in
   orphan objects &mdash; objects that are not referenced by anything, and
   simply occupy disk space.
  </para>

  <para>
   The <filename>lo</filename> module allows fixing this by attaching a trigger
   to tables that contain LO reference columns.  The trigger essentially just
   does a <function>lo_unlink</function> whenever you delete or modify a value
   referencing a large object.  When you use this trigger, you are assuming
   that there is only one database reference to any large object that is
   referenced in a trigger-controlled column!
  </para>

  <para>
   The module also provides a data type <type>lo</type>, which is really just
   a <glossterm linkend="glossary-domain">domain</glossterm> over
   the <type>oid</type> type.  This is useful for differentiating
   database columns that hold large object references from those that are
   OIDs of other things.  You don't have