A single integer increment inside a 3.4 KB PostgreSQL JSONB column generated 142 MB of Write-Ahead Log (WAL) traffic across just 20,000 updates in my local benchmarkβnearly 8x more WAL than updating dedicated scalar columns for the exact same logical change.
On paper, JSONB looks like the cleanest way to store evolving payloads, webhook metadata, and background job states without constant schema migrations. In read-heavy workloads, it delivers. Under frequent single-key UPDATE traffic, however, JSONB becomes a quiet write-amplification engine that inflates disk IOPS, saturates replication bandwidth, and forces VACUUM into overtime.
Treating JSONB Like an In-Place Document Store
When building event pipelines, background job runners, or user preference stores, developers often collapse mutable state and static metadata into a single JSONB column:
CREATE TABLE webhook_deliveries (
id bigserial PRIMARY KEY,
payload jsonb NOT NULL
);
When a worker retries a delivery or records a heartbeat timestamp, the application runs jsonb_set():
UPDATE webhook_deliveries
SET payload = jsonb_set(
jsonb_set(payload, '{retry_count}', to_jsonb((payload->>'retry_count')::int + 1)),
'{updated_at}',
to_jsonb(now())
)
WHERE id = 42;
In application code, that looks like a tiny, surgical mutation. Inside PostgreSQL's storage engine, nothing about it is surgical.
MVCC, TOAST, and GIN Amplification
Three PostgreSQL storage mechanics collide whenever you mutate a key inside a moderately sized JSONB column:
1. Whole-Value Rewrites Under MVCC
PostgreSQL stores JSONB as a single binary value rather than individually addressable storage cells. Under Multi-Version Concurrency Control (MVCC), every UPDATE writes a brand-new row version. Even if only one integer inside payload changes, PostgreSQL must construct and serialize the entire JSONB binary object from scratchβand acquire a row-level lock on the whole tuple, as noted in the PostgreSQL Documentation: JSON Types.
2. Out-of-Line TOAST Chunk Churn
PostgreSQL uses a fixed 8 KB page size and does not allow a single tuple to span multiple pages directly. When a row exceeds TOAST_TUPLE_THRESHOLD (roughly 2 KB after compression), PostgreSQL's TOAST (The Oversized-Attribute Storage Technique) compresses the JSONB value and slices it into chunks inside a hidden pg_toast table.
Here is the catch:
- If an
UPDATEmodifies a normal scalar column and leaves the TOASTedJSONBcolumn untouched, PostgreSQL reuses the existing TOAST pointer in the new tuple. Zero TOAST chunks are rewritten. - If an
UPDATEmodifies even one byte inside thatJSONBcolumn, PostgreSQL allocates a brand-new TOAST value OID, writes every chunk topg_toastagain, logs all of those chunks to WAL, and leaves the old chunks behind as dead tuples.
3. GIN Index Maintenance and Lost HOT Updates
Most JSONB columns carry a GIN index to keep key lookups fast. Once a column is indexed, modifying it disqualifies the row from Heap-Only Tuple (HOT) updates. Instead of keeping the update localized to a single heap page, PostgreSQL must insert new index entriesβor push them into the GIN pending list (fastupdate = on), causing periodic latency spikes when a later query flushes the pending list.
Official References:
Pure JSONB vs. Hybrid Schema
To measure the exact overhead, I created two logged tables with 100,000 rows each. Each row contains ~3.4 KB of high-entropy JSONB data (using MD5 hashes so pglz/lz4 compression cannot shrink the payload below the 2 KB TOAST threshold).
Setup Script
-- Table 1: Everything inside a single JSONB column
CREATE TABLE events_jsonb (
id bigserial PRIMARY KEY,
payload jsonb NOT NULL
);
CREATE INDEX idx_events_jsonb_gin ON events_jsonb USING gin (payload);
-- Table 2: Mutable fields extracted to scalar columns + fillfactor for HOT updates
CREATE TABLE events_hybrid (
id bigserial PRIMARY KEY,
status text NOT NULL,
retry_count int NOT NULL,
updated_at timestamptz NOT NULL,
payload jsonb NOT NULL
) WITH (fillfactor = 80);
CREATE INDEX idx_events_hybrid_gin ON events_hybrid USING gin (payload);
CREATE INDEX idx_events_hybrid_status ON events_hybrid (status) WHERE status = 'pending';
-- Seed 100,000 rows (~3.4 KB incompressible JSONB per row)
INSERT INTO events_jsonb (payload)
SELECT jsonb_build_object(
'status', 'pending',
'retry_count', 0,
'updated_at', now(),
'customer_id', g,
'trace_chunks', (
SELECT jsonb_agg(md5(g::text || '-' || i::text))
FROM generate_series(1, 90) AS i
)
)
FROM generate_series(1, 100000) AS g;
INSERT INTO events_hybrid (status, retry_count, updated_at, payload)
SELECT
payload->>'status',
(payload->>'retry_count')::int,
(payload->>'updated_at')::timestamptz,
payload - 'status' - 'retry_count' - 'updated_at'
FROM events_jsonb;
VACUUM ANALYZE events_jsonb;
VACUUM ANALYZE events_hybrid;
Running 20,000 Single-Row Updates
-- Measure WAL and HOT updates on events_jsonb
SELECT pg_current_wal_lsn() AS lsn_before \gset
DO $$
BEGIN
FOR i IN 1..20000 LOOP
UPDATE events_jsonb
SET payload = jsonb_set(
jsonb_set(payload, '{retry_count}', to_jsonb((payload->>'retry_count')::int + 1)),
'{updated_at}',
to_jsonb(now())
)
WHERE id = (i % 100000) + 1;
END LOOP;
END $$;
SELECT
pg_size_pretty(pg_wal_lsn_diff(pg_current_wal_lsn(), :'lsn_before')) AS wal_generated,
pg_size_pretty(pg_total_relation_size('events_jsonb')) AS total_size,
pg_stat_get_tuples_hot_updated('events_jsonb'::regclass) AS hot_updates;
Running the same 20,000-iteration loop against events_hybrid updates only the unindexed scalar columns (retry_count and updated_at):
SELECT pg_current_wal_lsn() AS lsn_before \gset
DO $$
BEGIN
FOR i IN 1..20000 LOOP
UPDATE events_hybrid
SET retry_count = retry_count + 1,
updated_at = now()
WHERE id = (i % 100000) + 1;
END LOOP;
END $$;
SELECT
pg_size_pretty(pg_wal_lsn_diff(pg_current_wal_lsn(), :'lsn_before')) AS wal_generated,
pg_size_pretty(pg_total_relation_size('events_hybrid')) AS total_size,
pg_stat_get_tuples_hot_updated('events_hybrid'::regclass) AS hot_updates;
Benchmark Results
| Metric (20,000 Updates on 100k Rows) | Pure JSONB Schema |
Hybrid Schema (fillfactor = 80) |
Difference |
|---|---|---|---|
| WAL Generated | ~142 MB | ~18 MB | ~7.9x less WAL |
| TOAST Rewrites | 20,000 full blobs | 0 (pointer reused) | 100% eliminated |
| HOT Updates | 0 | ~19,800+ | No index writes |
| GIN Index Churn | Every update | None | Zero GIN bloat |
Hot Scalar Columns + Cold JSONB
You do not need to abandon JSONB to eliminate write amplification. Separate columns by mutation frequency:
-
Promote hot fields to native columns: Any field updated frequently (
status,retry_count,updated_at,worker_id,version) belongs in a typed scalar column. -
Keep
JSONBfor append-only or cold payloads: Store raw webhook bodies, arbitrary user metadata, or snapshot attributes inJSONBwhere they are written once and rarely mutated. -
Set
fillfactor = 80on update-heavy tables: Leaving 20% free space per 8 KB page allows PostgreSQL to place new row versions on the same page, unlocking HOT updates whenever indexed columns remain unchanged. -
Replace broad GIN indexes with targeted partial B-tree indexes: Instead of indexing the entire
JSONBdocument, index only the specific extracted column and status values your queries actually filter on.
Run this diagnostic query to compare main heap size against TOAST storage size and check your HOT update ratio: If How to check if your production tables suffer from TOAST churn
SELECT
relname AS table_name,
pg_size_pretty(pg_relation_size(relid)) AS heap_size,
pg_size_pretty(pg_total_relation_size(relid) - pg_relation_size(relid) - pg_indexes_size(relid)) AS toast_size,
n_tup_upd AS total_updates,
n_tup_hot_upd AS hot_updates,
ROUND(100.0 * n_tup_hot_upd / NULLIF(n_tup_upd, 0), 2) AS hot_update_pct
FROM pg_stat_user_tables
WHERE n_tup_upd > 0
ORDER BY (pg_total_relation_size(relid) - pg_relation_size(relid)) DESC
LIMIT 10;
toast_size dominates your table footprint while hot_update_pct sits near 0.00%, frequent JSONB mutations are likely driving your WAL and IOPS overhead.
When to Keep vs. Extract JSONB Fields
| Field Characteristic | Keep in JSONB
|
Extract to Scalar Column |
|---|---|---|
| Written once, read occasionally | Yes | No |
| Updated more than once per row lifecycle | No | Yes |
Used in WHERE clauses on hot paths |
Only with targeted index | Yes |
| Payload size regularly exceeds 2 KB | Yes (if immutable) | Yes (for mutable keys) |
Needs strict NOT NULL or foreign keys |
No | Yes |
Migration Checklist for Existing JSONB Tables
Before refactoring a production table, walk through these steps:
- [ ] Inspect
pg_stat_user_tables(n_tup_upd,n_tup_hot_upd) andpg_total_relation_sizevs.pg_relation_sizeto spot oversized TOAST tables. - [ ] Add nullable scalar columns for the top 2β4 frequently mutated keys.
- [ ] Dual-write to both the new scalar columns and
JSONBduring rollout, then backfill historical rows in batches. - [ ] Switch
UPDATEstatements to target only the scalar columns so PostgreSQL reuses existing TOAST pointers. - [ ] Tune
ALTER TABLE ... SET (fillfactor = 80)and drop redundant GIN indexes once query plans confirm index usage.
Quick Q&A
Does PostgreSQL compress JSONB automatically before TOASTing?
Yes. By default, JSONB uses the EXTENDED storage strategy, which attempts inline compression (pglz or lz4 depending on default_toast_compression) before moving values over ~2 KB out-of-line to pg_toast. However, high-entropy payloads (UUIDs, hashes, tokens, encrypted blobs) compress poorly and still trigger full TOAST rewrites on every mutation.
What if I use a GENERATED ALWAYS AS (...) STORED column for a JSONB key?
A stored generated column extracts the value for faster reads and indexing, but it does not eliminate JSONB write amplification if your UPDATE statement still mutates the source JSONB column. Make the scalar column the primary write target instead.
The Takeaway
JSONB is an outstanding read model for semi-structured data, but PostgreSQL's MVCC and TOAST architecture penalizes partial mutations on large documents. Extracting frequently updated keys into native scalar columns preserves schema flexibility for the payload while cutting WAL volume, TOAST churn, and index bloat by nearly an order of magnitude.
Have you ever caught a JSONB column quietly driving up your WAL size or IOPS in production? How did you refactor it?
Connect with Me
If you found this article helpful, let's connect!
- π» GitHub: johnnylemonny

Top comments (0)