Invalid idle_in_transaction_session_timeout data type

On Thu, Mar 11, 2021 at 10:48:21AM +0000, Alex wrote:

Documentation https://www.postgresql.org/docs/13/runtime-config-client.html
<https://www.postgresql.org/docs/13/runtime-config-client.html&gt; shows that
`idle_in_transaction_session_timeout` is integer, bug you can set text
values '30s' and `show idle_in_transaction_session_timeout` returns `30s`
not an integer.
Documentation should be updated to include this data field format.

The documentation is correct. This parameter has a unit and you can therefore
use that unit for a better readability. There's a mention of that on the
setting documentation:

If this value is specified without units, it is taken as milliseconds. A value
of zero (the default) disables the timeout.

If you want to get the stored value, without unit, you can use

SELECT setting FROM pg_settings WHERE name = 'guc_name';

For more details on how unit for GUC works, see the documentation at
https://www.postgresql.org/docs/current/config-setting.html:

Numeric with Unit: Some numeric parameters have an implicit unit, because they
describe quantities of memory or time. The unit might be bytes, kilobytes,
blocks (typically eight kilobytes), milliseconds, seconds, or minutes. An
unadorned numeric value for one of these settings will use the setting's
default unit, which can be learned from pg_settings.unit. For convenience,
settings can be given with a unit specified explicitly, for example '120 ms'
for a time value, and they will be converted to whatever the parameter's actual
unit is. Note that the value must be written as a string (with quotes) to use
this feature.

https://www.postgresql.org/docs/13/runtime-config-client.html
<https://www.postgresql.org/docs/13/runtime-config-client.html&gt; shows
that `idle_in_transaction_session_timeout` is integer, bug you can set
text values '30s' and `show idle_in_transaction_session_timeout`
returns `30s` not an integer.
Documentation should be updated to include this data field format.

The documentation says:
"If this value is specified without units, it is taken as milliseconds."

If the value is specified with units, it follows the rule described here:
https://www.postgresql.org/docs/13/config-setting.html

"Numeric with Unit: Some numeric parameters have an implicit unit,
because they describe quantities of memory or time. The unit might be
bytes, kilobytes, blocks (typically eight kilobytes), milliseconds,
seconds, or minutes."
:
:
"Valid time units are us (microseconds), ms (milliseconds), s
(seconds), min (minutes), h (hours), and d (days)."

So I see no problem with the document.

Best regards,
--
Tatsuo Ishii
SRA OSS, Inc. Japan
English: http://www.sraoss.co.jp/index_en.php
Japanese:http://www.sraoss.co.jp

In my opinion, it would be more clear if "Numeric with Unit" would be
specified on that property documentation, so that I can search more about
what that means (eventually a link pointing to details).
I saw "(integer)" so I assumed `show idle_in_transaction_session_timeout `
will return an integer.
To actually deduce its format I should read much more documentation, and
the average user usually fast searches and scans documents only for
keywords.
Tatsuo Ishii wrote:
https://www.postgresql.org/docs/13/runtime-config-client.html
<https://www.postgresql.org/docs/13/runtime-config-client.html&gt;
<https://www.postgresql.org/docs/13/runtime-config-client.html
<https://www.postgresql.org/docs/13/runtime-config-client.html&gt; > shows
that `idle_in_transaction_session_timeout` is integer, bug you can set
text values '30s' and `show idle_in_transaction_session_timeout`
returns `30s` not an integer.
Documentation should be updated to include this data field format.
The documentation says:
"If this value is specified without units, it is taken as milliseconds."
If the value is specified with units, it follows the rule described here:
https://www.postgresql.org/docs/13/config-setting.html
<https://www.postgresql.org/docs/13/config-setting.html&gt;
"Numeric with Unit: Some numeric parameters have an implicit unit,
because they describe quantities of memory or time. The unit might be
bytes, kilobytes, blocks (typically eight kilobytes), milliseconds,
seconds, or minutes."
:
:
"Valid time units are us (microseconds), ms (milliseconds), s
(seconds), min (minutes), h (hours), and d (days)."
So I see no problem with the document.
Best regards,
--
Tatsuo Ishii
SRA OSS, Inc. Japan
English: http://www.sraoss.co.jp/index_en.php
<http://www.sraoss.co.jp/index_en.php&gt;
Japanese:http://www.sraoss.co.jp <http://www.sraoss.co.jp&gt;

[ redirecting to pgsql-docs ]

Alex <cdalxndr@yahoo.com> writes:

In my opinion, it would be more clear if "Numeric with Unit" would be
specified on that property documentation, so that I can search more about
what that means (eventually a link pointing to details).
I saw "(integer)" so I assumed `show idle_in_transaction_session_timeout `
will return an integer.

This complaint isn't totally without merit. I wonder whether there is
any value in listing a unit-ized GUC's default unit as part of the
type info, so that we'd have entries like

work_mem (integer, kilobytes)

statement_timeout (integer, milliseconds)

That'd both provide some concrete info about which unit applies,
and cue unwary users that there might be more to it than just a
number.

I'm not sure whether this could replace the existing boilerplate
phrases about "If this value is specified without units, it is taken
as kilobytes", but it's sure more compact.

regards, tom lane

The following changes would make docs clear:
work_mem (numeric with memory unit)
statement_timeout (numeric with time unit)
,where "numeric with memory unit" and "numeric with time unit" are links
that point to "https://www.postgresql.org/docs/current/config-setting.html&quot;
Tom Lane wrote:
[ redirecting to pgsql-docs ]
Alex <cdalxndr@yahoo.com <mailto:cdalxndr@yahoo.com> > writes:
In my opinion, it would be more clear if "Numeric with Unit" would be
specified on that property documentation, so that I can search more about
what that means (eventually a link pointing to details).
I saw "(integer)" so I assumed `show idle_in_transaction_session_timeout `
will return an integer.
This complaint isn't totally without merit. I wonder whether there is
any value in listing a unit-ized GUC's default unit as part of the
type info, so that we'd have entries like
work_mem (integer, kilobytes)
statement_timeout (integer, milliseconds)
That'd both provide some concrete info about which unit applies,
and cue unwary users that there might be more to it than just a
number.
I'm not sure whether this could replace the existing boilerplate
phrases about "If this value is specified without units, it is taken
as kilobytes", but it's sure more compact.
regards, tom lane

Alex <cdalxndr@yahoo.com> writes:

The following changes would make docs clear:
work_mem (numeric with memory unit)
statement_timeout (numeric with time unit)

I'm not sure about "clear", but I am sure that'd be inaccurate.
We have integer GUCs and float8 GUCs, but no numeric GUCs.
I do not see a useful purpose in obscuring that distinction.

I could see using a couple more words than I suggested before:

work_mem (integer, units of kilobytes)

regards, tom lane

On 3/12/21 2:50 AM, Tom Lane wrote:

Alex <cdalxndr@yahoo.com> writes:

The following changes would make docs clear:
work_mem (numeric with memory unit)
statement_timeout (numeric with time unit)

I'm not sure about "clear", but I am sure that'd be inaccurate.
We have integer GUCs and float8 GUCs, but no numeric GUCs.
I do not see a useful purpose in obscuring that distinction.

I could see using a couple more words than I suggested before:

work_mem (integer, units of kilobytes)

This gets a little more complicated with:

shared_buffers (integer, units of BLOCKSZ)
--
Vik Fearing

Vik Fearing <vik@postgresfriends.org> writes:

On 3/12/21 2:50 AM, Tom Lane wrote:

I could see using a couple more words than I suggested before:
work_mem (integer, units of kilobytes)

This gets a little more complicated with:

shared_buffers (integer, units of BLOCKSZ)

Given the in-line explanation under shared_buffers, I think it'd
be enough to write that as

shared_buffers (integer, units of blocks)

regards, tom lane