postgres documentation - proposed improvement/clarification - Mailing list pgsql-bugs

Hi everyone

The documentation for postgres is generally great, but I noticed a problem =
today while using the doc webpages to reply to a user on the pgsql-performa=
nce mailing list.=20

The problem relates to how default settings are communicated in the documen=
tation. Keep in mind that not all postgresql admins have English as their f=
irst language, so it should not be necessary to guess from the phrasing of =
a paragraph about what is set by default. Also, many people keep around old=
er config files, or don't have a vanilla postgresql.conf file handy to chec=
k for reference (and you never know, someone might have modified your vanil=
la reference .conf...). So the documentation is for many the primary refere=
nce and it should be clear exactly what postgres does in the absence of act=
ively chosen configuration settings. It should also be clear what those set=
tings can be, and how they should be entered.

Take a look at this page, as an example:   http://www.postgresql.org/docs/9=
.4/static/runtime-config-wal.html

Thoughts:

1. Default values are not always specified for each setting, but should be.
Example: documentation for fsync (boolean) doesn't have the default specifi=
ed.


2. Default values are not specified in a consistent place or style in the t=
ext.
Examples: take a look at=20
wal_level (enum)
full_page_writes (boolean)
wal_buffers (integer)


3. Information about default values are sometimes mixed into longer sentenc=
es on another topic. This isn't a big problem but it makes it harder to spo=
t the default value in the paragraph.
Example:
wal_buffers (integer)


4. Default values are sometimes documented in a slightly different style or=
 format to their actual use in the config file. For example, integers like =
5 are given as text 'five'. This isn't a big problem but it makes it harder=
 to find the default value in the paragraph; you're looking for an integer =
in the text, but the number is written as a string. It might be better to b=
reak the writing convention of putting some numbers as text in English. Thi=
s is a document explaining what to type into the config file. Examples or d=
efaults should always be valid cases if  copied directly into the config fi=
le.=20

Example:=20
commit_delay (integer)
"The default commit_delay is zero (no delay)"        (actual commit_delay d=
efault is '0', of course, not 'zero')
vs.
checkpoint_completion_target (floating point)
"The default is 0.5."


5. Where the type is specified as 'boolean', the normal & default values ar=
e not 'true/false' or '1/0', as would be expected for a boolean typed param=
eter. Yes, I know on/off is also boolean, but I bet if you surveyed 100 pro=
grammers and asked them about likely default values for a boolean setting, =
few would say 'on' in reply. It actually makes me wonder if this is better =
described to users as a 2-value enum type.
Example:
full_page_writes (boolean)
"The default is on."


6. The present method of documenting the datatype alongside the name isn't =
actually that helpful for most people reading the documentation. How many r=
eaders are helped by knowing that wal_sync_method is an (enum) as the first=
 thing they read about it?


7. Default units? And should units be included in the setting value?=20

Look at this example. Can anyone tell me, using *only* reference to this pa=
rameter documentation, if the parameter can be set to "8", "8kB", "8KB" or =
"8MB" in the config file?=20
Again, using only this documentation, can you tell for certain that if I ch=
oose '8' it will be bytes , or kb, or a configuration error?

=3D=3D=3D=3D=3D
wal_buffers (integer)
The amount of shared memory used for WAL data that has not yet been written=
 to disk. The default setting of -1 selects a size equal to 1/32nd (about 3=
%) ofshared_buffers, but not less than 64kB nor more than the size of one W=
AL segment, typically 16MB. This value can be set manually if the automatic=
 choice is too large or too small, but any positive value less than 32kB wi=
ll be treated as 32kB. This parameter can only be set at server start.

The contents of the WAL buffers are written out to disk at every transactio=
n commit, so extremely large values are unlikely to provide a significant b=
enefit. However, setting this value to at least a few megabytes can improve=
 write performance on a busy server where many clients are committing at on=
ce. The auto-tuning selected by the default setting of -1 should give reaso=
nable results in most cases.
=3D=3D=3D=3D=3D



Proposed solutions.

Perhaps it might be worth extending or replacing the type information in th=
e header, by including info about the default, possibly replacing the type =
info at that part of the document.=20


e.g. How about this style?

        synchronous_commit (default: on)

        Specifies whether transaction commit will wait for WAL records to be...


or this style?

        synchronous_commit (enum, default: on)

        Specifies whether transaction commit will wait for WAL records to be...


or this?

        synchronous_commit (enum)
        permitted values: on, remote_write, local, off  =20
        default: on
    =09

        wal_buffers (integer)
        permitted values (in kB): -1 (auto-tuning)  and 32-65536.=20
        default: -1




In most cases, this information is there in the paragraph somewhere, but pr=
esenting the config option in this way would make it easier to refer to wit=
hout needing to parse and understand the entire description to understand t=
he default and permitted settings.=20

This would make it easier for people to quickly check how their server is s=
etup if a) the config file is lacking the setting or b) may have been modif=
ied in the past or c) may have been retained from a previous version of pos=
tgres with different defaults.=20

It also means that we don't need e.g. duplicate specification of default va=
lues in the text description - e.g. take a look at wal_buffers (integer), w=
hich specifies it twice.=20

Thoughts?

Graeme Bell