v2-0002-docs-Demote-Monitoring-Disk-Usage-from-chapter-to.patch
application/octet-stream
Filename: v2-0002-docs-Demote-Monitoring-Disk-Usage-from-chapter-to.patch
Type: application/octet-stream
Part: 1
Message:
Re: documentation structure
Patch
Same data as JSON:
GET /api/v1/attachments/:id/patch
the parsed metadata as JSON — format, series position, per-file stats; never the diff bytes.
API reference →
Format: format-patch
Series: patch v2-0002
Subject: docs: Demote "Monitoring Disk Usage" from chapter to section.
| File | + | − |
|---|---|---|
| doc/src/sgml/diskusage.sgml | 0 | 144 |
| doc/src/sgml/filelist.sgml | 0 | 1 |
| doc/src/sgml/monitoring.sgml | 143 | 0 |
| doc/src/sgml/postgres.sgml | 0 | 1 |
From adce7677286f48a6971251758b9a78877db1895a Mon Sep 17 00:00:00 2001 From: Robert Haas <rhaas@postgresql.org> Date: Wed, 20 Mar 2024 10:52:16 -0400 Subject: [PATCH v2 2/5] docs: Demote "Monitoring Disk Usage" from chapter to section. This chapter is very short, and the immediately preceding chapter is called "Monitoring Database Activity". So, instead of having a separate chapter for this, make it the last section of the preceding chapter instead. --- doc/src/sgml/diskusage.sgml | 144 ----------------------------------- doc/src/sgml/filelist.sgml | 1 - doc/src/sgml/monitoring.sgml | 143 ++++++++++++++++++++++++++++++++++ doc/src/sgml/postgres.sgml | 1 - 4 files changed, 143 insertions(+), 146 deletions(-) delete mode 100644 doc/src/sgml/diskusage.sgml diff --git a/doc/src/sgml/diskusage.sgml b/doc/src/sgml/diskusage.sgml deleted file mode 100644 index 75467582e4..0000000000 --- a/doc/src/sgml/diskusage.sgml +++ /dev/null @@ -1,144 +0,0 @@ -<!-- 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 — 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> diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index b7d1222e3e..f39b4efe38 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -34,7 +34,6 @@ <!ENTITY backup SYSTEM "backup.sgml"> <!ENTITY charset SYSTEM "charset.sgml"> <!ENTITY client-auth SYSTEM "client-auth.sgml"> -<!ENTITY diskusage SYSTEM "diskusage.sgml"> <!ENTITY high-availability SYSTEM "high-availability.sgml"> <!ENTITY installation SYSTEM "installation.sgml"> <!ENTITY targets-meson SYSTEM "targets-meson.sgml"> diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml index 8736eac284..eda54b4985 100644 --- a/doc/src/sgml/monitoring.sgml +++ b/doc/src/sgml/monitoring.sgml @@ -7282,4 +7282,147 @@ if (TRACE_POSTGRESQL_TRANSACTION_START_ENABLED()) </sect1> + <sect1 id="diskusage"> + <title>Monitoring Disk Usage</title> + + <para> + This section discusses how to monitor the disk usage of a + <productname>PostgreSQL</productname> database system. + </para> + + <sect2 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 — 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> + </sect2> + + <sect2 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> + </sect2> + </sect1> + </chapter> diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml index 7c234ff1db..73b497bcf8 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -161,7 +161,6 @@ break is not needed in a wider output rendering. &backup; &high-availability; &monitoring; - &diskusage; &wal; &logical-replication; &jit; -- 2.39.3 (Apple Git-145)