From 85a0a67c5ee3b377100bc8d4cb5f7f3a87544876 Mon Sep 17 00:00:00 2001 From: Sami Imseih Date: Tue, 22 Sep 2026 20:22:13 +0000 Subject: [PATCH v4 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 have 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. The wait is not bounded by the transactions that were running when the command started, because the snapshot builder also has to wait for the ones that start while the wait is in progress, so say that too. Mention as well that another REPACK (CONCURRENTLY) holds a transaction ID for its whole duration, which is easy to be surprised by. 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. 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. -- 2.50.1