Table rewrite preflight

PostgreSQL VACUUM FULL Disk Space Checker

Test a conservative rewritten relation working set against current free disk before an operation that cannot release its old files immediately.

Decision guide

Reclaiming table space first requires room for replacement files

What this tool helps you decide

This checker answers a narrow preflight question: does the filesystem have enough free space for the table, TOAST data, and index outputs you expect a PostgreSQL VACUUM FULL rewrite to create while the old relation still exists? It reports modeled operation space, usable free disk after reserve, headroom, minimum current free disk, and potential footprint reduction. It does not recommend VACUUM FULL merely because a table contains dead tuples.

Before you start

Measure the exact table and TOAST relation separately from its indexes, and identify their tablespaces. Estimate rewritten output from evidence such as live-tuple and free-space inspection, a representative copy, or an equivalent staging operation. Do not apply an invented shrink percentage. Measure filesystem free bytes immediately before the maintenance window. Add expected writes, temporary spill, and monitoring uncertainty as the concurrent growth allowance or reserve. Confirm that every entered file belongs to the same capacity boundary.

How the calculation works

Current footprint is current table plus current indexes. Rewritten footprint is expected new table plus expected rebuilt indexes. The conservative additional operation need is rewritten footprint plus concurrent growth. Usable free disk is current free disk multiplied by one minus the reserve fraction. Headroom is usable free disk minus operation need. Minimum free disk reverses the reserve equation. Potential reclaimed footprint is current footprint minus rewritten footprint, never shown below zero.

How to interpret the results

A pass means only that the entered byte model fits. Small positive headroom is fragile when estimates exclude another tablespace, write activity grows, indexes are larger than expected, or monitoring reports a different filesystem. A failure means the planned rewrite should not begin under these assumptions. Add storage, move the operation to a roomy tablespace, reduce scope, or choose a different maintenance approach after reviewing locks and recovery. Never delete database files manually to manufacture headroom.

Worked example

An 800 GB table with 240 GB of indexes currently occupies 1,040 GB. Evidence suggests a 560 GB rewritten table and 210 GB of rebuilt indexes. Adding 30 GB for concurrent growth produces an 800 GB operation need. A filesystem with 1,000 GB free and a 15% reserve supplies 850 GB of usable free space, so the preflight passes with 50 GB headroom. The modeled final footprint is 770 GB, or 270 GB below the current footprint.

Assumptions and limitations

PostgreSQL documentation states that VACUUM FULL writes a complete new table file and requires extra disk until the old copy can be released. This tool deliberately uses a conservative user-entered index output rather than claiming an exact internal peak for every PostgreSQL version, index method, tablespace layout, and failure path. It does not inspect a server, estimate locks or duration, model WAL, temp files outside the selected allowance, filesystem metadata, replicas, snapshots, copy-on-write amplification, or managed-service restrictions.

Next steps

Confirm the command and lock impact in the current official PostgreSQL VACUUM documentation. Capture relation and filesystem measurements with timestamps, alert below the selected reserve, and preserve a tested recovery path. If index work is the main boundary, use the Index Build & Reindex Space Planner. If replication lag or archive failure can retain WAL during the window, also run the WAL Retention & Replication Slot Planner.