Thread: 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 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 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[@]dcc.uchile.cl>) "Tiene valor aquel que admite que es un cobarde" (Fernandel)
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[@]dcc.uchile.cl>) "La soledad es compañía"
Alvaro Herrera Munoz <alvherre@dcc.uchile.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@varlena.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 >
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 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/
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@fetter.org http://fetter.org/ phone: +1 510 893 6100 mobile: +1 415 235 3778 Remember to vote!
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
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