Re: Additional Chapter for Tutorial - Mailing list pgsql-hackers

From David G. Johnston
Subject Re: Additional Chapter for Tutorial
Date
Msg-id CAKFQuwaEp3HRgB=C3CfqLWsHqH3p_kmow+n+ERuaCRR=ozt0nw@mail.gmail.com
Whole thread Raw
In response to Re: Additional Chapter for Tutorial  (Jürgen Purtz <juergen@purtz.de>)
Responses Re: Additional Chapter for Tutorial  (Jürgen Purtz <juergen@purtz.de>)
List pgsql-hackers
On Sun, Nov 8, 2020 at 8:56 AM Jürgen Purtz <juergen@purtz.de> wrote:

Good catches. Everything applied.

Reviewed the first three sections.

template0 - I would remove the schema portions of this and simply note this as being a pristine recovery database in the diagram.

I would drop the word "more" and just say "system schemas".  I would drop pg_toast from the list of system schema and focus on the three user-facing ones.

Instead of "my_schema" (optional) I would do "my_schema" (example)

Server Graphic
#3 Global SQL Objects: Objects which are shared among all databases within a cluster.
#6 Client applications are prohibited from connecting to template0
#1 If by you we mean "the client" saying that you work "in the cluster data" doesn't really help.  I would emphasize the point that the client sees an endpoint the Postmaster publishes as a port or socket file and that plus the database name defines the endpoint the client connects to (meld with #5)

In lieu of some of the existing detail provided about structure I would add information about configuration and search_path at this level.

I like the object type enumeration - I would suggest grouping them by type in a manner consistent with the documentation and making each one a link to its "primary" section - the SQL Command reference if all else fails.

The "i" in internal in 51.3 (the image) needs capitalization).

You correctly add both Extension and Collation as database-level objects but they are not mentioned anywhere else.  They do belong here and need to be tied in properly in the text.

The whole thing needs a good pass focused on capitalization.  Both for typos and to decide when various primary concepts like Instance should be capitalized and when not.

51.4 - When you look at the diagram seeing /pg/data/base looks really cool, but when reading the prose where both the "pg" and the "base" are omitted and all you get are repeated references to "data", the directory name choice becomes an issue IMO.  I suggest (and changed the attached) to name the actual root directory "pgdata".  You should change the /pg/ directory name to something like ".../tutorial_project/".

Since you aren't following alphabetical order anyway I would place pg_tblspc after globals since tablespaces are globals and thus proximity links them here - and pointing out that pg_tblspc holds the data makes stating that global doesn't contain tablespace data unnecessary.

Maybe point out somewhere the the "base/databaseOID" directory represents the default tablespace for each database, which isn't "global", only the non-default tablespaces are considered globals (or just get rid of the mentioned on "non-default tablespace" for now).

David J.

Attachment

pgsql-hackers by date:

Previous
From: Thomas Munro
Date:
Subject: Re: -Wformat-signedness
Next
From: Alvaro Herrera
Date:
Subject: Re: Hybrid Hash/Nested Loop joins and caching results from subplans