PHP Manual

PEAR Manual

Smarty Manual

PostgreSQL

MySQL Manual

Perl Manual

postgresql 8.2devel documentation
prevfast backwardfast forwardnext

chapter 50. database physical storage

table of contents
50.1. database file layout
50.2. toast
50.3. database page layout

this chapter provides an overview of the physical storage format used by postgresql databases.

50.1. database file layout

this section describes the storage format at the level of files and directories.

all the data needed for a database cluster is stored within the cluster's data directory, commonly referred to as pgdata (after the name of the environment variable that can be used to define it). a common location for pgdata is /var/lib/pgsql/data. multiple clusters, managed by different postmasters, can exist on the same machine.

the pgdata directory contains several subdirectories and control files, as shown in table 50-1. in addition to these required items, the cluster configuration files postgresql.conf, pg_hba.conf, and pg_ident.conf are traditionally stored in pgdata (although in postgresql 8.0 and later, it is possible to keep them elsewhere).

table 50-1. contents of pgdata

itemdescription
pg_versiona file containing the major version number of postgresql
basesubdirectory containing per-database subdirectories
globalsubdirectory containing cluster-wide tables, such as pg_database
pg_clogsubdirectory containing transaction commit status data
pg_multixactsubdirectory containing multitransaction status data (used for shared row locks)
pg_subtranssubdirectory containing subtransaction status data
pg_tblspcsubdirectory containing symbolic links to tablespaces
pg_twophasesubdirectory containing state files for prepared transactions
pg_xlogsubdirectory containing wal (write ahead log) files
postmaster.optsa file recording the command-line options the postmaster was last started with
postmaster.pida lock file recording the current postmaster pid and shared memory segment id (not present after postmaster shutdown)

for each database in the cluster there is a subdirectory within pgdata/base, named after the database's oid in pg_database. this subdirectory is the default location for the database's files; in particular, its system catalogs are stored there.

each table and index is stored in a separate file, named after the table or index's filenode number, which can be found in pg_class.relfilenode.

caution

note that while a table's filenode often matches its oid, this is not necessarily the case; some operations, like truncate, reindex, cluster and some forms of alter table, can change the filenode while preserving the oid. avoid assuming that filenode and table oid are the same.

when a table or index exceeds 1gb, it is divided into gigabyte-sized segments. the first segment's file name is the same as the filenode; subsequent segments are named filenode.1, filenode.2, etc. this arrangement avoids problems on platforms that have file size limitations. the contents of tables and indexes are discussed further in section 50.3.

a table that has columns with potentially large entries will have an associated toast table, which is used for out-of-line storage of field values that are too large to keep in the table rows proper. pg_class.reltoastrelid links from a table to its toast table, if any. see section 50.2 for more information.

tablespaces make the scenario more complicated. each user-defined tablespace has a symbolic link inside the pgdata/pg_tblspc directory, which points to the physical tablespace directory (as specified in its create tablespace command). the symbolic link is named after the tablespace's oid. inside the physical tablespace directory there is a subdirectory for each database that has elements in the tablespace, named after the database's oid. tables within that directory follow the filenode naming scheme. the pg_default tablespace is not accessed through pg_tblspc, but corresponds to pgdata/base. similarly, the pg_global tablespace is not accessed through pg_tblspc, but corresponds to pgdata/global.

prevhomenext
crash recoveryuptoast