huge_pages

Controls explicit huge-page use for PostgreSQL’s main shared-memory area on supported operating systems.

Note

Fact — official short description: “Use of huge pages on Linux or Windows.”

Identity

Type , Valueenum: Upstream pg_settings type
Context , Valuepostmaster: Requires a server restart
Unit , Value—: Raw unit
Range , Value—: Raw limits in the last observed version
Enum values , Valueoff, on, try: — for non-enum types
Category , ValueResource Usage / Memory: Upstream classification
Latest boot value , Valuetry: try

Lifecycle

Fact	Value
First observed	PG9.4
Present in	PG9.4–19 Beta 3
Removed in	No
Introduction commit	`f8ce16d0d264` — Rename huge_tlb_pages to huge_pages, and improve docs.
Commit date	2014-03-03
Discussion	—

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions	Raw `boot_val`	Unit	Human value
PG9.4–19 Beta 3	`try`	—	try

How it works

huge_pages affects the main shared-memory area and is evaluated only at server start. try requests huge pages and falls back to normal pages, on makes failure fatal, and off skips the request.

Explicit huge pages can reduce page-table size and CPU time spent on memory management, especially with a large contiguous shared-memory allocation. On Linux, PostgreSQL requires shared_memory_type=mmap and enough pre-provisioned huge pages; huge_pages_status reports the actual outcome.

Explicit HugeTLB pages are not the same as Linux Transparent Huge Pages. PostgreSQL documentation currently discourages THP for some Linux versions even while describing explicit huge pages as potentially beneficial.

Tuning advice

Tip

Advice. These are workload-specific starting points and must be validated with measurements.

Workload	Guidance
OLTP	Use try while validating operating-system provisioning and huge_pages_status. Switch to on only when failure to obtain huge pages should deliberately block startup and the reservation is managed reliably across reboots.
OLAP	Large shared-memory footprints may benefit more, but calculate the required page count and leave memory for backends, query workspaces, and the OS. Benchmark rather than treating huge pages as an automatic throughput win.
Small nodes	Leave try or use off when huge-page reservation would create more operational complexity than benefit. Do not reserve a large fraction of a small host without a complete memory budget.

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	`try`	same as boot	`try`
OLAP	`try`	same as boot	`try`
CRIT	`try`	same as boot	`try`
TINY	`try`	same as boot	`try`

Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.4–19 Beta 3 = try (dcs); OLAP: PG9.4–19 Beta 3 = try (dcs); CRIT: PG9.4–19 Beta 3 = try (dcs); TINY: PG9.4–19 Beta 3 = try (dcs). Advice, pending human review — Editorial inference: this preserves opportunistic use when the node is provisioned while keeping startup safe when huge pages are unavailable; OS-level reservation policy must be reviewed separately.

Common pitfalls

Confusing explicit huge pages with Transparent Huge Pages.
Setting on before provisioning enough pages, causing PostgreSQL startup to fail.
Assuming the setting covers work_mem or other ordinary per-process allocations; it targets the main shared-memory area.
Checking configuration but not the runtime huge_pages_status result.

huge_page_size · huge_pages_status · shared_buffers · shared_memory_type · min_dynamic_shared_memory