PostgreSQL TOAST Visualized

Interactive visualization of PostgreSQL's TOAST machinery. Watch wide values get compressed, sliced into chunks, and relocated from the main heap into pg_toast, with the four storage strategies and two compression methods as live controls.

A PostgreSQL heap tuple cannot exceed the 8KB page, yet a single text or jsonb column can hold up to 1GB. TOAST is the trick. When a row would cross the 2KB threshold, PostgreSQL compresses its variable-length columns, slices the survivors into chunks, and stores them in a companion pg_toast_<oid> relation, leaving an 18-byte pointer behind on the main heap.

Pick an insert (tiny, compressible, incompressible, huge) and watch where the bytes land. Flip the storage strategy (EXTENDED, EXTERNAL, MAIN, PLAIN) and the compression method (pglz, lz4) and re-insert to see the redistribution change. UPDATE a row to watch its old chunks turn dead, then VACUUM to reclaim them. Click any heap tuple for the full TOAST pointer, or any chunk for its row in pg_toast.

Rows

Heap bytes

0 B

TOAST chunks

TOAST bytes

0 B

Dead chunks

sql>

-- pick an INSERT to begin

Storage strategy (ALTER COLUMN body SET STORAGE …)

EXTENDED EXTERNAL MAIN PLAIN

Compression (SET COMPRESSION …)

pglz lz4

toast_demo (id, label, body)

(no rows yet; pick an INSERT below)

pg_toast.pg_toast_16478 (chunk_id, chunk_seq, chunk_data)

(no out-of-line chunks yet)

INSERT row · body =

UPDATE existing row

Maintenance

Body storage mode

INLINE small enough to live in the heap tuple as-is

INLINE COMP compressed but still inline

OUT-OF-LINE moved to pg_toast as chunks (compressed if the compressor finds real gain; uncompressed if it bails out)

Try this

Insert the 32 KB incompressible blob, then watch chunks fan out.

Switch storage to EXTERNAL and re-insert the compressible one; compression is skipped.

UPDATE an out-of-line row; old chunks turn dead until VACUUM.

Click any tuple or chunk for the full state.

Inspector click any heap tuple or TOAST chunk

Learn More