database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-07-28 23:42:10 +03:00
Code Activity

Update intro in face of TOAST.

Browse Source
This commit is contained in:
Peter Eisentraut
2001-09-16 22:53:52 +00:00
parent 264f8f2b6c
commit d3215af7ad
1 changed files with 70 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

117
doc/src/sgml/lobj.sgml
View File

@ -1,54 +1,74 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/lobj.sgml,v 1.21 2001/09/15 16:08:59 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/lobj.sgml,v 1.22 2001/09/16 22:53:52 petere Exp $
--> -->
<chapter id="largeObjects"> <chapter id="largeObjects">
<title id="largeObjects-title">Large Objects</title> <title id="largeObjects-title">Large Objects</title>
<para> <sect1 id="lo-intro">
In <productname>Postgres</productname>, <title>Introduction</title>
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,
<productname>Postgres</productname> 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
<productname>Postgres</productname>
large object data.
</para>
<sect1 id="lo-history">
<title>Historical Note</title>
<para> <para>
Originally, <productname>Postgres 4.2</productname> supported three standard In <productname>PostgreSQL</productname> releases prior to 7.1,
implementations of large objects: as files external the size of any row in the database could not exceed the size of a
to <productname>Postgres</productname>, as data page. Since the size of a data page is 8192 bytes (the
external files managed by <productname>Postgres</productname>, and as data default, which can be raised up to 32768), the upper limit on the
stored within the <productname>Postgres</productname> database. It causes size of a data value was relatively low. To support the storage of
considerable confusion among users. As a result, we only larger atomic values, <productname>PostgreSQL</productname>
support large objects as data stored within the <productname>Postgres</productname> provided and continues to provide a large object interface. This
database in <productname>PostgreSQL</productname>. Even though it is slower to interface provides file-oriented access to user data that has been
access, it provides stricter data integrity. declared to be a large object.
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 <productname>PostgreSQL 7.1</productname> all large objects are placed in
one system table called <classname>pg_largeobject</classname>.
</para> </para>
<para>
<productname>POSTGRES 4.2</productname>, the indirect predecessor
of <productname>PostgreSQL</productname>, supported three standard
implementations of large objects: as files external to the
<productname>POSTGRES</productname> server, as external files
managed by the <productname>POSTGRES</productname> server, and as
data stored within the <productname>POSTGRES</productname>
database. This caused considerable confusion among users. As a
result, only support for large objects as data stored within the
database is retained in <productname>PostgreSQL</productname>.
Even though this is slower to access, it provides stricter data
integrity. For historical reasons, this storage scheme is
referred to as <firstterm>Inversion large
objects</firstterm>. (You will see the term Inversion used
occasionally to mean the same thing as large object.) Since
<productname>PostgreSQL 7.1</productname>, all large objects are
placed in one system table called
<classname>pg_largeobject</classname>.
</para>
<para>
<productname>PostgreSQL 7.1</productname> introduced a mechanism
(nicknamed <quote><acronym>TOAST</acronym></quote>) 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
<acronym>TOAST</acronym> with such functionality in the future.
</para>
<para>
This section 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 section, but most programming
interfaces native to <productname>PostgreSQL</productname> support
equivalent functionality. Other interfaces may use the large
object interface internally to provide generic support for large
values. This is not described here.
</para>
</sect1> </sect1>
<sect1 id="lo-implementation"> <sect1 id="lo-implementation">
<title>Implementation Features</title> <title>Implementation Features</title>
<para> <para>
The Inversion large object implementation breaks large The large object implementation breaks large
objects up into <quote>chunks</quote> and stores the chunks in objects up into <quote>chunks</quote> and stores the chunks in
tuples in the database. A B-tree index guarantees fast tuples in the database. A B-tree index guarantees fast
searches for the correct chunk number when doing random 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
<title>Interfaces</title> <title>Interfaces</title>
<para> <para>
The facilities <productname>Postgres</productname> provides to The facilities <productname>PostgreSQL</productname> provides to
access large objects, both in the backend as part of user-defined access large objects, both in the backend as part of user-defined
functions or the front end as part of an application functions or the front end as part of an application
using the interface, are described below. For users using the interface, are described below. For users
familiar with <productname>Postgres 4.2</productname>, familiar with <productname>POSTGRES 4.2</productname>,
<productname>PostgreSQL</productname> has a new set of <productname>PostgreSQL</productname> has a new set of
functions providing a more coherent interface. 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
<para> <para>
All large object manipulation <emphasis>must</emphasis> take All large object manipulation <emphasis>must</emphasis> take
place within an SQL transaction. This requirement is strictly place within an SQL transaction. This requirement is strictly
enforced as of Postgres 6.5, though it has been an enforced as of <productname>PostgreSQL 6.5</>, though it has been an
implicit requirement in previous versions, resulting in implicit requirement in previous versions, resulting in
misbehavior if ignored. misbehavior if ignored.
</para> </para>
@ -80,7 +100,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/lobj.sgml,v 1.21 2001/09/15 16:08:59 petere
</para> </para>
<para> <para>
The <productname>Postgres</productname> large object interface is modeled after The <productname>PostgreSQL</productname> large object interface is modeled after
the <acronym>Unix</acronym> file system interface, with analogues of the <acronym>Unix</acronym> file system interface, with analogues of
<function>open(2)</function>, <function>read(2)</function>, <function>open(2)</function>, <function>read(2)</function>,
<function>write(2)</function>, <function>write(2)</function>,
@ -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. examined, by the beard function.
Large objects may be accessed from dynamically-loaded <acronym>C</acronym> Large objects may be accessed from dynamically-loaded <acronym>C</acronym>
functions or database client programs that link the functions or database client programs that link the
library. <productname>Postgres</productname> provides a set of routines that library. <productname>PostgreSQL</productname> provides a set of routines that
support opening, reading, writing, closing, and seeking on support opening, reading, writing, closing, and seeking on
large objects. large objects.
</para> </para>
@ -113,15 +133,14 @@ Oid lo_creat(PGconn *<replaceable class="parameter">conn</replaceable>, int <rep
<replaceable class="parameter">mode</replaceable> is a bit mask <replaceable class="parameter">mode</replaceable> is a bit mask
describing several different attributes of the new describing several different attributes of the new
object. The symbolic constants listed here are defined object. The symbolic constants listed here are defined
in in the header file <filename>libpq/libpq-fs.h</filename>.
<filename>$<envar>PGROOT</envar>/src/backend/libpq/libpq-fs.h</filename>
The access type (read, write, or both) is controlled by The access type (read, write, or both) is controlled by
OR'ing together the bits <acronym>INV_READ</acronym> and OR'ing together the bits <symbol>INV_READ</symbol> and
<acronym>INV_WRITE</acronym>. The low-order sixteen bits of mask are <symbol>INV_WRITE</symbol>. The low-order sixteen bits of the mask have
the storage manager number on which the large object historically been used at Berkeley to designate the storage manager number on which the large object
should reside. For sites other than Berkeley, these should reside. These
bits should always be zero. bits should always be zero now.
The commands below create an (Inversion) large object: The commands below create a large object:
<programlisting> <programlisting>
inv_oid = lo_creat(INV_READ|INV_WRITE); inv_oid = lo_creat(INV_READ|INV_WRITE);
</programlisting> </programlisting>