huge_page_size

huge_page_size — The size of huge page that should be requested. Observed in PG14–19 Beta 3; its last measured boot default is 0 B 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: “The size of huge page that should be requested.”

Identity

Type , Valueinteger: Upstream pg_settings type
Context , Valuepostmaster: Requires a server restart
Unit , ValuekB: Raw unit
Range , Value0 – 2147483647: Raw limits in the last observed version
Enum values , Value—: — for non-enum types
Category , ValueResource Usage / Memory: Upstream classification
Latest boot value , Value0: 0 B

Lifecycle

Fact	Value
First observed	PG14
Present in	PG14–19 Beta 3
Removed in	No
Introduction commit	`d2bddc2500fb` — Add huge_page_size setting for use on Linux.
Commit date	2020-07-17
Discussion	thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions	Raw `boot_val`	Unit	Human value
PG14–19 Beta 3	`0`	`kB`	0 B

How it works

huge_page_size selects the explicit huge-page size requested for PostgreSQL’s main shared-memory area when huge_pages is used. Zero means the operating system’s default huge-page size.

This is a startup allocation choice, not an amount of memory. Supported nonzero sizes are architecture and kernel dependent, and PostgreSQL currently supports nondefault selection only on Linux.

The requested page size must match provisioned huge-page pools and the shared-memory allocation. It affects the main shared area, not ordinary backend allocations such as work_mem. Its postmaster context fixes the value at server start; changing it requires a restart.

Tuning advice

Tip

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

Workload	Guidance
OLTP	Keep 0 so PostgreSQL uses the system’s default explicit huge-page size. Choose a nonzero size only on Linux after provisioning the matching huge-page pool and verifying startup plus huge_pages_status with the intended shared-memory footprint.
OLAP	A large main shared-memory region can make page-table savings material, but the useful size depends on architecture, kernel pools, fragmentation, and restart operations—not bulk-I/O throughput. Benchmark the exact host and preserve enough ordinary memory for backends and the OS.
Small nodes	Keep 0. A nondefault explicit size adds kernel provisioning and startup-failure risk that rarely pays back on a small shared-memory allocation.

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	Unmodified	—	—
OLAP	Unmodified	—	—
CRIT	Unmodified	—	—
TINY	Unmodified	—	—

Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG14–19 Beta 3 unmodified; OLAP: PG14–19 Beta 3 unmodified; CRIT: PG14–19 Beta 3 unmodified; TINY: PG14–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

Reading 0 as zero-byte huge pages rather than ‘use the system default huge-page size’.
Selecting a nonzero size on a non-Linux platform, where nondefault sizes are not supported.
Requesting a page size whose kernel pool has not been provisioned and causing startup failure when huge_pages=on.
Confusing explicit huge pages for the main shared-memory area with Transparent Huge Pages or per-backend memory.

huge_pages · huge_pages_status · shared_buffers · shared_memory_type · min_dynamic_shared_memory