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