Thread: Proposal for Re-ordering CONF (was: Re: GUC and postgresql.conf docs)
Bruce, > I have developed the following patch to address these issues. I have > removed the lock GUC settings from postgresql.conf, as suggested. (They > aren't even enabled in the general builds.) Great! Just to keep you from getting complacent, what follows is a proposal for re-ordering the settings in the postgresql.conf.sample file. (sorry for replying to your thread on a different list; I'm not subscribed to PATCHES). THE PROPOSAL: We should re-order the settings in postgresql.conf.sample in order to make more logical groupings per the attached outline. The online documenation should be then re-sorted to match this order. THE REASONS WHY: Our current ordering of settings in the CONF file is largely based on history (i.e. based on when settings were added rather than any more logical order). This makes understanding the CONF file baffling to newcomers, and even experienced DBAs can miss important settings because they are not grouped with their logical associates.For that matter, the current ordering can be baffling to developers. WhenI started this thread, Tom wasn't sure that CONF and GUC.c corresponded 100%. And no wonder! postgresql.conf.sample is in one order, the "Run-time configuration" doc page in a second order, and GUC.c in yet a third order! It took me most of an afternoon just to match up the various options. The CONF file and the docs should be in the same order, leaving us only two orderings to keep track of. THE ARGUMENT AGAINST: This would be an annoyance for anyone who "diffs" their conf files as part of upgrading. I cannot think of any other objection, except for the work involved, which I am quite willing to help with. THE OUTLINE ATTACHED: is my proposed ordering. I've put it in outline form, so that the groupings I'm using are obvious; I feel that the final postgresql.conf.sample should keep the group and subgroup headers as comments for additional clarity. I welcome improvements and suggestions -- the only thing I'm attached to is the idea of logical re-ordering, not this particular order.PLEASE NOTE THAT THIS OUTLINE IS BASED ON 7.3.2 postgresql.conf. My laptop is in the shop and I don't have a copy of 7.4 cvs on my back-up computer. If my proposal is accepted in general, I will flesh it out for 7.4 before June 15. COMMITTMENT TO FOLLOW-UP: I will also be posting an article entitled "The Annotated PostgreSQL.conf" either on Techdocs or at Elein's web site based on this ordering to help people decipher their .conf files. This will include the official docs, comments from the -PERFORMANCE mailing list, the command line options, and whether or not each variable can be SET by the user. -- Josh Berkus Aglio Database Solutions San Francisco
Agreed, postgresql.conf and the documentation should match. Guc.c needs to be in variable _type_ order, so I don't know what can be done there. The current postgresql.conf ordering is based on my reordering a few releases back to make it clearer. Feel free to improve it. I don't think people change _that_ _many_ postgresql.conf settings, so reordering should be OK with them, especially if they get a clearer output. Just to throw in a wrench, consider that SHOW ALL shows the settings in alphabetical order. I think that is OK, but I thought I should mention it. --------------------------------------------------------------------------- Josh Berkus wrote: > Bruce, > > > I have developed the following patch to address these issues. I have > > removed the lock GUC settings from postgresql.conf, as suggested. (They > > aren't even enabled in the general builds.) > > Great! Just to keep you from getting complacent, what follows is a proposal > for re-ordering the settings in the postgresql.conf.sample file. (sorry for > replying to your thread on a different list; I'm not subscribed to PATCHES). > > THE PROPOSAL: We should re-order the settings in postgresql.conf.sample in > order to make more logical groupings per the attached outline. The online > documenation should be then re-sorted to match this order. > > THE REASONS WHY: Our current ordering of settings in the CONF file is largely > based on history (i.e. based on when settings were added rather than any more > logical order). This makes understanding the CONF file baffling to > newcomers, and even experienced DBAs can miss important settings because they > are not grouped with their logical associates. > For that matter, the current ordering can be baffling to developers. When I > started this thread, Tom wasn't sure that CONF and GUC.c corresponded 100%. > And no wonder! postgresql.conf.sample is in one order, the "Run-time > configuration" doc page in a second order, and GUC.c in yet a third order! > It took me most of an afternoon just to match up the various options. The > CONF file and the docs should be in the same order, leaving us only two > orderings to keep track of. > > THE ARGUMENT AGAINST: This would be an annoyance for anyone who "diffs" their > conf files as part of upgrading. I cannot think of any other objection, > except for the work involved, which I am quite willing to help with. > > THE OUTLINE ATTACHED: is my proposed ordering. I've put it in outline form, > so that the groupings I'm using are obvious; I feel that the final > postgresql.conf.sample should keep the group and subgroup headers as comments > for additional clarity. I welcome improvements and suggestions -- the only > thing I'm attached to is the idea of logical re-ordering, not this particular > order. > PLEASE NOTE THAT THIS OUTLINE IS BASED ON 7.3.2 postgresql.conf. My laptop > is in the shop and I don't have a copy of 7.4 cvs on my back-up computer. > If my proposal is accepted in general, I will flesh it out for 7.4 before > June 15. > > COMMITTMENT TO FOLLOW-UP: I will also be posting an article entitled "The > Annotated PostgreSQL.conf" either on Techdocs or at Elein's web site based on > this ordering to help people decipher their .conf files. This will include > the official docs, comments from the -PERFORMANCE mailing list, the command > line options, and whether or not each variable can be SET by the user. > > -- > Josh Berkus > Aglio Database Solutions > San Francisco [ Attachment, skipping... ] -- Bruce Momjian | http://candle.pha.pa.us pgman@candle.pha.pa.us | (610) 359-1001+ If your life is a hard drive, | 13 Roberts Road + Christ can be your backup. | Newtown Square, Pennsylvania19073
Bruce, > I don't think people change _that_ _many_ postgresql.conf settings, so > reordering should be OK with them, especially if they get a clearer > output. Yeah. I put in the objection because Elein already made it to me. I also think that most people don't adjust *enough* Postgresql.conf settings, which is one thing I'm trying to change. > Just to throw in a wrench, consider that SHOW ALL shows the settings in > alphabetical order. I think that is OK, but I thought I should mention > it. I think it's OK too. Presumably, people running SHOW ALL are looking for a particular setting, not trying to tweak everything. I considered simply alpha-ordering the CONF file. However, too many options have a logical grouping that really need to be adjusted together and are spread wide apart in the alphabet (WAL_files and Checkpoint_segments, for example). For that matter, I dealt with a couple of distros of SAMBA that decided to "simplify" smb.conf by alphabetizing the settings, and ended up reordering them on my own. Bleah. -- Josh Berkus Aglio Database Solutions San Francisco
Bruce Momjian <pgman@candle.pha.pa.us> writes:
> Agreed, postgresql.conf and the documentation should match. Guc.c needs
> to be in variable _type_ order, so I don't know what can be done
> there.
We could make each table in guc.c follow the logical ordering Josh
suggests for its subset of the variables. But on the other hand, it'd
be just as defensible to put each table in alphabetical order. I'd vote
for doing one or the other rather than leaving the kinda-random order
that's there now.
Josh's proposal looks pretty good to me in general, though some of the
details seem a little odd. "max_files_per_process" doesn't belong under
lock management (perhaps better to stick it under Memory Usage, possibly
renaming that category to Resource Consumption) and the Query Tuning/Other
section seems kinda random. But "miscellaneous" variables are always a
bear to classify.
regards, tom lane
Tom, > Josh's proposal looks pretty good to me in general, though some of the > details seem a little odd. "max_files_per_process" doesn't belong under > lock management (perhaps better to stick it under Memory Usage, possibly > renaming that category to Resource Consumption) and the Query Tuning/Other > section seems kinda random. But "miscellaneous" variables are always a > bear to classify. OK, sure. I'll track everybody's suggestions an post a revised ordering tommorrow or wednesday. One of my objectives was to avoid having a "Miscellaneous" section, as I find such sections tend to grow with time. I couldn't avoid the Query Tuning/Other section, though, or for that matter Client Connection/Other; the options named definitely belong in that category, but don't have an appropriate sub-category that I can think of. Anybody see anything else that should be moved? -- Josh Berkus Aglio Database Solutions San Francisco