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

 <chapter id="largeobjects">
  <title>Large Objects</title>

  <indexterm zone="largeobjects"><primary>large object</primary></indexterm>
  <indexterm><primary>BLOB</primary><see>large object</see></indexterm>

   <para>
    <productname>PostgreSQL</productname> has a <firstterm>large object</firstterm>
    facility, which provides stream-style access to user data that is stored
    in a special large-object structure.  Streaming access is useful
    when working with data values that are too large to manipulate
    conveniently as a whole.
   </para>

   <para>
    This chapter describes the implementation and the programming and
    query language interfaces to <productname>PostgreSQL</productname>
    large object data.  We use the <application>libpq</application> C
    library for the examples in this chapter, but most programming
    interfaces native to <productname>PostgreSQL</productname> support
    equivalent functionality.  Other interfaces might use the large
    object interface internally to provide generic support for large
    values.  This is not described here.
   </para>

  <sect1 id="lo-intro">
   <title>Introduction</title>

   <indexterm>
    <primary>TOAST</primary>
    <secondary>versus large objects</secondary>
   </indexterm>

   <para>
    All large objects are stored in a single system table named <link
    linkend="catalog-pg-largeobject"><structname>pg_largeobject</structname></link>.
    Each large object also has an entry in the system table <link
    linkend="catalog-pg-largeobject-metadata"><structname>pg_largeobject_metadata</structname></link>.
    Large objects can be created, modified, and deleted using a read/write API
    that is similar to standard operations on files.
   </para>

   <para>
    <productname>PostgreSQL</productname> also supports a storage system called
    <link
    linkend="storage-toast"><quote><acronym>TOAST</acronym></quote></link>,
    which automatically stores values
    larger than a single database page into a secondary storage area per table.
    This makes the large object facility partially obsolete.  One
    remaining advantage of the large object facility is that it allows values
    up to 4 TB in size, whereas <acronym>TOAST</acronym>ed fields can be at
    most 1 GB.  Also, reading and updating portions of a large object can be
    done efficiently, while most operations on a <acronym>TOAST</acronym>ed
    field will read or write the whole value as a unit.
   </para>

  </sect1>

  <sect1 id="lo-implementation">
   <title>Implementation Features</title>

   <para>
    The large object implementation breaks large
    objects up into <quote>chunks</quote> and stores the chunks in
    rows in the database.  A B-tree index guarantees fast
    searches for the correct chunk number when doing random
    access reads and writes.
   </para>

   <para>
    The chunks stored for a large object do not have to be contiguous.
    For example, if an application opens a new large object, seeks to offset
    1000000, and writes a few bytes there, this does not result in allocation
    of 1000000 bytes worth of storage; only of chunks covering the range of
    data bytes actually written.  A read operation will, however, read out
    zeroes for any unallocated locations preceding the last existing chunk.
    This corresponds to the common behavior of <quote>sparsely allocated</quote>
    files in <acronym>Unix</acronym> file systems.
   </para>

   <para>
    As of <productname>PostgreSQL</productname> 9.0, large objects have an owner
    and a set of access permissions, which can be managed using
    <xref linkend="sql-grant"/> and
    <xref linkend="sql-revoke"/>.
    <literal>SELECT</literal> privileges are required to read a large
    object, and
    <literal>UPDATE</literal> privileges are required to write or
    truncate it.
    Only the large object's owner (or a database superuser) can delete,
    comment on, or change the owner