From c28d6624ef34c250edddac27e981e58b27cc5919 Mon Sep 17 00:00:00 2001 From: Michael Renner Date: Wed, 13 May 2015 11:59:21 +0200 Subject: [PATCH 1/3] Document pg_repack behavior --- doc/pg_repack.rst | 34 ++++++++++++++++++++++++++++------ 1 file changed, 28 insertions(+), 6 deletions(-) diff --git a/doc/pg_repack.rst b/doc/pg_repack.rst index 5bf243b..26b6552 100644 --- a/doc/pg_repack.rst +++ b/doc/pg_repack.rst @@ -429,13 +429,35 @@ earlier versions which could result in data corruption. Details ------- -To perform full table repacks, pg_repack creates a work table in the "repack" -schema and sorts the rows in this table. Then, it updates the system catalogs -directly to swap the work table and the original one. +Full table repack +^^^^^^^^^^^^^^^^^ -To perform index only repacks, pg_repack creates its work index on the target -table and then updates the system catalogs directly to swap the work index and -the original index. +To perform a full table repack, pg_repack will: + +* create a log table for changes +* create a trigger on the old table to log all changes to the table +* create a new table containing all data in the old table +* create all indexes on the new table +* apply all changes from the log table to the new table +* switch all table files in the system catalog +* drop the old table + +pg_repack will only acquire ACCESS EXCLUSIVE locks when creating the trigger and when +switching the table files, all other operations are lock-free on the source table. + + +Index only repack +^^^^^^^^^^^^^^^^^ + +To perform a index only repack, pg_repack will: + +* create a new index on the table using CONCURRENTLY +* swap the index in the catalog +* drop the old index + +Creating indexes concurrently comes with a few caveats, please see `the documentation`__ for details. + + .. __: http://www.postgresql.org/docs/current/static/sql-createindex.html#SQL-CREATEINDEX-CONCURRENTLY Releases From c375c2009d02ffe5648f82126763f88e405b7d99 Mon Sep 17 00:00:00 2001 From: Michael Renner Date: Wed, 13 May 2015 14:47:56 +0200 Subject: [PATCH 2/3] wording --- doc/pg_repack.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/pg_repack.rst b/doc/pg_repack.rst index 26b6552..037d71c 100644 --- a/doc/pg_repack.rst +++ b/doc/pg_repack.rst @@ -434,12 +434,12 @@ Full table repack To perform a full table repack, pg_repack will: -* create a log table for changes -* create a trigger on the old table to log all changes to the table +* create a log table +* create a trigger on the old table to log all changes to the log table * create a new table containing all data in the old table * create all indexes on the new table * apply all changes from the log table to the new table -* switch all table files in the system catalog +* when the log table is empty, swap the table in the system catalog * drop the old table pg_repack will only acquire ACCESS EXCLUSIVE locks when creating the trigger and when From 8fe2cf1296bccb688e2c67d1c2061d051fecd1c2 Mon Sep 17 00:00:00 2001 From: Josh Kupershmidt Date: Tue, 19 May 2015 20:10:25 -0400 Subject: [PATCH 3/3] Some further fixes/cleanup/wordsmithing of the doc changes. --- doc/pg_repack.rst | 39 +++++++++++++++++++++------------------ 1 file changed, 21 insertions(+), 18 deletions(-) diff --git a/doc/pg_repack.rst b/doc/pg_repack.rst index 037d71c..4492288 100644 --- a/doc/pg_repack.rst +++ b/doc/pg_repack.rst @@ -429,31 +429,34 @@ earlier versions which could result in data corruption. Details ------- -Full table repack -^^^^^^^^^^^^^^^^^ +Full Table Repacks +^^^^^^^^^^^^^^^^^^ -To perform a full table repack, pg_repack will: +To perform a full-table repack, pg_repack will: -* create a log table -* create a trigger on the old table to log all changes to the log table -* create a new table containing all data in the old table -* create all indexes on the new table -* apply all changes from the log table to the new table -* when the log table is empty, swap the table in the system catalog -* drop the old table +1. create a log table to record changes made to the original table +2. add a trigger onto the original table, logging INSERTs, UPDATEs and DELETEs into our log table +3. create a new table containing all the rows in the old table +4. build indexes on this new table +5. apply all changes which have accrued in the log table to the new table +6. swap the tables, including indexes and toast tables, using the system catalogs +7. drop the original table -pg_repack will only acquire ACCESS EXCLUSIVE locks when creating the trigger and when -switching the table files, all other operations are lock-free on the source table. +pg_repack will only hold an ACCESS EXCLUSIVE lock for a short period during +initial setup (steps 1 and 2 above) and during the final swap-and-drop phase +(steps 6 and 7). For the rest of its time, pg_repack only needs +to hold an ACCESS SHARE lock on the original table, meaning INSERTs, UPDATEs, +and DELETEs may proceed as usual. -Index only repack -^^^^^^^^^^^^^^^^^ +Index Only Repacks +^^^^^^^^^^^^^^^^^^ -To perform a index only repack, pg_repack will: +To perform an index-only repack, pg_repack will: -* create a new index on the table using CONCURRENTLY -* swap the index in the catalog -* drop the old index +1. create new indexes on the table using CONCURRENTLY matching the definitions of the old indexes +2. swap out the old for the new indexes in the catalogs +3. drop the old indexes Creating indexes concurrently comes with a few caveats, please see `the documentation`__ for details.