Subject: Doc: shared_memory_size_in_huge_pages with the "SHOW" command.

From: Seino Yuki <[email-masked]>
Date: Fri, 11 Oct 2024 17:25:04 +0900

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]"
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

Regards,
--
Yuki Seino
NTT DATA CORPORATION

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

---

From: Michael Paquier <[email-masked]>
Date: Wed, 16 Oct 2024 09:31:49 +0900

On Fri, Oct 11, 2024 at 05:25:04PM +0900, Seino Yuki wrote:
> This wording could be misunderstood to imply that the parameter cannot be
> accessed

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

---

From: Nathan Bossart <[email-masked]>
Date: Tue, 15 Oct 2024 20:26:06 -0500

> server is running as we don't want to allocate anything when tuning

Agreed.

> "*must* be shut down".  How about doing a simpler s/must/should/ for a

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

---

From: "David G. Johnston" <[email-masked]>
Date: Tue, 15 Oct 2024 18:46:44 -0700

> 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.

---

From: Michael Paquier <[email-masked]>
Date: Wed, 16 Oct 2024 14:18:16 +0900

> 	parameter with the postgres command.

I'm OK with the "postgres command" addition.
--
Michael

---

From: Fujii Masao <[email-masked]>
Date: Wed, 16 Oct 2024 15:31:05 +0900

> 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

---

From: Nathan Bossart <[email-masked]>
Date: Wed, 16 Oct 2024 09:44:27 -0500

>     before starting the server with a <command>postgres</command> command like:

WFM

-- 
nathan

---

From: Seino Yuki <[email-masked]>
Date: Thu, 17 Oct 2024 14:07:32 +0900

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 
I've fixed the patch and will register it in the CF.

Regards,
--
Yuki Seino
NTT DATA CORPORATION

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

---

From: Nathan Bossart <[email-masked]>
Date: Thu, 17 Oct 2024 16:59:54 -0500

> I've fixed the patch and will register it in the CF.

Thanks.  Here is what I have staged for commit.

-- 
nathan
>From 8aff8ec54a6588614f952693f509b75bf240851c Mon Sep 17 00:00:00 2001
From: Nathan Bossart <[email-masked]>
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)

---

From: Michael Paquier <[email-masked]>
Date: Fri, 18 Oct 2024 07:10:08 +0900

> Thanks.  Here is what I have staged for commit.

Fine by me.  Thanks.
--
Michael

---

From: Fujii Masao <[email-masked]>
Date: Fri, 18 Oct 2024 14:47:37 +0900

>> Thanks.  Here is what I have staged for commit.

LGTM, too. Thanks!

Regards,

---

From: Nathan Bossart <[email-masked]>
Date: Fri, 18 Oct 2024 10:22:51 -0500

> On 2024/10/18 7:10, Michael Paquier wrote:

Committed.

-- 
nathan