Doc: shared_memory_size_in_huge_pages with the "SHOW" command.
Hello,
Add a reference method for shared_memory_size_in_huge_pages
with the "SHOW" command.
The current documentation explains the use of the postgres -C command,
but this method may be limited in DBaaS or managed service environments.
In particular, CloudNativePG does not allow the server to be stopped,
making the execution of $ postgres -C impossible.
Alternatively, the "SHOW" command can be used, though the documentation
states,
"Note that the server must be shut down to view this runtime-computed
parameter.[1]https://www.postgresql.org/docs/devel/kernel-resources.html#LINUX-HUGE-PAGES"
This wording could be misunderstood to imply that the parameter cannot
be accessed
while the server is running.
[1]: https://www.postgresql.org/docs/devel/kernel-resources.html#LINUX-HUGE-PAGES
https://www.postgresql.org/docs/devel/kernel-resources.html#LINUX-HUGE-PAGES
Regards,
--
Yuki Seino
NTT DATA CORPORATION
Attachments:
v1-0001-shared_memory_size_in_huge_pages_using_show.patchtext/x-diff; name=v1-0001-shared_memory_size_in_huge_pages_using_show.patchDownload
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 2c4d5ef640..aaac025c90 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1441,6 +1441,17 @@ $ <userinput>grep ^Hugepagesize /proc/meminfo</userinput>
Hugepagesize: 2048 kB
$ <userinput>ls /sys/kernel/mm/hugepages</userinput>
hugepages-1048576kB hugepages-2048kB
+</programlisting>
+
+ If the server is running, this parameter can be viewed using the
+ <command>SHOW</command> command.
+ This might look like:
+<programlisting>
+postgres=# <userinput>SHOW shared_memory_size_in_huge_pages;</userinput>
+ shared_memory_size_in_huge_pages
+----------------------------------
+ 3170
+(1 row)
</programlisting>
In this example the default is 2MB, but you can also explicitly request
On Fri, Oct 11, 2024 at 05:25:04PM +0900, Seino Yuki wrote:
Alternatively, the "SHOW" command can be used, though the documentation
states,
"Note that the server must be shut down to view this runtime-computed
parameter.[1]"
This wording could be misunderstood to imply that the parameter cannot be
accessed
while the server is running.
I am not sure that neither mentioning nor recommending SHOW for this
area is a good idea, the point being to encourage its use before the
server is running as we don't want to allocate anything when tuning
it.
Point taken that the current wording can be confusing because of the
"*must* be shut down". How about doing a simpler s/must/should/ for a
softer wording?
--
Michael
On Wed, Oct 16, 2024 at 09:31:49AM +0900, Michael Paquier wrote:
I am not sure that neither mentioning nor recommending SHOW for this
area is a good idea, the point being to encourage its use before the
server is running as we don't want to allocate anything when tuning
it.
Agreed.
Point taken that the current wording can be confusing because of the
"*must* be shut down". How about doing a simpler s/must/should/ for a
softer wording?
Well, the point is that you can't use "postgres -C" to view this GUC while
the server is running. I can see how the present wording might be
misinterpreted, though. Perhaps we should change this sentence to
something like:
Note that the server must be shut down to view this runtime-computed
parameter with the postgres command.
--
nathan
On Friday, October 11, 2024, Seino Yuki <seinoyu@oss.nttdata.com> wrote:
The current documentation explains the use of the postgres -C command,
but this method may be limited in DBaaS or managed service environments.
In particular, CloudNativePG does not allow the server to be stopped,
making the execution of $ postgres -C impossible.
If your environment doesn’t allow shutting down the Postgres service it
seems highly unlikely you’d be able to perform the other low-level
operating system actions required here as well.
I think the wording is fine as-is, though for consistency with an earlier
mention on the page we could instead write:
This parameter can be viewed before starting the server with a postgres command
like:
David J.
On Tue, Oct 15, 2024 at 08:26:06PM -0500, Nathan Bossart wrote:
Well, the point is that you can't use "postgres -C" to view this GUC while
the server is running. I can see how the present wording might be
misinterpreted, though. Perhaps we should change this sentence to
something like:Note that the server must be shut down to view this runtime-computed
parameter with the postgres command.
I'm OK with the "postgres command" addition.
--
Michael
On 2024/10/16 14:18, Michael Paquier wrote:
On Tue, Oct 15, 2024 at 08:26:06PM -0500, Nathan Bossart wrote:
Well, the point is that you can't use "postgres -C" to view this GUC while
the server is running. I can see how the present wording might be
misinterpreted, though. Perhaps we should change this sentence to
something like:Note that the server must be shut down to view this runtime-computed
parameter with the postgres command.I'm OK with the "postgres command" addition.
Another idea is to use the same wording as for num_os_semaphores in runtime.sgml, like this:
This parameter can be viewed
before starting the server with a <command>postgres</command> command like:
Regards,
--
Fujii Masao
Advanced Computing Technology Center
Research and Development Headquarters
NTT DATA CORPORATION
On Wed, Oct 16, 2024 at 03:31:05PM +0900, Fujii Masao wrote:
Another idea is to use the same wording as for num_os_semaphores in runtime.sgml, like this:
This parameter can be viewed
before starting the server with a <command>postgres</command> command like:
WFM
--
nathan
Thank you, everyone.
the point being to encourage its use before the server is running
as we don't want to allocate anything when tuning it.
I was mistaken and now understand that it needs to be run before the
server is running.
Another idea is to use the same wording as for num_os_semaphores in
runtime.sgml, like this:WFM
I've fixed the patch and will register it in the CF.
Regards,
--
Yuki Seino
NTT DATA CORPORATION
Attachments:
v2-0001-shared_memory_size_in_huge_pages_docfix.patchtext/x-diff; name=v2-0001-shared_memory_size_in_huge_pages_docfix.patchDownload
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 2c4d5ef640..63669f2d2e 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1431,9 +1431,9 @@ export PG_OOM_ADJUST_VALUE=0
the operating system to provide enough huge pages of the desired size.
To determine the number of huge pages needed, use the
<command>postgres</command> command to see the value of
- <xref linkend="guc-shared-memory-size-in-huge-pages"/>. Note that the
- server must be shut down to view this runtime-computed parameter.
- This might look like:
+ <xref linkend="guc-shared-memory-size-in-huge-pages"/>. This parameter
+ can be viewed before starting the server with a <command>postgres</command>
+ command like:
<programlisting>
$ <userinput>postgres -D $PGDATA -C shared_memory_size_in_huge_pages</userinput>
3170
On Thu, Oct 17, 2024 at 02:07:32PM +0900, Seino Yuki wrote:
I've fixed the patch and will register it in the CF.
Thanks. Here is what I have staged for commit.
--
nathan
Attachments:
v3-0001-Adjust-documentation-for-configuring-Linux-huge-p.patchtext/plain; charset=us-asciiDownload
From 8aff8ec54a6588614f952693f509b75bf240851c Mon Sep 17 00:00:00 2001
From: Nathan Bossart <nathan@postgresql.org>
Date: Thu, 17 Oct 2024 16:56:52 -0500
Subject: [PATCH v3 1/1] Adjust documentation for configuring Linux huge pages.
The present wording about viewing shared_memory_size_in_huge_pages
seems to suggest that the parameter cannot be viewed after startup
at all, whereas the intent is to make it clear that you can't use
"postgres -C" to view this GUC while the server is running. This
commit rephrases this section to remove the ambiguity.
Author: Seino Yuki
Reviewed-by: Michael Paquier, David G. Johnston, Fujii Masao
Discussion: https://postgr.es/m/420584fd274f9ec4f337da55ffb3b790%40oss.nttdata.com
Backpatch-through: 15
---
doc/src/sgml/runtime.sgml | 9 ++++-----
1 file changed, 4 insertions(+), 5 deletions(-)
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 2c4d5ef640..a47fa67b38 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1429,11 +1429,10 @@ export PG_OOM_ADJUST_VALUE=0
with <varname>CONFIG_HUGETLBFS=y</varname> and
<varname>CONFIG_HUGETLB_PAGE=y</varname>. You will also have to configure
the operating system to provide enough huge pages of the desired size.
- To determine the number of huge pages needed, use the
- <command>postgres</command> command to see the value of
- <xref linkend="guc-shared-memory-size-in-huge-pages"/>. Note that the
- server must be shut down to view this runtime-computed parameter.
- This might look like:
+ The runtime-computed parameter
+ <xref linkend="guc-shared-memory-size-in-huge-pages"/> reports the number
+ of huge pages required. This parameter can be viewed before starting the
+ server with a <command>postgres</command> command like:
<programlisting>
$ <userinput>postgres -D $PGDATA -C shared_memory_size_in_huge_pages</userinput>
3170
--
2.39.5 (Apple Git-154)
On Thu, Oct 17, 2024 at 04:59:54PM -0500, Nathan Bossart wrote:
Thanks. Here is what I have staged for commit.
Fine by me. Thanks.
--
Michael
On 2024/10/18 7:10, Michael Paquier wrote:
On Thu, Oct 17, 2024 at 04:59:54PM -0500, Nathan Bossart wrote:
Thanks. Here is what I have staged for commit.
Fine by me. Thanks.
LGTM, too. Thanks!
Regards,
--
Fujii Masao
Advanced Computing Technology Center
Research and Development Headquarters
NTT DATA CORPORATION