pg_repack: removing bloat from a live PostgreSQL table without locking it out

The gap between VACUUM FULL and what you actually need

The README states the problem precisely. pg_repack is a PostgreSQL extension that removes bloat from tables and indexes, and can optionally restore the physical order of clustered indexes. What distinguishes it from the two built-in commands is the locking behavior:

Unlike CLUSTER and VACUUM FULL it works online, without holding an exclusive lock on the processed tables during processing.

That single sentence is the entire reason this extension exists. VACUUM FULL rewrites the table into a new file and swaps it in, which returns the space but blocks every reader and writer on that table for the whole rewrite. On a large table that can be hours. CLUSTER has the same problem, since it also rewrites the table.

The README also addresses a performance question directly, saying pg_repack is efficient to boot, with performance comparable to using CLUSTER directly. That is the honest framing: this is not a way to rebuild a table faster than the built-in, it is a way to do it while your application keeps running.

The cost of that guarantee is extra disk space, since a rewrite needs somewhere to put the new copy, and some coordination work, which is why the tool is not a single command with no setup.

A descendant of pg_reorg, and the fork explains the design

The README includes a section answering a question readers always have, which is what the relationship is to pg_reorg. pg_repack is a fork of that project, which the README says has proven hugely successful, but notes that new feature development on the original has slowed or stopped since late 2011.

The first release of pg_repack was positioned as a drop-in replacement for pg_reorg, addressing shortcomings of the final pg_reorg version, specifically PostgreSQL 9.2 support and EXTENSION packaging, along with known bugs.

That history explains two things about the current codebase. The EXTENSION packaging mention matters practically: pg_reorg predates the modern extension packaging system, and pg_repack was written to work with it, which is why a Makefile target for PGXN submission exists. And the version numbers in the tree go back a long way, because this is a fork that inherited decades of work rather than a fresh implementation.

One warning in the README deserves attention. Version 1.2 introduced parallel index builds and the ability to rebuild only indexes, and the README says that in some cases its behavior may differ from the 1.1.x release, so it should not be considered a drop-in replacement from that point on. It advises checking the documentation before upgrading from previous versions. In other words, do not assume the pg_reorg compatibility claim still holds.

The Makefile is where the real requirements hide

The README is short and points you at a doc directory for installation and usage. The Makefile at the repository root is more informative about what the build actually requires, because it derives everything from your local PostgreSQL installation.

It calls out `pg_config` to determine the PostgreSQL version, and fails with an explicit error if it is not found:

PG_CONFIG ?= pg_config
EXTENSION = pg_repack

It then enforces a minimum version, and the check is worth noting because it is stricter than the README's history suggests:

ifeq ($(shell echo $$(($(INTVERSION) < 904))),1)
$(error $(EXTENSION) requires PostgreSQL 9.4 or later. This is $(VERSION))
endif

So despite the README mentioning PostgreSQL 9.2 support as a historical improvement over pg_reorg, the current build refuses anything below 9.4. If you are on an old cluster, this error message is where you will find out.

The version is extracted from pg_config and converted to a number, with a comment giving the example that 9.1.4 becomes 901. The extension's own version is read out of META.json rather than hardcoded, and a comment in the Makefile says to keep that consistent with the file. That is a small sign of a project that takes its release process seriously.

A PGXN extension with a regression suite, packaged for a version matrix

The tree is organized like a serious C extension rather than a single-file patch. There are separate `bin/` and `lib/` directories for the executable and the library, a `regress/` directory for tests, and a `doc/` directory that the README points at for installation and usage.

The regression suite is the part that tells you about the project's process. It is a PostgreSQL-style regression test setup, which means the extension's behavior is checked against expected output rather than merely compiling. Combined with the GitHub Actions badge at the top of the README for the regression workflow, that indicates continuous verification across versions.

Distribution is handled through PGXN, PostgreSQL's extension network. The README gives the download location at pgxn.org/dist/pg_repack/, and the Makefile has a target that produces the archive required for submission:

package: dist dist/$(EXTENSION)-$(EXTVERSION).zip

dist/$(EXTENSION)-$(EXTVERSION).zip:
	git archive --format zip --prefix=$(EXTENSION)-$(EXTVERSION)/ --output $@ master

Because the archive is produced from a named ref rather than a working tree, what you package is a specific commit, which is the correct behavior for a release.

There is also an `msvc/` directory for Windows builds, and a COPYRIGHT file retaining attributions from NTT and Itagaki Takahiro from the original pg_reorg era, alongside the Reorg Development Team.

Installing this needs the documentation, not the README

The README is explicit that it is not the place to look for setup instructions. It says to check the documentation, in the doc directory or online, for installation and usage, and points to reorg.github.io/pg_repack for the online version.

That is a reasonable division, since PostgreSQL extension builds vary meaningfully between major versions and between installation methods, and a README that tried to cover all of them would go stale immediately. The practical path is PGXN, which handles the version matrix for you, or a source build using the Makefile once you have confirmed your PostgreSQL version meets the 9.4 floor.

There is a related question worth planning for before you repack anything. Repacking is a rewrite, so it needs free disk space roughly equal to the size of the table and its indexes, and it has to be run by a user with the right privileges on the target tables. The README does not cover either requirement, so treat the doc directory and your own disk as the things to check.

One more structural note. The repository has no releases attached and no topic tags, so version history has to come from the changelog in the doc directory or from the PGXN page. The last push recorded is 2026-05-08, so the extension is being worked on, with 195 forks and 90 open issues.

Editorial conclusion

pg_repack fills a gap that PostgreSQL itself leaves open. VACUUM FULL reclaims space but takes an exclusive lock for the duration, and CLUSTER rewrites a table in index order but does the same, so on a table that people are actively reading neither is acceptable. This extension does the same work with only a brief lock, and the README is specific that it is efficient to start and comparable in performance to CLUSTER used directly. The packaging tells you how mature it is: this is a PGXN extension with a regression suite and versioned distribution archives, not a loose script, and it descends from pg_reorg. Because the repository carries no release history of its own and installation differs between PostgreSQL versions, follow the doc directory rather than guessing, and confirm your cluster's major version against the version requirement before you build.

Frequently asked questions

Official sources

1. Issues
2. License: BSD-3-Clause
3. README
4. reorg/pg_repack on GitHub