head	1.3;
access;
symbols
	REL7_4_29:1.1
	REL8_0_25:1.1
	REL8_1_21:1.2
	REL8_2_17:1.2
	REL7_4_28:1.1
	REL8_0_24:1.1
	REL8_1_20:1.2
	REL8_2_16:1.2
	REL7_4_27:1.1
	REL8_0_23:1.1
	REL8_1_19:1.2
	REL8_2_15:1.2
	REL7_4_26:1.1
	REL8_0_22:1.1
	REL8_1_18:1.2
	REL8_2_14:1.2
	REL7_4_25:1.1
	REL8_0_21:1.1
	REL8_1_17:1.2
	REL8_2_13:1.2
	REL7_4_24:1.1
	REL8_0_20:1.1
	REL8_1_16:1.2
	REL8_2_12:1.2
	REL7_4_23:1.1
	REL8_0_19:1.1
	REL8_1_15:1.2
	REL8_2_11:1.2
	REL7_4_22:1.1
	REL8_0_18:1.1
	REL8_1_14:1.2
	REL8_2_10:1.2
	REL7_4_21:1.1
	REL8_0_17:1.1
	REL8_1_13:1.2
	REL8_2_9:1.2
	REL7_4_20:1.1
	REL8_0_16:1.1
	REL8_1_12:1.2
	REL8_2_8:1.2
	REL8_2_7:1.2
	REL7_3_21:1.1
	REL7_4_19:1.1
	REL8_0_15:1.1
	REL8_1_11:1.2
	REL8_2_6:1.2
	REL8_3_BETA2:1.2
	REL8_3_BETA1:1.2
	REL7_3_20:1.1
	REL7_4_18:1.1
	REL8_0_14:1.1
	REL8_1_10:1.2
	REL8_2_5:1.2
	REL7_3_19:1.1
	REL7_4_17:1.1
	REL8_0_13:1.1
	REL8_1_9:1.2
	REL8_2_4:1.2
	REL8_0_12:1.1
	REL8_1_8:1.2
	REL8_2_3:1.2
	REL7_3_18:1.1
	REL7_4_16:1.1
	REL8_0_11:1.1
	REL8_1_7:1.2
	REL8_2_2:1.2
	REL8_0_10:1.1
	REL8_1_6:1.2
	REL8_2_1:1.2
	REL7_4_15:1.1
	REL7_3_17:1.1
	REL8_2_STABLE:1.2.0.4
	REL8_2_0:1.2
	REL8_2_RC1:1.2
	REL8_2_BETA3:1.2
	REL8_2_BETA2:1.2
	REL8_1_5:1.2
	REL8_0_9:1.1
	REL7_4_14:1.1
	REL7_3_16:1.1
	REL8_2_BETA1:1.2
	REL7_3_15:1.1
	REL7_4_13:1.1
	REL8_0_8:1.1
	REL8_1_4:1.2
	REL7_3_14:1.1
	REL7_4_12:1.1
	REL8_0_7:1.1
	REL8_1_3:1.2
	REL7_3_13:1.1
	REL7_4_11:1.1
	REL8_0_6:1.1
	REL8_1_2:1.2
	REL7_3_12:1.1
	REL7_4_10:1.1
	REL8_0_5:1.1
	REL8_1_1:1.2
	REL8_1_STABLE:1.2.0.2
	REL8_1_0:1.2
	REL8_1_0RC1:1.2
	REL8_1_0BETA4:1.2
	REL8_1_0BETA3:1.2
	REL7_3_11:1.1
	REL7_4_9:1.1
	REL8_0_4:1.1
	REL8_1_0BETA2:1.2
	REL8_1_0BETA1:1.2
	REL7_2_8:1.1
	REL7_3_10:1.1
	REL7_4_8:1.1
	REL8_0_3:1.1
	REL8_0_2:1.1
	REL7_2_7:1.1
	REL7_3_9:1.1
	REL7_4_7:1.1
	REL8_0_1:1.1
	REL8_0_STABLE:1.1.0.14
	REL8_0_0:1.1.0.12
	REL8_0_0RC5:1.1
	REL8_0_0RC4:1.1
	REL8_0_0RC3:1.1
	REL8_0_0RC2:1.1
	REL8_0_0RC1:1.1
	REL8_0_0BETA5:1.1
	REL8_0_0BETA4:1.1
	REL7_4_6:1.1
	REL7_3_8:1.1
	REL7_2_6:1.1
	REL8_0_0BETA3:1.1
	REL8_0_0BETA2:1.1
	REL7_2_5:1.1
	REL7_4_5:1.1
	REL7_3_7:1.1
	REL7_4_4:1.1
	REL8_0_0BETA1:1.1
	REL7_4_3:1.1
	REL7_4_2:1.1
	REL7_3_6:1.1
	REL7_4_1:1.1
	REL7_3_5:1.1
	REL7_4:1.1
	REL7_4_RC2:1.1
	REL7_4_STABLE:1.1.0.10
	REL7_4_RC1:1.1
	REL7_4_BETA5:1.1
	REL7_4_BETA4:1.1
	REL7_4_BETA3:1.1
	REL7_4_BETA2:1.1
	WIN32_DEV:1.1.0.8
	REL7_4_BETA1:1.1
	REL7_3_4:1.1
	REL7_3_2:1.1
	REL7_2_4:1.1
	REL7_3_STABLE:1.1.0.6
	REL7_2_3:1.1
	REL7_2_STABLE:1.1.0.4
	REL7_2:1.1
	REL7_2_RC2:1.1
	REL7_2_RC1:1.1
	REL7_2_BETA5:1.1
	REL7_2_BETA4:1.1
	REL7_2_BETA3:1.1
	REL7_2_BETA2:1.1
	REL7_2_BETA1:1.1
	REL7_1_2:1.1
	REL7_1_STABLE:1.1.0.2
	REL7_1_BETA:1.1
	REL7_1_BETA3:1.1
	REL7_1_BETA2:1.1
	REL7_1:1.1;
locks; strict;
comment	@# @;


1.3
date	2007.11.10.23.30.45;	author momjian;	state dead;
branches;
next	1.2;

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

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


desc
@@


1.3
log
@Move most /contrib README files into SGML.  Some still need conversion
or will never be converted.
@
text
@PostgreSQL type extension for managing Large Objects
----------------------------------------------------

Overview

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.

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.

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.


The Fix

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!

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.

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.


Install

Ok, first build the shared library, and install. Typing 'make install' in the
contrib/lo directory should do it.

Then, as the postgres super user, run the lo.sql script in any database that
needs the features. This will install the type, and define the support
functions.  You can run the script once in template1, and the objects will be
inherited by subsequently-created databases.


How to Use

The easiest way is by an example:

> 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);

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.


Issues

* Dropping a table will still orphan any objects it contains, as the trigger
  is not executed.

  Avoid this by preceding the 'drop table' with 'delete from {table}'.

  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.

* 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.

As the ODBC driver needs a permanent lo type (& 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.

I'm releasing this into contrib, just to get it out, and tested.

Peter Mount <peter@@retep.org.uk> June 13 1998
@


1.2
log
@Cleanup the contrib/lo module: there is no need anymore to implement
a physically separate type.  Defining 'lo' as a domain over OID works
just fine and is more efficient.  Improve documentation and fix up the
test script.  (Would like to turn test script into a proper regression
test, but right now its output is not constant because of numeric OIDs;
plus it makes Unix-specific assumptions about files it can import.)
@
text
@@


1.1
log
@Add missing /contrib files
@
text
@d11 5
a15 2
As PostgreSQL stands, this doesn't occur. It allocates an OID for each object,
and it is up to the application to store, and ultimately delete the objects.
d17 2
a18 2
Now this is fine for new postgresql specific applications, but existing ones
using JDBC or ODBC wont delete the objects, arising to orphaning - objects
d21 1
d25 14
a38 1
a Trigger which handles the orphaning problem.
a39 3
The 'lo' type was created because we needed to differenciate between normal
Oid's and Large Objects. Currently the JDBC driver handles this dilema 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.
d46 5
a50 2
Then, as the postgres super user, run the lo.sql script. This will install the
type, and define the support functions.
d56 8
a63 2
> create table image (title text,raster lo);
> create trigger t_image before update or delete on image for each row execute procedure lo_manage(raster);
a64 1
Here, a trigger is created for each column that contains a lo type.
d68 2
a69 5
* dropping a table will still orphan any objects it contains, as the trigger
  is not actioned.

  For now, precede the 'drop table' with 'delete from {table}'. However, this
  could be fixed by having 'drop table' perform an additional
d71 1
a71 1
      'select lo_unlink({colname}::oid) from {tablename}'
d73 4
a76 1
  for each column, before actually dropping the table.
a81 2
  This can be solved, but would involve changes to the parser.

a88 1

@

