Folks,

I'm trying to prepare comprehensive documentation on the contents of the 
postgresql.conf file for 7.3.2.   However, I'm running into some confusion in 
the docs (which is why I'm preparing the document in the first place).

Can I aassume that any setting documented under "3.4. Run-time Configuration" 
is a GUC variable modifiable through a SET statement?  If not, where can I 
find documenation on which .conf settings are GUC variables and which are 
not?

Thanks ... this'll go up at Techdocs when I have a draft together.

-- 
Josh Berkus
Aglio Database Solutions
San Francisco


Mon, 12 May 2003 10:20:19 -0700
Josh Berkus <josh@agliodbs.com>
GUC and postgresql.conf docs
Josh Berkus <josh@agliodbs.com> writes:
> Can I aassume that any setting documented under "3.4. Run-time Configuration"
> is a GUC variable modifiable through a SET statement?  If not, where can I 
> find documenation on which .conf settings are GUC variables and which are 
> not?

Use the source, Luke.

The tables in src/backend/utils/misc/guc.c are the authoritative reference.
Read the comments in src/include/utils/guc.h first.

Yes, everything in postgresql.conf is a GUC variable; but I think there
may be some GUC variables that were omitted from postgresql.conf.
Hopefully intentionally, not by oversight ...

			regards, tom lane


Mon, 12 May 2003 13:31:51 -0400
Tom Lane <tgl@sss.pgh.pa.us>
Re: GUC and postgresql.conf docs 
Tom,

> The tables in src/backend/utils/misc/guc.c are the authoritative reference.
> Read the comments in src/include/utils/guc.h first.

Thanks.   Would never have found it on my own ...

> Yes, everything in postgresql.conf is a GUC variable; but I think there
> may be some GUC variables that were omitted from postgresql.conf.
> Hopefully intentionally, not by oversight ...

Mmm?   I think I have some terminology confusion somewhere.  I thought that a 
GUC variable meant that it could be changed through a SET statement.  But 
some settings, like TCP/IP socket, cannot be SET.   What distinguises 
settings that can be SET from GUC variables that are restart-only?

I sense more posts to the list in the offing.

-- 
Josh Berkus
Aglio Database Solutions
San Francisco


Mon, 12 May 2003 10:40:06 -0700
Josh Berkus <josh@agliodbs.com>
Re: GUC and postgresql.conf docs
Josh Berkus writes:

> Can I aassume that any setting documented under "3.4. Run-time Configuration"
> is a GUC variable

Yes, although "GUC" is not an official term that is defined anywhere.

> modifiable through a SET statement?

No, some of them say that they can only be set at server start.  But you
can run SHOW on all of them.

-- 
Peter Eisentraut   peter_e@gmx.net


Mon, 12 May 2003 19:40:37 +0200 (CEST)
Peter Eisentraut <peter_e@gmx.net>
Re: GUC and postgresql.conf docs
Josh Berkus <josh@agliodbs.com> writes:
> What distinguises 
> settings that can be SET from GUC variables that are restart-only?

The PGC_CONTEXT settings.  Go back and read those comments I pointed
you to.

			regards, tom lane


Mon, 12 May 2003 13:54:38 -0400
Tom Lane <tgl@sss.pgh.pa.us>
Re: GUC and postgresql.conf docs 
Tom, Peter,

Since I had to do this anyway, I thought the following would help you clean up 
a little.  Please check my report for accuracy; postgresql.conf.sample lists 
the GUC variables in one order, the online documentation in another, and 
guc.c in a third, completely different order.  So it's entirely possible I 
missed something.

BTW, my next proposal after finishing this list will be to re-order the 
variables in postgresql.conf.sample into something more logical than the 
current "incremental development order".  Expect it next week.

GUC Options with no documentation:
The following options exist in postgresql.conf.sample and in guc.c but not in 
the online documenation anywhere the search box can find:

trace_locks
trace_userlocks
trace_lwlocks
debug_deadlocks
trace_lock_oidmin
trace_lock_table

show_btree_build_stats


Defined in guc.c but not in PostgreSQL.conf or docs:
The following four GUC variables are defined in guc.c, but are not included in 
postgresql.conf.sample, and do not show up in the online docs under anything 
I can search on.  Do they do anything?  If so, what?


{"fixbtree", PGC_POSTMASTER}, &FixBTree,
		true, NULL, NULL
{"pre_auth_delay", PGC_SIGHUP}, &PreAuthDelay,
		0, 0, 60, NULL, NULL
{"server_encoding", PGC_USERSET}, &server_encoding_string,
		"SQL_ASCII", assign_server_encoding, show_server_encoding
{"session_authorization", PGC_USERSET, GUC_NO_SHOW_ALL | GUC_NO_RESET_ALL},
		&session_authorization_string,
		NULL, assign_session_authorization, show_session_authorization
		

Defined in guc.c and docs but not in postgresql.conf:
These four related settings are defined guc's that somehow made it into the 
docs but not into postgresql.conf.sample:

{"lc_messages", PGC_SUSET}, &locale_messages,
"", locale_messages_assign, NULL

{"lc_monetary", PGC_USERSET}, &locale_monetary,
"C", locale_monetary_assign, NULL

{"lc_numeric", PGC_USERSET}, &locale_numeric,
"C", locale_numeric_assign, NULL

{"lc_time", PGC_USERSET}, &locale_time,
"C", locale_time_assign, NULL


Hope that helps clean up for the next release!

-- 
Josh Berkus
Aglio Database Solutions
San Francisco


Mon, 12 May 2003 22:09:12 -0700
Josh Berkus <josh@agliodbs.com>
Re: GUC and postgresql.conf docs
Josh Berkus <josh@agliodbs.com> writes:
> GUC Options with no documentation:
> The following options exist in postgresql.conf.sample and in guc.c but not in
> the online documenation anywhere the search box can find:

> trace_locks
> trace_userlocks
> trace_lwlocks
> debug_deadlocks
> trace_lock_oidmin
> trace_lock_table
> show_btree_build_stats

These are all debugging options that probably don't need to be in the
user documentation (ie, if you aren't familiar enough with the source
code to find out about 'em from there, you do not need them and should
probably not be messing with 'em --- in fact, many of them don't even
exist except in specially-hacked builds).  I'd vote for taking them out
of postgresql.conf.sample, I think.

> The following four GUC variables are defined in guc.c, but are not included in 
> postgresql.conf.sample, and do not show up in the online docs under anything 
> I can search on.  Do they do anything?  If so, what?

> {"fixbtree", PGC_POSTMASTER}, &FixBTree,
> 		true, NULL, NULL

This one is gone anyway in CVS tip.

> {"pre_auth_delay", PGC_SIGHUP}, &PreAuthDelay,
> 		0, 0, 60, NULL, NULL

This is another debugging option of rather questionable general
usefulness.

> {"server_encoding", PGC_USERSET}, &server_encoding_string,
> 		"SQL_ASCII", assign_server_encoding, show_server_encoding

I'm not sure why this one is marked PGC_USERSET --- seems like it should
not be possible to override it from SET.  It should be documented as a
read-only option, I think.  (Looks ... actually it is set up that way
in CVS tip.)

> {"session_authorization", PGC_USERSET, GUC_NO_SHOW_ALL | GUC_NO_RESET_ALL},
> 		&session_authorization_string,
> 		NULL, assign_session_authorization, show_session_authorization

This one makes no sense to set in postgresql.conf, certainly.  Not sure
how the docs ought to describe it.

> These four related settings are defined guc's that somehow made it into the 
> docs but not into postgresql.conf.sample:

> {"lc_messages", PGC_SUSET}, &locale_messages,
> "", locale_messages_assign, NULL
> {"lc_monetary", PGC_USERSET}, &locale_monetary,
> "C", locale_monetary_assign, NULL
> {"lc_numeric", PGC_USERSET}, &locale_numeric,
> "C", locale_numeric_assign, NULL
> {"lc_time", PGC_USERSET}, &locale_time,
> "C", locale_time_assign, NULL

These guys are added to postgresql.conf by initdb, so I think that's
okay.  But perhaps that process could be documented better.

			regards, tom lane


Tue, 13 May 2003 01:25:05 -0400
Tom Lane <tgl@sss.pgh.pa.us>
Re: GUC and postgresql.conf docs 
Tom Lane writes:

> > {"server_encoding", PGC_USERSET}, &server_encoding_string,
> > 		"SQL_ASCII", assign_server_encoding, show_server_encoding
>
> I'm not sure why this one is marked PGC_USERSET --- seems like it should
> not be possible to override it from SET.  It should be documented as a
> read-only option, I think.  (Looks ... actually it is set up that way
> in CVS tip.)

Do we even need this one?  If you want to find out the server encoding
(which should be rare anyway), you can select it from pg_database.

-- 
Peter Eisentraut   peter_e@gmx.net


Tue, 13 May 2003 10:04:03 +0200 (CEST)
Peter Eisentraut <peter_e@gmx.net>
Re: GUC and postgresql.conf docs 
Peter Eisentraut <peter_e@gmx.net> writes:
> {"server_encoding", PGC_USERSET}, &server_encoding_string,
> "SQL_ASCII", assign_server_encoding, show_server_encoding

> Do we even need this one?  If you want to find out the server encoding
> (which should be rare anyway), you can select it from pg_database.

This is now in the same class as server_version, i.e., it's a read-only
GUC variable.  I did it that way so that these values could be
transmitted to the frontend via the new 3.0 protocol's ParameterStatus
mechanism.

I know we have a difference of opinion about the cleanliness of
read-only "variables", but I think it's a reasonable approach to take.
It certainly beats inventing a mechanism that duplicates the display
portions of GUC.  For instance, isn't "show lc_collate" a lot better
than having to run pg_controldata to find out the database locale?

			regards, tom lane


Tue, 13 May 2003 09:54:30 -0400
Tom Lane <tgl@sss.pgh.pa.us>
Re: GUC and postgresql.conf docs 
Tom Lane writes:

> This is now in the same class as server_version, i.e., it's a read-only
> GUC variable.  I did it that way so that these values could be
> transmitted to the frontend via the new 3.0 protocol's ParameterStatus
> mechanism.

Do we need to communicate the server encoding during any part of the
protocol?  ISTM that the server encoding shouldn't ever be needed by a
client for computation, except out of pure interest.

> For instance, isn't "show lc_collate" a lot better than having to run
> pg_controldata to find out the database locale?

No, because you would like to be able to see it inside an SQL session.
But the server encoding can already be fetched inside an SQL session from
the official source.  A read-only parameter to make this information
available in a different way just seems wasteful.  We don't have read-only
parameters for any of the other columns in pg_database either.

-- 
Peter Eisentraut   peter_e@gmx.net


Tue, 13 May 2003 17:43:11 +0200 (CEST)
Peter Eisentraut <peter_e@gmx.net>
Re: GUC and postgresql.conf docs 
Guys,

One dumb question:

What numbers are INT_MAX and DBL_MAX in C?   

-- 
Josh Berkus
Aglio Database Solutions
San Francisco


Tue, 13 May 2003 09:16:44 -0700
Josh Berkus <josh@agliodbs.com>
Re: GUC and postgresql.conf docs


--On Tuesday, May 13, 2003 09:16:44 -0700 Josh Berkus <josh@agliodbs.com> 
wrote:

> Guys,
>
> One dumb question:
>
> What numbers are INT_MAX and DBL_MAX in C?
The maximum for that type that can be represented.  It's platform dependent.

on FreeBSD 4:
#define INT_MAX         0x7fffffff      /* max value for an int */
#define DBL_MAX         1.7976931348623157E+308



-- 
Larry Rosenman                     http://www.lerctr.org/~ler
Phone: +1 972-414-9812                 E-Mail: ler@lerctr.org
US Mail: 1905 Steamboat Springs Drive, Garland, TX 75044-6749


Tue, 13 May 2003 11:20:26 -0500
Larry Rosenman <ler@lerctr.org>
Re: GUC and postgresql.conf docs
Peter Eisentraut <peter_e@gmx.net> writes:
> Do we need to communicate the server encoding during any part of the
> protocol?

Probably.  What if the client needs to know what is the set of
characters that can actually be stored in the database?  client_encoding
doesn't tell you the whole truth on that.  I'm also still unconvinced
that binary data I/O should perform encoding conversion (it does as of
CVS tip, but I'm not 100% sold that that's the right choice).

> But the server encoding can already be fetched inside an SQL session from
> the official source.

... if you know where to look for it, and if you know that you are not
currently in an aborted transaction, and probably a few other "if's".

> A read-only parameter to make this information
> available in a different way just seems wasteful.

It is duplicative to a certain extent, but the point is to make life
easier for client libraries.  See past discussions with Barry Lind in
particular.  The general mechanism seems necessary in any case, and
once we have it, applying it to these particular values isn't adding
much bloat.

			regards, tom lane


Tue, 13 May 2003 13:30:54 -0400
Tom Lane <tgl@sss.pgh.pa.us>
Re: GUC and postgresql.conf docs 
Tom Lane writes:

> > Do we need to communicate the server encoding during any part of the
> > protocol?
>
> Probably.  What if the client needs to know what is the set of
> characters that can actually be stored in the database?

That sort of thing might be interesting to know, but it does not seem to
be part of the protocol.

Anyway, you cannot answer that question reliably by looking at the server
encoding.  You need to know which conversion will be invoked and what that
conversion will do, and that is a lot harder to do programmatically.

> I'm also still unconvinced that binary data I/O should perform encoding
> conversion (it does as of CVS tip, but I'm not 100% sold that that's the
> right choice).

That depends on what you intend to achieve with the binary format.  For
some of the numeric types it's obvious, but for strings it's not.

> The general mechanism seems necessary in any case, and once we have it,
> applying it to these particular values isn't adding much bloat.

But where does it stop?  What's the criterion?

-- 
Peter Eisentraut   peter_e@gmx.net


Wed, 14 May 2003 00:46:47 +0200 (CEST)
Peter Eisentraut <peter_e@gmx.net>
Re: GUC and postgresql.conf docs 
Peter Eisentraut <peter_e@gmx.net> writes:
> Tom Lane writes:
>> I'm also still unconvinced that binary data I/O should perform encoding
>> conversion (it does as of CVS tip, but I'm not 100% sold that that's the
>> right choice).

> That depends on what you intend to achieve with the binary format.  For
> some of the numeric types it's obvious, but for strings it's not.

Sorry if I wasn't clear.  Binary-encoded numeric values don't go through
encoding conversion.  Text strings currently do.  The only place where I
had any difficulty deciding what a particular datatype should do is with
the 1-byte "char" type, which has a foot in both camps.  I decided to
treat it as an unconverted single byte (but am willing to listen to
argument if anyone thinks differently).

>> The general mechanism seems necessary in any case, and once we have it,
>> applying it to these particular values isn't adding much bloat.

> But where does it stop?  What's the criterion?

Usefulness to client libraries, I think.  If anyone pops up and says "my
library really needs to know the value of setting X", I'm happy to add X
to the set of values reported by ParameterStatus.  If that set starts to
get large then I'd be willing to think about making it
run-time-configurable --- the only reason it isn't already is we don't
have enough examples to prove the need.

			regards, tom lane


Tue, 13 May 2003 19:04:05 -0400
Tom Lane <tgl@sss.pgh.pa.us>
Re: GUC and postgresql.conf docs 
Tom, Peter,

While I'm writing this guide ... where does PostgreSQL store temp files for 
queires which are too large for sort_mem?   I can't seem to find docs on 
this.

-- 
-Josh Berkus
 Aglio Database Solutions
 San Francisco


Tue, 13 May 2003 16:21:58 -0700
Josh Berkus <josh@agliodbs.com>
Re: GUC and postgresql.conf docs
Josh Berkus <josh@agliodbs.com> writes:
> While I'm writing this guide ... where does PostgreSQL store temp files for 
> queires which are too large for sort_mem?

Each database has a temp directory.  I think it's called
$PGDATA/base/DBOID/pgsql_tmp.  You can replace that subdirectory by a
symlink if you want to put temp files someplace else.

			regards, tom lane


Tue, 13 May 2003 19:37:36 -0400
Tom Lane <tgl@sss.pgh.pa.us>
Re: GUC and postgresql.conf docs 
Tom Lane wrote:
> Josh Berkus <josh@agliodbs.com> writes:
> > GUC Options with no documentation:
> > The following options exist in postgresql.conf.sample and in guc.c but not in
> > the online documenation anywhere the search box can find:
> 
> > trace_locks
> > trace_userlocks
> > trace_lwlocks
> > debug_deadlocks
> > trace_lock_oidmin
> > trace_lock_table
> > show_btree_build_stats
> 
> These are all debugging options that probably don't need to be in the
> user documentation (ie, if you aren't familiar enough with the source
> code to find out about 'em from there, you do not need them and should
> probably not be messing with 'em --- in fact, many of them don't even
> exist except in specially-hacked builds).  I'd vote for taking them out
> of postgresql.conf.sample, I think.

Agreed, they should not be in postgresql.conf.

-- 
  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, Pennsylvania 19073

Wed, 14 May 2003 23:37:05 -0400 (EDT)
Bruce Momjian <pgman@candle.pha.pa.us>
Re: GUC and postgresql.conf docs
Josh Berkus wrote:
> Tom, Peter,
> 
> While I'm writing this guide ... where does PostgreSQL store temp files for 
> queires which are too large for sort_mem?   I can't seem to find docs on 
> this.

They exist under each database directory in /pgsql_tmp.

-- 
  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, Pennsylvania 19073

Wed, 14 May 2003 23:38:34 -0400 (EDT)
Bruce Momjian <pgman@candle.pha.pa.us>
Re: GUC and postgresql.conf docs
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.)

I also added comments to guc.c to indicate settings that shouldn't be in
postgresql.conf so we have a record of why they are not in there.

All the other mentioned items have already been dealt with.

---------------------------------------------------------------------------

Tom Lane wrote:
> Josh Berkus <josh@agliodbs.com> writes:
> > GUC Options with no documentation:
> > The following options exist in postgresql.conf.sample and in guc.c but not in
> > the online documenation anywhere the search box can find:
> 
> > trace_locks
> > trace_userlocks
> > trace_lwlocks
> > debug_deadlocks
> > trace_lock_oidmin
> > trace_lock_table
> > show_btree_build_stats
> 
> These are all debugging options that probably don't need to be in the
> user documentation (ie, if you aren't familiar enough with the source
> code to find out about 'em from there, you do not need them and should
> probably not be messing with 'em --- in fact, many of them don't even
> exist except in specially-hacked builds).  I'd vote for taking them out
> of postgresql.conf.sample, I think.
> 
> > The following four GUC variables are defined in guc.c, but are not included in 
> > postgresql.conf.sample, and do not show up in the online docs under anything 
> > I can search on.  Do they do anything?  If so, what?
> 
> > {"fixbtree", PGC_POSTMASTER}, &FixBTree,
> > 		true, NULL, NULL
> 
> This one is gone anyway in CVS tip.
> 
> > {"pre_auth_delay", PGC_SIGHUP}, &PreAuthDelay,
> > 		0, 0, 60, NULL, NULL
> 
> This is another debugging option of rather questionable general
> usefulness.
> 
> > {"server_encoding", PGC_USERSET}, &server_encoding_string,
> > 		"SQL_ASCII", assign_server_encoding, show_server_encoding
> 
> I'm not sure why this one is marked PGC_USERSET --- seems like it should
> not be possible to override it from SET.  It should be documented as a
> read-only option, I think.  (Looks ... actually it is set up that way
> in CVS tip.)
> 
> > {"session_authorization", PGC_USERSET, GUC_NO_SHOW_ALL | GUC_NO_RESET_ALL},
> > 		&session_authorization_string,
> > 		NULL, assign_session_authorization, show_session_authorization
> 
> This one makes no sense to set in postgresql.conf, certainly.  Not sure
> how the docs ought to describe it.
> 
> > These four related settings are defined guc's that somehow made it into the 
> > docs but not into postgresql.conf.sample:
> 
> > {"lc_messages", PGC_SUSET}, &locale_messages,
> > "", locale_messages_assign, NULL
> > {"lc_monetary", PGC_USERSET}, &locale_monetary,
> > "C", locale_monetary_assign, NULL
> > {"lc_numeric", PGC_USERSET}, &locale_numeric,
> > "C", locale_numeric_assign, NULL
> > {"lc_time", PGC_USERSET}, &locale_time,
> > "C", locale_time_assign, NULL
> 
> These guys are added to postgresql.conf by initdb, so I think that's
> okay.  But perhaps that process could be documented better.
> 
> 			regards, tom lane
> 
> 
> ---------------------------(end of broadcast)---------------------------
> TIP 1: subscribe and unsubscribe commands go to majordomo@postgresql.org
> 

-- 
  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, Pennsylvania 19073

Index: src/backend/utils/misc/guc.c
===================================================================
RCS file: /cvsroot/pgsql-server/src/backend/utils/misc/guc.c,v
retrieving revision 1.127
diff -c -c -r1.127 guc.c
*** src/backend/utils/misc/guc.c	28 May 2003 18:19:09 -0000	1.127
--- src/backend/utils/misc/guc.c	2 Jun 2003 16:03:20 -0000
***************
*** 689,694 ****
--- 689,695 ----
  		60, 1, 600, NULL, NULL
  	},
  
+ 	/* Not for general use */
  	{
  		{"pre_auth_delay", PGC_SIGHUP}, &PreAuthDelay,
  		0, 0, 60, NULL, NULL
***************
*** 871,876 ****
--- 872,878 ----
  		"$user,public", assign_search_path, NULL
  	},
  
+ 	/* Can't be set in postgresql.conf */
  	{
  		{"server_encoding", PGC_INTERNAL, GUC_REPORT},
  		&server_encoding_string,
***************
*** 888,893 ****
--- 890,896 ----
  		"notice", assign_log_min_messages, NULL
  	},
  
+ 	/* Not for general use --- used by SET SESSION AUTHORIZATION */
  	{
  		{"session_authorization", PGC_USERSET, GUC_NO_SHOW_ALL | GUC_NO_RESET_ALL},
  		&session_authorization_string,
Index: src/backend/utils/misc/postgresql.conf.sample
===================================================================
RCS file: /cvsroot/pgsql-server/src/backend/utils/misc/postgresql.conf.sample,v
retrieving revision 1.78
diff -c -c -r1.78 postgresql.conf.sample
*** src/backend/utils/misc/postgresql.conf.sample	14 May 2003 03:26:02 -0000	1.78
--- src/backend/utils/misc/postgresql.conf.sample	2 Jun 2003 16:03:20 -0000
***************
*** 182,201 ****
  
  
  #
- #	Lock Tracing
- #
- #trace_notify = false
- 
- # requires LOCK_DEBUG
- #trace_locks = false
- #trace_userlocks = false
- #trace_lwlocks = false
- #debug_deadlocks = false
- #trace_lock_oidmin = 16384
- #trace_lock_table = 0
- 
- 
- #
  #	Misc
  #
  #dynamic_library_path = '$libdir'
--- 182,187 ----
Mon, 2 Jun 2003 12:07:28 -0400 (EDT)
Bruce Momjian <pgman@candle.pha.pa.us>
Re: [HACKERS] 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.  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
Mon, 2 Jun 2003 10:01:31 -0700
Josh Berkus <josh@agliodbs.com>
Proposal for Re-ordering CONF (was: Re: GUC and postgresql.conf docs)

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, Pennsylvania 19073

Mon, 2 Jun 2003 13:08:55 -0400 (EDT)
Bruce Momjian <pgman@candle.pha.pa.us>
Re: Proposal for Re-ordering CONF (was: Re: GUC and postgresql.conf
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

Mon, 2 Jun 2003 10:15:28 -0700
Josh Berkus <josh@agliodbs.com>
Re: Proposal for Re-ordering CONF (was: Re: GUC and postgresql.conf
	docs)
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

Mon, 02 Jun 2003 13:36:43 -0400
Tom Lane <tgl@sss.pgh.pa.us>
Re: Proposal for Re-ordering CONF (was: Re: GUC and postgresql.conf
	docs)
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

Mon, 2 Jun 2003 11:04:01 -0700
Josh Berkus <josh@agliodbs.com>
Re: Proposal for Re-ordering CONF (was: Re: GUC and postgresql.conf
	docs)