Lesson 7 of 8

TOAST: How PostgreSQL Stores Oversized Values

Applies to PostgreSQL 13–17 Last reviewed May 2026 Grounded in source

The one thing to understand first

A tuple must fit within a single 8KB page — PostgreSQL does not span a row across blocks. So how does a text column hold a megabyte? The answer is TOAST (The Oversized-Attribute Storage Technique), implemented in src/backend/access/common/toast_internals.c and detoast.c. When a row would be too big, TOAST compresses and/or moves large field values out of the main tuple.

Your wide columns may not live in your table at all — they live in a hidden side table, fetched only when you touch them. Once you know that, a “small” table with a huge on-disk footprint, a slow SELECT * that only needed an integer, and mysterious TOAST bloat all stop being mysteries.

varlena: the variable-length header

Variable-length types (text, bytea, jsonb, arrays, numeric) begin with a varlena header. The header encodes the total length and a flag indicating whether the value is stored inline, compressed, or as an out-of-line pointer. Reading such a value always passes through detoast_attr(), which transparently fetches and decompresses as needed — callers just see the full value.

This is a Pro lesson

Get every Learning Pathway and cookbook recipe — grounded in PostgreSQL source code, with diagnostics, fixes, and prevention for each topic.

Continue this lesson to learn:

  • The threshold and the four strategies
  • The TOAST relation
  • Compression: pglz and LZ4
  • Layer 3 — Watch it happen on your own database
  • Layer 4 — The levers this hands you
  • Layer 5 — What an Oracle DBA should expect vs what they get
  • All 36 Learning Pathway lessons
  • 170+ cookbook recipes
  • Source-grounded diagnostics & fixes

Secure checkout Cancel anytime Source-grounded

Was this helpful?

← Back to 01 — Foundations: PostgreSQL Internals 101