Re: language cleanups in code and docs

From: David Steele <david(at)pgmasters(dot)net>
To: Andres Freund <andres(at)anarazel(dot)de>, pgsql-hackers(at)postgresql(dot)org
Subject: Re: language cleanups in code and docs
Date: 2020-06-16 21:14:57
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

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


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


In response to


Browse pgsql-hackers by date

  From Date Subject
Next Message Andres Freund 2020-06-16 22:27:10 Re: language cleanups in code and docs
Previous Message Andres Freund 2020-06-16 19:27:57 Re: global barrier & atomics in signal handlers (Re: Atomic operations within spinlocks)