initdb - creating clusters

On Thu, 2020-07-09 at 15:25 +0000, PG Doc comments form wrote:

I'm searching for what a cluster is and how to create one. The
documentation tells me to use initdb -D path/to/cluster. I am told that
this is installed when I installed postgresql. I try to run it with no
success. Searching for an answer I find that I'm supposed to use
pg_createcluster because initdb is version dependent and not made
executable. It seems like there is an omission here as the documentation on
this page also mentions pg_ctl which my system (Ubuntu 18.04) knows nothing
about using the 'which' command. I can imagine that someone might argue
that this is system dependent - I don't know whether that is true or not. I
have generally found the documentation excellent and certainly not inward
looking. For instance the documentation on replication strategies includes
proprietary solutions.

I would suggest that you include a paragraph stating that various operating
systems use other commands to avoid version conflict and suggest the reader
search for '<user-system> pg_ctl'. I can understand why you might not want
to link to external sites in your documentation. (While writing this I have
searched to make sure I'm not writing rubbish and already understand that
pg_createcluster is a Debian solution/variant.)

Something like the attached?

Yours,
Laurenz Albe

Laurenz Albe <laurenz.albe@cybertec.at> writes:

On Thu, 2020-07-09 at 15:25 +0000, PG Doc comments form wrote:

I would suggest that you include a paragraph stating that various operating
systems use other commands to avoid version conflict and suggest the reader
search for '<user-system> pg_ctl'. I can understand why you might not want
to link to external sites in your documentation. (While writing this I have
searched to make sure I'm not writing rubbish and already understand that
pg_createcluster is a Debian solution/variant.)

Something like the attached?

I think the problem is more general than that. The packager might
well provide a substitute or wrapper for initdb, but it's even more
likely that there's some other way to start and stop the server than
what we describe.

I experimented with putting a disclaimer at the very top of the chapter,
as attached. I like that from a wording standpoint, but from a usability
standpoint it's still got the question of whether users will see it at
all. (This is not helped any by the fact that our current docs toolchain
insists on putting a chapter TOC in front of the chapter head material,
so that what ought to be the most important information becomes something
you don't see at all unless you think to scroll down.)

Another approach would be to put something along this line at the heads
of each of the relevant sections, which'd be 18.1, 18.2, 18.3, 18.5,
and 18.6 by my count. That seems very repetitive; but it would have
the advantage that people could hardly miss it.

I do agree that we ought to do something here. I think only a small
minority of users build their own Postgres installations anymore.

regards, tom lane

On 11 Jul 2020, at 23:36, Tom Lane <tgl@sss.pgh.pa.us> wrote:

+  For example, there may be special scripts for creating a database
+  cluster.  There almost certainly will be a mechanism for starting
+  the server,

Aren't we really talking about "running the server as a service" and not just
starting it? Perhaps thats hair-splitting territory?

cheers ./daniel

Daniel Gustafsson <daniel@yesql.se> writes:

On 11 Jul 2020, at 23:36, Tom Lane <tgl@sss.pgh.pa.us> wrote:
+  For example, there may be special scripts for creating a database
+  cluster.  There almost certainly will be a mechanism for starting
+  the server,

Aren't we really talking about "running the server as a service" and not just
starting it? Perhaps thats hair-splitting territory?

Yeah, but that terminology might itself be a bit platform-specific.
I considered giving specific examples, like systemd unit files,
but was afraid that that'd just confuse people on other platforms.
Not sure what the best way to approach this is.

regards, tom lane

On Sat, Jul 11, 2020 at 2:37 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:

Another approach would be to put something along this line at the heads
of each of the relevant sections, which'd be 18.1, 18.2, 18.3, 18.5,
and 18.6 by my count. That seems very repetitive; but it would have
the advantage that people could hardly miss it.

I do agree that we ought to do something here. I think only a small
minority of users build their own Postgres installations anymore.

Taken to an extreme...

Presently 16 and 17 explicitly describe source installation. 18 extends
upon how to go about using a source installation but then also dives into
topics that are relevant regardless of the architecture of the server
binaries, and to some extent more accurately represents "server
configuration" or maybe "server-os integration" if you want to keep that
stuff in its own chapter. So 18 gets split with 18 retaining the material
that pertains to source installed binaries. Then add a new chapter, 18.3
(overall numbering will shift), making mention of package installers and
maybe even allow for some detail to be covered in that chapter before
handing the user off to the distro's documentation. Then 18.6 gets
"server-os integration/configuration" while 19 remains "server
configuration".

David J.

p.s. This thread started on the 9th and Laurenz responded on the 10th but
this email (11th) from Tom is the first I've seen of this thread. As
I write this I haven't seen Daniel's response but I do see Tom's reply to
Daniel's reponse. This "I see responses but not originals" is quite common
for me. Using GMail.

On 12 Jul 2020, at 00:24, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Daniel Gustafsson <daniel@yesql.se> writes:

On 11 Jul 2020, at 23:36, Tom Lane <tgl@sss.pgh.pa.us> wrote:
+  For example, there may be special scripts for creating a database
+  cluster.  There almost certainly will be a mechanism for starting
+  the server,

Aren't we really talking about "running the server as a service" and not just
starting it? Perhaps thats hair-splitting territory?

Yeah, but that terminology might itself be a bit platform-specific.

I guess thats a good point.

I considered giving specific examples, like systemd unit files,
but was afraid that that'd just confuse people on other platforms.
Not sure what the best way to approach this is.

Hmm, since the section is aimed at reducing confusion for inexperienced users I
agree that adding more detail might be detrimental to the point.

Re-reading it with bug-reports etc in mind, I think the only thing that I
propose would be to expand the terminology for what a package is to be
"pre-packaged or vendor-supplied".

cheers ./daniel

On Thu, Jul 9, 2020 at 03:25:14PM +0000, PG Doc comments form wrote:

looking. For instance the documentation on replication strategies includes
proprietary solutions.

Uh, what proprietary solutions are listed in our documentation?

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

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

On 21 Jul 2020, at 02:25, Bruce Momjian <bruce@momjian.us> wrote:

On Thu, Jul 9, 2020 at 03:25:14PM +0000, PG Doc comments form wrote:

looking. For instance the documentation on replication strategies includes
proprietary solutions.

Uh, what proprietary solutions are listed in our documentation?

I think "proprietary" here implies outside-of-core, and we have a few of those
listed in the "Comparison of Different Solutions" section.

cheers ./daniel

On Tue, Jul 21, 2020 at 10:40:59AM +0200, Daniel Gustafsson wrote:

On 21 Jul 2020, at 02:25, Bruce Momjian <bruce@momjian.us> wrote:

On Thu, Jul 9, 2020 at 03:25:14PM +0000, PG Doc comments form wrote:

looking. For instance the documentation on replication strategies includes
proprietary solutions.

Uh, what proprietary solutions are listed in our documentation?

I think "proprietary" here implies outside-of-core, and we have a few of those
listed in the "Comparison of Different Solutions" section.

Oh, OK, those seem fine to me.

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

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

On 22 Jul 2020, at 18:34, Bruce Momjian <bruce@momjian.us> wrote:

On Tue, Jul 21, 2020 at 10:40:59AM +0200, Daniel Gustafsson wrote:

On 21 Jul 2020, at 02:25, Bruce Momjian <bruce@momjian.us> wrote:

On Thu, Jul 9, 2020 at 03:25:14PM +0000, PG Doc comments form wrote:

looking. For instance the documentation on replication strategies includes
proprietary solutions.

Uh, what proprietary solutions are listed in our documentation?

I think "proprietary" here implies outside-of-core, and we have a few of those
listed in the "Comparison of Different Solutions" section.

Oh, OK, those seem fine to me.

I took the liberty of adding the proposed patch upthread to the next commitfest
to make sure it's not forgotten about, as I do think it will improve the docs.

cheers ./daniel

On Wed, Aug 26, 2020 at 12:05 AM Daniel Gustafsson <daniel@yesql.se> wrote:

I took the liberty of adding the proposed patch upthread to the next commitfest
to make sure it's not forgotten about, as I do think it will improve the docs.

+  The discussions in this chapter assume that you are working with
+  an unmodified version of <productname>PostgreSQL</productname>,
+  for example one that you built from source according to the directions
+  in the preceding chapters.  If you are working with a pre-packaged

Rather than "unmodified", would it be better to say something more
like "without any extra supporting infrastructure"?

My point is that packagers don't typically *modify* PG, rather they
supply a bunch of wrappers (eg Debian postgresql-common), service
management scripting (eg systemd gloopity-gloop), post-install
scripting (eg Debian's policy of automatically starting any service
when you install it, implying that it must also run initdb for you).

Thomas Munro <thomas.munro@gmail.com> writes:

+  The discussions in this chapter assume that you are working with
+  an unmodified version of <productname>PostgreSQL</productname>,
+  for example one that you built from source according to the directions
+  in the preceding chapters.  If you are working with a pre-packaged

Rather than "unmodified", would it be better to say something more
like "without any extra supporting infrastructure"?

So maybe "... you are working with plain
<productname>PostgreSQL</productname> without any additional
infrastructure, for example a copy that you built from source
according to the directions in the preceding chapters." ?

Do you have a feeling one way or the other about whether to repeat
some of this text in each of the relevant sub-sections? I initially
didn't want to do that, but thinking about how people consume the
HTML docs, I'm afraid that anything not appearing on the same page
won't get seen.

regards, tom lane

On 30.08.20 17:21, Tom Lane wrote:

Do you have a feeling one way or the other about whether to repeat
some of this text in each of the relevant sub-sections? I initially
didn't want to do that, but thinking about how people consume the
HTML docs, I'm afraid that anything not appearing on the same page
won't get seen.

If we do so but avoid redundant text parts, we can use the entity
mechanism or the more modern XInclude mechanism. The attached patch uses
both techniques in an example file: brin.sgml includes lorem.sgml two times.

(In both cases we should avoid files with multiple root elements, eg.
multiple <para> or <sect1> without a parent element, because this would
violate the well-formed-ness of the included XML document.)

--

J. Purtz

On 30 Aug 2020, at 17:21, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Thomas Munro <thomas.munro@gmail.com> writes:

+  The discussions in this chapter assume that you are working with
+  an unmodified version of <productname>PostgreSQL</productname>,
+  for example one that you built from source according to the directions
+  in the preceding chapters.  If you are working with a pre-packaged

Rather than "unmodified", would it be better to say something more
like "without any extra supporting infrastructure"?

So maybe "... you are working with plain
<productname>PostgreSQL</productname> without any additional
infrastructure, for example a copy that you built from source
according to the directions in the preceding chapters." ?

That seems pretty clearly worded to me.

Do you have a feeling one way or the other about whether to repeat
some of this text in each of the relevant sub-sections? I initially
didn't want to do that, but thinking about how people consume the
HTML docs, I'm afraid that anything not appearing on the same page
won't get seen.

I think you're right here, duplicating the content is probably required for it
to be useful.

cheers ./daniel

Daniel Gustafsson <daniel@yesql.se> writes:

On 30 Aug 2020, at 17:21, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Do you have a feeling one way or the other about whether to repeat
some of this text in each of the relevant sub-sections? I initially
didn't want to do that, but thinking about how people consume the
HTML docs, I'm afraid that anything not appearing on the same page
won't get seen.

I think you're right here, duplicating the content is probably required for it
to be useful.

I took a stab at doing it that way, as attached. (I couldn't resist
the temptation to do some minor editing on adjacent material, too.)

regards, tom lane

On 2 Sep 2020, at 18:43, Tom Lane <tgl@sss.pgh.pa.us> wrote:

I took a stab at doing it that way, as attached. (I couldn't resist
the temptation to do some minor editing on adjacent material, too.)

LGTM. I didn't try to build the docs with this applied, but reading it I can't
see anything odd about the markup.

cheers ./daniel

Daniel Gustafsson <daniel@yesql.se> writes:

On 2 Sep 2020, at 18:43, Tom Lane <tgl@sss.pgh.pa.us> wrote:
I took a stab at doing it that way, as attached. (I couldn't resist
the temptation to do some minor editing on adjacent material, too.)

LGTM. I didn't try to build the docs with this applied, but reading it I can't
see anything odd about the markup.

Hearing no other comments, pushed.

regards, tom lane