Chapter 28. Large Objects

Table of Contents
28.1. History
28.2. Implementation Features
28.3. Client Interfaces
28.3.1. Creating a Large Object
28.3.2. Importing a Large Object
28.3.3. Exporting a Large Object
28.3.4. Opening an Existing Large Object
28.3.5. Writing Data to a Large Object
28.3.6. Reading Data from a Large Object
28.3.7. Seeking in a Large Object
28.3.8. Obtaining the Seek Position of a Large Object
28.3.9. Closing a Large Object Descriptor
28.3.10. Removing a Large Object
28.4. Server-Side Functions
28.5. Example Program

PostgreSQL has a large object 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.

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

28.1. History

POSTGRES 4.2, the indirect predecessor of PostgreSQL, supported three standard implementations of large objects: as files external to the POSTGRES server, as external files managed by the POSTGRES server, and as data stored within the POSTGRES database. This caused considerable confusion among users. As a result, only support for large objects as data stored within the database is retained in PostgreSQL. Even though this is slower to access, it provides stricter data integrity. For historical reasons, this storage scheme is referred to as Inversion large objects. (You will see the term Inversion used occasionally to mean the same thing as large object.) Since PostgreSQL 7.1, all large objects are placed in one system table called pg_largeobject.

PostgreSQL 7.1 introduced a mechanism (nicknamed "TOAST") that allows data values to be much larger than single pages. This makes the large object facility partially obsolete. One remaining advantage of the large object facility is that it allows values up to 2 GB in size, whereas TOASTed fields can be at most 1 GB. Also, large objects can be manipulated piece-by-piece much more easily than ordinary data fields, so the practical limits are considerably different.