language cleanups in code and docs

On 15 Jun 2020, at 20:22, Andres Freund <andres@anarazel.de> wrote:

Thanks for picking this up!

1) 'postmaster'. As changing that would be somewhat invasive, the word
is a bit more ambiguous, and it's largely just internal, I've left
this alone for now. I personally would rather see this renamed as
supervisor, which'd imo actually would also be a lot more
descriptive. I'm willing to do the work, but only if there's at least
some agreement.

FWIW, I've never really liked the name postmaster as I don't think it conveys
meaning. I support renaming to supervisor or a similar term.

cheers ./daniel

On Tue, Jun 16, 2020 at 7:04 AM Daniel Gustafsson <daniel@yesql.se> wrote:

On 15 Jun 2020, at 20:22, Andres Freund <andres@anarazel.de> wrote:

Thanks for picking this up!

1) 'postmaster'. As changing that would be somewhat invasive, the word
is a bit more ambiguous, and it's largely just internal, I've left
this alone for now. I personally would rather see this renamed as
supervisor, which'd imo actually would also be a lot more
descriptive. I'm willing to do the work, but only if there's at least
some agreement.

FWIW, I've never really liked the name postmaster as I don't think it conveys
meaning. I support renaming to supervisor or a similar term.

+1. Postmaster has always sounded like a mailer daemon or something,
which we ain't.

On Tue, Jun 16, 2020 at 09:53:34AM +1200, Thomas Munro wrote:

On Tue, Jun 16, 2020 at 7:04 AM Daniel Gustafsson <daniel@yesql.se> wrote:

On 15 Jun 2020, at 20:22, Andres Freund <andres@anarazel.de> wrote:

Thanks for picking this up!

1) 'postmaster'. As changing that would be somewhat invasive, the word
is a bit more ambiguous, and it's largely just internal, I've left
this alone for now. I personally would rather see this renamed as
supervisor, which'd imo actually would also be a lot more
descriptive. I'm willing to do the work, but only if there's at least
some agreement.

FWIW, I've never really liked the name postmaster as I don't think it conveys
meaning. I support renaming to supervisor or a similar term.

+1. Postmaster has always sounded like a mailer daemon or something,
which we ain't.

Postmaster is historically confused with the postmaster email account:

https://en.wikipedia.org/wiki/Postmaster_(computing)

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com

The usefulness of a cup is in its emptiness, Bruce Lee

Daniel Gustafsson <daniel@yesql.se> writes:

On 15 Jun 2020, at 20:22, Andres Freund <andres@anarazel.de> wrote:

1) 'postmaster'. As changing that would be somewhat invasive, the word
is a bit more ambiguous, and it's largely just internal, I've left
this alone for now. I personally would rather see this renamed as
supervisor, which'd imo actually would also be a lot more
descriptive. I'm willing to do the work, but only if there's at least
some agreement.

FWIW, I've never really liked the name postmaster as I don't think it conveys
meaning. I support renaming to supervisor or a similar term.

Meh. That's carrying PC naming foibles to the point where they
negatively affect our users (by breaking start scripts and such).
I think we should leave this alone.

regards, tom lane

Hi,

On 2020-06-15 19:54:25 -0400, Tom Lane wrote:

Daniel Gustafsson <daniel@yesql.se> writes:

On 15 Jun 2020, at 20:22, Andres Freund <andres@anarazel.de> wrote:

1) 'postmaster'. As changing that would be somewhat invasive, the word
is a bit more ambiguous, and it's largely just internal, I've left
this alone for now. I personally would rather see this renamed as
supervisor, which'd imo actually would also be a lot more
descriptive. I'm willing to do the work, but only if there's at least
some agreement.

FWIW, I've never really liked the name postmaster as I don't think it conveys
meaning. I support renaming to supervisor or a similar term.

Meh. That's carrying PC naming foibles to the point where they
negatively affect our users (by breaking start scripts and such).
I think we should leave this alone.

postmaster is just a symlink, which we very well could just leave in
place... I was really just thinking of the code level stuff. And I think
there's some clarity reasons to rename it as well (see comments by
others in the thread).

Anyway, for now my focus is on patches in the series...

- Andres

On Mon, Jun 15, 2020 at 4:54 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:

Meh. That's carrying PC naming foibles to the point where they
negatively affect our users (by breaking start scripts and such).
I think we should leave this alone.

+1. Apart from the practical considerations, I just don't see a
problem with the word postmaster. My mother is a postmistress.

I'm in favor of updating any individual instances of the word "master"
to the preferred equivalent in code and code comments, though.

--
Peter Geoghegan

On Tue, Jun 16, 2020 at 2:23 AM Andres Freund <andres@anarazel.de> wrote:

Hi,

On 2020-06-15 19:54:25 -0400, Tom Lane wrote:

Daniel Gustafsson <daniel@yesql.se> writes:

On 15 Jun 2020, at 20:22, Andres Freund <andres@anarazel.de> wrote:

1) 'postmaster'. As changing that would be somewhat invasive, the word
is a bit more ambiguous, and it's largely just internal, I've left
this alone for now. I personally would rather see this renamed as
supervisor, which'd imo actually would also be a lot more
descriptive. I'm willing to do the work, but only if there's at least
some agreement.

FWIW, I've never really liked the name postmaster as I don't think it

conveys

meaning. I support renaming to supervisor or a similar term.

Meh. That's carrying PC naming foibles to the point where they
negatively affect our users (by breaking start scripts and such).
I think we should leave this alone.

postmaster is just a symlink, which we very well could just leave in
place... I was really just thinking of the code level stuff. And I think
there's some clarity reasons to rename it as well (see comments by
others in the thread).

Is the symlink even used? If not we could just get rid of it.

I'd be more worried about for example postmaster.pid, which would break a
*lot* of scripts and integrations. postmaster is also exposed in the system
catalogs.

--
Magnus Hagander
Me: https://www.hagander.net/ <http://www.hagander.net/&gt;
Work: https://www.redpill-linpro.com/ <http://www.redpill-linpro.com/&gt;

On 6/16/20 3:26 AM, Magnus Hagander wrote:

On Tue, Jun 16, 2020 at 2:23 AM Andres Freund wrote:
postmaster is just a symlink, which we very well could just leave in
place... I was really just thinking of the code level stuff. And I think
there's some clarity reasons to rename it as well (see comments by
others in the thread).

Is the symlink even used? If not we could just get rid of it. 

I am pretty sure that last time I checked Devrim was still using it in his
systemd unit file bundled with the PGDG rpms, although that was probably a
couple of years ago.

Joe
--
Crunchy Data - http://crunchydata.com
PostgreSQL Support for Secure Enterprises
Consulting, Training, & Open Source Development

On 6/16/20 9:10 AM, Joe Conway wrote:

On 6/16/20 3:26 AM, Magnus Hagander wrote:

On Tue, Jun 16, 2020 at 2:23 AM Andres Freund wrote:
postmaster is just a symlink, which we very well could just leave in
place... I was really just thinking of the code level stuff. And I think
there's some clarity reasons to rename it as well (see comments by
others in the thread).

Is the symlink even used? If not we could just get rid of it. 

I am pretty sure that last time I checked Devrim was still using it in his
systemd unit file bundled with the PGDG rpms, although that was probably a
couple of years ago.

Just checked a recent install and it's there.

Honestly, I think I'm with Tom, and we can just let this one alone.

cheers

andrew

--
Andrew Dunstan https://www.2ndQuadrant.com
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

Magnus Hagander <magnus@hagander.net> writes:

I'd be more worried about for example postmaster.pid, which would break a
*lot* of scripts and integrations. postmaster is also exposed in the system
catalogs.

Oooh, that's an excellent point. A lot of random stuff knows that file
name.

To be clear, I'm not against removing incidental uses of the word
"master". But the specific case of "postmaster" seems a little too
far ingrained to be worth changing.

regards, tom lane

On Mon, Jun 15, 2020 at 11:22:35AM -0700, Andres Freund wrote:

0006: docs: s/master/root/
Here using root seems a lot better than master anyway (master seems
confusing in regard to inheritance scenarios). But perhaps parent
would be better? Went with root since it's about the topmost table.

Because we allow multiple levels of inheritance, I have always wanted a
clear term for the top-most parent.

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com

The usefulness of a cup is in its emptiness, Bruce Lee

Hi Andres,

Thanks for doing this!

On 6/15/20 2:22 PM, Andres Freund wrote:

We've removed the use of "slave" from most of the repo (one use
remained, included here), but we didn't do the same for master. In the
attached series I replaced most of the uses.

0001: tap tests: s/master/primary/
Pretty clear cut imo.

Nothing to argue with here as far as I can see. It's a lot of churn,
though, so the sooner it goes in the better so people can update for the
next CF.

0002: code: s/master/primary/
This also includes a few minor other changes (s/in master/on the
primary/, a few 'the's added). Perhaps it'd be better to do those
separately?

I would only commit the grammar/language separately if the commit as a
whole does not go in. Some of them really do make the comments much
clearer beyond just in/on.

I think the user-facing messages, e.g.:

-			 errhint("Make sure the configuration parameter \"%s\" is set on the 
master server.",
+			 errhint("Make sure the configuration parameter \"%s\" is set on the 
primary server.",

should go in no matter what so we are consistent with our documentation.
Same for the postgresql.conf updates.

0003: code: s/master/leader/
This feels pretty obvious. We've largely used the leader / worker
terminology, but there were a few uses of master left.

Yeah, leader already outnumbers master by a lot. Looks good.

0004: code: s/master/$other/
This is most of the remaining uses of master in code. A number of
references to 'master' in the context of toast, a few uses of 'master
copy'. I guess some of these are a bit less clear cut.

Not sure I love authoritative, e.g.

+ * fullPageWrites is the authoritative value used by all backends to

and

+ * grabbed a WAL insertion lock to read the authoritative value in

Possibly "shared"?

+ * Create the Tcl interpreter subsidiary to pltcl_hold_interp.

Maybe use "worker" here? Not much we can do about the Tcl function name,
though. It's pretty localized, though, so may not matter much.

0005: docs: s/master/primary/
These seem mostly pretty straightforward to me. The changes in
high-availability.sgml probably deserve the most attention.

+ on primary and the current time on the standby. Delays in transfer

on *the* primary

I saw a few places where readability could be improved, but this patch
did not make any of them worse, and did make a few better.

0006: docs: s/master/root/
Here using root seems a lot better than master anyway (master seems
confusing in regard to inheritance scenarios). But perhaps parent
would be better? Went with root since it's about the topmost table.

I looked through to see if there was an instance of parent that should
be changed to root but I didn't see any. Even if there are, it's no
worse than before.

0007: docs: s/master/supervisor/
I guess this could be a bit more contentious. Supervisor seems clearer
to me, but I can see why people would disagree. See also later point
about changes I have not done at this stage.

Supervisor seems OK to me, but the postmaster has a special place since
there is only one of them. Main supervisor, root supervisor?

0008: docs: WIP multi-master rephrasing.
I like neither the new nor the old language much. I'd welcome input.

Why not multi-primary?

After this series there are only two widespread use of 'master' in the
tree.
1) 'postmaster'. As changing that would be somewhat invasive, the word
is a bit more ambiguous, and it's largely just internal, I've left
this alone for now. I personally would rather see this renamed as
supervisor, which'd imo actually would also be a lot more
descriptive. I'm willing to do the work, but only if there's at least
some agreement.

FWIW, I don't consider this to be a very big change from an end-user
perspective. I don't think the majority of users interact directly with
the postmaster, rather they are using systemd, pg_ctl, pg_ctlcluster, etc.

As for postmaster.pid and postmaster.opts, we have renamed plenty of
things in the past so this is just one more. They'd be better and
clearer as postgresql.pid and postgresql.opts, IMO.

Overall I'm +.5 because I may just be ignorant of the pain this will cause.

2) 'master' as a reference to the branch. Personally I be in favor of
changing the branch name, but it seems like it'd be better done as a
somewhat separate discussion to me, as it affects development
practices to some degree.

Happily this has no end-user impact. I think "main" is a good
alternative but I agree this feels like a separate topic.

One last thing -- are we considering back-patching any/all of this?

Regards,
--
-David
david@pgmasters.net

Hi,

On 2020-06-16 17:14:57 -0400, David Steele wrote:

On 6/15/20 2:22 PM, Andres Freund wrote:

We've removed the use of "slave" from most of the repo (one use
remained, included here), but we didn't do the same for master. In the
attached series I replaced most of the uses.

0001: tap tests: s/master/primary/
Pretty clear cut imo.

Nothing to argue with here as far as I can see. It's a lot of churn, though,
so the sooner it goes in the better so people can update for the next CF.

Yea, unless somebody protests I'm planning to push this part soon.

0004: code: s/master/$other/
This is most of the remaining uses of master in code. A number of
references to 'master' in the context of toast, a few uses of 'master
copy'. I guess some of these are a bit less clear cut.

Not sure I love authoritative, e.g.

+ * fullPageWrites is the authoritative value used by all backends to

and

+ * grabbed a WAL insertion lock to read the authoritative value in

Possibly "shared"?

I don't think shared is necessarily correct for all of these. E.g. in
the GetRedoRecPtr() there's two shared values at play, but only one is
"authoritative".

+ * Create the Tcl interpreter subsidiary to pltcl_hold_interp.

Maybe use "worker" here? Not much we can do about the Tcl function name,
though. It's pretty localized, though, so may not matter much.

I don't think it matters much what we use here

0008: docs: WIP multi-master rephrasing.
I like neither the new nor the old language much. I'd welcome input.

Why not multi-primary?

My understanding of primary is that there really can't be two things
that are primary in relation to each other. active/active is probably
the most common term in use besides multi-master.

One last thing -- are we considering back-patching any/all of this?

I don't think there's a good reason to do so.

Thanks for the look!

Greetings,

Andres Freund

On 6/16/20 6:27 PM, Andres Freund wrote:

On 2020-06-16 17:14:57 -0400, David Steele wrote:

On 6/15/20 2:22 PM, Andres Freund wrote:

0008: docs: WIP multi-master rephrasing.
I like neither the new nor the old language much. I'd welcome input.

Why not multi-primary?

My understanding of primary is that there really can't be two things
that are primary in relation to each other.

Well, I think the same is true for multi-master and that's pretty common.

active/active is probably
the most common term in use besides multi-master.

Works for me and can always be updated later if we come up with
something better. At least active-active will be easier to search for.

One last thing -- are we considering back-patching any/all of this?

I don't think there's a good reason to do so.

I was thinking of back-patching pain but if you don't think that's an
issue then I'm not worried about it.

Thanks for the look!

You are welcome!

--
-David
david@pgmasters.net

On 6/15/20 2:22 PM, Andres Freund wrote:

2) 'master' as a reference to the branch. Personally I be in favor of
changing the branch name, but it seems like it'd be better done as a
somewhat separate discussion to me, as it affects development
practices to some degree.

I'm OK with this, but I would need plenty of notice to get the buildfarm
adjusted.

cheers

andrew

--
Andrew Dunstan https://www.2ndQuadrant.com
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

Andrew Dunstan <andrew.dunstan@2ndquadrant.com> writes:

On 6/15/20 2:22 PM, Andres Freund wrote:

2) 'master' as a reference to the branch. Personally I be in favor of
changing the branch name, but it seems like it'd be better done as a
somewhat separate discussion to me, as it affects development
practices to some degree.

I'm OK with this, but I would need plenty of notice to get the buildfarm
adjusted.

"master" is the default branch name established by git, is it not? Not
something we picked. I don't feel like we need to be out front of the
rest of the world in changing that. It'd be a cheaper change than some of
the other proposals in this thread, no doubt, but it would still create
confusion for new hackers who are used to the standard git convention.

regards, tom lane

On Tue, 16 Jun 2020 at 19:55, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Andrew Dunstan <andrew.dunstan@2ndquadrant.com> writes:

On 6/15/20 2:22 PM, Andres Freund wrote:

2) 'master' as a reference to the branch. Personally I be in favor of
changing the branch name, but it seems like it'd be better done as a
somewhat separate discussion to me, as it affects development
practices to some degree.

I'm OK with this, but I would need plenty of notice to get the buildfarm
adjusted.

"master" is the default branch name established by git, is it not? Not
something we picked. I don't feel like we need to be out front of the
rest of the world in changing that. It'd be a cheaper change than some of
the other proposals in this thread, no doubt, but it would still create
confusion for new hackers who are used to the standard git convention.

While it is the default I expect that will change soon. Github is planning
on making main the default.
https://www.zdnet.com/article/github-to-replace-master-with-alternative-term-to-avoid-slavery-references/

Many projects are moving from master to main.

I expect it will be less confusing than you think.

Dave Cramer
www.postgres.rocks

On 2020-Jun-16, Tom Lane wrote:

Andrew Dunstan <andrew.dunstan@2ndquadrant.com> writes:

On 6/15/20 2:22 PM, Andres Freund wrote:

2) 'master' as a reference to the branch. Personally I be in favor of
changing the branch name, but it seems like it'd be better done as a
somewhat separate discussion to me, as it affects development
practices to some degree.

I'm OK with this, but I would need plenty of notice to get the buildfarm
adjusted.

"master" is the default branch name established by git, is it not? Not
something we picked. I don't feel like we need to be out front of the
rest of the world in changing that. It'd be a cheaper change than some of
the other proposals in this thread, no doubt, but it would still create
confusion for new hackers who are used to the standard git convention.

Git itself is discussing this:
https://public-inbox.org/git/41438A0F-50E4-4E58-A3A7-3DAAECB5576B@jramsay.com.au/T/#t
and it seems that "main" is the winning choice.

(Personally) I would leave master to have root, would leave root to have
default, would leave default to have primary, would leave primary to
have base, would leave base to have main, would leave main to have
mainline.

--
�lvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

Alvaro Herrera <alvherre@2ndquadrant.com> writes:

On 2020-Jun-16, Tom Lane wrote:

"master" is the default branch name established by git, is it not? Not
something we picked.

Git itself is discussing this:
https://public-inbox.org/git/41438A0F-50E4-4E58-A3A7-3DAAECB5576B@jramsay.com.au/T/#t
and it seems that "main" is the winning choice.

Oh, interesting. If they do change I'd be happy to follow suit.
But let's wait and see what they do, rather than possibly ending
up with our own private convention.

regards, tom lane