Horton

Thread

Commits

  1. Doc: mention packager-supplied tools for server start/stop, initdb, etc.

  1. initdb - creating clusters

    The Post Office <noreply@postgresql.org> — 2020-07-09T15:25:14Z

    The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/10/creating-cluster.html
Description:

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.)

Thanks for all you do

Gary

  2. Re: initdb - creating clusters

    Laurenz Albe <laurenz.albe@cybertec.at> — 2020-07-10T06:51:22Z

    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

  3. Re: initdb - creating clusters

    Tom Lane <tgl@sss.pgh.pa.us> — 2020-07-11T21:36:42Z

    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

  4. Re: initdb - creating clusters

    Daniel Gustafsson <daniel@yesql.se> — 2020-07-11T22:06:16Z

    > 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

  5. Re: initdb - creating clusters

    Tom Lane <tgl@sss.pgh.pa.us> — 2020-07-11T22:24:40Z

    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

  6. Re: initdb - creating clusters

    David G. Johnston <david.g.johnston@gmail.com> — 2020-07-11T22:54:19Z

    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.

  7. Re: initdb - creating clusters

    Daniel Gustafsson <daniel@yesql.se> — 2020-07-13T07:40:13Z

    > 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

  8. Re: initdb - creating clusters

    Bruce Momjian <bruce@momjian.us> — 2020-07-21T00:25:03Z

    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

  9. Re: initdb - creating clusters

    Daniel Gustafsson <daniel@yesql.se> — 2020-07-21T08:40:59Z

    > 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

  10. Re: initdb - creating clusters

    Bruce Momjian <bruce@momjian.us> — 2020-07-22T16:34:37Z

    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

  11. Re: initdb - creating clusters

    Daniel Gustafsson <daniel@yesql.se> — 2020-08-25T12:04:55Z

    > 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

  12. Re: initdb - creating clusters

    Thomas Munro <thomas.munro@gmail.com> — 2020-08-29T22:05:50Z

    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).

  13. Re: initdb - creating clusters

    Tom Lane <tgl@sss.pgh.pa.us> — 2020-08-30T15:21:36Z

    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

  14. Re: initdb - creating clusters

    Jürgen Purtz <juergen@purtz.de> — 2020-08-31T10:09:57Z

    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

  15. Re: initdb - creating clusters

    Daniel Gustafsson <daniel@yesql.se> — 2020-09-02T13:02:00Z

    > 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

  16. Re: initdb - creating clusters

    Tom Lane <tgl@sss.pgh.pa.us> — 2020-09-02T16:43:18Z

    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

  17. Re: initdb - creating clusters

    Daniel Gustafsson <daniel@yesql.se> — 2020-09-02T19:02:34Z

    > 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

  18. Re: initdb - creating clusters

    Tom Lane <tgl@sss.pgh.pa.us> — 2020-09-03T15:46:26Z

    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