Re: Documentation of server configuration

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/

On Sat, Nov 13, 2004 at 09:20:51PM +0100, Peter Eisentraut wrote:
> 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 agree it's somewhat uncomfortable. As for unusability peak ...
I have seen worse things :-)

> 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.

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[(at)]dcc(dot)uchile(dot)cl>)
"Tiene valor aquel que admite que es un cobarde" (Fernandel)

On Saturday 13 November 2004 15:20, Peter Eisentraut wrote:
> 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?

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

On Sat, Nov 13, 2004 at 04:17:26PM -0500, Robert Treat wrote:
> On Saturday 13 November 2004 15:20, Peter Eisentraut wrote:
> > 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 thought runtime-config was supposed to be ordered in the same order as the
> default postgresql.conf ?

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

--
Alvaro Herrera (<alvherre[(at)]dcc(dot)uchile(dot)cl>)
"La soledad es compañía"

Alvaro Herrera Munoz <alvherre(at)dcc(dot)uchile(dot)cl> writes:
> On Sat, Nov 13, 2004 at 04:17:26PM -0500, Robert Treat wrote:
>> I thought runtime-config was supposed to be ordered in the same order as the
>> default postgresql.conf ?

> To what end? A lot of people may want to look up parameters without
> 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

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:
> 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/
>
>
> ---------------------------(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
>

Peter,

> 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.

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 subsections don't have any obvious order.
> - 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. 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.

> - If a parameter has a list of possible values, the values are not
> 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

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.

> > - There are too many sections.
>
> 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.

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

On Sun, 2004-11-14 at 01:54, Josh Berkus wrote:
> Peter Eisentraut wrote...
> > 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.
>
> 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
> about an *index*?

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

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

Neil,

> 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?

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

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
elein(at)varlena(dot)com

On Mon, Nov 15, 2004 at 10:16:53AM -0800, Josh Berkus wrote:
> Neil,
>
> > 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?
>
> 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
>
> ---------------------------(end of broadcast)---------------------------
> TIP 7: don't forget to increase your free space map settings
>

On Mon, 2004-11-15 at 18:48, elein wrote:
> 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.
>

Agreed.

--
Best Regards, Simon Riggs

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.

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

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.

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

Peter,

> 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.

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

On Sat, Nov 13, 2004 at 09:20:51PM +0100, Peter Eisentraut wrote:
> 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.

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 david(at)fetter(dot)org http://fetter.org/
phone: +1 510 893 6100 mobile: +1 415 235 3778

Remember to vote!

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

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

From Main host i'm trying to connect to PostgreSQL to Guest host
But as a result i'm receiving next message:

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

Have you configured postgresql
to work with tcp/ip ?

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

Succes

Estienne

ON.KG wrote:

>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
>
>From Main host i'm trying to connect to PostgreSQL to Guest host
>But as a result i'm receiving next message:
>
>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
>
>---------------------------(end of broadcast)---------------------------
>TIP 3: if posting/reading through Usenet, please send an appropriate
> subscribe-nomail command to majordomo(at)postgresql(dot)org so that your
> message can get through to the mailing list cleanly
>
>

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

From Main host i'm trying to connect to PostgreSQL to Guest host
But as a result i'm receiving next message:

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

On 11/15/2004 5:05 PM, ON.KG wrote:
> Hi!
>
> Description:
> VMware 4.0
> Main host is WinXP Pro (on FAT32)
> 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.

>
> On Guest Host - PostgreSQL 8.0-beta2-dev3
>
>>From Main host i'm trying to connect to PostgreSQL to Guest host
> But as a result i'm receiving next message:
>
> 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?

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

Jan