Thread: GUC context information in the document.
Hello, I had a question that whether a change of some GUC parameter needs restart or not and similar questions come every now and then. As shown below, descriptions about GUC context is surely put there but I believe the average reader of the document doesn't recognize that clearly while looking into an item without comparing it with several other itmes that he/she knows how behave. Addition to that, the description for PGC_POSTMASTER doesn't say that it also can be set on command line, and description for PGC_SIGHUP doesn't state clearly that realoading makes it effective, and PGC_USERSET has even no description. If I'm not missing anyting, putting stereotyped information about GUC contexts like following would be usable. > share_buffers (integer), (effective after server restart) > log_destination (string), (effetive after config reload) > log_min_duration_statement (integer), (effective in-session, superuser only) > DateStyle (string), (effective in-session) What do you think about this? regards, ===== The typical descriptions are listed below. A. PGC_POSTMASTER http://www.postgresql.org/docs/devel/static/runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-MEMORY > shared_buffers (integer) > ... This parameter can only be set at server start. B. PGC_SIGHUP http://www.postgresql.org/docs/devel/static/runtime-config-logging.html#GUC-LOG-DESTINATION > log_destination (string) > ... This parameter can only be set in the postgresql.conf > file or on the server command line. C. PGC_SUSET http://www.postgresql.org/docs/devel/static/runtime-config-logging.html#GUC-LOG-MIN-DURATION-STATEMENT > log_min_duration_statement (integer) > ... Only superusers can change this setting. D. PGC_USERSET http://www.postgresql.org/docs/devel/static/runtime-config-client.html#GUC-DATESTYLE > DateStyle (string)... nothing about GUC context is written ... -- Kyotaro Horiguchi NTT Open Source Software Center
Kyotaro HORIGUCHI <horiguchi.kyotaro@lab.ntt.co.jp> writes:
> If I'm not missing anyting, putting stereotyped information about
> GUC contexts like following would be usable.
>> share_buffers (integer), (effective after server restart)
>> log_destination (string), (effetive after config reload)
>> log_min_duration_statement (integer), (effective in-session, superuser only)
>> DateStyle (string), (effective in-session)
> What do you think about this?
TBH, those don't seem like improvements over the existing boilerplate
texts, particularly not the last two.
I follow the general idea of getting rid of the boilerplate sentences
in favor of an annotation similar to the variable datatype notations;
but such annotations would have to be *very* carefully wordsmithed
to be both precise and understandable yet brief enough to fit ... and
these are not. I'm not sure such a goal is possible at all.
If we were to go in this direction, I'd favor just annotating with
the same context keywords that we already expose to users in the
pg_settings view, ie more like
shared_buffers (integer, postmaster context)
and then we'd need some introductory text in section 18.1 that defines
these keywords. Maybe we could move the text about them that's currently
associated with the pg_settings view (section 48.69 ATM).
But TBH, I'm not sure that anything like this would reduce the number
of questions. It's basically relying on the assumption that people would
read section 18.1 before asking, and that's a shaky assumption.
regards, tom lane
Hello, thank you for the comment. At Tue, 31 Mar 2015 15:07:08 -0400, Tom Lane <tgl@sss.pgh.pa.us> wrote in <24663.1427828828@sss.pgh.pa.us> > Kyotaro HORIGUCHI <horiguchi.kyotaro@lab.ntt.co.jp> writes: > > If I'm not missing anyting, putting stereotyped information about > > GUC contexts like following would be usable. > > >> share_buffers (integer), (effective after server restart) > > >> log_destination (string), (effetive after config reload) > > >> log_min_duration_statement (integer), (effective in-session, superuser only) > > >> DateStyle (string), (effective in-session) > > > What do you think about this? > > TBH, those don't seem like improvements over the existing boilerplate > texts, particularly not the last two. > > I follow the general idea of getting rid of the boilerplate sentences > in favor of an annotation similar to the variable datatype notations; > but such annotations would have to be *very* carefully wordsmithed > to be both precise and understandable yet brief enough to fit ... and > these are not. I'm not sure such a goal is possible at all. Exactly. Inappropriate wording results in simply moving the problem to another place, and I know I am completely not fit the work.. > If we were to go in this direction, I'd favor just annotating with > the same context keywords that we already expose to users in the > pg_settings view, ie more like > > shared_buffers (integer, postmaster context) This was an choice came to me but I feel it a little difficult to recognize for users. But since any possible (simple) wording won't tell what itself precisely means, and it would be easy to maintain for developers, it seems the best way now. > and then we'd need some introductory text in section 18.1 that defines > these keywords. Maybe we could move the text about them that's currently > associated with the pg_settings view (section 48.69 ATM). > > But TBH, I'm not sure that anything like this would reduce the number > of questions. It's basically relying on the assumption that people would > read section 18.1 before asking, and that's a shaky assumption. Mmm. I completely agree with you about the first question for the questioner. I hope that no second question comes (for the questioner alone) if we could say "Hem, the answer for your question is written here in the documentation.". But on the other hand, I personally think that it is very similar to "Hem, the SQL statement below gives you the answer for your question.". Ok, this porposal doesn't seem to get approvals so much. I'll try the second way above for the time being. regards, -- Kyotaro Horiguchi NTT Open Source Software Center