From d3215af7ad2303ae83960d5ea014a73c9a5d6337 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Sun, 16 Sep 2001 22:53:52 +0000 Subject: [PATCH] Update intro in face of TOAST. --- doc/src/sgml/lobj.sgml | 121 ++++++++++++++++++++++++----------------- 1 file changed, 70 insertions(+), 51 deletions(-) diff --git a/doc/src/sgml/lobj.sgml b/doc/src/sgml/lobj.sgml index 6ba725d360..6e8e9a7ac9 100644 --- a/doc/src/sgml/lobj.sgml +++ b/doc/src/sgml/lobj.sgml @@ -1,54 +1,74 @@ Large Objects - - In Postgres, - data values are stored in tuples and - individual tuples cannot span data pages. Since the size of - a data page is 8192 bytes, the upper limit on the size - of a data value is relatively low. To support the storage - of larger atomic values, - Postgres provides a large - object interface. This interface provides file - oriented access to user data that has been declared to - be a large type. - This section describes the implementation and the - programming and query language interfaces to - Postgres - large object data. - - - - Historical Note + + Introduction - Originally, Postgres 4.2 supported three standard - implementations of large objects: as files external - to Postgres, as - external files managed by Postgres, and as data - stored within the Postgres database. It causes - considerable confusion among users. As a result, we only - support large objects as data stored within the Postgres - database in PostgreSQL. Even though it is slower to - access, it provides stricter data integrity. - For historical reasons, this storage scheme is referred to as - Inversion large objects. (We will use Inversion and large - objects interchangeably to mean the same thing in this - section.) - Since PostgreSQL 7.1 all large objects are placed in - one system table called pg_largeobject. + 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 has been + declared to be a large object. + + + 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 random access to the data, i.e., the ability to read or + write small chunks of a large value. It is planned to equip + TOAST with such functionality in the future. + + + + This section 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 section, 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. + + Implementation Features - The Inversion large object implementation breaks large + The large object implementation breaks large objects up into chunks and stores the chunks in tuples in the database. A B-tree index guarantees fast searches for the correct chunk number when doing random @@ -60,11 +80,11 @@ $Header: /cvsroot/pgsql/doc/src/sgml/lobj.sgml,v 1.21 2001/09/15 16:08:59 petere Interfaces - The facilities Postgres provides to + The facilities PostgreSQL provides to access large objects, both in the backend as part of user-defined functions or the front end as part of an application using the interface, are described below. For users - familiar with Postgres 4.2, + familiar with POSTGRES 4.2, PostgreSQL has a new set of functions providing a more coherent interface. @@ -72,7 +92,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/lobj.sgml,v 1.21 2001/09/15 16:08:59 petere All large object manipulation must take place within an SQL transaction. This requirement is strictly - enforced as of Postgres 6.5, though it has been an + enforced as of PostgreSQL 6.5, though it has been an implicit requirement in previous versions, resulting in misbehavior if ignored. @@ -80,7 +100,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/lobj.sgml,v 1.21 2001/09/15 16:08:59 petere - The Postgres large object interface is modeled after + The PostgreSQL large object interface is modeled after the Unix file system interface, with analogues of open(2), read(2), write(2), @@ -96,7 +116,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/lobj.sgml,v 1.21 2001/09/15 16:08:59 petere examined, by the beard function. Large objects may be accessed from dynamically-loaded C functions or database client programs that link the - library. Postgres provides a set of routines that + library. PostgreSQL provides a set of routines that support opening, reading, writing, closing, and seeking on large objects. @@ -113,18 +133,17 @@ Oid lo_creat(PGconn *conn, int mode is a bit mask describing several different attributes of the new object. The symbolic constants listed here are defined - in - $PGROOT/src/backend/libpq/libpq-fs.h + in the header file libpq/libpq-fs.h. The access type (read, write, or both) is controlled by - OR'ing together the bits INV_READ and - INV_WRITE. The low-order sixteen bits of mask are - the storage manager number on which the large object - should reside. For sites other than Berkeley, these - bits should always be zero. - The commands below create an (Inversion) large object: - + OR'ing together the bits INV_READ and + INV_WRITE. The low-order sixteen bits of the mask have + historically been used at Berkeley to designate the storage manager number on which the large object + should reside. These + bits should always be zero now. + The commands below create a large object: + inv_oid = lo_creat(INV_READ|INV_WRITE); - +