huge_page_size

Definition PG 18 manual

Controls the size of huge pages, when they are enabled with huge_pages. The default is zero (0). When set to 0, the default huge page size on the system will be used. This parameter can only be set at server start.

Some commonly available page sizes on modern 64 bit server architectures include: 2MB and 1GB (Intel and AMD), 16MB and 16GB (IBM POWER), and 64kB, 2MB, 32MB and 1GB (ARM). For more information about usage and support, see Section 18.4.5.

Non-default settings are currently supported only on Linux.

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.

Operational considerations

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.

Workload guidance

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.

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.

SMALL: Keep 0. A nondefault explicit size adds kernel provisioning and startup-failure risk that rarely pays back on a small shared-memory allocation.