On Linux, why run PostgreSQL's shared memory on huge pages, and how do you size vm.nr_hugepages and confirm the server actually got them?
answer
- page tables per backend
- try, on or off
- a runtime-computed parameter read with -C
- a status setting added in 17
basics
~10 sHuge pages shrink page tables and memory-management CPU for a large shared_buffers. Size vm.nr_hugepages from postgres -C shared_memory_size_in_huge_pages, and check SHOW huge_pages_status, since the default huge_pages = try silently falls back.
solid answer
~40 sA multi-gigabyte `shared_buffers` mapped with ordinary 4 kB pages costs page-table memory and CPU in every backend that touches it; huge pages (2MB or 1GB) cut that overhead. `huge_pages` (restart) is `try` by default, `on` refuses to start without them, `off` never asks. To size the kernel pool, run `postgres -D $PGDATA -C shared_memory_size_in_huge_pages` on the stopped server: it reports the pages the whole main shared memory area needs, which is more than `shared_buffers` divided by the page size. Set `vm.nr_hugepages` to at least that, persist it in `/etc/sysctl.conf`, and after starting check `SHOW huge_pages_status` (on, off), available since 17, because `try` falls back to normal pages without failing. Transparent huge pages are a different kernel feature the manual discourages.
code
bash · 6 linespostgres -D "$PGDATA" -C shared_memory_size_in_huge_pages
grep ^Hugepagesize /proc/meminfo
sysctl -w vm.nr_hugepages=8600
echo 'vm.nr_hugepages = 8600' >> /etc/sysctl.conf
pg_ctl -D "$PGDATA" start
psql -c 'SHOW huge_pages_status;'go deeper
Know that huge pages are a Linux feature for PostgreSQL's large shared memory, and that the huge_pages setting defaults to try.
Explain why page tables per backend grow with shared_buffers, and the difference between try, on and off.
Show you size the pool from shared_memory_size_in_huge_pages, persist the sysctl, verify huge_pages_status and decide whether on is worth the start-up risk.
Treat huge page reservation as part of host provisioning, so a resize of shared_buffers and the kernel pool always change together.
## Why huge pages help PostgreSQL PostgreSQL's main shared memory area, dominated by `shared_buffers`, is mapped by **every backend process**. With ordinary 4 kB pages, a 16 GB area is about four million pages, and each process that touches them needs its own page-table entries. With many connections that adds up to real memory spent on page tables and CPU spent on address translation. The manual sums it up: huge pages give **smaller page tables and less CPU time spent on memory management**. They only apply to the main shared memory area; per-backend memory such as `work_mem` is unaffected. ## The settings | setting | default | context | meaning | |---|---|---|---| | `huge_pages` | `try` | restart | `try` requests them and falls back; `on` fails start-up without them; `off` never requests them | | `huge_page_size` | `0` | restart | `0` uses the kernel default (often 2MB); can ask for 2MB or 1GB pages | | `shared_memory_size_in_huge_pages` | computed | read-only | huge pages needed for the main shared memory area | | `huge_pages_status` | computed | read-only | `on` or `off` in a running server (`unknown` under `postgres -C`); added in 17 | On Linux the feature also needs the default `shared_memory_type = mmap`, and it works on Linux and Windows only. ## Sizing the kernel pool 1. Stop the server, or prepare the configuration before first start. 2. Ask PostgreSQL how many pages it needs: `postgres -D $PGDATA -C shared_memory_size_in_huge_pages`. The number covers the whole area, including structures beyond `shared_buffers`, so it is larger than `shared_buffers` divided by the page size. 3. Check the kernel's page size with `grep ^Hugepagesize /proc/meminfo`. 4. Reserve at least that many: `sysctl -w vm.nr_hugepages=<n>`, and persist it in `/etc/sysctl.conf` (or a boot parameter), adding headroom if other programs also use huge pages. 5. Where needed, allow the database user to use them through `vm.hugetlb_shm_group` and the locked-memory limit. 6. Start PostgreSQL and verify. Fragmentation can stop the kernel from reserving all requested pages on a long-running machine; the manual suggests retrying or setting them right after a reboot. ## Confirming the result With the default `try`, a shortage is **silent**: PostgreSQL logs nothing fatal and runs on normal pages. That is the trap after a reboot that lost an unpersisted sysctl, or after `shared_buffers` grew past the reserved pool. Two ways to check: - `SHOW huge_pages_status;` returns `on` or `off` in PostgreSQL 17 and 18. - On 16 and older, compare `HugePages_Total`, `HugePages_Free` and `HugePages_Rsvd` in `/proc/meminfo` before and after start-up. If running on normal pages is unacceptable, set `huge_pages = on`: the server then refuses to start without enough huge pages, which turns a silent performance regression into a loud start-up failure. That trade suits a dedicated server whose sysctl is managed; `try` remains the safer default where start-up must never fail. ## A worked example On a 64 GB logistics server with `shared_buffers = 16GB` and 2MB huge pages: - 16 GB divided by 2MB is 8192 pages, but `shared_memory_size_in_huge_pages` reports a somewhat higher number because the main shared memory area also holds WAL buffers, lock tables and other shared structures; - reserve that number plus a little headroom, for example about 8600, and persist it; - those pages are taken out of ordinary memory as soon as they are reserved, whether or not PostgreSQL uses them, so a reservation far above the need wastes RAM that sorts and the page cache could have used; - when `shared_buffers` is later raised, recompute the count first, or the next start falls back to normal pages under `try` or fails under `on`. ## Transparent huge pages are something else Linux **transparent huge pages (THP)** promote ordinary memory to huge pages automatically, without PostgreSQL asking. The manual reports performance degradation with PostgreSQL on some Linux versions and discourages THP, as opposed to the explicit huge pages above. Kernel-side reading of memory figures is an operating-system subject.
- Why would you set huge_pages = on instead of leaving the default try?With `try`, a shortage of huge pages makes PostgreSQL fall back to normal pages without failing, so a reboot that lost the sysctl, or a larger `shared_buffers`, quietly costs performance. `on` makes start-up fail instead, which surfaces the problem at once; the price is that the server will not start until the kernel pool is fixed.
- Are Linux transparent huge pages the same thing as PostgreSQL's huge_pages setting?No. `huge_pages` makes PostgreSQL explicitly request huge pages for its main shared memory area from a reserved kernel pool. Transparent huge pages are the kernel promoting ordinary memory on its own; the PostgreSQL manual reports degradation with them on some Linux versions and discourages their use.
- Enabling transparent huge pages is how PostgreSQL uses huge pages.
- With huge_pages = try, PostgreSQL refuses to start if huge pages run out.
- huge_pages can be switched on with a reload while the server runs.
- Huge pages also back each backend's work_mem and sort memory.
- vm.nr_hugepages should equal shared_buffers divided by 2MB exactly.
Assumes PostgreSQL 18; huge_pages_status exists since 17, so on 16 and older you confirm huge page use from /proc/meminfo instead.