head	1.6;
access;
symbols
	REL9_0_0:1.3.16.3
	REL9_1_ALPHA1:1.6
	REL9_0_RC1:1.3.16.3
	REL9_0_BETA4:1.3.16.1
	REL9_0_STABLE:1.3.0.16
	REL9_0_BETA3:1.3
	REL9_0_BETA2:1.3
	REL8_3_11:1.3
	REL8_4_4:1.3
	REL9_0_BETA1:1.3
	REL9_0_ALPHA5_BRANCH:1.3.0.14
	REL9_0_ALPHA5:1.3
	REL8_3_10:1.3
	REL8_4_3:1.3
	REL9_0_ALPHA4:1.3
	REL9_0_ALPHA4_BRANCH:1.3.0.12
	REL8_5_ALPHA3:1.3
	REL8_5_ALPHA3_BRANCH:1.3.0.10
	REL8_3_9:1.3
	REL8_4_2:1.3
	REL8_5_ALPHA2:1.3
	REL8_5_ALPHA2_BRANCH:1.3.0.8
	REL8_3_8:1.3
	REL8_4_1:1.3
	REL8_5_ALPHA1:1.3
	REL8_5_ALPHA1_BRANCH:1.3.0.6
	REL8_4_STABLE:1.3.0.4
	REL8_4_0:1.3
	REL8_4_RC2:1.3
	REL8_4_RC1:1.3
	REL8_4_BETA2:1.3
	REL8_4_BETA1:1.3
	REL8_3_7:1.3
	REL8_3_6:1.3
	REL8_3_5:1.3
	REL8_3_4:1.3
	REL8_3_3:1.3
	REL8_3_2:1.3
	REL8_3_1:1.3
	REL8_3_STABLE:1.3.0.2
	REL8_3_0:1.3
	REL8_3_RC2:1.3
	REL8_3_RC1:1.3
	REL8_3_BETA4:1.1
	REL8_3_BETA3:1.1;
locks; strict;
comment	@# @;


1.6
date	2010.08.17.04.47.04;	author petere;	state Exp;
branches;
next	1.5;

1.5
date	2010.08.17.04.37.20;	author petere;	state Exp;
branches;
next	1.4;

1.4
date	2010.07.29.19.34.40;	author petere;	state Exp;
branches;
next	1.3;

1.3
date	2007.12.06.04.12.10;	author tgl;	state Exp;
branches
	1.3.16.1;
next	1.2;

1.2
date	2007.12.03.23.49.50;	author tgl;	state Exp;
branches;
next	1.1;

1.1
date	2007.11.10.23.30.46;	author momjian;	state Exp;
branches;
next	;

1.3.16.1
date	2010.07.29.19.34.36;	author petere;	state Exp;
branches;
next	1.3.16.2;

1.3.16.2
date	2010.08.17.04.37.17;	author petere;	state Exp;
branches;
next	1.3.16.3;

1.3.16.3
date	2010.08.17.04.47.03;	author petere;	state Exp;
branches;
next	;


desc
@@


1.6
log
@Revert: looks like Binary Large OBject[sic] wasn't a misspelling
@
text
@<!-- $PostgreSQL: pgsql/doc/src/sgml/lo.sgml,v 1.5 2010/08/17 04:37:20 petere Exp $ -->

<sect1 id="lo">
 <title>lo</title>

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

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

 <sect2>
  <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</> 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</>-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</> module allows fixing this by attaching a trigger
   to tables that contain LO reference columns.  The trigger essentially just
   does a <function>lo_unlink</> 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</>, which is really just
   a domain of the <type>oid</> 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 to use the <type>lo</> type to
   use the trigger, but it may be convenient to use it to keep track of which
   columns in your database represent large objects that you are managing with
   the trigger.  It is also rumored that the ODBC driver gets confused if you
   don't use <type>lo</> for BLOB columns.
  </para>
 </sect2>

 <sect2>
  <title>How to Use It</title>

  <para>
   Here's a simple example of usage:
  </para>

<programlisting>
CREATE TABLE image (title TEXT, raster lo);

CREATE TRIGGER t_raster BEFORE UPDATE OR DELETE ON image
    FOR EACH ROW EXECUTE PROCEDURE lo_manage(raster);
</programlisting>

  <para>
   For each column that will contain unique references to large objects,
   create a <literal>BEFORE UPDATE OR DELETE</> trigger, and give the column
   name as the sole trigger argument.  If you need multiple <type>lo</>
   columns in the same table, create a separate trigger for each one,
   remembering to give a different name to each trigger on the same table.
  </para>
 </sect2>

 <sect2>
  <title>Limitations</title>

  <itemizedlist>
   <listitem>
    <para>
     Dropping a table will still orphan any objects it contains, as the trigger
     is not executed.  You can avoid this by preceding the <command>DROP
     TABLE</> with <command>DELETE FROM <replaceable>table</></command>.
    </para>

    <para>
     <command>TRUNCATE</> has the same hazard.
    </para>

    <para>
     If you already have, or suspect you have, orphaned large objects, see the
     <filename>contrib/vacuumlo</> module (<xref linkend="vacuumlo">) to help
     you clean them up.  It's a good idea to run <application>vacuumlo</>
     occasionally as a back-stop to the <function>lo_manage</> trigger.
    </para>
   </listitem>

   <listitem>
    <para>
     Some frontends may create their own tables, and will not create the
     associated trigger(s).  Also, users may not remember (or know) to create
     the triggers.
    </para>
   </listitem>
  </itemizedlist>
 </sect2>

 <sect2>
  <title>Author</title>

  <para>
   Peter Mount <email>peter@@retep.org.uk</email>
  </para>
 </sect2>

</sect1>
@


1.5
log
@Spell and markup checking
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/lo.sgml,v 1.4 2010/07/29 19:34:40 petere Exp $ -->
d22 1
a22 1
   Large Objects) are stored within a table, and if that entry is changed, the
@


1.4
log
@Fix indentation of verbatim block elements

Block elements with verbatim formatting (literallayout, programlisting,
screen, synopsis) should be aligned at column 0 independent of the surrounding
SGML, because whitespace is significant, and indenting them creates erratic
whitespace in the output.  The CSS stylesheets already take care of indenting
the output.

Assorted markup improvements to go along with it.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/lo.sgml,v 1.3 2007/12/06 04:12:10 tgl Exp $ -->
d22 1
a22 1
   Large OBjects) are stored within a table, and if that entry is changed, the
@


1.3
log
@Make an editorial pass over the newly SGML-ified contrib documentation.
Fix lots of bad markup, bad English, bad explanations.

This commit covers only about half the contrib modules, but I grow weary...
@
text
@d1 1
a1 1
<!-- $PostgreSQL$ -->
d69 2
a70 2
  <programlisting>
   CREATE TABLE image (title TEXT, raster lo);
d72 3
a74 3
   CREATE TRIGGER t_raster BEFORE UPDATE OR DELETE ON image
     FOR EACH ROW EXECUTE PROCEDURE lo_manage(raster);
  </programlisting>
@


1.3.16.1
log
@Fix indentation of verbatim block elements

Block elements with verbatim formatting (literallayout, programlisting,
screen, synopsis) should be aligned at column 0 independent of the surrounding
SGML, because whitespace is significant, and indenting them creates erratic
whitespace in the output.  The CSS stylesheets already take care of indenting
the output.

Assorted markup improvements to go along with it.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/lo.sgml,v 1.3 2007/12/06 04:12:10 tgl Exp $ -->
d69 2
a70 2
<programlisting>
CREATE TABLE image (title TEXT, raster lo);
d72 3
a74 3
CREATE TRIGGER t_raster BEFORE UPDATE OR DELETE ON image
    FOR EACH ROW EXECUTE PROCEDURE lo_manage(raster);
</programlisting>
@


1.3.16.2
log
@Spell and markup checking
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/lo.sgml,v 1.3.16.1 2010/07/29 19:34:36 petere Exp $ -->
d22 1
a22 1
   Large Objects) are stored within a table, and if that entry is changed, the
@


1.3.16.3
log
@Revert: looks like Binary Large OBject[sic] wasn't a misspelling
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/lo.sgml,v 1.3.16.2 2010/08/17 04:37:17 petere Exp $ -->
d22 1
a22 1
   Large OBjects) are stored within a table, and if that entry is changed, the
@


1.2
log
@Entity-ify a passel of & < > characters.  Per gripe from Devrim.
@
text
@d1 1
d5 1
a5 1
 
d11 3
a13 1
  PostgreSQL type extension for managing Large Objects
d17 2
a18 1
  <title>Overview</title>
d21 2
a22 2
   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
d25 1
d27 5
a31 5
   As PostgreSQL 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.
d33 1
d35 4
a38 3
   Now this is fine for new PostgreSQL-specific applications, but existing ones
   using JDBC or ODBC won't delete the objects, resulting in orphaning - objects
   that are not referenced by anything, and simply occupy disk space.
a39 1
 </sect2>
a40 2
 <sect2>
  <title>The Fix</title>
d42 6
a47 12
   I've fixed this by creating a new data type 'lo', some support functions, and
   a Trigger which handles the orphaning problem.  The trigger essentially just
   does a 'lo_unlink' 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 'lo' type was created because we needed to differentiate between plain
   OIDs and Large Objects. Currently the JDBC driver handles this dilemma easily,
   but (after talking to Byron), the ODBC driver needed a unique type. They had
   created an 'lo' type, but not the solution to orphaning.
d49 1
d51 8
a58 3
   You don't actually have to use the 'lo' type to use the trigger, but it may be
   convenient to use it to keep track of which columns in your database represent
   large objects that you are managing with the trigger.
d63 2
a64 1
  <title>How to Use</title>
d66 1
a66 1
   The easiest way is by an example:
d68 1
d71 1
d75 1
d77 5
a81 4
   Create a trigger for each column that contains a lo type, and give the column
   name as the trigger procedure argument.  You can have more than one trigger on
   a table if you need multiple lo columns in the same table, but don't forget to
   give a different name to each trigger.
d86 1
a86 1
  <title>Issues</title>
d92 2
a93 1
     is not executed.
d95 1
d97 1
a97 1
     Avoid this by preceding the 'drop table' with 'delete from {table}'.
d99 1
d101 4
a104 4
     If you already have, or suspect you have, orphaned large objects, see
     the contrib/vacuumlo module to help you clean them up.  It's a good idea
     to run contrib/vacuumlo occasionally as a back-stop to the lo_manage
     trigger.
d107 1
d111 1
a111 1
     associated trigger(s). Also, users may not remember (or know) to create
a115 6

  <para>
   As the ODBC driver needs a permanent lo type (&amp; JDBC could be optimised to
   use it if it's Oid is fixed), and as the above issues can only be fixed by
   some internal changes, I feel it should become a permanent built-in type.
  </para>
d120 1
d122 1
a122 1
   Peter Mount <email>peter@@retep.org.uk</email> June 13 1998
d125 1
a126 1

@


1.1
log
@Move most /contrib README files into SGML.  Some still need conversion
or will never be converted.
@
text
@d105 1
a105 1
   As the ODBC driver needs a permanent lo type (& JDBC could be optimised to
@

