Re: Improving postgresql.conf

Lists: pgsql-hackers
From: "Greg Sabino Mullane" <greg(at)turnstep(dot)com>
To: pgsql-hackers(at)postgresql(dot)org
Subject: Improving postgresql.conf
Date: 2004-06-09 10:19:52
Message-ID: f8b35db42df1c3af53c557da477ac2ce@biglumber.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers


-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1


(warning: rehashing of issues ahead)

Sometimes when I talk to technical people about using PostgreSQL,
I get a strong reaction along the lines of "it's ugly, complex, and
hard to set up." While we have gotten better than we used to be,
some of this is still true. I usually press for further details.
One of the top items mentioned is the configuration files,
especially postgresql.conf. Specifically, it is non-standard and
cryptic.

One thing that would go a long way is to remove the confusing
"default is commented out" behavior. This is ugly and unnecessary:
simply explicitly list every value.

The second thing that would help is better documentation. It doesn't
have to be quite as verbose as the httpd.conf file, but a nice
multi-line explanation of every item in the file, perhaps with a
URL for further information, would be a very nice addition. Moving
the comments above each item, rather than trying to squeeze some of
them next to the parameter, would also make the file more readable
and more consistent.

For example, this original sample:

#shared_buffers = 1000 # min 16, at least max_connections*2, 8KB each
#work_mem = 1024 # min 64, size in KB

becomes:

## shared_buffers (kilobytes)
## Sets the number of shared memory buffers used by the database server.
## Increasing the number of buffers makes it more likely backends will find
## the information they need in the cache, thus avoiding an expensive operating
## system request. The default is typically 1000, but may be less if your
## kernel settings will not support it. Each buffer is 8192 bytes. The minimum
## value is 16, or twice the value of the 'max_connections' parameter. Settings
## significantly higher than the minimum are usually needed for good performance.
## Values of a few thousand are recommended for production installations.
## URL: http://www.postgresql.org/docs/current/static/runtime-config.html

shared_buffers = 1000


## work_mem (kilobytes)
## (Previously known as sort_mem)
## Sets the amount of memory to be used by internal sort operations and hash tables before
## switching to temporary disk files. The default value is 1024 kilobytes (1 MB).
## Note that for a complex query, several sort or hash operations might be running in parallel;
## each one will be allowed to use up to the value set here before it starts to put data
## into temporary files. Also, several running sessions could be doing sort operations
## simultaneously. So the total memory used could be many times the value set here.

work_mem = 1024



- --
Greg Sabino Mullane greg(at)turnstep(dot)com
PGP Key: 0x14964AC8 200406090615

-----BEGIN PGP SIGNATURE-----

iD8DBQFAxuPnvJuQZxSWSsgRAgAtAKDReW6WOREYapbWi61yacBi05im6gCeLrvd
Dj/mlTtUh97C1gHVkJTtLyY=
=J0CZ
-----END PGP SIGNATURE-----


From: Bruce Momjian <pgman(at)candle(dot)pha(dot)pa(dot)us>
To: Greg Sabino Mullane <greg(at)turnstep(dot)com>
Cc: pgsql-hackers(at)postgresql(dot)org
Subject: Re: Improving postgresql.conf
Date: 2004-06-09 13:24:54
Message-ID: 200406091324.i59DOsf13949@candle.pha.pa.us
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers


We discussed this and thought that it would end up duplicating stuff
already in the docs, and removing the comments means that you have no
way to know which are being set to non-default values. Both seem to be
a loss.

Are people saying the Apache config files are easier to use? I actually
find it quite hard to understand, especially httpd.conf.

One idea that has been floated around is to pull the docs automatically
from SGML and put them in postgresql.conf. We do that for psql's use of
\help now, so it seems this is possible.

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

Greg Sabino Mullane wrote:
[ There is text before PGP section. ]
>
[ PGP not available, raw data follows ]
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
>
> (warning: rehashing of issues ahead)
>
> Sometimes when I talk to technical people about using PostgreSQL,
> I get a strong reaction along the lines of "it's ugly, complex, and
> hard to set up." While we have gotten better than we used to be,
> some of this is still true. I usually press for further details.
> One of the top items mentioned is the configuration files,
> especially postgresql.conf. Specifically, it is non-standard and
> cryptic.
>
> One thing that would go a long way is to remove the confusing
> "default is commented out" behavior. This is ugly and unnecessary:
> simply explicitly list every value.
>
> The second thing that would help is better documentation. It doesn't
> have to be quite as verbose as the httpd.conf file, but a nice
> multi-line explanation of every item in the file, perhaps with a
> URL for further information, would be a very nice addition. Moving
> the comments above each item, rather than trying to squeeze some of
> them next to the parameter, would also make the file more readable
> and more consistent.
>
> For example, this original sample:
>
> #shared_buffers = 1000 # min 16, at least max_connections*2, 8KB each
> #work_mem = 1024 # min 64, size in KB
>
> becomes:
>
> ## shared_buffers (kilobytes)
> ## Sets the number of shared memory buffers used by the database server.
> ## Increasing the number of buffers makes it more likely backends will find
> ## the information they need in the cache, thus avoiding an expensive operating
> ## system request. The default is typically 1000, but may be less if your
> ## kernel settings will not support it. Each buffer is 8192 bytes. The minimum
> ## value is 16, or twice the value of the 'max_connections' parameter. Settings
> ## significantly higher than the minimum are usually needed for good performance.
> ## Values of a few thousand are recommended for production installations.
> ## URL: http://www.postgresql.org/docs/current/static/runtime-config.html
>
> shared_buffers = 1000
>
>
> ## work_mem (kilobytes)
> ## (Previously known as sort_mem)
> ## Sets the amount of memory to be used by internal sort operations and hash tables before
> ## switching to temporary disk files. The default value is 1024 kilobytes (1 MB).
> ## Note that for a complex query, several sort or hash operations might be running in parallel;
> ## each one will be allowed to use up to the value set here before it starts to put data
> ## into temporary files. Also, several running sessions could be doing sort operations
> ## simultaneously. So the total memory used could be many times the value set here.
>
> work_mem = 1024
>
>
>
> - --
> Greg Sabino Mullane greg(at)turnstep(dot)com
> PGP Key: 0x14964AC8 200406090615
>
> -----BEGIN PGP SIGNATURE-----
>
> iD8DBQFAxuPnvJuQZxSWSsgRAgAtAKDReW6WOREYapbWi61yacBi05im6gCeLrvd
> Dj/mlTtUh97C1gHVkJTtLyY=
> =J0CZ
> -----END PGP SIGNATURE-----
>
>
>
> ---------------------------(end of broadcast)---------------------------
> TIP 4: Don't 'kill -9' the postmaster
>
[ Decrypting message... End of raw data. ]

--
Bruce Momjian | http://candle.pha.pa.us
pgman(at)candle(dot)pha(dot)pa(dot)us | (610) 359-1001
+ If your life is a hard drive, | 13 Roberts Road
+ Christ can be your backup. | Newtown Square, Pennsylvania 19073


From: Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>
To: Bruce Momjian <pgman(at)candle(dot)pha(dot)pa(dot)us>
Cc: Greg Sabino Mullane <greg(at)turnstep(dot)com>, pgsql-hackers(at)postgresql(dot)org
Subject: Re: Improving postgresql.conf
Date: 2004-06-09 14:10:19
Message-ID: 20658.1086790219@sss.pgh.pa.us
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

Bruce Momjian <pgman(at)candle(dot)pha(dot)pa(dot)us> writes:
> One idea that has been floated around is to pull the docs automatically
> from SGML and put them in postgresql.conf.

In theory, postgresql.conf.sample could be a generated file: pull the
docs from SGML and the default values from the GUC tables. However I'm
of the same opinion Bruce mentioned, that duplicating the docs in the
file isn't an improvement. Perhaps it would help to put an explicit
pointer to the docs at the top of the file?

regards, tom lane


From: pgsql(at)mohawksoft(dot)com
To: "Greg Sabino Mullane" <greg(at)turnstep(dot)com>
Cc: pgsql-hackers(at)postgresql(dot)org
Subject: Re: Improving postgresql.conf
Date: 2004-06-09 14:11:11
Message-ID: 18104.64.119.142.34.1086790271.squirrel@mail.mohawksoft.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

I have a LOT of opinions about postgresql.conf, and frankly, I think more
comments are not where the problems lie.

If you *really* want to make configuring postgresql easier,
postgresql.conf HAS to live outside the data directory and specify where
everything is. postgresql.conf should do exactly as one would assume it
does, configure postgresql.

Right now it doesn't. Right now it just sets parameters and the "-D" or
PGDATA environment variable *really* configure postgresql. If you do not
know how a machine is setup, you have to look for the install. Hopefuly,
the previous administrator did not have any test directories which would
confuse the search. Sorry, I'm ranting.

In an ideal world, I envision Postgresql having a default location for
postgresql.conf, in this file will be the declarations for where the data
directory is, possible included files, etc. i.e. the stuff I've been
pushing litterally for years. I am not saying that the current behavior
change in any way, what I am saying is that a more world compatible
methodology should be possible.

Once the postgresql.conf file is out of the data directory, you have a new
paradigm from which to work. One could write a setup application, in java
or something, which creates a new postgresql.conf file, right down to
where you want the installed directory to be, and THAT is used by initdb.
The setup application can also provide context sensitive help for each of
the setting. The user may not even *know* that there is such a file as
postgresql.conf.

The application should behave like a control panel of sorts which would
allow you to modify an existing configuration file and optionally restart
the correct postgresql process.

(Obviously, this program can be made to look at other files in other
locations.)

The work flow would be something like this:

run setup application.
Choose volume and directory for database.
set various options
press OK
standard "are you sure" dialog.
run initdb with variables,

In linux, freebsd, or Windows, have the option to start server at system
start.

This is all basically doable right now. Granted we have to hammer out a
few details in my configuration patch, but there are no show stoppers that
I can see. I even have a Windows application which will start and monitor
a cygwin PostgreSQL. It should be easily modified for a mingwin version.

That, IMHO, would *really* make PostgreSQL easy, almost brainless to
install and use.

>
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
>
> (warning: rehashing of issues ahead)
>
> Sometimes when I talk to technical people about using PostgreSQL,
> I get a strong reaction along the lines of "it's ugly, complex, and
> hard to set up." While we have gotten better than we used to be,
> some of this is still true. I usually press for further details.
> One of the top items mentioned is the configuration files,
> especially postgresql.conf. Specifically, it is non-standard and
> cryptic.
>
> One thing that would go a long way is to remove the confusing
> "default is commented out" behavior. This is ugly and unnecessary:
> simply explicitly list every value.
>
> The second thing that would help is better documentation. It doesn't
> have to be quite as verbose as the httpd.conf file, but a nice
> multi-line explanation of every item in the file, perhaps with a
> URL for further information, would be a very nice addition. Moving
> the comments above each item, rather than trying to squeeze some of
> them next to the parameter, would also make the file more readable
> and more consistent.
>
> For example, this original sample:
>
> #shared_buffers = 1000 # min 16, at least max_connections*2, 8KB
> each
> #work_mem = 1024 # min 64, size in KB
>
> becomes:
>
> ## shared_buffers (kilobytes)
> ## Sets the number of shared memory buffers used by the database server.
> ## Increasing the number of buffers makes it more likely backends will
> find
> ## the information they need in the cache, thus avoiding an expensive
> operating
> ## system request. The default is typically 1000, but may be less if your
> ## kernel settings will not support it. Each buffer is 8192 bytes. The
> minimum
> ## value is 16, or twice the value of the 'max_connections' parameter.
> Settings
> ## significantly higher than the minimum are usually needed for good
> performance.
> ## Values of a few thousand are recommended for production installations.
> ## URL: http://www.postgresql.org/docs/current/static/runtime-config.html
>
> shared_buffers = 1000
>
>
> ## work_mem (kilobytes)
> ## (Previously known as sort_mem)
> ## Sets the amount of memory to be used by internal sort operations and
> hash tables before
> ## switching to temporary disk files. The default value is 1024 kilobytes
> (1 MB).
> ## Note that for a complex query, several sort or hash operations might be
> running in parallel;
> ## each one will be allowed to use up to the value set here before it
> starts to put data
> ## into temporary files. Also, several running sessions could be doing
> sort operations
> ## simultaneously. So the total memory used could be many times the value
> set here.
>
> work_mem = 1024
>
>
>
> - --
> Greg Sabino Mullane greg(at)turnstep(dot)com
> PGP Key: 0x14964AC8 200406090615
>
> -----BEGIN PGP SIGNATURE-----
>
> iD8DBQFAxuPnvJuQZxSWSsgRAgAtAKDReW6WOREYapbWi61yacBi05im6gCeLrvd
> Dj/mlTtUh97C1gHVkJTtLyY=
> =J0CZ
> -----END PGP SIGNATURE-----
>
>
>
> ---------------------------(end of broadcast)---------------------------
> TIP 4: Don't 'kill -9' the postmaster
>


From: Shridhar Daithankar <shridhar(at)frodo(dot)hserus(dot)net>
To: pgsql(at)mohawksoft(dot)com
Cc: pgsql-hackers(at)postgresql(dot)org
Subject: Re: Improving postgresql.conf
Date: 2004-06-09 14:23:19
Message-ID: 40C71D57.9040802@frodo.hserus.net
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

pgsql(at)mohawksoft(dot)com wrote:

> I have a LOT of opinions about postgresql.conf, and frankly, I think more
> comments are not where the problems lie.
>
> If you *really* want to make configuring postgresql easier,
> postgresql.conf HAS to live outside the data directory and specify where
> everything is. postgresql.conf should do exactly as one would assume it
> does, configure postgresql.
>
> Right now it doesn't. Right now it just sets parameters and the "-D" or
> PGDATA environment variable *really* configure postgresql. If you do not
> know how a machine is setup, you have to look for the install. Hopefuly,
> the previous administrator did not have any test directories which would
> confuse the search. Sorry, I'm ranting.
>
> In an ideal world, I envision Postgresql having a default location for
> postgresql.conf, in this file will be the declarations for where the data
> directory is, possible included files, etc. i.e. the stuff I've been
> pushing litterally for years. I am not saying that the current behavior
> change in any way, what I am saying is that a more world compatible
> methodology should be possible.
>
> Once the postgresql.conf file is out of the data directory, you have a new
> paradigm from which to work. One could write a setup application, in java
> or something, which creates a new postgresql.conf file, right down to
> where you want the installed directory to be, and THAT is used by initdb.
> The setup application can also provide context sensitive help for each of
> the setting. The user may not even *know* that there is such a file as
> postgresql.conf.

Well, the statement 'postgresql.conf outside data directory' isn't going to win
I think.

postgresql.conf is a cluster configuration file. I remember previous discussion
on this and I agree with that a cluster configuration file should remain in
cluster itself.

Let me put it in a different way. What you are asking is a service configuration
file. It is *not* same as current postgresql configuration file. It will/should
be unique to a perticular installation of postgresql. i.e. something like
/etc/postgresql/7.4.2/service.conf

I think it makes a lot of sense then. It would allow to maitain different
clusters, like in another thread where OP wanted different locales/collation.
And it will still allow multiple versions of postgresql to be installed.

I remember chasing mandrake couple of years ago for not to make postgresql
database live in /var/lib/data... but to make it configurable. It didn't go
anywhere though.

I think it is a rather good idea to add service configuration to default
postgresql install. May be linux distro. vendors can customize thr. the init
scripts.

Also pulling postgresql.conf out of cluster has a drawback. All the clusters
would have to share same tuning parameters which is not exactly ideal. If we
define a services file with multiple clusters we woudl still provide ultimate
control to the DBA/system admin.

Just a thought..

Shridhar


From: Andrew Dunstan <andrew(at)dunslane(dot)net>
To: pgsql-hackers(at)postgresql(dot)org
Subject: Re: Improving postgresql.conf
Date: 2004-06-09 15:05:20
Message-ID: 40C72730.1070301@dunslane.net
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers


Greg Sabino Mullane wrote:

>(warning: rehashing of issues ahead)
>
>[snipped: suggestion to have much more documentation in sample postgresql.conf]
>
>

Wasn't RedHat working on a configuration utility for Postgres? That
seems to me like a much more productive way to go.

cheers

andrew


From: Honza Pazdziora <adelton(at)informatics(dot)muni(dot)cz>
To: Shridhar Daithankar <shridhar(at)frodo(dot)hserus(dot)net>
Cc: pgsql-hackers(at)postgresql(dot)org
Subject: Re: Improving postgresql.conf
Date: 2004-06-09 15:26:44
Message-ID: 20040609152644.GE29863@anxur.fi.muni.cz
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

On Wed, Jun 09, 2004 at 07:53:19PM +0530, Shridhar Daithankar wrote:
>
> Well, the statement 'postgresql.conf outside data directory' isn't going to
> win I think.

One day there won't be any data directory because the data will be
on raw partitions. Then you will _have_ to have the configuration
somewhere else. Ideally, only the absolute minimum of parameters
needed to start the server ought to be in the external configuration.
Everything else may happily reside within the database storage.

> Let me put it in a different way. What you are asking is a service
> configuration file. It is *not* same as current postgresql configuration
> file. It will/should be unique to a perticular installation of postgresql.
> i.e. something like /etc/postgresql/7.4.2/service.conf

Why? The administrator may want to run second cluster on the same
machine, share a couple of options using "include" directive while
preserving separate configuration, including the location of data
store, for things that should be different for each of these
clusters.

> I think it is a rather good idea to add service configuration to default

What is that "service" you mention?

> Also pulling postgresql.conf out of cluster has a drawback. All the
> clusters would have to share same tuning parameters which is not exactly
> ideal.

Why would they _have_ to? Pulling postgresql.conf out of cluster only
means that the file resides somewhere else and in it the location of
the data directory is specified. It does not mandate there will only
be one cluster and it does not mean that each cluster cannot have
completely different configuration file.

--
------------------------------------------------------------------------
Honza Pazdziora | adelton(at)fi(dot)muni(dot)cz | http://www.fi.muni.cz/~adelton/
.project: Perl, mod_perl, DBI, Oracle, large Web systems, XML/XSL, ...
Only self-confident people can be simple.


From: Shridhar Daithankar <shridhar(at)frodo(dot)hserus(dot)net>
To: Honza Pazdziora <adelton(at)informatics(dot)muni(dot)cz>
Cc: pgsql-hackers(at)postgresql(dot)org
Subject: Re: Improving postgresql.conf
Date: 2004-06-09 15:43:05
Message-ID: 40C73009.7040307@frodo.hserus.net
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

Honza Pazdziora wrote:

> On Wed, Jun 09, 2004 at 07:53:19PM +0530, Shridhar Daithankar wrote:
>
>>Well, the statement 'postgresql.conf outside data directory' isn't going to
>>win I think.
> One day there won't be any data directory because the data will be
> on raw partitions. Then you will _have_ to have the configuration
> somewhere else. Ideally, only the absolute minimum of parameters
> needed to start the server ought to be in the external configuration.
> Everything else may happily reside within the database storage.

Given that postgresql by design does not outsmart OS in any overlapping
functionality, I doubt we would see raw storage anytime soon but anyways..

>>Let me put it in a different way. What you are asking is a service
>>configuration file. It is *not* same as current postgresql configuration
>>file. It will/should be unique to a perticular installation of postgresql.
>>i.e. something like /etc/postgresql/7.4.2/service.conf
> Why? The administrator may want to run second cluster on the same
> machine, share a couple of options using "include" directive while
> preserving separate configuration, including the location of data
> store, for things that should be different for each of these
> clusters.

Well that is easy. In the service file just say

[Cluster1]
datapath=/data/foo

[Cluster2]
datapath=/data/foo1

and postgresql.conf could still reside inside each cluster to provide specific
configuration.

Thenhave a script which can say 'service postgresql cluster1 start'

>>I think it is a rather good idea to add service configuration to default
> What is that "service" you mention?

Postgresql as a database server is a service. A cluster is an service instance.
A service configuration file documents all service instances and their
parameters required for all tuning and control purposes. Add a possibility of
multiple versions of postgresql on same box. That sums it up pretty well..

>>Also pulling postgresql.conf out of cluster has a drawback. All the
>>clusters would have to share same tuning parameters which is not exactly
>>ideal.
> Why would they _have_ to? Pulling postgresql.conf out of cluster only
> means that the file resides somewhere else and in it the location of
> the data directory is specified. It does not mandate there will only
> be one cluster and it does not mean that each cluster cannot have
> completely different configuration file.

Well, I wish I could have some archives link handy but suffice to say that Tom
has rejected this idea many times before..

Shridhar


From: Honza Pazdziora <adelton(at)informatics(dot)muni(dot)cz>
To: Shridhar Daithankar <shridhar(at)frodo(dot)hserus(dot)net>
Cc: pgsql-hackers(at)postgresql(dot)org
Subject: Re: Improving postgresql.conf
Date: 2004-06-10 06:42:57
Message-ID: 20040610064256.GF29863@anxur.fi.muni.cz
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

On Wed, Jun 09, 2004 at 09:13:05PM +0530, Shridhar Daithankar wrote:
>
> Well that is easy. In the service file just say
>
> [Cluster1]
> datapath=/data/foo
>
> [Cluster2]
> datapath=/data/foo1
>
> and postgresql.conf could still reside inside each cluster to provide
> specific configuration.
>
> Thenhave a script which can say 'service postgresql cluster1 start'

This is awfull way of doing configuration. Why should different
installation share anything, in one file? Running

/usr/bin/pg_ctl -C /etc/postgres.isp1.conf start

seems much more maintainable. And /etc/postgres.isp1.conf can specify
that the data files are in /bigdisk/data/isp1x or wherever you
please.

> Postgresql as a database server is a service. A cluster is an service
> instance. A service configuration file documents all service instances and
> their parameters required for all tuning and control purposes. Add a
> possibility of multiple versions of postgresql on same box. That sums it up

One file does not add possibility of multiple versions of postgresql
on same box, it merely makes it harder.

> Well, I wish I could have some archives link handy but suffice to say that
> Tom has rejected this idea many times before..

That does not necessarily mean the idea is broken. Tom's main
objection (IIRC) was that he needs to be able to have multiple
postgresqls on one machine. That can easily be achieved, either by
specifying datadirectory in the configuration file, or even defaulting
to the same directory where the .conf file is stored when no
datadirectory option is used.

--
------------------------------------------------------------------------
Honza Pazdziora | adelton(at)fi(dot)muni(dot)cz | http://www.fi.muni.cz/~adelton/
.project: Perl, mod_perl, DBI, Oracle, large Web systems, XML/XSL, ...
Only self-confident people can be simple.


From: "Greg Sabino Mullane" <greg(at)turnstep(dot)com>
To: pgsql-hackers(at)postgresql(dot)org
Subject: Re: Improving postgresql.conf
Date: 2004-06-10 11:57:59
Message-ID: 031837d81a4f78d7026db09ada0c7a5e@biglumber.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers


-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1


> We discussed this and thought that it would end up duplicating stuff
> already in the docs

Which is fine. Keeping some documentation in the file itself is a
necessity. For example, we've changed "sort_mem" to "work_mem".
There should at the least be a note to this effect in the postgresql.conf
file. Better yet, there should be a brief explanation of what each of
the parameters _means_ and what each one _does_. It does not have to go
into detail, but there should be enough language to remind somebody what
exactly the sometimes cryptically named parameter does. The name alone
is not enough. When in doubt, it is always better to err on the side
of more verbose documentation.

> and removing the comments means that you have no way to know which are
> being set to non-default values.

This seems a non-issue to me. The end-user does not really care so much
about what is "default" so much as what it is right now. We are overloading
the "#" operator, so to speak, by making it not only a documentation
markup, but by making it a "set default because it is commented out." What
happens when somebody changes the sort_mem to something, and then comments
it out to "turn it back to the default"? The next person looking at the file
is not going to know what the setting is, because instead of the default being
in the documentation part of the file, it is in the commented-out parameter,
and it is now wrong. Far better to explicitly set every parameter. You can
then go into the file and know exactly what each parameter is set to.

> Are people saying the Apache config files are easier to use? I actually
> find it quite hard to understand, especially httpd.conf.

It is certainly well documented. You can step into it for the first time
and have a relatively complete understanding of what each setting does.
It's also laid out logically, but we have mostly addressed this in the
last big rearrangement of postgresql.conf that happened a few months ago.

> One idea that has been floated around is to pull the docs automatically
> from SGML and put them in postgresql.conf. We do that for psql's use of
> \help now, so it seems this is possible.

I'm not sure this is the way to go. The SGML should be more detailed, and
also assumes that you are reading it in a different context than from within
the configuration file.

- --
Greg Sabino Mullane greg(at)turnstep(dot)com
PGP Key: 0x14964AC8 200406100751

-----BEGIN PGP SIGNATURE-----

iD8DBQFAyE0rvJuQZxSWSsgRAqL3AJ0eR28O8LyWV3Kn5wgMtggqJi8/nACeI/JC
onWV778+vewEdBeAI+EYOkw=
=/wqn
-----END PGP SIGNATURE-----


From: Fabien COELHO <coelho(at)cri(dot)ensmp(dot)fr>
To: Greg Sabino Mullane <greg(at)turnstep(dot)com>
Cc: pgsql-hackers(at)postgresql(dot)org
Subject: Re: Improving postgresql.conf
Date: 2004-06-10 12:10:56
Message-ID: Pine.LNX.4.58.0406101404150.23525@sablons.cri.ensmp.fr
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers


Dear Greg,

> > One idea that has been floated around is to pull the docs automatically
> > from SGML and put them in postgresql.conf. We do that for psql's use of
> > \help now, so it seems this is possible.
>
> I'm not sure this is the way to go. The SGML should be more detailed, and
> also assumes that you are reading it in a different context than from within
> the configuration file.

As for the level defail, I guess the idea is to extract only a relevant
part of the sgml doc: parameter name, summary and advices, default value.
Sure the doc can contains more than that, but at least this should be
available.

As for the context, I think that is is factual enough so as to be able to
write documentation that would fit both the doc and the configuration
file.

--
Fabien Coelho - coelho(at)cri(dot)ensmp(dot)fr


From: Bruce Momjian <pgman(at)candle(dot)pha(dot)pa(dot)us>
To: Greg Sabino Mullane <greg(at)turnstep(dot)com>
Cc: pgsql-hackers(at)postgresql(dot)org
Subject: Re: Improving postgresql.conf
Date: 2004-06-10 12:22:39
Message-ID: 200406101222.i5ACMdj14113@candle.pha.pa.us
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers


I understand your points below. However, the group has weighed in the
direction of clearly showing non-default values and not duplicating
documentation. We can change that, but you will need more folks
agreeing with your direction.

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

Greg Sabino Mullane wrote:
[ There is text before PGP section. ]
>
[ PGP not available, raw data follows ]
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
>
> > We discussed this and thought that it would end up duplicating stuff
> > already in the docs
>
> Which is fine. Keeping some documentation in the file itself is a
> necessity. For example, we've changed "sort_mem" to "work_mem".
> There should at the least be a note to this effect in the postgresql.conf
> file. Better yet, there should be a brief explanation of what each of
> the parameters _means_ and what each one _does_. It does not have to go
> into detail, but there should be enough language to remind somebody what
> exactly the sometimes cryptically named parameter does. The name alone
> is not enough. When in doubt, it is always better to err on the side
> of more verbose documentation.
>
> > and removing the comments means that you have no way to know which are
> > being set to non-default values.
>
> This seems a non-issue to me. The end-user does not really care so much
> about what is "default" so much as what it is right now. We are overloading
> the "#" operator, so to speak, by making it not only a documentation
> markup, but by making it a "set default because it is commented out." What
> happens when somebody changes the sort_mem to something, and then comments
> it out to "turn it back to the default"? The next person looking at the file
> is not going to know what the setting is, because instead of the default being
> in the documentation part of the file, it is in the commented-out parameter,
> and it is now wrong. Far better to explicitly set every parameter. You can
> then go into the file and know exactly what each parameter is set to.
>
> > Are people saying the Apache config files are easier to use? I actually
> > find it quite hard to understand, especially httpd.conf.
>
> It is certainly well documented. You can step into it for the first time
> and have a relatively complete understanding of what each setting does.
> It's also laid out logically, but we have mostly addressed this in the
> last big rearrangement of postgresql.conf that happened a few months ago.
>
> > One idea that has been floated around is to pull the docs automatically
> > from SGML and put them in postgresql.conf. We do that for psql's use of
> > \help now, so it seems this is possible.
>
> I'm not sure this is the way to go. The SGML should be more detailed, and
> also assumes that you are reading it in a different context than from within
> the configuration file.
>
> - --
> Greg Sabino Mullane greg(at)turnstep(dot)com
> PGP Key: 0x14964AC8 200406100751
>
> -----BEGIN PGP SIGNATURE-----
>
> iD8DBQFAyE0rvJuQZxSWSsgRAqL3AJ0eR28O8LyWV3Kn5wgMtggqJi8/nACeI/JC
> onWV778+vewEdBeAI+EYOkw=
> =/wqn
> -----END PGP SIGNATURE-----
>
>
>
> ---------------------------(end of broadcast)---------------------------
> TIP 1: subscribe and unsubscribe commands go to majordomo(at)postgresql(dot)org
>
[ Decrypting message... End of raw data. ]

--
Bruce Momjian | http://candle.pha.pa.us
pgman(at)candle(dot)pha(dot)pa(dot)us | (610) 359-1001
+ If your life is a hard drive, | 13 Roberts Road
+ Christ can be your backup. | Newtown Square, Pennsylvania 19073


From: Gaetano Mendola <mendola(at)bigfoot(dot)com>
To: Bruce Momjian <pgman(at)candle(dot)pha(dot)pa(dot)us>
Subject: Re: Improving postgresql.conf
Date: 2004-06-10 18:05:19
Message-ID: 40C8A2DF.2030100@bigfoot.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

Bruce Momjian wrote:

> I understand your points below. However, the group has weighed in the
> direction of clearly showing non-default values and not duplicating
> documentation. We can change that, but you will need more folks
> agreeing with your direction.

I don't remember the behaviour but tell me what happen if
I comment out a value changing the value. Kill UP the postmater.
Recommenting that value and now re killing the postmaster.

I believe that postmaster will not run with the default value.
Who will look the configuration file will not understand the right
reality.

Regards
Gaetano Mendola