Re: Inconsistency between postgresql.conf and docs

All,

A tester correctly reported this:

========

But in the sample file, the "synchronous_standby_names" parameter is the
first parameter under the heading "- Streaming Replication - Server
Settings" while in the documentation, that parameter has its own
subsection 18.5.5 after the "streaming replication" section 18.5.4.
Since the rest of section 18.5.4 was more than a screenful in my
browser, at first glance i didn't spot 18.5.5 and was confused.

========

He is correct. So, my question is, should the docs change, or should
postgresql.conf.sample change?

--
Josh Berkus
PostgreSQL Experts Inc.
http://pgexperts.com

On Tue, Jun 28, 2011 at 11:52 PM, Josh Berkus <josh(at)agliodbs(dot)com> wrote:
> But in the sample file, the "synchronous_standby_names" parameter is the
> first parameter under the heading "- Streaming Replication - Server
> Settings" while in the documentation, that parameter has its own
> subsection 18.5.5 after the "streaming replication" section 18.5.4.
> Since the rest of section 18.5.4 was more than a screenful in my
> browser, at first glance i didn't spot 18.5.5 and was confused.
>
> He is correct.  So, my question is, should the docs change, or should
> postgresql.conf.sample change?

Another thing that's a bit strange there is that most of the
section-header comments in postgresql.conf say:

# - Section Name -

i.e. they begin and end with a dash. Whereas that one for some reason says:

# - Streaming Replication - Server Settings

And probably should just say:

# - Streaming Replication -

I don't have a strong feeling on whether or not we should put that
setting in its own section. Right now, we only have one setting for
synchronous replication, so I guess maybe it depends on if we think
there will be more in the future.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

> I don't have a strong feeling on whether or not we should put that
> setting in its own section. Right now, we only have one setting for
> synchronous replication, so I guess maybe it depends on if we think
> there will be more in the future.

I believe there will be more in the future. However, given that the
replication section isn't exactly overpopulated, I think we could
consolidate.

My preference would be to have:

# REPLICATION

# - Master Settings -
# these settings affect the master role in replication
# they will be ignored on the standby

... settings ...

# - Standby Settings -
# these settings affect the standby role in replication
# they will be ignored on the master

... settings ...

That's how I've been setting up the file for my customers; it's fairly
clear and understandable.

--
Josh Berkus
PostgreSQL Experts Inc.
http://pgexperts.com

On Thu, Jun 30, 2011 at 1:34 AM, Josh Berkus <josh(at)agliodbs(dot)com> wrote:
> My preference would be to have:
>
> # REPLICATION
>
> # - Master Settings -
> # these settings affect the master role in replication
> # they will be ignored on the standby
>
> ... settings ...
>
> # - Standby Settings -
> # these settings affect the standby role in replication
> # they will be ignored on the master
>
> ... settings ...
>
>
> That's how I've been setting up the file for my customers; it's fairly
> clear and understandable.

Looks better than it's now. Anyway, if you change those, you would
need to change also the config_group in guc.c.

Regards,

--
Fujii Masao
NIPPON TELEGRAPH AND TELEPHONE CORPORATION
NTT Open Source Software Center

Fujii Masao <masao(dot)fujii(at)gmail(dot)com> writes:
> On Thu, Jun 30, 2011 at 1:34 AM, Josh Berkus <josh(at)agliodbs(dot)com> wrote:
>> My preference would be to have:
>>
>> # REPLICATION
>>
>> # - Master Settings -
>> # these settings affect the master role in replication
>> # they will be ignored on the standby
>>
>> ... settings ...
>>
>> # - Standby Settings -
>> # these settings affect the standby role in replication
>> # they will be ignored on the master
>>
>> ... settings ...
>>
>>
>> That's how I've been setting up the file for my customers; it's fairly
>> clear and understandable.

> Looks better than it's now. Anyway, if you change those, you would
> need to change also the config_group in guc.c.

OK, so the plan is to move these settings into a separate top-level
group "Replication", and sub-divide into master and standby settings,
removing the current classification for "streaming" versus
"synchronous"? That makes sense to me too, but it touches code as
well as docs ... last call for objections ...

regards, tom lane

On Thu, Jul 7, 2011 at 1:26 PM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> Fujii Masao <masao(dot)fujii(at)gmail(dot)com> writes:
>> On Thu, Jun 30, 2011 at 1:34 AM, Josh Berkus <josh(at)agliodbs(dot)com> wrote:
>>> My preference would be to have:
>>>
>>> # REPLICATION
>>>
>>> # - Master Settings -
>>> # these settings affect the master role in replication
>>> # they will be ignored on the standby
>>>
>>> ... settings ...
>>>
>>> # - Standby Settings -
>>> # these settings affect the standby role in replication
>>> # they will be ignored on the master
>>>
>>> ... settings ...
>>>
>>>
>>> That's how I've been setting up the file for my customers; it's fairly
>>> clear and understandable.
>
>> Looks better than it's now. Anyway, if you change those, you would
>> need to change also the config_group in guc.c.
>
> OK, so the plan is to move these settings into a separate top-level
> group "Replication", and sub-divide into master and standby settings,
> removing the current classification for "streaming" versus
> "synchronous"?  That makes sense to me too, but it touches code as
> well as docs ... last call for objections ...

None here. +1.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

On tor, 2011-07-07 at 13:26 -0400, Tom Lane wrote:
> OK, so the plan is to move these settings into a separate top-level
> group "Replication", and sub-divide into master and standby settings,

Most of the messages use the term "primary" rather than "master". I
think there was a discussion in 9.0 in favor of that term.

Peter Eisentraut <peter_e(at)gmx(dot)net> writes:
> On tor, 2011-07-07 at 13:26 -0400, Tom Lane wrote:
>> OK, so the plan is to move these settings into a separate top-level
>> group "Replication", and sub-divide into master and standby settings,

> Most of the messages use the term "primary" rather than "master". I
> think there was a discussion in 9.0 in favor of that term.

Well, there seems to be a lot more usage of the term "master" than
the other in the docs ...

regards, tom lane