free-space-map

PostgreSQL Free Space Map tracking uses a 3-level tree structure with category encoding to monitor available space within heap pages. This mechanism facilitates efficient storage utilization by allowing operations to find and reuse existing space rather than unnecessarily extending relations.

INSERT operations extend relations when the Free Space Map fails to reconcile available space properly, often due to VACUUM issues or lock protocol conflicts. Debugging the FSM tree structure and category encoding helps identify why space tracking is failing.

Debug VACUUM space reconciliation by systematically analyzing the Free Space Map category encoding for the target relation. This approach identifies potential reconciliation issues and verifies if VACUUM is correctly updating the FSM tree structure for page reuse.

Modifying PostgreSQL storage logic requires strict lock protocols for safe interaction with heap and index storage. Proper WAL and locking discipline must be maintained when implementing new FSM consumers to prevent data corruption and ensure space tracking accuracy.

FSM category encoding limitations stem from its 3-level tree structure granularity, which may not capture exact byte-level free space. When space reconciliation fails, INSERT or COPY operations cannot find available space, causing unexpected relation extension instead of page reuse.