Chapter 29. Large Objects

Table of Contents
29.1. History
29.2. Implementation Features
29.3. Client Interfaces
29.3.1. Creating a Large Object
29.3.2. Importing a Large Object
29.3.3. Exporting a Large Object
29.3.4. Opening an Existing Large Object
29.3.5. Writing Data to a Large Object
29.3.6. Reading Data from a Large Object
29.3.7. Seeking in a Large Object
29.3.8. Obtaining the Seek Position of a Large Object
29.3.9. Closing a Large Object Descriptor
29.3.10. Removing a Large Object
29.4. Server-Side Functions
29.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.

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