debug_discard_caches

Definition PG 18 manual

When set to 1, each system catalog cache entry is invalidated at the first possible opportunity, whether or not anything that would render it invalid really occurred. Caching of system catalogs is effectively disabled as a result, so the server will run extremely slowly. Higher values run the cache invalidation recursively, which is even slower and only useful for testing the caching logic itself. The default value of 0 selects normal catalog caching behavior.

This parameter can be very helpful when trying to trigger hard-to-reproduce bugs involving concurrent catalog changes, but it is otherwise rarely needed. See the source code files inval.c and pg_config_manual.h for details.

This parameter is supported when DISCARD_CACHES_ENABLED was defined at compile time (which happens automatically when using the configure option --enable-cassert). In production builds, its value will always be 0 and attempts to set it to another value will raise an error.

How it works

debug_discard_caches invalidates system-catalog cache entries at the earliest opportunity; higher values recurse the behavior. Nonzero values make the server extremely slow to expose cache invalidation bugs.

It is supported only in builds compiled with DISCARD_CACHES_ENABLED, automatically associated with --enable-cassert. Production builds keep zero and reject attempts to change it.

The parameter tests correctness under pathological cache churn. It does not flush shared_buffers, the operating-system page cache, or ordinary query result caches. Its superuser context permits an authorized session change without a server restart.

Operational considerations

Leaving debug_discard_caches enabled after the bounded diagnostic or recovery task.

Running the experiment on the only copy of production data.

Underestimating log, core-file, temporary-file, WAL, CPU, or connection-slot amplification.

Treating a server that merely starts or completes a query as proof that data and behavior are correct.

Workload guidance

OLAP: Long analytical runs can amplify debug_discard_caches's debug overhead and artifacts. Prefer standard EXPLAIN and statistics first, and isolate any developer experiment from normal users.

OLTP: Do not tune production OLTP with debug_discard_caches. Enable it only for a bounded reproduction with an owner, log/disk budget, rollback condition, and evidence-capture plan; restore the default immediately afterward.

SMALL: Keep debug_discard_caches at its upstream default. A small host has less spare CPU, disk, connection, and log capacity for developer instrumentation.