1 files changed, 144 insertions, 0 deletions
diff --git a/doc/src/sgml/diskusage.sgml b/doc/src/sgml/diskusage.sgml
new file mode 100644
index 0000000..7546758
--- /dev/null
+++ b/doc/src/sgml/diskusage.sgml
@@ -0,0 +1,144 @@
+<!-- doc/src/sgml/diskusage.sgml -->
+
+<chapter id="diskusage">
+ <title>Monitoring Disk Usage</title>
+
+ <para>
+  This chapter discusses how to monitor the disk usage of a
+  <productname>PostgreSQL</productname> database system.
+ </para>
+
+ <sect1 id="disk-usage">
+  <title>Determining Disk Usage</title>
+
+  <indexterm zone="disk-usage">
+   <primary>disk usage</primary>
+  </indexterm>
+
+  <para>
+   Each table has a primary heap disk file where most of the data is
+   stored. If the table has any columns with potentially-wide values,
+   there also might be a <acronym>TOAST</acronym> file associated with the table,
+   which is used to store values too wide to fit comfortably in the main
+   table (see <xref linkend="storage-toast"/>).  There will be one valid index
+   on the <acronym>TOAST</acronym> table, if present. There also might be indexes
+   associated with the base table.  Each table and index is stored in a
+   separate disk file &mdash; possibly more than one file, if the file would
+   exceed one gigabyte.  Naming conventions for these files are described
+   in <xref linkend="storage-file-layout"/>.
+  </para>
+
+  <para>
+   You can monitor disk space in three ways:
+   using the SQL functions listed in <xref linkend="functions-admin-dbsize"/>,
+   using the <xref linkend="oid2name"/> module, or
+   using manual inspection of the system catalogs.
+   The SQL functions are the easiest to use and are generally recommended.
+   The remainder of this section shows how to do it by inspection of the
+   system catalogs.
+  </para>
+
+  <para>
+   Using <application>psql</application> on a recently vacuumed or analyzed database,
+   you can issue queries to see the disk usage of any table:
+<programlisting>
+SELECT pg_relation_filepath(oid), relpages FROM pg_class WHERE relname = 'customer';
+
+ pg_relation_filepath | relpages
+----------------------+----------
+ base/16384/16806     |       60
+(1 row)
+</programlisting>
+   Each page is typically 8 kilobytes. (Remember, <structfield>relpages</structfield>
+   is only updated by <command>VACUUM</command>, <command>ANALYZE</command>, and
+   a few DDL commands such as <command>CREATE INDEX</command>.)  The file path name
+   is of interest if you want to examine the table's disk file directly.
+  </para>
+
+  <para>
+   To show the space used by <acronym>TOAST</acronym> tables, use a query
+   like the following:
+<programlisting>
+SELECT relname, relpages
+FROM pg_class,
+     (SELECT reltoastrelid
+      FROM pg_class
+      WHERE relname = 'customer') AS ss
+WHERE oid = ss.reltoastrelid OR
+      oid = (SELECT indexrelid
+             FROM pg_index
+             WHERE indrelid = ss.reltoastrelid)
+ORDER BY relname;
+
+       relname        | relpages
+----------------------+----------
+ pg_toast_16806       |        0
+ pg_toast_16806_index |        1
+</programlisting>
+  </para>
+
+  <para>
+   You can easily display index sizes, too:
+<programlisting>
+SELECT c2.relname, c2.relpages
+FROM pg_class c, pg_class c2, pg_index i
+WHERE c.relname = 'customer' AND
+      c.oid = i.indrelid AND
+      c2.oid = i.indexrelid
+ORDER BY c2.relname;
+
+      relname      | relpages
+-------------------+----------
+ customer_id_index |       26
+</programlisting>
+  </para>
+
+  <para>
+   It is easy to find your largest tables and indexes using this
+   information:
+<programlisting>
+SELECT relname, relpages
+FROM pg_class
+ORDER BY relpages DESC;
+
+       relname        | relpages
+----------------------+----------
+ bigtable             |     3290
+ customer             |     3144
+</programlisting>
+  </para>
+ </sect1>
+
+ <sect1 id="disk-full">
+  <title>Disk Full Failure</title>
+
+  <para>
+   The most important disk monitoring task of a database administrator
+   is to make sure the disk doesn't become full.  A filled data disk will
+   not result in data corruption, but it might prevent useful activity
+   from occurring. If the disk holding the WAL files grows full, database
+   server panic and consequent shutdown might occur.
+  </para>
+
+  <para>
+   If you cannot free up additional space on the disk by deleting
+   other things, you can move some of the database files to other file
+   systems by making use of tablespaces. See <xref
+   linkend="manage-ag-tablespaces"/> for more information about that.
+  </para>
+
+  <tip>
+   <para>
+    Some file systems perform badly when they are almost full, so do
+    not wait until the disk is completely full to take action.
+   </para>
+  </tip>
+
+  <para>
+   If your system supports per-user disk quotas, then the database
+   will naturally be subject to whatever quota is placed on the user
+   the server runs as.  Exceeding the quota will have the same bad
+   effects as running out of disk space entirely.
+  </para>
+ </sect1>
+</chapter>