pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedNo discussion of custom variables; no "See also" for set_config, current_setting, pg_settings
4+ messages / 4 participants
[nested] [flat]
* No discussion of custom variables; no "See also" for set_config, current_setting, pg_settings
@ 2022-09-02 20:24 PG Doc comments form <noreply@postgresql.org>
0 siblings, 2 replies; 4+ messages in thread
From: PG Doc comments form @ 2022-09-02 20:24 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: guyren@relevantlogic.com
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.
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: No discussion of custom variables; no "See also" for set_config, current_setting, pg_settings
@ 2022-09-02 22:07 David G. Johnston <david.g.johnston@gmail.com>
parent: PG Doc comments form <noreply@postgresql.org>
1 sibling, 0 replies; 4+ messages in thread
From: David G. Johnston @ 2022-09-02 22:07 UTC (permalink / raw)
To: guyren@relevantlogic.com <guyren@relevantlogic.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
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:
https://www.postgresql.org/docs/current/docguide.html
There is also existing material out there on contributing patches, it
applies even if those patches only touch the documentation.
David J.
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: No discussion of custom variables; no "See also" for set_config, current_setting, pg_settings
@ 2022-09-02 22:16 Tom Lane <tgl@sss.pgh.pa.us>
parent: PG Doc comments form <noreply@postgresql.org>
1 sibling, 1 reply; 4+ messages in thread
From: Tom Lane @ 2022-09-02 22:16 UTC (permalink / raw)
To: guyren@relevantlogic.com; +Cc: pgsql-docs@lists.postgresql.org
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/
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: No discussion of custom variables; no "See also" for set_config, current_setting, pg_settings
@ 2022-09-02 22:28 guyren@relevantlogic.com <guyren@gmail.com>
parent: Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 0 replies; 4+ messages in thread
From: guyren@relevantlogic.com @ 2022-09-02 22:28 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: pgsql-docs@lists.postgresql.org
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/
^ permalink raw reply [nested|flat] 4+ messages in thread
end of thread, other threads:[~2022-09-02 22:28 UTC | newest]
Thread overview: 4+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2022-09-02 20:24 No discussion of custom variables; no "See also" for set_config, current_setting, pg_settings PG Doc comments form <noreply@postgresql.org>
2022-09-02 22:07 ` David G. Johnston <david.g.johnston@gmail.com>
2022-09-02 22:16 ` Tom Lane <tgl@sss.pgh.pa.us>
2022-09-02 22:28 ` guyren@relevantlogic.com <guyren@gmail.com>
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