← Back to branch summary

~ubuntu-branches/ubuntu/oneiric/postgresql-9.1/oneiric-security

« back to all changes in this revision

Viewing changes to doc/src/sgml/lo.sgml

  • Committer: Bazaar Package Importer
  • Author(s): Martin Pitt
  • Date: 2011-05-11 10:41:53 UTC
  • Revision ID: james.westby@ubuntu.com-20110511104153-psbh2o58553fv1m0
Tags: upstream-9.1~beta1
Import upstream version 9.1~beta1

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/sgml/lo.sgml
 
1
<!-- doc/src/sgml/lo.sgml -->
 
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
     <xref linkend="vacuumlo"> module 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>