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 on 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

In PostgreSQL releases prior to 7.1, the size of any row in the database could not exceed the size of a data page. Since the size of a data page is 8192 bytes (the default, which can be raised up to 32768), the upper limit on the size of a data value was relatively low. To support the storage of larger atomic values, PostgreSQL provided and continues to provide a large object interface. This interface provides file-oriented access to user data that is stored in a special large-object structure.

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 rows to be much larger than individual data pages. This makes the large object interface partially obsolete. One remaining advantage of the large object interface is that it allows values up to 2 GB in size, whereas TOAST can only handle 1 GB.