begriffs open source - ai-pg/blob - full-docs/txt/lo.txt

   1
   2 F.21. lo — manage large objects #
   3
   4    F.21.1. Rationale
   5    F.21.2. How to Use It
   6    F.21.3. Limitations
   7    F.21.4. Author
   8
   9    The lo module provides support for managing Large Objects (also called
  10    LOs or BLOBs). This includes a data type lo and a trigger lo_manage.
  11
  12    This module is considered “trusted”, that is, it can be installed by
  13    non-superusers who have CREATE privilege on the current database.
  14
  15 F.21.1. Rationale #
  16
  17    One of the problems with the JDBC driver (and this affects the ODBC
  18    driver also), is that the specification assumes that references to
  19    BLOBs (Binary Large OBjects) are stored within a table, and if that
  20    entry is changed, the associated BLOB is deleted from the database.
  21
  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
  24    by OID, but there can be multiple table entries referencing the same
  25    large object OID, so the system doesn't delete the large object just
  26    because you change or remove one such entry.
  27
  28    Now this is fine for PostgreSQL-specific applications, but standard
  29    code using JDBC or ODBC won't delete the objects, resulting in orphan
  30    objects — objects that are not referenced by anything, and simply
  31    occupy disk space.
  32
  33    The lo module allows fixing this by attaching a trigger to tables that
  34    contain LO reference columns. The trigger essentially just does a
  35    lo_unlink whenever you delete or modify a value referencing a large
  36    object. When you use this trigger, you are assuming that there is only
  37    one database reference to any large object that is referenced in a
  38    trigger-controlled column!
  39
  40    The module also provides a data type lo, which is really just a domain
  41    over the oid type. This is useful for differentiating database columns
  42    that hold large object references from those that are OIDs of other
  43    things. You don't have to use the lo type to use the trigger, but it
  44    may be convenient to use it to keep track of which columns in your
  45    database represent large objects that you are managing with the
  46    trigger. It is also rumored that the ODBC driver gets confused if you
  47    don't use lo for BLOB columns.
  48
  49 F.21.2. How to Use It #
  50
  51    Here's a simple example of usage:
  52 CREATE TABLE image (title text, raster lo);
  53
  54 CREATE TRIGGER t_raster BEFORE UPDATE OR DELETE ON image
  55     FOR EACH ROW EXECUTE FUNCTION lo_manage(raster);
  56
  57    For each column that will contain unique references to large objects,
  58    create a BEFORE UPDATE OR DELETE trigger, and give the column name as
  59    the sole trigger argument. You can also restrict the trigger to only
  60    execute on updates to the column by using BEFORE UPDATE OF column_name.
  61    If you need multiple lo columns in the same table, create a separate
  62    trigger for each one, remembering to give a different name to each
  63    trigger on the same table.
  64
  65 F.21.3. Limitations #
  66
  67      * Dropping a table will still orphan any objects it contains, as the
  68        trigger is not executed. You can avoid this by preceding the DROP
  69        TABLE with DELETE FROM table.
  70        TRUNCATE has the same hazard.
  71        If you already have, or suspect you have, orphaned large objects,
  72        see the vacuumlo module to help you clean them up. It's a good idea
  73        to run vacuumlo occasionally as a back-stop to the lo_manage
  74        trigger.
  75      * Some frontends may create their own tables, and will not create the
  76        associated trigger(s). Also, users may not remember (or know) to
  77        create the triggers.
  78
  79 F.21.4. Author #
  80
  81    Peter Mount <peter@retep.org.uk>