References between initdb and pg_controldata

[Paul Weiss]

As with other see-alsos in Part VI, I think it would be useful to have 
see-alsos between initdb and pg_controldata. Currently the pg_controldata page 
at least mentions initdb, but the initdb page does not mention pg_controldata.

Paul

Making the first few chapters of Part III more novice-friendly

[Paul Weiss]

The intro to Part III says "The first few chapters are written so they can be 
understood without prerequisite knowledge, so new users who need to set up 
their own server can begin their exploration with this part." With that in 
mind, could chapters on installation and chapters 18 & 19 be made more 
novice-friendly?

For example, consider adding a brief chapter before chapter 16 on installation 
in general, explaining the options in general, the pros and cons of each, and a 
link to https://www.postgresql.org/download/. Or add those things to Section 
1.1 in part I . It says "If you are installing PostgreSQL yourself, then refer 
to Chapter 16 for 
instructions on installation", but chapter 16 is only really about installation 
from source code.

The intro to chapter 16 also states "If you are building PostgreSQL for 
Microsoft Windows, read this chapter if you intend to build with MinGW or 
Cygwin; but if you intend to build with Microsoft's Visual C++, see Chapter 
17 instead." A novice 
might infer from that that those are the only 2 options, rather than knowing 
about the much-easier-to-install binary version. Another example is at the top 
18.1. It would be nice to have a brief explanation what a server daemon is, or 
if nothing else, a link to the Wikipedia article.

It would be great to make these chapters more friendly to PostgreSQL novices 
who are Windows users. Windows (for non-developers) doesn't use the concept of 
file ownership, and uses "user account" differently, so explanations of those 
would be helpful. The second paragraph begins "To add a Unix user account to 
your system", but nothing about Windows or macOS (I think many Mac users do not 
know it is based on UNIX). In the first paragraph of 18.2 talks about 
initializing a storage area, but "initializing" is not a term regularly used by 
Windows users. In the third sentence of the second paragraph it would be 
helpful to either add a Windows example, or at least say something like "There 
is no default, although in UNIX popular locations include /usr/local/pgsql/data 
and /var/lib/pgsql/data." (Related, it would also be nice in section 3 of the 
preface to note that most commands in the manual are given in UNIX, and that in 
Windows you would use backslashes rather than forward slashes in, for example, 
path names.) While 18.3 has specific content for 5 UNIX varieties, there is no 
specific content for Windows.

I am happy to help develop solutions for any of the comments I send out.

Paul

Re: the concept of a database cluster

[Paul Weiss]

Oh, I didn't mean to imply that I am confused. It is clear that there are two 
concepts here, sharing a term. I was trying to communicate that the manual does 
not always make it immediately clear from context which concept is meant in a 
particular sentence.

A garage is a good analogy. A garage is a container for cars rather than a 
collection of cars. You wouldn't say "I sold my garage" to mean "I sold my car 
collection". Containers and collections are different things.

Here's a simple example In our context: "remove the cluster" could mean "delete 
the folder containing the databases", or "drop the databases". Those actions 
are not identical. I would think we would want to be clear to our users which 
we mean.

Paul


From: David G. Johnston 
Sent: Friday, January 3, 2020 12:21 AM
To: lib...@hotmail.com ; pgsql-docs@lists.postgresql.org 

Subject: Re: the concept of a database cluster

On Thursday, January 2, 2020, PG Doc comments form 
mailto:nore...@postgresql.org>> wrote:
The following documentation comment has been logged on the website:

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

In 18.2, a database cluster is said to be "a database storage area on disk",
and then shortly afterward is is defined as "a collection of databases that
is managed by a single instance of a running database server". Those seem
very different things. Sometimes in the manual I can't tell which usage is
intended.

A garage is a “car storage area for a house”. A garage can (typically) store 
multiple cars just as a database cluster can store multiple databases.  The 
files are only useful if there is a running instance and all databases stored 
in the cluster are managed by a single shared instance.  You will need to 
better explain your confusion because the documentation is describing a complex 
system accurately but in parts that are related - two sides of the same coin, 
if you will.

David J.

Re: the concept of a database cluster

[David G. Johnston]

On Saturday, January 4, 2020, Paul Weiss  wrote:

> Oh, I didn't mean to imply that I am confused. It is clear that there are
> two concepts here, sharing a term. I was trying to communicate that the
> manual does not always make it immediately clear from context which concept
> is meant in a particular sentence.
>
> A garage is a good analogy. A garage is a container for cars rather than a
> collection of cars. You wouldn't say "I sold my garage" to mean "I sold my
> car collection". Containers and collections are different things.
>
> Here's a simple example In our context: "remove the cluster" could mean
> "delete the folder containing the databases", or "drop the databases".
> Those actions are not identical. I would think we would want to be clear to
> our users which we mean.
>

I’m sure we’d be willing to fix concrete problematic examples but a lack of
those suggests there is no actual problem here...as you aren’t confused or
providing concrete examples and suggestions I have no idea what you are
trying to accomplish with this thread.  Awareness of what seems to be a
non-existent issue?

David J.