JSONB columns: what they are good for and when a column is better

What it is

PostgreSQL has two JSON types. The documentation states that json stores an exact copy of the input text, while jsonb stores a decomposed binary form that does not preserve white space, key order or duplicate keys, is slightly slower to input and significantly faster to process, and supports indexing; it recommends jsonb for most applications. Containment (@>), key existence (?) and JSON path operators (@?, @@) can use a GIN index; the non-default operator class jsonb_path_ops does not support the key-existence operators but is usually much smaller than the default class and typically searches better. The design section recommends documents with a somewhat fixed structure and a manageable size, because any update locks the whole row.

Why it matters

jsonb removes migrations for attributes that change often or are defined by someone else: webhook payloads, user-defined fields, per-tenant settings. Used for core data it removes the database's ability to enforce types, uniqueness and references, and it moves every validation into application code, where each writer must repeat it.

How to apply

• Use jsonb for raw payloads kept for audit, sparse attributes that differ per record type, settings read and written as a whole, and data whose schema is owned by another system.
• Use columns for anything filtered, joined, aggregated or sorted in most queries, anything with a foreign key, uniqueness or CHECK, and for money, dates and identifiers that need their own types.
• Index with GIN (col jsonb_path_ops) for containment queries; for one hot key, an expression index on (col->>'key') or a generated column is smaller and supports equality and range scans.
• Constrain the shape with a CHECK using jsonb_typeof on required keys, or validate against a JSON Schema before writing; document the expected keys next to the column.
• Update paths with jsonb_set or || rather than round-tripping through the application, keeping in mind that the row version is rewritten either way.

Pitfalls

Choosing json because it looks simpler: it cannot be indexed the same way and preserves duplicates and key order that jsonb drops. The documentation notes that jsonb rejects the \u0000 escape and numbers outside the numeric range. Large documents updated field by field cause bloat and lock contention. A GIN index does not help ORDER BY or range predicates on a key.