<!-- doc/src/sgml/storage.sgml -->

<chapter id="storage">

<title>Database Physical Storage</title>

<para>
This chapter provides an overview of the physical storage format used by
<productname>PostgreSQL</productname> databases.
</para>

<sect1 id="storage-file-layout">

<title>Database File Layout</title>

<para>
This section describes the storage format at the level of files and
directories.
</para>

<para>
Traditionally, the configuration and data files used by a database
cluster are stored together within the cluster's data
directory, commonly referred to as <varname>PGDATA</varname> (after the name of the
environment variable that can be used to define it).  A common location for
<varname>PGDATA</varname> is <filename>/var/lib/pgsql/data</filename>.  Multiple clusters,
managed by different server instances, can exist on the same machine.
</para>

<para>
The <varname>PGDATA</varname> directory contains several subdirectories and control
files, as shown in <xref linkend="pgdata-contents-table"/>.  In addition to
these required items, the cluster configuration files
<filename>postgresql.conf</filename>, <filename>pg_hba.conf</filename>, and
<filename>pg_ident.conf</filename> are traditionally stored in
<varname>PGDATA</varname>, although it is possible to place them elsewhere.
</para>

<table tocentry="1" id="pgdata-contents-table">
<title>Contents of <varname>PGDATA</varname></title>
<tgroup cols="2">
<thead>
<row>
<entry>
Item
</entry>
<entry>Description</entry>
</row>
</thead>

<tbody>

<row>
 <entry><filename>PG_VERSION</filename></entry>
 <entry>A file containing the major version number of <productname>PostgreSQL</productname></entry>
</row>

<row>
 <entry><filename>base</filename></entry>
 <entry>Subdirectory containing per-database subdirectories</entry>
</row>

<row>
 <entry><filename>current_logfiles</filename></entry>
 <entry>File recording the log file(s) currently written to by the logging
  collector</entry>
</row>

<row>
 <entry><filename>global</filename></entry>
 <entry>Subdirectory containing cluster-wide tables, such as
 <structname>pg_database</structname></entry>
</row>

<row>
 <entry><filename>pg_commit_ts</filename></entry>
 <entry>Subdirectory containing transaction commit timestamp data</entry>
</row>

<row>
 <entry><filename>pg_dynshmem</filename></entry>
 <entry>Subdirectory containing files used by the dynamic shared memory
  subsystem</entry>
</row>

<row>
 <entry><filename>pg_logical</filename></entry>
 <entry>Subdirectory containing status data for logical decoding</entry>
</row>

<row>
 <entry><filename>pg_multixact</filename></entry>
 <entry>Subdirectory containing multitransaction status data
  (used for shared row locks)</entry>
</row>

<row>
 <entry><filename>pg_notify</filename></entry>
 <entry>Subdirectory containing LISTEN/NOTIFY status data</entry>
</row>

<row>
 <entry><filename>pg_replslot</filename></entry>
 <entry>Subdirectory containing replication slot data</entry>
</row>

<row>
 <entry><filename>pg_serial</filename></entry>
 <entry>Subdirectory containing information about committed serializable transactions</entry>
</row>

<row>
 <entry><filename>pg_snapshots</filename></entry>
 <entry>Subdirectory containing exported snapshots</entry>
</row>

<row>
 <entry><filename>pg_stat</filename></entry>
 <entry>Subdirectory containing permanent files for the statistics
  subsystem</entry>
</row>

<row>
 <entry><filename>pg_stat_tmp</filename></entry>
 <entry>Subdirectory containing temporary files for the statistics
  subsystem</entry>
</row>

<row>
 <entry><filename>pg_subtrans</filename></entry>
 <entry>Subdirectory containing subtransaction status data</entry>
</row>

<row>
 <entry><filename>pg_tblspc</filename></entry>
 <entry>Subdirectory containing symbolic links to tablespaces</entry>
</row>

<row>
 <entry><filename>pg_twophase</filename></entry>
 <entry>Subdirectory containing state files for prepared transactions</entry>
</row>

<row>
 <entry><filename>pg_wal</filename></entry>