PostgreSQL Tutorial: Enabling Linux Huge Pages

Summary: Using Huge Pages reduces the memory page table size of PostgreSQL processes and cuts down CPU overhead spent on memory management, thereby improving overall database performance.

Table of Contents

Introduction

Enabling Huge Pages is a highly effective performance optimization technique for PostgreSQL, especially under large-scale data processing and high-concurrency workloads.

By default, Linux uses a standard memory page size of 4KB. When you allocate dozens of gigabytes of shared_buffers to PostgreSQL, the operating system must manage millions of individual memory pages. This forces the CPU to consume significant processing time maintaining the Page Table. Huge Pages (typically 2MB in size) greatly alleviates this overhead.

When Should You Enable Huge Pages?

You can determine whether to enable Huge Pages based on the following key indicators:

1. shared_buffers exceeds 1GB

This is the most straightforward criterion.

• If your shared_buffers is set to a small value (hundreds of megabytes), the default 4KB pages are sufficient, and Huge Pages will deliver negligible performance gains.
• Once shared_buffers reaches 2GB to 8GB or higher, the page table grows substantially. Enabling Huge Pages reduces TLB (Translation Lookaside Buffer) misses and significantly improves CPU efficiency.

2. Large total system memory

On servers with 64GB, 128GB, or even larger memory capacity, page table entries consume massive amounts of physical memory. Huge Pages reclaim hundreds of megabytes to multiple gigabytes of memory for actual application workload usage.

3. High kernel CPU utilization with low I/O wait

When observing CPU metrics via top or htop, if the %sys (kernel-space CPU) ratio is abnormally high while database I/O wait remains low and there are no frequent system calls, the bottleneck is most likely excessive CPU overhead from page table lookups (TLB misses).

4. High-concurrency connection workloads

Every PostgreSQL backend process maps to the shared_buffers region. With a large number of connections (hundreds of processes), each process maintains its own large page table mapping. Huge Pages drastically eliminates this redundant overhead.

Benefits and Risks of Enabling Huge Pages

Configuration Steps

Step 1: Check PostgreSQL Huge Page Requirements

You can run a test command to check the recommended number of Huge Pages required by PostgreSQL.

The runtime parameter shared_memory_size_in_huge_pages reports the required Huge Page count. Run the following command with the postgres binary before starting the database service:

$ postgres -D $PGDATA -C shared_memory_size_in_huge_pages
1091

Step 2: Operating System Configuration (Linux)

Calculate the required number of Huge Pages and apply system kernel configuration. For example, to allocate 1091 pieces of 2MB Huge Pages (totaling 2.1GB):

$ sysctl -w vm.nr_hugepages=1091

To make the setting permanent, edit /etc/sysctl.conf and add:

vm.nr_hugepages=1091

Apply the configuration immediately:

sysctl -p

Step 3: Validation

Start the PostgreSQL service and verify successful Huge Page activation.

Run the following command to inspect system Huge Page status:

grep Huge /proc/meminfo

Configuration is successful if:

• HugePages_Rsvd > 0 (Huge Pages have been reserved)
• The value of HugePages_Free decreases correspondingly

Example output:

$ grep Huge /proc/meminfo
AnonHugePages:     14336 kB
ShmemHugePages:        0 kB
FileHugePages:         0 kB
HugePages_Total:    1091
HugePages_Free:     1025
HugePages_Rsvd:     1025
HugePages_Surp:        0
Hugepagesize:       2048 kB
Hugetlb:         2234368 kB

This confirms PostgreSQL has successfully utilized Huge Pages.

You may also verify via the PostgreSQL system parameter huge_pages_status:

show huge_pages_status;
 huge_pages_status
-------------------
 on
(1 row)

A result of on validates that the configuration is fully active.

See more

PostgreSQL Optimization