From: Peter Eisentraut <peter.eisentraut@enterprisedb.com>
To: Daniel Gustafsson <daniel@yesql.se>
Cc: Jonathan S. Katz <jkatz@postgresql.org>
Cc: Pg Docs <pgsql-docs@lists.postgresql.org>
Subject: Re: confusing positioning of notes in connection settings
Date: Wed, 31 May 2023 07:16:56 -0400
Message-ID: <ab7511ea-a089-2445-f64d-0bf72ebb7bc4@enterprisedb.com> (raw)
In-Reply-To: <39202431-DF62-42E2-B0C1-500C93AD37C8@yesql.se>
References: <6f825d42-a1ce-492a-2ea7-c83e6e65fa8b@postgresql.org>
<4e34fcb4-6791-0266-7352-27b769c478f9@enterprisedb.com>
<D70737D3-C949-471A-9471-9E2C22C428F4@yesql.se>
<39202431-DF62-42E2-B0C1-500C93AD37C8@yesql.se>
On 26.04.23 07:36, Daniel Gustafsson wrote:
>> On 26 Apr 2023, at 10:18, Daniel Gustafsson <daniel@yesql.se> wrote:
>>
>>> On 26 Apr 2023, at 08:08, Peter Eisentraut <peter.eisentraut@enterprisedb.com> wrote:
>>
>>> I wonder if the notes are even true. The text for tcp_keepalives_interval already says that it is only supported if TCP_KEEPCNT is supported.
>
> Re-reading this I think there was some confusion, definitely so on my part.
>
> tcp_keepalives_interval relies on TCP_KEEPINTVL, with the Windows equivalent
> being SIO_KEEPALIVE_VALS. TCP_KEEPCNT is for tcp_keepalives_count which indeed
> is not supported on Windows. Jonathans original question was regarding _count
> and _timeout and not _interval.
>
> I do agree that all of these notes may just as well be added to the text, the
> option client_connection_check_interval following these have text about
> platform compatibility without using a note.
How about this patch?
The first two hunks are pretty straightforward, they just move the
existing text around.
For the other two, which are not supported on Windows, I added an
explicit parenthetical note. We don't list which of the Unix-like
platforms support the respective options, but I suspect that it's all of
them in practice? (Otherwise we should be more explicit.) So I think
calling out Windows explicitly is sensible, also considering that the
first two settings are supported on Windows but the latter two are not.
From 97fe489263f18314e99ec471ab160dbc026a1841 Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter@eisentraut.org>
Date: Wed, 31 May 2023 07:12:38 -0400
Subject: [PATCH] doc: Fix confusing positioning of notes in connection
settings
Discussion: https://www.postgresql.org/message-id/flat/6f825d42-a1ce-492a-2ea7-c83e6e65fa8b%40postgresql.org
---
doc/src/sgml/config.sgml | 30 ++++++------------------------
1 file changed, 6 insertions(+), 24 deletions(-)
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgmlindex 5da74b3c40..5873a0ef2f 100644--- a/doc/src/sgml/config.sgml+++ b/doc/src/sgml/config.sgml@@ -950,18 +950,14 @@ <title>TCP Settings</title>
the operating system should send a TCP keepalive message to the client.
If this value is specified without units, it is taken as seconds.
A value of 0 (the default) selects the operating system's default.
+ On Windows, setting a value of 0 will set this parameter to 2 hours,+ since Windows does not provide a way to read the system default value.
This parameter is supported only on systems that support
<symbol>TCP_KEEPIDLE</symbol> or an equivalent socket option, and on
Windows; on other systems, it must be zero.
In sessions connected via a Unix-domain socket, this parameter is
ignored and always reads as zero.
</para>
- <note>- <para>- On Windows, setting a value of 0 will set this parameter to 2 hours,- since Windows does not provide a way to read the system default value.- </para>- </note>
</listitem>
</varlistentry>
@@ -977,18 +973,14 @@ <title>TCP Settings</title>
that has not been acknowledged by the client should be retransmitted.
If this value is specified without units, it is taken as seconds.
A value of 0 (the default) selects the operating system's default.
+ On Windows, setting a value of 0 will set this parameter to 1 second,+ since Windows does not provide a way to read the system default value.
This parameter is supported only on systems that support
<symbol>TCP_KEEPINTVL</symbol> or an equivalent socket option, and on
Windows; on other systems, it must be zero.
In sessions connected via a Unix-domain socket, this parameter is
ignored and always reads as zero.
</para>
- <note>- <para>- On Windows, setting a value of 0 will set this parameter to 1 second,- since Windows does not provide a way to read the system default value.- </para>- </note>
</listitem>
</varlistentry>
@@ -1004,16 +996,11 @@ <title>TCP Settings</title>
the server's connection to the client is considered dead.
A value of 0 (the default) selects the operating system's default.
This parameter is supported only on systems that support
- <symbol>TCP_KEEPCNT</symbol> or an equivalent socket option;+ <symbol>TCP_KEEPCNT</symbol> or an equivalent socket option (which does not include Windows);
on other systems, it must be zero.
In sessions connected via a Unix-domain socket, this parameter is
ignored and always reads as zero.
</para>
- <note>- <para>- This parameter is not supported on Windows, and must be zero.- </para>- </note>
</listitem>
</varlistentry>
@@ -1030,15 +1017,10 @@ <title>TCP Settings</title>
If this value is specified without units, it is taken as milliseconds.
A value of 0 (the default) selects the operating system's default.
This parameter is supported only on systems that support
- <symbol>TCP_USER_TIMEOUT</symbol>; on other systems, it must be zero.+ <symbol>TCP_USER_TIMEOUT</symbol> (which does not include Windows); on other systems, it must be zero.
In sessions connected via a Unix-domain socket, this parameter is
ignored and always reads as zero.
</para>
- <note>- <para>- This parameter is not supported on Windows, and must be zero.- </para>- </note>
</listitem>
</varlistentry>
--
2.40.1
Attachments:
[text/plain] 0001-doc-Fix-confusing-positioning-of-notes-in-connection.patch (4.2K, ../ab7511ea-a089-2445-f64d-0bf72ebb7bc4@enterprisedb.com/2-0001-doc-Fix-confusing-positioning-of-notes-in-connection.patch)
download | inline diff:
From 97fe489263f18314e99ec471ab160dbc026a1841 Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter@eisentraut.org>
Date: Wed, 31 May 2023 07:12:38 -0400
Subject: [PATCH] doc: Fix confusing positioning of notes in connection
settings
Discussion: https://www.postgresql.org/message-id/flat/6f825d42-a1ce-492a-2ea7-c83e6e65fa8b%40postgresql.org
---
doc/src/sgml/config.sgml | 30 ++++++------------------------
1 file changed, 6 insertions(+), 24 deletions(-)
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgmlindex 5da74b3c40..5873a0ef2f 100644--- a/doc/src/sgml/config.sgml+++ b/doc/src/sgml/config.sgml@@ -950,18 +950,14 @@ <title>TCP Settings</title>
the operating system should send a TCP keepalive message to the client.
If this value is specified without units, it is taken as seconds.
A value of 0 (the default) selects the operating system's default.
+ On Windows, setting a value of 0 will set this parameter to 2 hours,+ since Windows does not provide a way to read the system default value.
This parameter is supported only on systems that support
<symbol>TCP_KEEPIDLE</symbol> or an equivalent socket option, and on
Windows; on other systems, it must be zero.
In sessions connected via a Unix-domain socket, this parameter is
ignored and always reads as zero.
</para>
- <note>- <para>- On Windows, setting a value of 0 will set this parameter to 2 hours,- since Windows does not provide a way to read the system default value.- </para>- </note>
</listitem>
</varlistentry>
@@ -977,18 +973,14 @@ <title>TCP Settings</title>
that has not been acknowledged by the client should be retransmitted.
If this value is specified without units, it is taken as seconds.
A value of 0 (the default) selects the operating system's default.
+ On Windows, setting a value of 0 will set this parameter to 1 second,+ since Windows does not provide a way to read the system default value.
This parameter is supported only on systems that support
<symbol>TCP_KEEPINTVL</symbol> or an equivalent socket option, and on
Windows; on other systems, it must be zero.
In sessions connected via a Unix-domain socket, this parameter is
ignored and always reads as zero.
</para>
- <note>- <para>- On Windows, setting a value of 0 will set this parameter to 1 second,- since Windows does not provide a way to read the system default value.- </para>- </note>
</listitem>
</varlistentry>
@@ -1004,16 +996,11 @@ <title>TCP Settings</title>
the server's connection to the client is considered dead.
A value of 0 (the default) selects the operating system's default.
This parameter is supported only on systems that support
- <symbol>TCP_KEEPCNT</symbol> or an equivalent socket option;+ <symbol>TCP_KEEPCNT</symbol> or an equivalent socket option (which does not include Windows);
on other systems, it must be zero.
In sessions connected via a Unix-domain socket, this parameter is
ignored and always reads as zero.
</para>
- <note>- <para>- This parameter is not supported on Windows, and must be zero.- </para>- </note>
</listitem>
</varlistentry>
@@ -1030,15 +1017,10 @@ <title>TCP Settings</title>
If this value is specified without units, it is taken as milliseconds.
A value of 0 (the default) selects the operating system's default.
This parameter is supported only on systems that support
- <symbol>TCP_USER_TIMEOUT</symbol>; on other systems, it must be zero.+ <symbol>TCP_USER_TIMEOUT</symbol> (which does not include Windows); on other systems, it must be zero.
In sessions connected via a Unix-domain socket, this parameter is
ignored and always reads as zero.
</para>
- <note>- <para>- This parameter is not supported on Windows, and must be zero.- </para>- </note>
</listitem>
</varlistentry>
--
2.40.1
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: peter.eisentraut@enterprisedb.com, daniel@yesql.se, jkatz@postgresql.org, pgsql-docs@lists.postgresql.org
Subject: Re: confusing positioning of notes in connection settings
In-Reply-To: <ab7511ea-a089-2445-f64d-0bf72ebb7bc4@enterprisedb.com>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox