Include PostgreSQL TOAST and indexes when explaining table storage

Separate heap, wide-value, and index storage before interpreting a PostgreSQL table-size difference.

Source facts

PostgreSQL 17 describes table storage as more than its main heap file. Wide values can live in an associated TOAST table with its own index, and the base table can have additional indexes. Relations may span more than one physical file. The manual recommends SQL size functions for ordinary monitoring. Its catalog-inspection examples use relpages, but that value updates through VACUUM, ANALYZE, and certain DDL commands rather than continuously reflecting every storage change.

Source: PostgreSQL 17 — Monitoring Disk Usage.

Applicability

This applies to PostgreSQL 17 table-footprint investigation. It concerns component accounting and catalog-estimate freshness, not service-user quotas, filesystem cleanup, or replacing raw database files.

DSE recommendation

DSE recommends recording whether a reported size refers to the heap alone or includes its associated storage before comparing capacity reports. Have the database owner identify significant wide-value and index contributions using supported SQL inspection. Record how fresh any catalog-derived estimate is and use the recommended size functions where appropriate. Avoid labeling an unexplained difference as corruption or wasted space without checking what each measurement includes. Keep any proposed index or data-retention change separate from this read-only investigation.

Verification

In a disposable database, compare storage measurements for a table with wide values and additional indexes. Review the components separately and observe catalog estimates before and after suitable analysis or maintenance. Retain query definitions and timestamps so reports with different scopes are not compared as equivalent measurements.

Official reference

PostgreSQL 17 — Monitoring Disk Usage. Reviewed October 15, 2026.