Subject: Documentation of server configuration

From: Peter Eisentraut <[email-masked]>
Date: Sat, 13 Nov 2004 21:20:51 +0100

I've just spent a day working through the current set of server 
configuration parameters, and I think that the documentation at 
<http://developer.postgresql.org/docs/postgres/runtime-config.html> has 
reached its peak of unusability.  I haven't been able to find a single 
parameter all day except by using a text search over the file.

A couple of obvious faults:

- There are too many sections.

- The sections don't have any obvious order.

- The subsections don't have any obvious order.

- The lists of individual parameters inside the sections don't have any 
order.

- If a parameter has a list of possible values, the values are not 
listed in a consistent order.

I have made an attempt and reformatted the whole section into one big 
alphabetical list, and while that has obvious drawbacks, I feel that 
it's already much more usable than what we have now.

Other ideas?

-- 
Peter Eisentraut
http://developer.postgresql.org/~petere/

---

From: Alvaro Herrera <[email-masked]>
Date: Sat, 13 Nov 2004 17:49:47 -0300

On Sat, Nov 13, 2004 at 09:20:51PM +0100, Peter Eisentraut wrote:
> reached its peak of unusability.

I agree it's somewhat uncomfortable.  As for unusability peak ...
I have seen worse things :-)

> it's already much more usable than what we have now.

What about a sort of table of contents, grouped by section and subsection,
inside each of which there would be an alphabetically sorted list of
parameters?  Each parameter in that list, in turn, would have an xref to
its entry in the one-big-alphabetical list.

-- 
Alvaro Herrera (<alvherre[@]dcc.uchile.cl>)
"Tiene valor aquel que admite que es un cobarde" (Fernandel)

---

From: Robert Treat <[email-masked]>
Date: Sat, 13 Nov 2004 16:17:26 -0500

> it's already much more usable than what we have now.

I thought runtime-config was supposed to be ordered in the same order as the 
default postgresql.conf ?

-- 
Robert Treat
Build A Brighter Lamp :: Linux Apache {middleware} PostgreSQL

---

From: Alvaro Herrera Munoz <[email-masked]>
Date: Sat, 13 Nov 2004 19:00:27 -0300

> default postgresql.conf ?

To what end?  A lot of people may want to look up parameters without
necessarily looking at postgresql.conf.

"La soledad es compañía"

---

From: Tom Lane <[email-masked]>
Date: Sat, 13 Nov 2004 19:17:35 -0500

> necessarily looking at postgresql.conf.

There was a great deal of effort put into categorizing the runtime
parameters just a release or two back.  Both runtime.sgml and the
postgresql.conf sample file follow that categorization.

I'm not sure if Peter is saying he doesn't like the current
categorization, or that he doesn't believe in the idea at all.
But I don't think "one big list" will fly.

			regards, tom lane

---

From: elein <[email-masked]>
Date: Sat, 13 Nov 2004 17:05:11 -0800

Is it possible to have an alphabetical hyperlink index to the sections?
I really like that it is in the same order as those in the
file and the like parameters are grouped.  

But the table is too big and needs an index for faster access...
no wait that was the database...no wait...

elein

On Sat, Nov 13, 2004 at 09:20:51PM +0100, Peter Eisentraut wrote:
> ---------------------------(end of broadcast)---------------------------
> TIP 9: the planner will ignore your desire to choose an index scan if your
>       joining column's datatypes do not match
>

---

From: Josh Berkus <[email-masked]>
Date: Sat, 13 Nov 2004 17:54:47 -0800

Peter,

> it's already much more usable than what we have now.

I disagree, absolutely and completely.   "one big alphabetical list" doesn't 
help at all in figuring out what you need to work with if you're running out 
of memory of if your queries have bad plans.   "effective_cache_size", for 
example, is nowhere near "random_page_cost", even though both parameters 
affect planner choice of index scans.  

I did the grouping for 7.4, and numerous people on the performance list felt 
it was an enormous improvement over the "one big list" we had before.  
Further, the ordering in runtime-config matches the ordering in 
postgresql.conf, which matches the ordering in the big spreadsheet of options 
I prepared for 7.4 (and will again for 8.0) and the groups match the 
categorization created in pg_settings view.

Further, I remember suggesting a couple months back that the runtime-config 
page was too large and ought to be broken up for readability.   You 
pooh-poohed the idea then, telling me there was nothing wrong with 
runtime-config the way it was.  Apparently you changed your mind?

> - There are too many sections.

I disagree.   In fact, I was thinking of creating some more sections.

> - The sections don't have any obvious order.

The current order is based loosely on the original postgresql.conf order, with 
connections, then memory, then wal, then logs, etc.    There's no particular 
reason for that section order other than familiarity.  I can see 
re-organizing the sections.

> - The lists of individual parameters inside the sections don't have any

Actually, there's ordered according to the frequency with which people monkey 
with that particular setting.   For example, lots of people change 
effective_cache_size and random_page_cost, but very few touch index_cpu_cost, 
for example.   In the postgresql.conf file, which is relatively compact, this 
isn't much of a problem; it's only in runtime-config where lots of scrolling 
is necessary that it makes stuff hard to find.

> listed in a consistent order.

Agreed.    I didn't touch the descriptions or reorder the parameters.

I can see that reordering the sections and subsections alphabetically might 
help.   However, I can also see a pretty strong argument against; that is, 
people are used to the current order and I don't see changing it just because 
the runtime-config file is unusable.   If you want to fix runtime-config, how 
about an *index*?

-- 
Josh Berkus
Aglio Database Solutions
San Francisco

---

From: Peter Eisentraut <[email-masked]>
Date: Sun, 14 Nov 2004 11:45:44 +0100

Josh Berkus wrote:
> I disagree, absolutely and completely.   "one big alphabetical list"
> doesn't help at all in figuring out what you need to work with if
> you're running out of memory of if your queries have bad plans.  
> "effective_cache_size", for example, is nowhere near
> "random_page_cost", even though both parameters affect planner choice
> of index scans.

For the record, I don't advocate "one big list".  It has turned out, for 
me, however, that the current organization is so useless that it's 
easier to scan through one big list than trying to find something in 
the current structure.

> Further, I remember suggesting a couple months back that the
> runtime-config page was too large and ought to be broken up for
> readability.   You pooh-poohed the idea then, telling me there was
> nothing wrong with runtime-config the way it was.  Apparently you
> changed your mind?

No, I'm still saying precisely that it's already broken up too much.

> I disagree.   In fact, I was thinking of creating some more sections.

No way.  I'm sure you all know the rule that there should be no more 
than 7 items in a menu.  This is the same thing.  It's around 14 now, 
depending on how you count it.  That is already way over the limit.  
It's already "one big list" of its own, but not the list the user is 
actually interested in.

I also find the categorization a bit suboptimal, but that is not the 
point here.  I think they are too much organized after the 
implementation concerns rather than trivial user concerns like 
"faster", "less resources", "more secure", "better".  (For example, 
what does "Write Ahead Log" or "Lock Management" do for me?  Aren't 
they resource or performance concerns?)

> > - The lists of individual parameters inside the sections don't have
> > any order.
>
> Actually, there's ordered according to the frequency with which
> people monkey with that particular setting.

While that is a commendable approach, I think it's nevertheless quite 
useless.  In most cases we clearly don't have that information or some 
arbitrary calls have been made.  Just take any two adjacent items and 
think about whether that order has any rationale in the eye of a user.

> If you want to fix runtime-config, how about an *index*?

Well, since you asked you will see that the current structure 
corresponds to an index scan (albeit using an index method that is 
under contention) and the one big list approach corresponds to a 
sequential scan.  Now think about why the cost factors are off.

---

From: Simon Riggs <[email-masked]>
Date: Sun, 14 Nov 2004 16:25:20 +0000

On Sun, 2004-11-14 at 01:54, Josh Berkus wrote:
> Peter Eisentraut wrote...
> I disagree, absolutely and completely.   

Unfortunately, I would agree with Josh, even though I strongly support
Peter's motivation.

For me, this section is the No.1 most hit section of the manual. Given
the speed of release of PostgreSQL (==good thing), I regularly refer to
manuals from 7.3, 7.4 and 8.0. Having a different ordering in the
manuals across different versions is somewhat annoying. A third
re-ordering would be just too annoying. People don't "make the change"
from one version to the next, then never refer back to the older
versions. Lets make as few changes as possible, please. 

> If you want to fix runtime-config, how 

Yes, a local index would do. Alvaro's idea is a good-one, but I'd like
it the other way around: Let's keep everything just as it is now, but
ADD an alphabetical list of parameters at the start or end of the
section which uses xrefs. All of the parameters already have xref
targets, so all we need to do is add the alphabetical list.

This way, those familiar and happy with the existing manual will
continue to be familiar and happy. Others wanting speedy access will
look for and use the new access method. I'm both of those.

That gives us many of the benefits that Peter seeks, with minimal
change. 

-- 
Best Regards, Simon Riggs

---

From: Neil Conway <[email-masked]>
Date: Mon, 15 Nov 2004 15:44:12 +1100

On Sun, 2004-11-14 at 16:25 +0000, Simon Riggs wrote:
> For me, this section is the No.1 most hit section of the manual.

I agree that this section is frequently accessed. Given that, I think it
is somewhat difficult to find -- we've all memorized that it is in the
"Server Run-time Environment" chapter, but I don't think that's the
first place most people would look. What do people think about
separating the configuration section out to be a new top-level chapter?

-Neil

---

From: Josh Berkus <[email-masked]>
Date: Mon, 15 Nov 2004 10:16:53 -0800

Neil,

> separating the configuration section out to be a new top-level chapter?

I'd be up for that.   The trick will be getting it done before 8.0 ... 
although if we're going into another beta, maybe time isn't precious yet.

Actually, what I'd see is:

1) a section explaining the most frequently modified options, and links;
2) a section grouping options by general purpose (like our current 
categories), with links;
3) a dictionary of config options, which personally I would prefer to be one 
per page like the SQL commands.

If we were to do the above, then re-ordering the "dictionary" to pure 
alphabetical would make perfect sense.

-- 
Josh Berkus
Aglio Database Solutions
San Francisco

---

From: elein <[email-masked]>
Date: Mon, 15 Nov 2004 10:48:09 -0800

As a header to the Config section, a hypertext index in alphabetical
order is what I suggested before.  It takes less space and
enables one to read it by section or to jump to where the
particular GUC is documented. 

I think the alpha index would be easier and more helpful
to people doing fast lookups like Peter was looking for
and lets the chapters stay in the nicely grouped format.

--elein
[email-masked]

On Mon, Nov 15, 2004 at 10:16:53AM -0800, Josh Berkus wrote:
> TIP 7: don't forget to increase your free space map settings
>

---

From: Simon Riggs <[email-masked]>
Date: Mon, 15 Nov 2004 18:53:30 +0000

> and lets the chapters stay in the nicely grouped format.

Agreed.

---

From: Peter Eisentraut <[email-masked]>
Date: Mon, 15 Nov 2004 20:02:06 +0100

ON.KG wrote:
> From Main host i'm trying to connect to PostgreSQL to Guest host
> But as a result i'm receiving next message:

This mailing list is for discussing the development of the PostgreSQL 
documentation.  Please post your question to a user support mailing 
list.

---

From: Peter Eisentraut <[email-masked]>
Date: Mon, 15 Nov 2004 20:04:13 +0100

Josh Berkus wrote:
> I'd be up for that.   The trick will be getting it done before 8.0

While we don't have a formal policy for stabilizing the documentation, I 
think that the time for making major moves in 8.0 is over.

---

From: Josh Berkus <[email-masked]>
Date: Mon, 15 Nov 2004 11:05:46 -0800

Peter,

> think that the time for making major moves in 8.0 is over.

Then it sounds like we drop in an alpha index and look to 8.1 for anything 
more sophisticated.

-- 
Josh Berkus
Aglio Database Solutions
San Francisco

---

From: David Fetter <[email-masked]>
Date: Mon, 15 Nov 2004 11:06:26 -0800

> parameter all day except by using a text search over the file.

My thoughts, hardly original, are:

1. Now is not the time to do massive re-arranging, 
2. We should provide an alphabetized grand list with links in some
obvious place.

I am volunteering to do said list & linking :)

Cheers,
D
-- 
David Fetter [email-masked] http://fetter.org/
phone: +1 510 893 6100   mobile: +1 415 235 3778

Remember to vote!

---

From: Josh Berkus <[email-masked]>
Date: Mon, 15 Nov 2004 12:16:30 -0800

David,

> I am volunteering to do said list & linking :)

I can help if you can give me the syntax for xrefs.

-- 
--Josh

Josh Berkus
Aglio Database Solutions
San Francisco

---

From: "ON.KG" <[email-masked]>
Date: Mon, 15 Nov 2004 23:49:37 +0300

Hi!

Description:
VMware 4.0
Main host is WinXP Pro (on FAT32)
and Guest Host is WinXP Pro (on NTFS)

On Guest Host - PostgreSQL 8.0-beta2-dev3

Connection Refused (0x0000274D/10061)
Is the server running on host xxx.xxx.xxx.xxx and accepting TCP/IP
connections on port 5432? 

Tell me please, what is the problem?

Thanx

---

From: Estienne van Velzen <[email-masked]>
Date: Mon, 15 Nov 2004 22:04:29 +0100

Have you configured postgresql
to work with tcp/ip ?

http://www.postgresql.org/docs/current/static/postmaster-start.html

Succes

Estienne

ON.KG wrote:

>TIP 3: if posting/reading through Usenet, please send an appropriate
>      subscribe-nomail command to [email-masked] so that your
>      message can get through to the mailing list cleanly
>  
>

---

From: "ON.KG" <[email-masked]>
Date: Tue, 16 Nov 2004 01:05:44 +0300

Hi!

Description:
VMware 4.0

Thanx

---

From: Jan Wieck <[email-masked]>
Date: Mon, 15 Nov 2004 22:03:06 -0500

> and Guest Host is WinXP Pro (on NTFS)

I hope you're running the guest with fully preallocated virtual disks. 
Any FAT inconsistency caused by a system crash could destroy your entire 
guest otherwise.

> Tell me please, what is the problem?

Windows XP has some basic firewall functionality. Could it be that this 
is blocking inbound access on the Guest side?

Jan