From e472ebd65deb98940fca7a22e940e6cc73592ece Mon Sep 17 00:00:00 2001
From: Bruce Momjian <bruce@momjian.us>
Date: Tue, 31 Mar 2020 18:10:39 -0400
Subject: [PATCH] doc:  clarify hierarchy of objects:  global, db, schema, etc.

The previous wording was confusing because it wasn't in decreasing order
and had to backtrack.  Also clarify role/user wording.

Reported-by: jbird@nuna.com

Discussion: https://postgr.es/m/158057750885.1123.2806779262588618988@wrigleys.postgresql.org

Backpatch-through: 9.5
---
 doc/src/sgml/ddl.sgml       | 15 +++++++--------
 doc/src/sgml/manage-ag.sgml | 16 +++++++---------
 2 files changed, 14 insertions(+), 17 deletions(-)

diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index 61e5e513001..b7943df8656 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -2054,19 +2054,18 @@ SELECT * FROM information WHERE group_id = 2 FOR UPDATE;
   </indexterm>
 
   <para>
-   A <productname>PostgreSQL</productname> database cluster
-   contains one or more named databases.  Users and groups of users are
-   shared across the entire cluster, but no other data is shared across
-   databases.  Any given client connection to the server can access
-   only the data in a single database, the one specified in the connection
-   request.
+   A <productname>PostgreSQL</productname> database cluster contains
+   one or more named databases.  Roles and a few other object types are
+   shared across the entire cluster.  A client connection to the server
+   can only access data in a single database, the one specified in the
+   connection request.
   </para>
 
   <note>
    <para>
     Users of a cluster do not necessarily have the privilege to access every
-    database in the cluster.  Sharing of user names means that there
-    cannot be different users named, say, <literal>joe</literal> in two databases
+    database in the cluster.  Sharing of role names means that there
+    cannot be different roles named, say, <literal>joe</literal> in two databases
     in the same cluster; but the system can be configured to allow
     <literal>joe</literal> access to only some of the databases.
    </para>
diff --git a/doc/src/sgml/manage-ag.sgml b/doc/src/sgml/manage-ag.sgml
index 0154064e506..985e625bbcc 100644
--- a/doc/src/sgml/manage-ag.sgml
+++ b/doc/src/sgml/manage-ag.sgml
@@ -22,15 +22,13 @@
   </indexterm>
 
   <para>
-   A database is a named collection of <acronym>SQL</acronym> objects
-   (<quote>database objects</quote>).  Generally, every database
-   object (tables, functions, etc.) belongs to one and only one
-   database.  (However there are a few system catalogs, for example
-   <literal>pg_database</literal>, that belong to a whole cluster and
-   are accessible from each database within the cluster.)  More
-   accurately, a database is a collection of schemas and the schemas
-   contain the tables, functions, etc.  So the full hierarchy is:
-   server, database, schema, table (or some other kind of object,
+   A small number of objects, like role, database, and tablespace
+   names, are defined at the cluster level and stored in the
+   <literal>pg_global</literal> tablespace.  Inside the cluster are
+   multiple databases, which are isolated from each other but can access
+   cluster-level objects.  Inside each database are multiple schemas,
+   which contain objects like tables and functions.  So the full hierarchy
+   is: cluster, database, schema, table (or some other kind of object,
    such as a function).
   </para>