Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jlLe5-0002Ve-Tx for pgsql-docs@arkaria.postgresql.org; Wed, 17 Jun 2020 00:09:38 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.92) (envelope-from ) id 1jlLe2-0008La-Ff for pgsql-docs@arkaria.postgresql.org; Wed, 17 Jun 2020 00:09:34 +0000 Received: from makus.postgresql.org ([2001:4800:3e1:1::229]) by malur.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jlLe2-0008LN-5F for pgsql-docs@lists.postgresql.org; Wed, 17 Jun 2020 00:09:34 +0000 Received: from mail-qk1-x743.google.com ([2607:f8b0:4864:20::743]) by makus.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.92) (envelope-from ) id 1jlLdz-0004Dy-5H for pgsql-docs@lists.postgresql.org; Wed, 17 Jun 2020 00:09:33 +0000 Received: by mail-qk1-x743.google.com with SMTP id w1so463284qkw.5 for ; Tue, 16 Jun 2020 17:09:30 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=2ndquadrant-com.20150623.gappssmtp.com; s=20150623; h=date:from:to:cc:subject:message-id:mime-version:content-disposition :content-transfer-encoding:in-reply-to:user-agent; bh=yH9iJcADEPenpwYbIeJHNNnp3DCvOkJ8M4mYdfxdTVs=; b=IP36o8WZ5x0cNqREchtvvBt7ymQaintCSqHPa7KSosYdrQlECeYkt3rJJQVB4oIyF8 O11Pq96bCJRG5ntXXQIeCQTgg+/+tuAv3TaRIR34ZdsoCERYzp5rLauPx06k2Ym4bSp7 IUt0VGyFDXR56yFLY3Zp99iYMDl+7bkNgs2mcQYPDPKc7kUKtJMLvcpaXGKb1YD+PWIl v6GPu6kMuGByB7Bptc9Qn2OtJ3O7ZsElHyXH/PncutVuPXe81K/prr50O01nYiXTPPdQ HRpwgO5eZWjDoVWlxsYYYfEvhEv6paJfGy+U4IRtSoz8rIbQfNr+YD8NpyfbjXr9huPd t9rg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:cc:subject:message-id:mime-version :content-disposition:content-transfer-encoding:in-reply-to :user-agent; bh=yH9iJcADEPenpwYbIeJHNNnp3DCvOkJ8M4mYdfxdTVs=; b=oM0pq3yOTlzllHL/tftV8IMNpNerdH/Sg/+eF3sLo4TgDkEVDBuBVCxxe4teBLbYdB HmKWL/iJrW0UJFOr8moD2hHRkiBrZgbo+oyId41+dCgVHSFngqv4LW5fJX5/w2hK/y3Z VVy+Tv3u0bHg75EHwdmPIE3wFcAnqMvwbdnV2e3tjRRKE/tEUTWZeBtt7OJ4sTel8llj CcfQTVhg1+iS78hZPUuo+lJmNbfVbJmyaT18IRxbSXmSq55CujiQywwH0e7z1co9CcSE 4Q5BW7eYxu3gJgyTcN7JSP2PfmtHhZOGKtQeqh0P26BkX/uXyfMf7ahFrnCLbdQFAzOe jHgg== X-Gm-Message-State: AOAM5304Eq2xb9ImgjrX4WWcqVj7HIIKPqw/zMm9uKR82q1QQHB8l+Gq FuCq+JfgTNmmsXjQsrUjN728ng== X-Google-Smtp-Source: ABdhPJwNrRGBTw603tqRqRa4FtD2BuUPXk0OX6nE+WMzJ1x10IJKjNnmqEhpwOHXSMXC4NwL9KYouQ== X-Received: by 2002:a37:9005:: with SMTP id s5mr22209322qkd.432.1592352570047; Tue, 16 Jun 2020 17:09:30 -0700 (PDT) Received: from perhan.alvh.no-ip.org ([190.95.18.252]) by smtp.gmail.com with ESMTPSA id i3sm15188082qkf.39.2020.06.16.17.09.28 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 16 Jun 2020 17:09:29 -0700 (PDT) Received: by perhan.alvh.no-ip.org (Postfix, from userid 1000) id 01EC32A39CE; Tue, 16 Jun 2020 20:09:26 -0400 (-04) Date: Tue, 16 Jun 2020 20:09:26 -0400 From: Alvaro Herrera To: =?iso-8859-1?Q?J=FCrgen?= Purtz Cc: Erik Rijkers , Laurenz Albe , Fabien COELHO , Peter Eisentraut , Corey Huinker , Justin Pryzby , Roger Harkavy , pgsql-hackers@postgresql.org, Michael Paquier , Pg Docs Subject: Re: Add A Glossary Message-ID: <20200617000926.GA11060@alvherre.pgsql> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="5vNYLRcllDrimb99" Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: User-Agent: Mutt/1.10.1 (2018-07-13) List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Precedence: bulk --5vNYLRcllDrimb99 Content-Type: text/plain; charset=iso-8859-1 Content-Disposition: inline Content-Transfer-Encoding: 8bit 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 --5vNYLRcllDrimb99 Content-Type: text/x-diff; charset=us-ascii Content-Disposition: attachment; filename="glossary.patch" 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 @@ The base directory on the filesystem of a server that contains all - data files and subdirectories associated with an - instance (with the - exception of tablespaces). + data files and subdirectories associated with a + database cluster + (with the exception of + tablespaces). The environment variable PGDATA is commonly used to - refer to the - data directory. + refer to the data directory. - An instance's storage + A cluster's storage space comprises the data directory plus any additional tablespaces. @@ -418,7 +418,7 @@ A named collection of - SQL objects. + local SQL objects. For more information, see @@ -427,6 +427,22 @@ + + Database cluster + + + A collection of databases and global SQL objects, + and their common static and dynamic meta-data. + Sometimes referred to as a + cluster. + + + In PostgreSQL, the term + cluster is also sometimes used to refer to an instance. + (Don't confuse this term with the SQL command CLUSTER.) + + + Database server @@ -634,7 +650,7 @@ Function - Any defined transformation of data. Many functions are already defined + A defined transformation of data. Many functions are already defined within PostgreSQL itself, but user-defined ones can also be added. @@ -724,14 +740,12 @@ Instance - A set of databases and accompanying global SQL objects that are stored in - the same data directory - in a single server. - If running, one + A group of backend and auxiliary processes that communicate using + a common shared memory area. One postmaster process - manages a group of backend and auxiliary processes that communicate - using a common shared memory - area. Many instances can run on the same + manages the instance; one instance manages exactly one + database cluster + with all its databases. Many instances can run on the same server as long as their TCP ports do not conflict. @@ -739,14 +753,10 @@ The instance handles all key features of a DBMS: read and write access to files and shared memory, assurance of the ACID properties, - connections to client processes, + connections to + client processes, privilege verification, crash recovery, replication, etc. - - In PostgreSQL, the term - cluster is also sometimes used to refer to an instance. - (Don't confuse this term with the SQL command CLUSTER.) - @@ -1245,12 +1255,17 @@ SQL objects, which all reside in the same database. - 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). 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 + database cluster. All system-defined SQL objects reside in schema pg_catalog, @@ -1384,27 +1399,34 @@ - SQL Object + SQL object Any object that can be created with a CREATE command. Most objects are specific to one database, and are commonly known as local objects. - Roles, - tablespaces, - 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 global objects. Most local objects belong to a specific - schema in their containing database. + schema in their + containing database, such as + all types of relations, + all types of functions, + data types, etc. There also exist local objects that do not belong to schemas; some examples are extensions, data type casts, and foreign data wrappers. - + + + Other object types, such as + roles, + tablespaces, + 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 global objects. + For more information, see . @@ -1489,7 +1511,7 @@ which require storage beyond their definition in the system catalog 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 pg_default. --5vNYLRcllDrimb99--