# shared_buffers

> shared_buffers — Sets the number of shared memory buffers used by the server. Observed in PG9.0–19 Beta 3; its last measured boot default is 128 MiB (16384 × 8kB) in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
---

> [!NOTE]
> **Fact — official short description:** “Sets the number of shared memory buffers used by the server.”

## Identity {#identity}

| Field | Value | Meaning |
| --- | --- | --- |
| Type | `integer` | Upstream pg_settings type |
| Context | `postmaster` | Requires a server restart |
| Unit | `8kB` | Raw unit |
| Range | `16` – `1073741823` | Raw limits in the last observed version |
| Enum values | — | — for non-enum types |
| Category | Resource Usage / Memory | Upstream classification |
| Latest boot value | `16384` | 128 MiB (16384 × 8kB) |
{.fields meta="-"}

## Lifecycle {#lifecycle}

| Fact | Value |
| --- | --- |
| First observed | PG9.0 (research boundary) |
| Present in | PG9.0–19 Beta 3 |
| Removed in | No |
| Introduction commit | Not asserted: predates the PG9.0 research boundary |
| Commit date | — |
| Discussion | — |

## Default history {#default-history}

| Versions | Raw `boot_val` | Unit | Human value |
| --- | --- | --- | --- |
| PG9.0–14 | `1024` | `8kB` | 8 MiB (1024 × 8kB) |
| PG15–19 Beta 3 | `16384` | `8kB` | 128 MiB (16384 × 8kB) |
{.full-width caption="Measured PG9.0–19 Beta 3 boot defaults"}

## How it works {#mechanism}

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.

## Tuning advice {#tuning-advice}

> [!TIP]
> **Advice.** These are workload-specific starting points and must be validated with measurements.

| Workload | Guidance |
| --- | --- |
| 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. |
| 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. |
| Small nodes | 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. |
{.full-width}

## Pigsty {#pigsty}

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG19 Beta 3; this does not assert current Pigsty support for that historical or beta release.

| Template | Effective value | Versus upstream boot | Source expression |
| --- | --- | --- | --- |
| OLTP | `8192MB` | different | `{{ pg_shared_buffers }}MB` |
| OLAP | `8192MB` | different | `{{ pg_shared_buffers }}MB` |
| CRIT | `8192MB` | different | `{{ pg_shared_buffers }}MB` |
| TINY | `8192MB` | different | `{{ pg_shared_buffers }}MB` |
{.full-width}

> [!CAUTION]
> **Advice — pending human review.** Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 8192MB (dcs); OLAP: PG9.0–19 Beta 3 = 8192MB (dcs); CRIT: PG9.0–19 Beta 3 = 8192MB (dcs); TINY: PG9.0–19 Beta 3 = 8192MB (dcs). Advice, pending human review — Editorial inference, pending maintainer review: Pigsty deliberately parameterizes real shared-buffer allocation instead of hard-coding the fixture's 8192MB; the published rationale must reference the host-memory sizing formula, not present 8192MB as a universal default.

## Common pitfalls {#common-pitfalls}

- 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.

## Related parameters {#related-parameters}

[`effective_cache_size`](/parameters/effective-cache-size/) · [`work_mem`](/parameters/work-mem/) · [`max_wal_size`](/parameters/max-wal-size/) · [`huge_pages`](/parameters/huge-pages/) · [`checkpoint_completion_target`](/parameters/checkpoint-completion-target/) · [`wal_buffers`](/parameters/wal-buffers/)

## References {#references}

- [PostgreSQL 19 Beta 3 — shared_buffers](https://www.postgresql.org/docs/19/runtime-config-resource.html#GUC-SHARED-BUFFERS)
- [PostgreSQL 19 release notes](https://www.postgresql.org/docs/19/release-19.html)
- [Machine-readable GUC export](/data/guc.jsonl)