From 62d37de2ddad70e168095c8b671f38cb144a9228 Mon Sep 17 00:00:00 2001 From: Radim Marek Date: Sun, 27 Sep 2026 08:46:18 -0700 Subject: [PATCH v3] doc: Document REPACK limits and point to VACUUM for wraparound REPACK (CONCURRENTLY) uses some memory per concurrently updated or deleted row and fails after about 100 million of them. Document that, and say that VACUUM, not REPACK, is the tool to prevent wraparound. Discussion: https://postgr.es/m/CAJgoLk+dodrwuwCuXERGYwgjQzSwrKd+xgitYrL32oWDt39zvA@mail.gmail.com --- doc/src/sgml/ref/repack.sgml | 71 ++++++++++++++++++++++++------------ 1 file changed, 48 insertions(+), 23 deletions(-) diff --git a/doc/src/sgml/ref/repack.sgml b/doc/src/sgml/ref/repack.sgml index 346cba89c90..a85f73f07ec 100644 --- a/doc/src/sgml/ref/repack.sgml +++ b/doc/src/sgml/ref/repack.sgml @@ -165,14 +165,19 @@ REPACK [ ( option [, ...] ) ] USING It is advisable to set to a reasonably large value (but not more than the amount of RAM you can dedicate to the REPACK operation) before repacking. + + + See below for additional resource requirements used when the + CONCURRENTLY option is given. + Parameters @@ -210,58 +215,61 @@ REPACK [ ( option [, ...] ) ] USING CONCURRENTLY Allow other transactions to use the table while it is being repacked. - Internally, REPACK copies the contents of the table + Without this option, REPACK copies the contents of the table (ignoring dead tuples) into a new file, sorted by the specified index, and also creates a new file for each index. Then it swaps the old and new files for the table and all the indexes, and deletes the old files. The ACCESS EXCLUSIVE lock is needed to make sure that the old files do not change during the processing because the changes would get lost due to the swap. - With the CONCURRENTLY option, the ACCESS - EXCLUSIVE lock is only acquired to swap the table and index - files. The data changes that took place during the creation of the new + With the CONCURRENTLY option, the bulk of the + operation is run with SHARE UPDATE EXCLUSIVE lock, + and the ACCESS EXCLUSIVE lock is only acquired + during the final phase to swap the table and index files. + The data changes that took place during the creation of the new table and index files are captured using logical decoding - () and applied before - the ACCESS EXCLUSIVE lock is requested. Thus the lock - is typically held only for the time needed to swap the files, which - should be pretty short. However, the time might still be noticeable if - too many data changes have been done to the table while - REPACK was waiting for the lock: those changes must - be processed just before the files are swapped, while the - ACCESS EXCLUSIVE lock is being held. + (see ) and applied before + the ACCESS EXCLUSIVE lock is requested. + Thus the lock is typically held only for the time needed to swap the + files, which should be pretty short. + However, the time might still be noticeable if too many data changes + have been done to the table while REPACK was + waiting for the lock: those changes must be processed just before + the files are swapped, while the ACCESS EXCLUSIVE + lock is being held. - Note that REPACK with the - CONCURRENTLY option does not try to order the rows + Note that REPACK (CONCURRENTLY) + does not try to order the rows inserted into the table after the repacking started. Also - note REPACK might fail to complete due to DDL - commands executed on the table by other transactions during the + note REPACK might fail to complete if DDL + commands are executed on the table by other transactions during the repacking. In addition to the temporary space requirements explained in , - the CONCURRENTLY option can add to the usage of - temporary space a bit more. The reason is that other transactions can - perform DML operations which cannot be applied to the new file until - REPACK has copied all the existing tuples from the - old file. Thus the tuples inserted into the old file during the copying - are also stored separately in a temporary file, until they can be - processed. + the CONCURRENTLY option causes the command + to require additional memory. + Each row that is updated or deleted takes a small additional amount + (16 bytes per row), not limited by , + and the command fails if more than about 104 million rows + are concurrently updated or deleted; though depending on + system memory pressure, the actual limit might be lower. The CONCURRENTLY option cannot be used in the following cases: @@ -380,14 +388,31 @@ REPACK [ ( option [, ...] ) ] USING Notes To repack a table, one must have the MAINTAIN privilege on the table. + + REPACK is primarily meant to remove bloat and, with + USING INDEX, to cluster the table, in order to improve + performance. Although it also advances the table's + relfrozenxid and relminmxid, + it is not a good way to prevent transaction ID or multixact ID wraparound: + it rewrites the whole table and all of its indexes, so it takes much longer + than VACUUM, and it can fail after most of the work + is done, especially with CONCURRENTLY on a busy table. + VACUUM is recommended for that instead (see + ). + When a table gets close to wraparound, VACUUM skips index + vacuuming on its own (see ), and its + INDEX_CLEANUP OFF + option can do the same earlier. + + REPACK refuses to process a table on which an invalid index exists. Such indexes must be dropped or reindexed by the user ahead of time. -- 2.47.3