PostgreSQL Maintenance Storage Formulas

Units and scope

The PostgreSQL maintenance tools use decimal units: 1 GB equals 1,000,000,000 bytes, 1 MB equals 1,000,000 bytes, and 1 TB equals 1,000 GB. Convert database and operating-system readings before entering them. A filesystem's free space is a boundary, not an asset total: do not add capacity from another mount unless the operation actually writes there.

Reserve and minimum free space

Every capacity tool applies an editable reserve:

usable free GB = current free GB × (1 − reserve percentage ÷ 100)

Headroom is usable free GB minus the modeled operation need. To reverse the calculation:

minimum current free GB = operation need GB ÷ (1 − reserve fraction)

The reserve must stay below 100% so the denominator remains positive. It is a planning assumption chosen from measurement variance and response time, not a PostgreSQL default.

VACUUM FULL rewrite equations

Current footprint equals current table and TOAST GB plus current index GB. Modeled rewritten footprint equals expected new table and TOAST GB plus expected rebuilt index GB. Additional operation space is rewritten footprint plus concurrent growth. Potential reclaimed footprint is the positive difference between current and rewritten footprints. This is conservative because it asks free disk to cover all entered new outputs together; it intentionally does not claim a universal peak for every version or index method.

Index build equations

Total new index output equals expected output per index multiplied by the number built at once. Peak additional need adds temporary sort or build files and concurrent write growth. CREATE INDEX, REINDEX, and concurrent variants share the byte equation because the tool asks for observed output and work allowances. Their lock, scan, wait, and failure behavior differs and must be checked in official documentation.

WAL retention equations

Generated WAL is measured GB/hour multiplied by lag hours. Projected retention adds existing retained bytes. Time to the reserved disk boundary is:

(usable WAL disk GB − existing retained WAL GB) ÷ WAL GB/hour

When a positive slot cap is entered, the same equation uses the cap as its capacity. Safe lag is the smaller non-negative time. The model does not round to WAL segments or add several consumers, because their retained segment ranges can overlap.

Base backup feedback equation

Decimal MB/s becomes GB/hour by multiplying by 3.6. When streamed WAL shares that rate, net progress equals stream GB/hour minus WAL GB/hour. If net progress is zero or negative, the simple continuous-stream model has no finite completion. Otherwise:

duration hours = base payload GB ÷ net progress GB/hour

WAL generated during backup equals WAL rate multiplied by duration. Per-copy target footprint is base payload plus that WAL, and total target footprint multiplies by copies. The base payload must already reflect the selected format and compression behavior.

Worked cross-check

For a 1,200 GB base payload at 180 MB/s, stream rate is 648 GB/hour. With 24 GB/hour of WAL, net progress is 624 GB/hour and duration is 1.9231 hours. Generated WAL is 46.1538 GB, so one target copy is 1,246.1538 GB. A 2,000 GB target with 15% reserve has 1,700 GB usable and about 453.8462 GB headroom.

Source hierarchy and limitations

The behavior basis is the official PostgreSQL documentation for VACUUM, CREATE INDEX, REINDEX, replication slots, and pg_basebackup. The equations do not encode a server version, provider quota, tablespace map, compression ratio, bloat estimate, or storage price.

Return to the PostgreSQL Maintenance Storage hub to run the matching preflight. Save raw measurements, commands, documentation version, and actual peak after execution so later planning can replace estimates with evidence.