From 13d5dd50956163cbd3268b1ab118aad801c78274 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Sat, 22 Oct 2016 14:04:51 -0400 Subject: [PATCH] Improve documentation about use of Linux huge pages. Show how to get the system's huge page size, rather than misleadingly referring to PAGE_SIZE (which is usually understood to be the regular page size). Show how to confirm whether huge pages have been allocated. Minor wordsmithing. Back-patch to 9.4 where this section appeared. --- doc/src/sgml/runtime.sgml | 64 ++++++++++++++++++++++++--------------- 1 file changed, 39 insertions(+), 25 deletions(-) diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml index eed55dd6db..7e7e9f8914 100644 --- a/doc/src/sgml/runtime.sgml +++ b/doc/src/sgml/runtime.sgml @@ -1375,53 +1375,67 @@ export PG_OOM_ADJUST_VALUE=0 - Linux huge pages + Linux Huge Pages Using huge pages reduces overhead when using large contiguous chunks of - memory, like PostgreSQL does. To enable this + memory, as PostgreSQL does, particularly when + using large values of . To use this feature in PostgreSQL you need a kernel with CONFIG_HUGETLBFS=y and - CONFIG_HUGETLB_PAGE=y. You also have to tune the system - setting vm.nr_hugepages. To estimate the number of - necessary huge pages start PostgreSQL without - huge pages enabled and check the VmPeak value from the - proc file system: + CONFIG_HUGETLB_PAGE=y. You will also have to adjust + the kernel setting vm.nr_hugepages. To estimate the + number of huge pages needed, start PostgreSQL + without huge pages enabled and check the + postmaster's VmPeak value, as well as the system's + huge page size, using the /proc file system. This might + look like: -$ head -1 /path/to/data/directory/postmaster.pid +$ head -1 $PGDATA/postmaster.pid 4170 $ grep ^VmPeak /proc/4170/status VmPeak: 6490428 kB +$ grep ^Hugepagesize /proc/meminfo +Hugepagesize: 2048 kB - 6490428 / 2048 - (PAGE_SIZE is 2MB in this case) are - roughly 3169.154 huge pages, so you will need at - least 3170 huge pages: + 6490428 / 2048 gives approximately + 3169.154, so in this example we need at + least 3170 huge pages, which we can set with: $ sysctl -w vm.nr_hugepages=3170 - Sometimes the kernel is not able to allocate the desired number of huge - pages, so it might be necessary to repeat that command or to reboot. Don't - forget to add an entry to /etc/sysctl.conf to persist - this setting through reboots. + A larger setting would be appropriate if other programs on the machine + also need huge pages. Don't forget to add this setting + to /etc/sysctl.conf so that it will be reapplied + after reboots. - It is also necessary to give the database server operating system + Sometimes the kernel is not able to allocate the desired number of huge + pages immediately, so it might be necessary to repeat the command or to + reboot. (Immediately after a reboot, most of the machine's memory + should be available to convert into huge pages.) To verify the huge + page allocation situation, use: + +$ grep Huge /proc/meminfo + + + + + It may also be necessary to give the database server's operating system user permission to use huge pages by setting - vm.hugetlb_shm_group via sysctl, and - permission to lock memory with ulimit -l. + vm.hugetlb_shm_group via sysctl, and/or + give permission to lock memory with ulimit -l. The default behavior for huge pages in PostgreSQL is to use them when possible and - to fallback to normal pages when failing. To enforce the use of huge - pages, you can set - huge_pages - to on. Note that in this case - PostgreSQL will fail to start if not enough huge - pages are available. + to fall back to normal pages when failing. To enforce the use of huge + pages, you can set + to on in postgresql.conf. + Note that with this setting PostgreSQL will fail to + start if not enough huge pages are available.