From bd2aebd7a7fe38b8ad832a10d5bfd1d841f048d8 Mon Sep 17 00:00:00 2001 From: Masahiko Sawada Date: Wed, 23 Sep 2026 14:57:48 -0700 Subject: [PATCH] doc: Clarify phase descriptions of pg_stat_progress_repack. The "initializing" phase was described as expected to be very brief, but for REPACK (CONCURRENTLY), it also covers enabling and initializing logical decoding, either of which can take a long time. Also, the "catch-up" phase includes waiting for the ACCESS EXCLUSIVE lock needed to swap the files, which was not mentioned. Adding separate progress phases for these steps is left for v20; for v19 we only clarify the description. Author: Sami Imseih Reviewed-by: Masahiko Sawada Reviewed-by: Manuel Reyes Bravo Discussion: https://postgr.es/m/CAN12%2BYJOeOyPYB5JS28VE_%2Brzg%3DRbzQXfj58TGfMYwv-TX9mJA%40mail.gmail.com Backpatch-through: 19 --- doc/src/sgml/monitoring.sgml | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml index 62dadf3e86c..0d038de1a23 100644 --- a/doc/src/sgml/monitoring.sgml +++ b/doc/src/sgml/monitoring.sgml @@ -7601,7 +7601,19 @@ 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. + expected to be very brief, except for + REPACK CONCURRENTLY, where it also covers enabling + logical decoding and then initializing it. Enabling has nothing to do + if is already + logical; otherwise it waits for all processes to + acknowledge that they started writing the additional WAL information + that logical decoding requires. Initializing then waits for the + transactions that have been assigned a transaction ID to end, including + ones that started while this wait was in progress, so this phase can + last longer than the longest transaction running when the command + started. This includes any other + REPACK CONCURRENTLY, which holds a transaction ID + until it finishes. @@ -7633,7 +7645,10 @@ FROM pg_stat_get_backend_idset() AS backendid; REPACK CONCURRENTLY is currently processing the DML commands that other transactions executed during any of the preceding - phases. + phases. This phase also covers waiting for the ACCESS + EXCLUSIVE lock needed to swap the files, so a command blocked + by a conflicting lock stays in this phase. + This phase is skipped when not in concurrent mode.