effective_cache_size

Definition PG 18 manual

Sets the planner's assumption about the effective size of the disk cache that is available to a single query. This is factored into estimates of the cost of using an index; a higher value makes it more likely index scans will be used, a lower value makes it more likely sequential scans will be used. When setting this parameter you should consider both PostgreSQL's shared buffers and the portion of the kernel's disk cache that will be used for PostgreSQL data files, though some data might exist in both places. Also, take into account the expected number of concurrent queries on different tables, since they will have to share the available space. This parameter has no effect on the size of shared memory allocated by PostgreSQL, nor does it reserve kernel disk cache; it is used only for estimation purposes. The system also does not assume data remains in the disk cache between queries. If this value is specified without units, it is taken as blocks, that is BLCKSZ bytes, typically 8kB. The default is 4 gigabytes (4GB). (If BLCKSZ is not 8kB, the default value scales proportionally to it.)

How it works

effective_cache_size is a cost-model input. Higher values make index scans look more attractive; lower values make sequential scans more attractive.

The estimate should reflect both shared_buffers and the portion of the operating-system page cache likely to hold PostgreSQL data, while accounting for overlap and for concurrent queries sharing the same cache capacity.

Changing this parameter does not resize PostgreSQL shared memory, reserve kernel cache, or guarantee that pages remain cached between queries. Its effect is indirect, through plan selection.

Operational considerations

Expecting the setting to allocate or reserve memory.

Setting it equal to installed RAM without subtracting memory unavailable to PostgreSQL caching.

Ignoring that concurrent queries on different data sets share the effective cache.

Overstating it and then attributing index-heavy plan choices to unrelated cost parameters.

Workload guidance

OLAP: Large scans can evict or compete with cached data, so do not equate installed RAM with cache available to a single analytical query. Calibrate against representative mixed and cold-cache runs.

OLTP: Estimate the cache actually usable by PostgreSQL after OS and co-located service needs, then validate index-heavy plans with EXPLAIN. Avoid copying a fixed percentage from a host with different concurrency or working-set behavior.

SMALL: Leave room for the OS and other services; a value near total RAM is usually an overstatement on a shared small host. Treat it as a planner estimate, not a memory target.