shared_buffers

Definition PG 18 manual

Sets the amount of memory the database server uses for shared memory buffers. The default is typically 128 megabytes (128MB), but might be less if your kernel settings will not support it (as determined during initdb). This setting must be at least 128 kilobytes. However, settings significantly higher than the minimum are usually needed for good performance. If this value is specified without units, it is taken as blocks, that is BLCKSZ bytes, typically 8kB. (Non-default values of BLCKSZ change the minimum value.) This parameter can only be set at server start.

If you have a dedicated database server with 1GB or more of RAM, a reasonable starting value for shared_buffers is 25% of the memory in your system. There are some workloads where even larger settings for shared_buffers are effective, but because PostgreSQL also relies on the operating system cache, it is unlikely that an allocation of more than 40% of RAM to shared_buffers will work better than a smaller amount. Larger settings for shared_buffers usually require a corresponding increase in max_wal_size, in order to spread out the process of writing large quantities of new or changed data over a longer period of time.

On systems with less than 1GB of RAM, a smaller percentage of RAM is appropriate, so as to leave adequate space for the operating system.

How it works

shared_buffers allocates PostgreSQL's real shared buffer cache at server start. Pages cached here are PostgreSQL-managed and coexist with the operating system page cache; the setting is not merely a planner estimate.

The PG10-14 Docker boot value in this catalog is 8MB while PG15-18 report 128MB, reflecting historical initdb/container defaults rather than a universal hardware recommendation. The official guidance treats about 25% of RAM as a starting point for a dedicated server and rarely expects more than 40% to help.

A larger cache changes checkpoint and WAL pressure, often requiring a larger max_wal_size, and leaves less memory for backend processes, work_mem, maintenance, extensions, and the OS. Buffer allocation uses BLCKSZ units, normally 8kB. Its postmaster context fixes the value at server start; changing it requires a restart.

Operational considerations

Changing shared_buffers without applying its documented unit and configuration context.

Optimizing an isolated benchmark while ignoring concurrent aggregate resource use.

Assuming a configured value guarantees operating-system or storage behavior.

Failing to retest startup, failover, and workload latency after the change.

Workload guidance

OLAP: Benchmark shared_buffers with representative bulk and scan phases. Include sustained throughput, spill/writeback, and interference with other sessions, not only one operation's elapsed time.

OLTP: Change shared_buffers only after identifying the corresponding resource bottleneck under concurrency. Budget total memory, I/O, disk, or kernel capacity rather than optimizing one process in isolation.

SMALL: Keep shared_buffers conservative on a small host and prefer the upstream default when evidence is weak. A setting copied from a large server can consume a disproportionate share of resources.