Postgres Pro
Downloads
Home   >   mailing lists

Thread: No discussion of custom variables; no "See also" for set_config, current_setting, pg_settings

No discussion of custom variables; no "See also" for set_config, current_setting, pg_settings

From
PG Doc comments form
Date:
The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/14/sql-set.html
Description:

A reader of this section
https://www.postgresql.org/docs/current/sql-set.html of the documentation
might be forgiven for thinking that Postgres does not support custom
variables.

There are also related commands and features that are not mentioned. These
might be covered by a reference to 20.1.3, but that section also does not
mention custom variables afaict.

I'd be happy to write some better documentation (for all the sections in
question). I think actually a separate section under 20.1 that could be
referred to from SET, SHOW etc might be best.

I've contributed to the documentation before, but I forget how. A
description of how at the bottom of the Documentation home page or at least
in the FAQ might be in order also.

Re: No discussion of custom variables; no "See also" for set_config, current_setting, pg_settings

From
"David G. Johnston"
Date:
On Friday, September 2, 2022, PG Doc comments form <noreply@postgresql.org> wrote:
The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/14/sql-set.html
Description:

A reader of this section
https://www.postgresql.org/docs/current/sql-set.html of the documentation
might be forgiven for thinking that Postgres does not support custom
variables.

There are also related commands and features that are not mentioned. These
might be covered by a reference to 20.1.3, but that section also does not
mention custom variables afaict.

20.16 “Customized Options” is how this is labelled in the documentation.


I'd be happy to write some better documentation (for all the sections in
question). I think actually a separate section under 20.1 that could be
referred to from SET, SHOW etc might be best.

I’m doubting that mentioning customized variables everywhere in the documentation besides the chapter that explains that they (and all other settings) exist is a benefit.
 

I've contributed to the documentation before, but I forget how. A
description of how at the bottom of the Documentation home page or at least
in the FAQ might be in order also.

Usually just post concrete ideas to -hackers or -bugs, or even -docs.  The good ones tend to get implemented even without a patch of the sgml provided.  Otherwise, read: 


There is also existing material out there on contributing patches, it applies even if those patches only touch the documentation.

David J.

Re: No discussion of custom variables; no "See also" for set_config, current_setting, pg_settings

From
Tom Lane
Date:
PG Doc comments form <noreply@postgresql.org> writes:
> A reader of this section
> https://www.postgresql.org/docs/current/sql-set.html of the documentation
> might be forgiven for thinking that Postgres does not support custom
> variables.

They are, in fact, *not* a supported feature.  The only intended use
of non-core GUCs was for extensions' parameters.  People have abused the
mechanism to create ad-hoc session variables, but we don't encourage it.
The underlying code won't scale to large numbers of variables, there's
no way to declare properties of such a variable in SQL, etc.

There's been an ongoing effort to create a respectable substitute,
but it still hasn't gotten across the finish line [1].

            regards, tom lane

[1] https://commitfest.postgresql.org/39/1608/

Re: No discussion of custom variables; no "See also" for set_config, current_setting, pg_settings

From
"guyren@relevantlogic.com"
Date:
Thanks for the quick response.

It’s a clearly useful, simplifying feature. Unless it is likely to be removed at some point, I propose it should be documented and declared supported wherever relevant.

In any event, I am happy to prepare some documentation changes that mention these caveats, but I won’t if there is no chance of it being accepted. Are we totally opposed?

On Sep 2, 2022, at 15:16 , Tom Lane <tgl@sss.pgh.pa.us> wrote:

PG Doc comments form <noreply@postgresql.org> writes:
A reader of this section
https://www.postgresql.org/docs/current/sql-set.html of the documentation
might be forgiven for thinking that Postgres does not support custom
variables.

They are, in fact, *not* a supported feature.  The only intended use
of non-core GUCs was for extensions' parameters.  People have abused the
mechanism to create ad-hoc session variables, but we don't encourage it.
The underlying code won't scale to large numbers of variables, there's
no way to declare properties of such a variable in SQL, etc.

There's been an ongoing effort to create a respectable substitute,
but it still hasn't gotten across the finish line [1].

regards, tom lane

[1] https://commitfest.postgresql.org/39/1608/