doc: Re-order sections of "28.4. Progress Reporting"

BEFORE
28.4.1. ANALYZE Progress Reporting
28.4.2. CREATE INDEX Progress Reporting
28.4.3. VACUUM Progress Reporting
28.4.4. CLUSTER Progress Reporting
28.4.5. Base Backup Progress Reporting
28.4.6. COPY Progress Reporting

AFTER
28.4.1. ANALYZE Progress Reporting
28.4.2. CLUSTER Progress Reporting
28.4.3. COPY Progress Reporting
28.4.4. CREATE INDEX Progress Reporting
28.4.5. VACUUM Progress Reporting
28.4.6. Base Backup Progress Reporting

Author: Peter Smith 
Reviewed-by: Tom Lane 
Discussion: https://www.postgresql.org/message-id/flat/CAHut+Pv8Oa7v06hJb3+HzCtM2u-3oHWMdvXVHhvi7ofB83pNbg@mail.gmail.com

diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index e2426f7210cbbb7e607e75d010243e2bbc8fda00..b0823a905009698b8d08dbbea0e4e691216e2247 100644 (file)
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -6012,6 +6012,362 @@ FROM pg_stat_get_backend_idset() AS backendid;
   
  
 
+ 
+  CLUSTER Progress Reporting
+
+  
+   pg_stat_progress_cluster
+  
+
+  
+   Whenever CLUSTER or VACUUM FULL is
+   running, the pg_stat_progress_cluster view will
+   contain a row for each backend that is currently running either command.
+   The tables below describe the information that will be reported and
+   provide information about how to interpret it.
+  
+
+  
+   <structname>pg_stat_progress_cluster</structname> View
+   
+    
+     
+      
+       Column Type
+      
+      
+       Description
+      
+     
+    
+
+    
+     
+      
+       pid integer
+      
+      
+       Process ID of backend.
+      
+     
+
+     
+      
+       datid oid
+      
+      
+       OID of the database to which this backend is connected.
+      
+     
+
+     
+      
+       datname name
+      
+      
+       Name of the database to which this backend is connected.
+      
+     
+
+     
+      
+       relid oid
+      
+      
+       OID of the table being clustered.
+      
+     
+
+     
+      
+       command text
+      
+      
+       The command that is running. Either CLUSTER or VACUUM FULL.
+      
+     
+
+     
+      
+       phase text
+      
+      
+       Current processing phase. See .
+      
+     
+
+     
+      
+       cluster_index_relid oid
+      
+      
+       If the table is being scanned using an index, this is the OID of the
+       index being used; otherwise, it is zero.
+      
+     
+
+     
+      
+       heap_tuples_scanned bigint
+      
+      
+       Number of heap tuples scanned.
+       This counter only advances when the phase is
+       seq scanning heap,
+       index scanning heap
+       or writing new heap.
+      
+     
+
+     
+      
+       heap_tuples_written bigint
+      
+      
+       Number of heap tuples written.
+       This counter only advances when the phase is
+       seq scanning heap,
+       index scanning heap
+       or writing new heap.
+      
+     
+
+     
+      
+       heap_blks_total bigint
+      
+      
+       Total number of heap blocks in the table.  This number is reported
+       as of the beginning of seq scanning heap.
+      
+     
+
+     
+      
+       heap_blks_scanned bigint
+      
+      
+       Number of heap blocks scanned.  This counter only advances when the
+       phase is seq scanning heap.
+      
+     
+
+     
+      
+       index_rebuild_count bigint
+      
+      
+       Number of indexes rebuilt.  This counter only advances when the phase
+       is rebuilding index.
+      
+     
+    
+   
+  
+
+  
+   CLUSTER and VACUUM FULL Phases
+   
+    
+    
+    
+    
+      Phase
+      Description
+     
+    
+
+   
+    
+     initializing
+     
+       The command is preparing to begin scanning the heap.  This phase is
+       expected to be very brief.
+     
+    
+    
+     seq scanning heap
+     
+       The command is currently scanning the table using a sequential scan.
+     
+    
+    
+     index scanning heap
+     
+       CLUSTER is currently scanning the table using an index scan.
+     
+    
+    
+     sorting tuples
+     
+       CLUSTER is currently sorting tuples.
+     
+    
+    
+     writing new heap
+     
+       CLUSTER is currently writing the new heap.
+     
+    
+    
+     swapping relation files
+     
+       The command is currently swapping newly-built files into place.
+     
+    
+    
+     rebuilding index
+     
+       The command is currently rebuilding an index.
+     
+    
+    
+     performing final cleanup
+     
+       The command is performing final cleanup.  When this phase is
+       completed, CLUSTER
+       or VACUUM FULL will end.
+     
+    
+   
+   
+  
+ 
+
+ 
+  COPY Progress Reporting
+
+  
+   pg_stat_progress_copy
+  
+
+  
+   Whenever COPY is running, the
+   pg_stat_progress_copy view will contain one row
+   for each backend that is currently running a COPY command.
+   The table below describes the information that will be reported and provides
+   information about how to interpret it.
+  
+
+  
+   <structname>pg_stat_progress_copy</structname> View
+   
+    
+     
+      
+       Column Type
+      
+      
+       Description
+      
+     
+    
+
+    
+     
+      
+       pid integer
+      
+      
+       Process ID of backend.
+      
+     
+
+     
+      
+       datid oid
+      
+      
+       OID of the database to which this backend is connected.
+      
+     
+
+     
+      
+       datname name
+      
+      
+       Name of the database to which this backend is connected.
+      
+     
+
+     
+      
+       relid oid
+      
+      
+       OID of the table on which the COPY command is
+       executed. It is set to 0 if copying from a
+       SELECT query.
+      
+     
+
+     
+      
+       command text
+      
+      
+       The command that is running: COPY FROM, or
+       COPY TO.
+      
+     
+
+     
+      
+       type text
+      
+      
+       The io type that the data is read from or written to:
+       FILE, PROGRAM,
+       PIPE (for COPY FROM STDIN and
+       COPY TO STDOUT), or CALLBACK
+       (used for example during the initial table synchronization in
+       logical replication).
+      
+     
+
+     
+      
+       bytes_processed bigint
+      
+      
+       Number of bytes already processed by COPY command.
+      
+     
+
+     
+      
+       bytes_total bigint
+      
+      
+       Size of source file for COPY FROM command in bytes.
+       It is set to 0 if not available.
+      
+     
+
+     
+      
+       tuples_processed bigint
+      
+      
+       Number of tuples already processed by COPY command.
+      
+     
+
+     
+      
+       tuples_excluded bigint
+      
+      
+       Number of tuples not processed because they were excluded by the
+       WHERE clause of the COPY command.
+      
+     
+    
+   
+  
+ 
+
  
   CREATE INDEX Progress Reporting
 
@@ -6333,235 +6689,9 @@ FROM pg_stat_get_backend_idset() AS backendid;
    rewrite the table, while regular VACUUM only modifies it
    in place. See .
   
-
-  
-   <structname>pg_stat_progress_vacuum</structname> View
-   
-    
-     
-      
-       Column Type
-      
-      
-       Description
-      
-     
-    
-
-    
-     
-      
-       pid integer
-      
-      
-       Process ID of backend.
-      
-     
-
-     
-      
-       datid oid
-      
-      
-       OID of the database to which this backend is connected.
-      
-     
-
-     
-      
-       datname name
-      
-      
-       Name of the database to which this backend is connected.
-      
-     
-
-     
-      
-       relid oid
-      
-      
-       OID of the table being vacuumed.
-      
-     
-
-     
-      
-       phase text
-      
-      
-       Current processing phase of vacuum.  See .
-      
-     
-
-     
-      
-       heap_blks_total bigint
-      
-      
-       Total number of heap blocks in the table.  This number is reported
-       as of the beginning of the scan; blocks added later will not be (and
-       need not be) visited by this VACUUM.
-      
-     
-
-     
-      
-       heap_blks_scanned bigint
-      
-      
-       Number of heap blocks scanned.  Because the
-       visibility map is used to optimize scans,
-       some blocks will be skipped without inspection; skipped blocks are
-       included in this total, so that this number will eventually become
-       equal to heap_blks_total when the vacuum is complete.
-       This counter only advances when the phase is scanning heap.
-      
-     
-
-     
-      
-       heap_blks_vacuumed bigint
-      
-      
-       Number of heap blocks vacuumed.  Unless the table has no indexes, this
-       counter only advances when the phase is vacuuming heap.
-       Blocks that contain no dead tuples are skipped, so the counter may
-       sometimes skip forward in large increments.
-      
-     
-
-     
-      
-       index_vacuum_count bigint
-      
-      
-       Number of completed index vacuum cycles.
-      
-     
-
-     
-      
-       max_dead_tuples bigint
-      
-      
-       Number of dead tuples that we can store before needing to perform
-       an index vacuum cycle, based on
-       .
-      
-     
-
-     
-      
-       num_dead_tuples bigint
-      
-      
-       Number of dead tuples collected since the last index vacuum cycle.
-      
-     
-    
-   
-  
-
-  
-   VACUUM Phases
-   
-    
-    
-    
-    
-      Phase
-      Description
-     
-    
-
-   
-    
-     initializing
-     
-       VACUUM is preparing to begin scanning the heap.  This
-       phase is expected to be very brief.
-     
-    
-    
-     scanning heap
-     
-       VACUUM is currently scanning the heap.  It will prune and
-       defragment each page if required, and possibly perform freezing
-       activity.  The heap_blks_scanned column can be used
-       to monitor the progress of the scan.
-     
-    
-    
-     vacuuming indexes
-     
-       VACUUM is currently vacuuming the indexes.  If a table has
-       any indexes, this will happen at least once per vacuum, after the heap
-       has been completely scanned.  It may happen multiple times per vacuum
-       if  (or, in the case of autovacuum,
-        if set) is insufficient to store
-       the number of dead tuples found.
-     
-    
-    
-     vacuuming heap
-     
-       VACUUM is currently vacuuming the heap.  Vacuuming the heap
-       is distinct from scanning the heap, and occurs after each instance of
-       vacuuming indexes.  If heap_blks_scanned is less than
-       heap_blks_total, the system will return to scanning
-       the heap after this phase is completed; otherwise, it will begin
-       cleaning up indexes after this phase is completed.
-     
-    
-    
-     cleaning up indexes
-     
-       VACUUM is currently cleaning up indexes.  This occurs after
-       the heap has been completely scanned and all vacuuming of the indexes
-       and the heap has been completed.
-     
-    
-    
-     truncating heap
-     
-       VACUUM is currently truncating the heap so as to return
-       empty pages at the end of the relation to the operating system.  This
-       occurs after cleaning up indexes.
-     
-    
-    
-     performing final cleanup
-     
-       VACUUM is performing final cleanup.  During this phase,
-       VACUUM will vacuum the free space map, update statistics
-       in pg_class, and report statistics to the cumulative
-       statistics system. When this phase is completed, VACUUM will end.
-     
-    
-   
-   
-  
-
- 
-
- 
-  CLUSTER Progress Reporting
-
-  
-   pg_stat_progress_cluster
-  
-
-  
-   Whenever CLUSTER or VACUUM FULL is
-   running, the pg_stat_progress_cluster view will
-   contain a row for each backend that is currently running either command.
-   The tables below describe the information that will be reported and
-   provide information about how to interpret it.
-  
-
-  
-   <structname>pg_stat_progress_cluster</structname> View
+
+  
+   <structname>pg_stat_progress_vacuum</structname> View
    
     
      
@@ -6607,16 +6737,7 @@ FROM pg_stat_get_backend_idset() AS backendid;
        relid oid
       
       
-       OID of the table being clustered.
-      
-     
-
-     
-      
-       command text
-      
-      
-       The command that is running. Either CLUSTER or VACUUM FULL.
+       OID of the table being vacuumed.
       
      
 
@@ -6625,81 +6746,81 @@ FROM pg_stat_get_backend_idset() AS backendid;
        phase text
       
       
-       Current processing phase. See -phases"/>.
+       Current processing phase of vacuum.  See -phases"/>.
       
      
 
      
       
-       cluster_index_relid oid
+       heap_blks_total bigint
       
       
-       If the table is being scanned using an index, this is the OID of the
-       index being used; otherwise, it is zero.
+       Total number of heap blocks in the table.  This number is reported
+       as of the beginning of the scan; blocks added later will not be (and
+       need not be) visited by this VACUUM.
       
      
 
      
       
-       heap_tuples_scanned bigint
+       heap_blks_scanned bigint
       
       
-       Number of heap tuples scanned.
-       This counter only advances when the phase is
-       seq scanning heap,
-       index scanning heap
-       or writing new heap.
+       Number of heap blocks scanned.  Because the
+       visibility map is used to optimize scans,
+       some blocks will be skipped without inspection; skipped blocks are
+       included in this total, so that this number will eventually become
+       equal to heap_blks_total when the vacuum is complete.
+       This counter only advances when the phase is scanning heap.
       
      
 
      
       
-       heap_tuples_written bigint
+       heap_blks_vacuumed bigint
       
       
-       Number of heap tuples written.
-       This counter only advances when the phase is
-       seq scanning heap,
-       index scanning heap
-       or writing new heap.
+       Number of heap blocks vacuumed.  Unless the table has no indexes, this
+       counter only advances when the phase is vacuuming heap.
+       Blocks that contain no dead tuples are skipped, so the counter may
+       sometimes skip forward in large increments.
       
      
 
      
       
-       heap_blks_total bigint
+       index_vacuum_count bigint
       
       
-       Total number of heap blocks in the table.  This number is reported
-       as of the beginning of seq scanning heap.
+       Number of completed index vacuum cycles.
       
      
 
      
       
-       heap_blks_scanned bigint
+       max_dead_tuples bigint
       
       
-       Number of heap blocks scanned.  This counter only advances when the
-       phase is seq scanning heap.
+       Number of dead tuples that we can store before needing to perform
+       an index vacuum cycle, based on
+       .
       
      
 
      
       
-       index_rebuild_count bigint
+       num_dead_tuples bigint
       
       
-       Number of indexes rebuilt.  This counter only advances when the phase
-       is rebuilding index.
+       Number of dead tuples collected since the last index vacuum cycle.
       
      
     
    
   
 
-  cluster-phases">
-   <span class="marked">CLUSTER and VACUUM FULL</span> Phases
+  vacuum-phases">
+   <span class="marked">VACUUM</span> Phases
    
     
     
@@ -6714,52 +6835,64 @@ FROM pg_stat_get_backend_idset() AS backendid;
     
      initializing
      
-       The command is preparing to begin scanning the heap.  This phase is
-       expected to be very brief.
-     
-    
-    
-     seq scanning heap
-     
-       The command is currently scanning the table using a sequential scan.
+       VACUUM is preparing to begin scanning the heap.  This
+       phase is expected to be very brief.
      
     
     
-     index scanning heap
+     scanning heap
      
-       CLUSTER is currently scanning the table using an index scan.
+       VACUUM is currently scanning the heap.  It will prune and
+       defragment each page if required, and possibly perform freezing
+       activity.  The heap_blks_scanned column can be used
+       to monitor the progress of the scan.
      
     
     
-     sorting tuples
+     vacuuming indexes
      
-       CLUSTER is currently sorting tuples.
+       VACUUM is currently vacuuming the indexes.  If a table has
+       any indexes, this will happen at least once per vacuum, after the heap
+       has been completely scanned.  It may happen multiple times per vacuum
+       if  (or, in the case of autovacuum,
+        if set) is insufficient to store
+       the number of dead tuples found.
      
     
     
-     writing new heap
+     vacuuming heap
      
-       CLUSTER is currently writing the new heap.
+       VACUUM is currently vacuuming the heap.  Vacuuming the heap
+       is distinct from scanning the heap, and occurs after each instance of
+       vacuuming indexes.  If heap_blks_scanned is less than
+       heap_blks_total, the system will return to scanning
+       the heap after this phase is completed; otherwise, it will begin
+       cleaning up indexes after this phase is completed.
      
     
     
-     swapping relation files
+     cleaning up indexes
      
-       The command is currently swapping newly-built files into place.
+       VACUUM is currently cleaning up indexes.  This occurs after
+       the heap has been completely scanned and all vacuuming of the indexes
+       and the heap has been completed.
      
     
     
-     rebuilding index
+     truncating heap
      
-       The command is currently rebuilding an index.
+       VACUUM is currently truncating the heap so as to return
+       empty pages at the end of the relation to the operating system.  This
+       occurs after cleaning up indexes.
      
     
     
      performing final cleanup
      
-       The command is performing final cleanup.  When this phase is
-       completed, CLUSTER
-       or VACUUM FULL will end.
+       VACUUM is performing final cleanup.  During this phase,
+       VACUUM will vacuum the free space map, update statistics
+       in pg_class, and report statistics to the cumulative
+       statistics system. When this phase is completed, VACUUM will end.
      
     
    
@@ -6942,140 +7075,6 @@ FROM pg_stat_get_backend_idset() AS backendid;
 
  
 
- 
-  COPY Progress Reporting
-
-  
-   pg_stat_progress_copy
-  
-
-  
-   Whenever COPY is running, the
-   pg_stat_progress_copy view will contain one row
-   for each backend that is currently running a COPY command.
-   The table below describes the information that will be reported and provides
-   information about how to interpret it.
-  
-
-  
-   <structname>pg_stat_progress_copy</structname> View
-   
-    
-     
-      
-       Column Type
-      
-      
-       Description
-      
-     
-    
-
-    
-     
-      
-       pid integer
-      
-      
-       Process ID of backend.
-      
-     
-
-     
-      
-       datid oid
-      
-      
-       OID of the database to which this backend is connected.
-      
-     
-
-     
-      
-       datname name
-      
-      
-       Name of the database to which this backend is connected.
-      
-     
-
-     
-      
-       relid oid
-      
-      
-       OID of the table on which the COPY command is
-       executed. It is set to 0 if copying from a
-       SELECT query.
-      
-     
-
-     
-      
-       command text
-      
-      
-       The command that is running: COPY FROM, or
-       COPY TO.
-      
-     
-
-     
-      
-       type text
-      
-      
-       The io type that the data is read from or written to:
-       FILE, PROGRAM,
-       PIPE (for COPY FROM STDIN and
-       COPY TO STDOUT), or CALLBACK
-       (used for example during the initial table synchronization in
-       logical replication).
-      
-     
-
-     
-      
-       bytes_processed bigint
-      
-      
-       Number of bytes already processed by COPY command.
-      
-     
-
-     
-      
-       bytes_total bigint
-      
-      
-       Size of source file for COPY FROM command in bytes.
-       It is set to 0 if not available.
-      
-     
-
-     
-      
-       tuples_processed bigint
-      
-      
-       Number of tuples already processed by COPY command.
-      
-     
-
-     
-      
-       tuples_excluded bigint
-      
-      
-       Number of tuples not processed because they were excluded by the
-       WHERE clause of the COPY command.
-      
-     
-    
-   
-  
- 
-