JSONB and when to use it

A document column, not an escape hatch

JSONB is the right choice for data whose shape genuinely varies per row: third-party payloads, user-defined fields, event properties. It is binary, indexable, and queryable.

It is the wrong choice for fields every row has. Those deserve real columns with real types and real constraints — a JSONB blob has none of that, and typos in key names fail silently.

Index it with a GIN index when you filter on containment. Without one, every query reads and parses every document in the table.