Folks,

We've been discussing this for a while on HACKERS.  However, I haven't been 
getting much feedback on the specific order proposed.

Attached is an outline of my proposed re-ordering of postgresql.conf.sample.   
Please send me comments.  I need to submit a patch by Thursday, so don't take 
too long.

This is an effort to make the order of run-time params in 
postgresql.conf.sample and in the docs more logical and less baffling to the 
new DBA.

Questions:
1) Should "enable_implicit_from" go in the "Version/Platform Compatibility" 
section where I have it now, or in "CLIENT CONNECTIONS-Statement Behavior", 
or somewhere else?

2) Where should "preload_libraries" go?   I'm very reluctant to start a 
"Misc." section.  Perhaps I should start a "LIBRARIES" section?

3) I have re-ordered each subsection somewhat.   The fixed ordering is based 
on:
        a) My guess at the frequency with which that option will be changed, 
with more common options toward the top of the subsection;
        b) Grouping for tightly related options and for options that cascade;
        c) where (a) and (b) are unclear, alpha order.
Does this order make sense looking at the file?

3) Should we use indenting in PostgreSQL.conf.sample?   I tend to think it 
would make the file easier to read, but I'm not sure what effect it would 
have, if any, on parsing the file and whether other people would find it easy 
to read.



-- 
-Josh Berkus
 Aglio Database Solutions
 San Francisco
Tue, 10 Jun 2003 11:01:46 -0700
Josh Berkus <josh@agliodbs.com>
Re-ordering .CONF params ... questions for this list
On Tuesday 10 Jun 2003 7:01 pm, Josh Berkus wrote:
> Folks,
>
> We've been discussing this for a while on HACKERS.  However, I haven't been
> getting much feedback on the specific order proposed.
>
> Attached is an outline of my proposed re-ordering of
> postgresql.conf.sample. Please send me comments.  I need to submit a patch
> by Thursday, so don't take too long.
>
> This is an effort to make the order of run-time params in
> postgresql.conf.sample and in the docs more logical and less baffling to
> the new DBA.
>
> Questions:
> 1) Should "enable_implicit_from" go in the "Version/Platform Compatibility"
> section where I have it now, or in "CLIENT CONNECTIONS-Statement Behavior",
> or somewhere else?

Version compatibility I'd vote for (hesitantly)

> 2) Where should "preload_libraries" go?   I'm very reluctant to start a
> "Misc." section.  Perhaps I should start a "LIBRARIES" section?

No useful ideas - sorry.

> 3) I have re-ordered each subsection somewhat.   The fixed ordering is
> based on:
>         a) My guess at the frequency with which that option will be
> changed, with more common options toward the top of the subsection;
>         b) Grouping for tightly related options and for options that
> cascade; c) where (a) and (b) are unclear, alpha order.
> Does this order make sense looking at the file?

Looks good, I'd suggest the following perhaps:

Logging & Debugging
I'd like this near the top, but then I use syslogging. With a new install I go 
in and check tcpip_socket etc, fix the logging and just see if everything is 
working. Then I go in and do a little tuning.
Actually, maybe the syslog sub-section should go above the others - say where 
you'll log to, and then what you'll log. Of course, I'm biased since I use 
syslog.

Client Connection Defaults/Other/password_encryption
This should probably go in the security section. Actually, looking at it 
"dynamic_librar_path" is in the wrong place too - cut & past error?

Query Tuning/Planner Method Enabling
I'm in two minds here - obviously it is more "basic" than the "cost 
constraints" section, but that's the one people will be tinkering with first. 
Nope - thinking about it, you've got it right.

> 3) Should we use indenting in PostgreSQL.conf.sample?   I tend to think it
> would make the file easier to read, but I'm not sure what effect it would
> have, if any, on parsing the file and whether other people would find it
> easy to read.

Not sure it would help that much - the comments need a URL to the relevant 
page in the online docs though. A couple more lines of comments too:

# Syslog
#   To log to syslog, use something like
#   syslog = 2, syslog_facility = 'LOCAL0', syslog_ident = 'postgres'
#   Don't forget to update your syslog.conf then too.
#
...etc

Otherwise, looks good to me.

-- 
  Richard Huxton
  Archonet Ltd

Tue, 10 Jun 2003 20:05:11 +0100
Richard Huxton <richardh@archonet.com>
Re: Re-ordering .CONF params ... questions for this list
Richard Huxton wrote:
>>2) Where should "preload_libraries" go?   I'm very reluctant to start a
>>"Misc." section.  Perhaps I should start a "LIBRARIES" section?
> 
> No useful ideas - sorry.

Sorry, I missed this earlier. This is a performance tuning option.

Joe


Tue, 10 Jun 2003 13:05:14 -0700
Joe Conway <mail@joeconway.com>
Re: Re-ordering .CONF params ... questions for this list
Richard,

> Logging & Debugging
> I'd like this near the top, but then I use syslogging. With a new install I 
go 
> in and check tcpip_socket etc, fix the logging and just see if everything is 
> working. Then I go in and do a little tuning.
> Actually, maybe the syslog sub-section should go above the others - say 
where 
> you'll log to, and then what you'll log. Of course, I'm biased since I use 
> syslog.

I have no objection to moving the syslog section.  Any other opinions?

> Client Connection Defaults/Other/password_encryption
> This should probably go in the security section. Actually, looking at it 
> "dynamic_librar_path" is in the wrong place too - cut & past error?

Not the way I read the docs; according to the docs:

password_encryption is whether or not the statement "ALTER USER joe_schmoe 
WITH PASSWORD 'xxxyyy'" is encrypted by default even if you don't use the 
"WITH ENCRYPTION" option.   And it is SET-able on each client connection, by 
regular users.  So it goes in "CLIENT CONNECTION SETTINGS".

"dynamic_library_path", while less obvious, is also SETable on each client 
connection.   I'd be happy to revise this if someone understands/uses this 
option and has a better idea where to put it.

> Not sure it would help that much - the comments need a URL to the relevant 
> page in the online docs though. A couple more lines of comments too:

Given that we're running out of time, I wasn't going to touch any of the 
comments in PostgreSQL.conf.sample.   Instead, I was going to leave the 
comments as-is, and post extensive comments on Techdocs before 7.4 beta.  
Then, in 7.5 or 8.0 we can re-comment .conf.

-- 
-Josh Berkus
 Aglio Database Solutions
 San Francisco


Tue, 10 Jun 2003 13:57:24 -0700
Josh Berkus <josh@agliodbs.com>
Re: Re-ordering .CONF params ... questions for this list
Josh Berkus <josh@agliodbs.com> writes:
> Given that we're running out of time, I wasn't going to touch any of the 
> comments in PostgreSQL.conf.sample.   Instead, I was going to leave the 
> comments as-is, and post extensive comments on Techdocs before 7.4
> beta.  

I doubt anyone would object to improving the comments during beta; so
you don't need to consider that part something that has to be done
before feature freeze.

			regards, tom lane

Tue, 10 Jun 2003 17:28:43 -0400
Tom Lane <tgl@sss.pgh.pa.us>
Re: Re-ordering .CONF params ... questions for this list 
Tom,

> I doubt anyone would object to improving the comments during beta; so
> you don't need to consider that part something that has to be done
> before feature freeze.

Oh, cool.  OK, then ... the hard part is just deciding on what comments to 
include.   We'll work on that in this list.

-- 
-Josh Berkus
 Aglio Database Solutions
 San Francisco


Tue, 10 Jun 2003 14:29:42 -0700
Josh Berkus <josh@agliodbs.com>
Re: Re-ordering .CONF params ... questions for this list
Folks,

Revised ordering of options, based on information and suggestions received 
here on both mailing lists.

-- 
-Josh Berkus

______AGLIO DATABASE SOLUTIONS___________________________
                                        Josh Berkus
   Complete information technology 	josh@agliodbs.com
    and data management solutions 	(415) 565-7293
   for law firms, small businesses 	 fax 621-2533
    and non-profit organizations. 	San Francisco
Tue, 10 Jun 2003 14:45:13 -0700
Josh Berkus <josh@agliodbs.com>
Re: Re-ordering .CONF params ... questions for this list
Josh- I took a quick look at your proposal on conf ordering-

The groupings are great.

Without a clear notion of dependencies, and only based on what I think
people are likely to tweak the most, I'd suggest promoting the "client
connection defaults", "version/platform compatibility" & "logging/debugging"
groups to positions 2,3 & 4 respectively.

Here's the thinking-

You'd have all of the options that a neophyte might need to set to perform a
particular task in a given environment in the first three groups. Problems
encountered while setting these up might require the adventurous beginner to
dip into logging/debugging to gather basic diagnostic info.

With this ordering, everything you might have to touch in order to get a
basic system up & running lives in the top 4 groups. (This also helps soften
the dilemma of where enable_implicit_from should go by putting the two
possible groups next to one another.)

Below the top four groups are the tuning parameters best not messed with
until one passes from neophyte to DB-Geek level. (And probably not worth
messing with even then.) These are only needed when you've passed over from
getting it running to needing it to run better.

-Nick



> -----Original Message-----
> From: pgsql-performance-owner@postgresql.org
> [mailto:pgsql-performance-owner@postgresql.org]On Behalf Of Josh Berkus
> Sent: Tuesday, June 10, 2003 1:02 PM
> To: pgsql-performance@postgresql.org
> Subject: [PERFORM] Re-ordering .CONF params ... questions for this list
>
>
> Folks,
>
> We've been discussing this for a while on HACKERS.  However, I
> haven't been
> getting much feedback on the specific order proposed.
>
> Attached is an outline of my proposed re-ordering of
> postgresql.conf.sample.
> Please send me comments.  I need to submit a patch by Thursday,
> so don't take
> too long.
>
> This is an effort to make the order of run-time params in
> postgresql.conf.sample and in the docs more logical and less
> baffling to the
> new DBA.
>
> Questions:
> 1) Should "enable_implicit_from" go in the "Version/Platform
> Compatibility"
> section where I have it now, or in "CLIENT CONNECTIONS-Statement
> Behavior",
> or somewhere else?
>
> 2) Where should "preload_libraries" go?   I'm very reluctant to start a
> "Misc." section.  Perhaps I should start a "LIBRARIES" section?
>
> 3) I have re-ordered each subsection somewhat.   The fixed
> ordering is based
> on:
>         a) My guess at the frequency with which that option will
> be changed,
> with more common options toward the top of the subsection;
>         b) Grouping for tightly related options and for options
> that cascade;
>         c) where (a) and (b) are unclear, alpha order.
> Does this order make sense looking at the file?
>
> 3) Should we use indenting in PostgreSQL.conf.sample?   I tend to
> think it
> would make the file easier to read, but I'm not sure what effect it would
> have, if any, on parsing the file and whether other people would
> find it easy
> to read.
>
>
>
> --
> -Josh Berkus
>  Aglio Database Solutions
>  San Francisco
>


Fri, 13 Jun 2003 17:31:54 -0500
"Nick Fankhauser" <nickf@ontko.com>
Re: Re-ordering .CONF params ... questions for this list
Nick,

> Without a clear notion of dependencies, and only based on what I think
> people are likely to tweak the most, I'd suggest promoting the "client
> connection defaults", "version/platform compatibility" & "logging/debugging"
> groups to positions 2,3 & 4 respectively.

I like your ideas, but there's two problems with them:

1) I mess around with postgresql.conf constantly, and seldom touch anything in 
the "client connection defaults" section.  I do, however, mess with the stuff 
in the "resource usage" section, as to most of the people on this list.

2) I just spent 4.5 hours re-arranging the Runtime-config docs page last 
night, and am very reluctant to do it again.


-- 
-Josh Berkus

______AGLIO DATABASE SOLUTIONS___________________________
                                        Josh Berkus
   Complete information technology 	josh@agliodbs.com
    and data management solutions 	(415) 565-7293
   for law firms, small businesses 	 fax 621-2533
    and non-profit organizations. 	San Francisco


Fri, 13 Jun 2003 15:51:14 -0700
Josh Berkus <josh@agliodbs.com>
Re: Re-ordering .CONF params ... questions for this list
> 2) I just spent 4.5 hours re-arranging the Runtime-config docs page last
> night, and am very reluctant to do it again.

I like this reason... I think you've already done a great service by
creating functional groups. The newbies won't be hurt by the need to scroll
down a bit, and the functional groupings already serve to eliminate the
confusion about what the params are for (which *does* hurt them). What
you've done is a great improvement. My additional comments below are offered
in the spirit of support for what you've already done along with thoughts to
consider for future revisions.





> 1) I mess around with postgresql.conf constantly, and seldom
> touch anything in
> the "client connection defaults" section.  I do, however, mess
> with the stuff
> in the "resource usage" section, as to most of the people on this list.

I agree... but are we the folks that the conf file needs to be made more
intuitive for?

If the intent is to make it easier for experienced folks like ourselves who
are working with large or unusual databases to deal with PostgreSQL, then
certainly the resource usage and tuning settings should go to the top. We'll
set the other params once & never touch them again.

On the other hand, I suspect that the majority of postgresql users play with
the other params a bit during install to get their systems working and never
touch the resource usage or tuning params ever. (And this is as it should
be, given that the defaults are reasonable for most systems.)

Part of my motivation in offering this advice is our sibling rivalry with
MySQL- once we look under the hood, we usually find that PostgreSQL is the
way to go, but all of us mechanics spend a silly amount of time wondering
aloud why the many people who don't enjoy looking under the hood don't get
it. If we want the legions of MySQL followers to get it, we need to put only
the necessary instruments on the dashboard and not force non-mechanics to
look under the hood. (And to stretch the metaphor a bit further- The hood
latch still needs to be near the dashboard for the folks who are ready for
the next step.)


I'll cross-post this to advocacy because I'm tottering off on that tangent.
I think the comments may be useful in this forum as well because the
advocacy folks need to pass thoughts to the active developers & documenters
in much the same way that marketing folks need to communicate well with
engineers in the commercial world.


Regards,
      -Nick


Sat, 14 Jun 2003 09:40:30 -0500
"Nick Fankhauser" <nickf@ontko.com>
A bit OT- RE: [PERFORM] Re-ordering .CONF params ... questions for
	this list
Nick,

> I agree... but are we the folks that the conf file needs to be made more
> intuitive for?
>
> If the intent is to make it easier for experienced folks like ourselves who
> are working with large or unusual databases to deal with PostgreSQL, then
> certainly the resource usage and tuning settings should go to the top.
> We'll set the other params once & never touch them again.
>
> On the other hand, I suspect that the majority of postgresql users play
> with the other params a bit during install to get their systems working and
> never touch the resource usage or tuning params ever. (And this is as it
> should be, given that the defaults are reasonable for most systems.)

This is a good argument.  Though if you pursue it, surely you're advocating a 
GUI tool for PostgreSQL.conf, not that that's a bad idea ...

How do other people feel about this?   What options in PostgreSQL.conf do you 
tweak most frequently?

-- 
Josh Berkus
Aglio Database Solutions
San Francisco

Mon, 16 Jun 2003 09:28:07 -0700
Josh Berkus <josh@agliodbs.com>
Re: A bit OT- RE: [PERFORM] Re-ordering .CONF params ... questions
	for this list