On 2020-Jun-09, Jürgen Purtz wrote:
> Can you agree to the following definitions? If no, we can alternatively
> formulate for each of them: "Under discussion - currently not defined". My
> proposals are inspired by chapter 2.2 Concepts: "Tables are grouped into
> databases, and a collection of databases managed by a single PostgreSQL
> server instance constitutes a database cluster."
After sleeping on it a few more times, I don't oppose the idea of making
"instance" be the running state and "database cluster" the on-disk stuff
that supports the instance. Here's a patch that does things pretty much
along the lines you suggested.
I made small adjustments to "SQL objects":
* SQL objects in schemas were said to have their names unique in the
schema, but we failed to say anything about names of objects not in
schemas and global objects. Added that.
* Had example object types for global objects and objects not in
schemas, but no examples for objects in schemas. Added that.
Some programs whose output we could tweak per this:
pg_ctl
> pg_ctl is a utility to initialize, start, stop, or control a PostgreSQL
> server.
> -D, --pgdata=DATADIR location of the database storage area
to:
> pg_ctl is a utility to initialize or control a PostgreSQL database cluster.
> -D, --pgdata=DATADIR location of the database directory
pg_basebackup:
> pg_basebackup takes a base backup of a running PostgreSQL server.
to:
> pg_basebackup takes a base backup of a PostgreSQL instance.
--
Álvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
index 25b03f3b37..e29b55e5ac 100644
--- a/doc/src/sgml/glossary.sgml
+++ b/doc/src/sgml/glossary.sgml
@@ -395,15 +395,15 @@
<para>
The base directory on the filesystem of a
<glossterm linkend="glossary-server">server</glossterm> that contains all
- data files and subdirectories associated with an
- <glossterm linkend="glossary-instance">instance</glossterm> (with the
- exception of <glossterm linkend="glossary-tablespace">tablespaces</glossterm>).
+ data files and subdirectories associated with a
+ <glossterm linkend="glossary-db-cluster">database cluster</glossterm>
+ (with the exception of
+ <glossterm linkend="glossary-tablespace">tablespaces</glossterm>).
The environment variable <literal>PGDATA</literal> is commonly used to
- refer to the
- <glossterm linkend="glossary-data-directory">data directory</glossterm>.
+ refer to the data directory.
</para>
<para>
- An <glossterm linkend="glossary-instance">instance</glossterm>'s storage
+ A <glossterm linkend="glossary-instance">cluster</glossterm>'s storage
space comprises the data directory plus any additional tablespaces.
</para>
<para>
@@ -418,7 +418,7 @@
<glossdef>
<para>
A named collection of
- <glossterm linkend="glossary-sql-object">SQL objects</glossterm>.
+ <glossterm linkend="glossary-sql-object">local SQL objects</glossterm>.
</para>
<para>
For more information, see
@@ -427,6 +427,22 @@
</glossdef>
</glossentry>
+ <glossentry id="glossary-db-cluster">
+ <glossterm>Database cluster</glossterm>
+ <glossdef>
+ <para>
+ A collection of databases and global SQL objects,
+ and their common static and dynamic meta-data.
+ Sometimes referred to as a
+ <firstterm>cluster</firstterm>.
+ </para>
+ <para>
+ In <productname>PostgreSQL</productname>, the term
+ <firstterm>cluster</firstterm> is also sometimes used to refer to an instance.
+ (Don't confuse this term with the SQL command <command>CLUSTER</command>.)
+ </para>
+ </glossentry>
+
<glossentry>
<glossterm>Database server</glossterm>
<glosssee otherterm="glossary-instance" />
@@ -634,7 +650,7 @@
<glossterm>Function</glossterm>
<glossdef>
<para>
- Any defined transformation of data. Many functions are already defined
+ A defined transformation of data. Many functions are already defined
within <productname>PostgreSQL</productname> itself, but user-defined
ones can also be added.
</para>
@@ -724,14 +740,12 @@
<glossterm>Instance</glossterm>
<glossdef>
<para>
- A set of databases and accompanying global SQL objects that are stored in
- the same <glossterm linkend="glossary-data-directory">data directory</glossterm>
- in a single <glossterm linkend="glossary-server">server</glossterm>.
- If running, one
+ A group of backend and auxiliary processes that communicate using
+ a common shared memory area. One
<glossterm linkend="glossary-postmaster">postmaster process</glossterm>
- manages a group of backend and auxiliary processes that communicate
- using a common <glossterm linkend="glossary-shared-memory">shared memory</glossterm>
- area. Many instances can run on the same
+ manages the instance; one instance manages exactly one
+ <glossterm linkend="glossary-db-cluster">database cluster</glossterm>
+ with all its databases. Many instances can run on the same
<glossterm linkend="glossary-server">server</glossterm>
as long as their <acronym>TCP</acronym> ports do not conflict.
</para>
@@ -739,14 +753,10 @@
The instance handles all key features of a <acronym>DBMS</acronym>:
read and write access to files and shared memory,
assurance of the <acronym>ACID</acronym> properties,
- <glossterm linkend="glossary-connection">connections</glossterm> to client processes,
+ <glossterm linkend="glossary-connection">connections</glossterm> to
+ <glossterm linkend="glossary-client">client processes</glossterm>,
privilege verification, crash recovery, replication, etc.
</para>
- <para>
- In <productname>PostgreSQL</productname>, the term
- <firstterm>cluster</firstterm> is also sometimes used to refer to an instance.
- (Don't confuse this term with the SQL command <command>CLUSTER</command>.)
- </para>
</glossdef>
</glossentry>
@@ -1245,12 +1255,17 @@
<glossterm linkend="glossary-sql-object">SQL objects</glossterm>,
which all reside in the same
<glossterm linkend="glossary-database">database</glossterm>.
- Each SQL object must reside in exactly one schema.
+ Each SQL object must reside in exactly one schema
+ (though certain types of SQL objects exist outside schemas).
</para>
<para>
The names of SQL objects of the same type in the same schema are enforced
to be unique.
There is no restriction on reusing a name in multiple schemas.
+ For local objects that exist outside schemas, their names are enforced
+ unique across the whole database. For global objects, their names
+ are enforced unique across the whole
+ <glossterm linkend="glossary-db-cluster">database cluster</glossterm>.
</para>
<para>
All system-defined SQL objects reside in schema <literal>pg_catalog</literal>,
@@ -1384,27 +1399,34 @@
</glossentry>
<glossentry id="glossary-sql-object">
- <glossterm>SQL Object</glossterm>
+ <glossterm>SQL object</glossterm>
<glossdef>
<para>
Any object that can be created with a <command>CREATE</command>
command. Most objects are specific to one database, and are commonly
known as <firstterm>local objects</firstterm>.
- <glossterm linkend="glossary-role">Roles</glossterm>,
- <glossterm linkend="glossary-tablespace">tablespaces</glossterm>,
- replication origins, subscriptions for logical replication, and
- databases themselves are not local SQL objects since they exist
- entirely outside of any specific database;
- they are called <firstterm>global objects</firstterm>.
</para>
<para>
Most local objects belong to a specific
- <glossterm linkend="glossary-schema">schema</glossterm> in their containing database.
+ <glossterm linkend="glossary-schema">schema</glossterm> in their
+ containing database, such as
+ <glossterm linkend="glossary-relation">all types of relations</glossterm>,
+ <glossterm linkend="glossary-function">all types of functions</glossterm>,
+ data types, etc.
There also exist local objects that do not belong to schemas; some examples are
<glossterm linkend="glossary-extension">extensions</glossterm>,
<glossterm linkend="glossary-cast">data type casts</glossterm>, and
<glossterm linkend="glossary-foreign-data-wrapper">foreign data wrappers</glossterm>.
- </para>
+ </para>
+ <para>
+ Other object types, such as
+ <glossterm linkend="glossary-role">roles</glossterm>,
+ <glossterm linkend="glossary-tablespace">tablespaces</glossterm>,
+ replication origins, subscriptions for logical replication, and
+ databases themselves are not local SQL objects since they exist
+ entirely outside of any specific database;
+ they are called <firstterm>global objects</firstterm>.
+ </para>
<para>
For more information, see
<xref linkend="manage-ag-overview"/>.
@@ -1489,7 +1511,7 @@
which require storage beyond their definition in the
<glossterm linkend="glossary-system-catalog">system catalog</glossterm>
must belong to a single tablespace.
- Initially, an instance contains a single usable tablespace which is
+ Initially, a database cluster contains a single usable tablespace which is
used as the default one for all SQL objects, called <literal>pg_default</literal>.
</para>
<para>
