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 1jlXYe-0006Ll-LU for pgsql-docs@arkaria.postgresql.org; Wed, 17 Jun 2020 12:52:48 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.92) (envelope-from ) id 1jlXYc-0005jb-EF for pgsql-docs@arkaria.postgresql.org; Wed, 17 Jun 2020 12:52:46 +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 1jlXYc-0005jR-4D; Wed, 17 Jun 2020 12:52:46 +0000 Received: from mout.kundenserver.de ([217.72.192.73]) by makus.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jlXYZ-0002Pd-CH; Wed, 17 Jun 2020 12:52:45 +0000 Received: from [192.168.178.43] ([77.181.54.182]) by mrelayeu.kundenserver.de (mreue107 [212.227.15.145]) with ESMTPSA (Nemesis) id 1Mq2Wi-1j7Xuf2qKQ-00n7oU; Wed, 17 Jun 2020 14:52:23 +0200 Subject: Re: Add A Glossary To: Alvaro Herrera Cc: Erik Rijkers , Laurenz Albe , Fabien COELHO , Peter Eisentraut , Corey Huinker , Justin Pryzby , Roger Harkavy , pgsql-hackers@postgresql.org, Michael Paquier , Pg Docs References: <20200617000926.GA11060@alvherre.pgsql> From: =?UTF-8?Q?J=c3=bcrgen_Purtz?= Message-ID: <292d6f42-e31c-bc73-6cfb-9083bc2c07fc@purtz.de> Date: Wed, 17 Jun 2020 14:52:19 +0200 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.8.0 MIME-Version: 1.0 In-Reply-To: <20200617000926.GA11060@alvherre.pgsql> Content-Type: multipart/mixed; boundary="------------57FED42AE4DF4DE3D4B2D025" Content-Language: en-US X-Provags-ID: V03:K1:eTukDudGYI67gCIN1t0fFc8puAbtUhiBDj5RxyqS9jX961MiA70 IoQ2gP1/4gUSXJjIzv8G+ip7+nDbGnIcLXK1pUmGpdzNs9siLdb5qaJ8rhCFsLdFHN9/Yv0 x7Z//IbyqGO5dKWW0kyHmorZvFWPu/ZzrKI5bKA+CsjSH8Zgd2KP349xJP3ZlPP2yijcC9v 0dnMolVYiVybWMBz166cQ== X-Spam-Flag: NO X-UI-Out-Filterresults: notjunk:1;V03:K0:FhG4TQKdwjs=:SSTUjSO8gICGrYvLBlUht8 H6HjMSSSkHvxOBVma6Engy9e1rnZThlQwRNXDA8qYpVUkSjgOpMa05qi+grs0OTCAFKYsKjGG yLp0/rF3pMbg+jhOjC03J5SlcNq3FGRxEUbs84/UV8SsrwQbzQ+Hgwg59WixBgtn76RVTIX0g pE1wkFjEUmyKDmOfHILqmgjGhjwNWixci9vauAtIyLAeXuxjsJXOh2HnSpJA6pMrGSl0HFN/Y aJd/llPiRcCEWrKHbX7wNKCdmmiNWQB8gT14pQ+4/4cRGsOXjNHuhkcJ5d0ObkXazyTUAyj9m baVHM7IPxq0nfgeCuKFWmIz49JS0rF8tOtJfQK9Bgas8YYMEaMZtegaGP4T8eZGwj/B1S2n28 wVqLyEDFh/tRbDyZ3gPk6f88D1CQ/VZ4IcrT9WVk67KrUQhvTw1TTij/dIturaBvN/9O6hE8z 1GudhK+mhwyz4ljwoKSPNagTw7O79bpSlYiOb0fscQJXYcrdnpvxZctCJ8+pQCIGFhjpWyAaU 4hecT7on2zyviGZvCdNjTU2DWu3wmX8xMSRTRTmxFCPCa6WW5cxLE/asc8+xeN894dDJlaDqk pX3X4fVGOQta6OHifQ2BkyDCfcxvq67Bm02fDfqavo2Gfcx/8Xn7lBZ6b+P/FgboCRK8prZdj uHwPfvPpwfBcw/xmCw1ZKIS2DOfKH9XxQvvJfgwUYYTgGnK2E1Vc7R5NO3d0srEsF3U3Po8WW IHeFq8JQ+HXL+HtgRklZH5X2y42aOcKPt7K5a4YgePVH5cLZArzBEKKAErslZVFq7+PSNZIq3 JtKCX5cSV9UdEbGSq55x05yWclXzz4YJn1jlHb7hgub3afQVaY= List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Precedence: bulk This is a multi-part message in MIME format. --------------57FED42AE4DF4DE3D4B2D025 Content-Type: multipart/alternative; boundary="------------5D9DFEA1987275AA71E797B8" --------------5D9DFEA1987275AA71E797B8 Content-Type: text/plain; charset=windows-1252; format=flowed Content-Transfer-Encoding: 8bit On 17.06.20 02:09, Alvaro Herrera wrote: > 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. +1, with two formal changes: -  Rearrangement of term "Data page" to meet alphabetical order. -  Add in one case to meet xml-well-formedness. One last question: The definition of "Data directory" reads "... A cluster's storage space comprises the data directory plus ..." and 'cluster' links to '"glossary-instance". Shouldn't it link to "glossary-db-cluster"? -- Jürgen Purtz --------------5D9DFEA1987275AA71E797B8 Content-Type: text/html; charset=windows-1252 Content-Transfer-Encoding: 8bit

On 17.06.20 02:09, Alvaro Herrera wrote:
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.


    

    
+1, with two formal changes:

    

    
-  Rearrangement of term "Data page" to meet alphabetical order.

    
-  Add </glossdef> in one case to meet xml-well-formedness.

    


    

    
One last question: The definition of "Data directory" reads "...
      A cluster's
      storage space comprises the data directory plus ..." and 'cluster'
      links to '"glossary-instance". Shouldn't it link to
      "glossary-db-cluster"?

    

    
--

    
Jürgen Purtz

    

    


    

  


--------------5D9DFEA1987275AA71E797B8--

--------------57FED42AE4DF4DE3D4B2D025
Content-Type: text/x-patch; charset=UTF-8;
 name="0004-glossary.patch"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
 filename="0004-glossary.patch"

diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
index e29b55e5ac..0499f9044f 100644
--- a/doc/src/sgml/glossary.sgml
+++ b/doc/src/sgml/glossary.sgml
@@ -413,6 +413,22 @@
    
   
 
+  
+   Data page
+   
+    
+     The basic structure used to store relation data.
+     All pages are of the same size.
+     Data pages are typically stored on disk, each in a specific file,
+     and can be read to shared buffers
+     where they can be modified, becoming
+     dirty.  They become clean when written
+     to disk.  New pages, which initially exist in memory only, are also
+     dirty until written.
+    
+   
+  
+
   
    Database
    
@@ -441,6 +457,7 @@
      cluster is also sometimes used to refer to an instance.
      (Don't confuse this term with the SQL command CLUSTER.)
     
+   
   
 
   
@@ -448,22 +465,6 @@
    
   
 
-  
-   Data page
-   
-    
-     The basic structure used to store relation data.
-     All pages are of the same size.
-     Data pages are typically stored on disk, each in a specific file,
-     and can be read to shared buffers
-     where they can be modified, becoming
-     dirty.  They become clean when written
-     to disk.  New pages, which initially exist in memory only, are also
-     dirty until written.
-    
-   
-  
-
   
    Datum
    

--------------57FED42AE4DF4DE3D4B2D025--