From e4062138e2d45e4f2719514b7169580cc5657237 Mon Sep 17 00:00:00 2001 From: Sami Imseih Date: Tue, 22 Sep 2026 20:22:13 +0000 Subject: [PATCH v2 1/2] doc: Improve REPACK phase documentation for long or unbounded steps For REPACK (CONCURRENTLY), the "initializing" phase also covers enabling logical decoding and then initializing it, and the latter waits for the transactions that had already been assigned a transaction ID to end, so describing the phase as very brief is misleading. Say what the two steps are, what they wait for, and when the first one has nothing to do. Also document that the "catch-up" phase covers the wait for the ACCESS EXCLUSIVE lock needed to swap the files, which is where a REPACK (CONCURRENTLY) blocked by a conflicting lock appears to sit, and that the phase is specific to the concurrent mode. Discussion: https://postgr.es/m/CAN12%2BYJOeOyPYB5JS28VE_%2Brzg%3DRbzQXfj58TGfMYwv-TX9mJA%40mail.gmail.com Backpatch-through: 19 --- doc/src/sgml/monitoring.sgml | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml index 62dadf3e86c..4c5057e7592 100644 --- a/doc/src/sgml/monitoring.sgml +++ b/doc/src/sgml/monitoring.sgml @@ -7601,7 +7601,15 @@ 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 backends to + acknowledge that they started writing the additional WAL information + that logical decoding requires. Initializing then waits for the + transactions that had already been assigned a transaction ID to end, so + this phase can last as long as the longest of those transactions. @@ -7633,7 +7641,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. -- 2.50.1