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 1jJHdr-00063z-Vj for pgsql-hackers@arkaria.postgresql.org; Tue, 31 Mar 2020 14:13:24 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.92) (envelope-from ) id 1jJHdq-0006z7-Rh for pgsql-hackers@arkaria.postgresql.org; Tue, 31 Mar 2020 14:13:22 +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 1jJHdq-0006yz-As for pgsql-hackers@lists.postgresql.org; Tue, 31 Mar 2020 14:13:22 +0000 Received: from mout.kundenserver.de ([212.227.126.131]) by makus.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.92) (envelope-from ) id 1jJHdm-0001ZF-BD for pgsql-hackers@postgresql.org; Tue, 31 Mar 2020 14:13:21 +0000 Received: from [192.168.178.43] ([77.179.192.120]) by mrelayeu.kundenserver.de (mreue011 [212.227.15.129]) with ESMTPSA (Nemesis) id 1MryCb-1iyIDg3Sgn-00nyKH; Tue, 31 Mar 2020 16:13:01 +0200 Subject: Re: Add A Glossary To: Corey Huinker Cc: Justin Pryzby , Alvaro Herrera , Roger Harkavy , pgsql-hackers@postgresql.org, Fabien COELHO , Michael Paquier References: <20200320001122.GA19602@alvherre.pgsql> <20200320195841.GA13662@telsasoft.com> <64b49f34-eaf6-6de2-e951-0eb8d4afabc2@purtz.de> <20200327201200.GV20103@telsasoft.com> From: =?UTF-8?Q?J=c3=bcrgen_Purtz?= Message-ID: <84cfa166-89d2-db0c-f5bd-421ca2b2f590@purtz.de> Date: Tue, 31 Mar 2020 16:13:00 +0200 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.4.1 MIME-Version: 1.0 In-Reply-To: Content-Type: multipart/mixed; boundary="------------7CB50E097477F47908D52839" Content-Language: en-US X-Provags-ID: V03:K1:9dkKZxRnmuIiUSb1eXBepYZ6PPU+mkPKt7LCQS9tDaIDwknWfo9 KG7Ow4HHUYUG97ECCgNL3+ZVv41V3Lvzkt5gOHkCT77YsPyysPOCNHpHWuoWp6RmxWUI+++ zGT14naETJwMS3CJQzNlAqRwKiH8VKdeRH/MklyzVW9+JkkFuzop0GZoDVvCFPCnTrxIlCJ 4heOIUcO3mvA3qIefrYzg== X-Spam-Flag: NO X-UI-Out-Filterresults: notjunk:1;V03:K0:7z2zi2him7s=:2kzFNToFMSb0aIeKY8p2WH z9+3yaVjtpyy+hEguqRBaCL2xd9dEHopyOZbrGJ3o0ztCyno+f0EzEXoFZhQTfhc84L+j8LMT oiF/HVaHNWitWHEKp0u7LMf/e7KU/azR8EtPZe2Oi/6P1yrxNUsOXE0AyrhppIibTY2sRz8kJ 4bCry3St5maE463VjrVwlCB1YwS5W9NGWzLq1UEhxYXkBN1Ht7Kb9gmzj0FCMHTiiO26PswrO vk8lhFY23M2Uxmtz3LcfhQ0FEoZLLfiaX8gtlx8igIiSs2XoD8GoIxDlrNbEx7ediTXq/Ikem CGkJBK0Bdb6ktihOv6Xysqj90TL59R1hEHB8y4eKjM1cgygVw0eyD+89YIGbWkizvuds5n09E zF0X4oZA8iYJvWRJiKbNvlTZbZgOPcCd7oo3hQ7IwGIUHuA4T4RDQNerhldjtWHAjcBvqoKuK VhsUax9nO5tM9WEDkmUWU/8Swq0xjr5Nosp0oBfMLCzC4Dgby1vcSCGh6FGW/y4ghVYYy1ybQ N5FiCaWVk2Q+6BhqVtPkCAfCx+yRlcX/CKpCWSiUnLTw8FZbNbYZJtkO8eF8uzo/ydJIV6RUt /Z8PRKCZMH+rc98dcrXGXRIxnvDxgNKt/As/7Pz/wAgXQFtgc0P8faILLh246M+SvEk23PTE7 1iJwydcWrF67rFYwp6/NHLz06MT68NLUmeDimCpw1Oyl8VEtnfMTyuQOZe6YyorfHV8YnN7R2 /niWaWHB1ymkblP7bwEahKkCoLt+9AXfqSG+pzEB43V49AuB09RocU58WMdnHa0cwcOlzTAq7 teIZESiy6kcgGs0B9qxMoaV6yxLhtk1r+3BrUsI4Tv4iqxD7+PXtk1bhRJDJeMoVpzP0tP/ List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Precedence: bulk This is a multi-part message in MIME format. --------------7CB50E097477F47908D52839 Content-Type: multipart/alternative; boundary="------------F9C692F1DD2795C4686EDE96" --------------F9C692F1DD2795C4686EDE96 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 8bit On 30.03.20 19:10, Corey Huinker wrote: > > > On Sun, Mar 29, 2020 at 5:29 AM Jürgen Purtz > wrote: > > On 27.03.20 21:12, Justin Pryzby wrote: > > On Fri, Mar 20, 2020 at 11:32:25PM +0100, Jürgen Purtz wrote: > >>>> + Archiver > >>> Can you change that to archiver process ? > >> I prefer the short term without the addition of 'process' - > concerning > >> 'Archiver' as well as the other cases. But I'm not an native > English > >> speaker. > > I didn't like it due to lack of context. > > > > What about "wal archiver" ? > > > > It occured to me when I read this. > > > https://www.postgresql.org/message-id/20200327.163007.128069746774242774.horikyota.ntt%40gmail.com > > > "WAL archiver" is ok for me. In the current documentation we have 2 > places with "WAL archiver" and 4 with "archiver"-only > (high-availability.sgml, monitoring.sgml). > > "backend process" is an exception to the other terms because the > standalone term "backend" is sensibly used in diverse situations. > > Kind regards, Jürgen > > > I've taken Alvarao's fixes and done my best to incorporate the > feedback into a new patch, which Roger's (tech writer) reviewed yesterday. > > The changes are too numerous to list, but the highlights are: > > New definitions: > * All four ACID terms > * Vacuum (split off from Autovacuum) > * Tablespace > * WAL Archiver (replaces Archiver) > > Changes to existing terms: > * Implemented most wording changes recommended by Justin > * all remaining links were either made into xrefs or edited out of > existence > > * de-tagged most second uses of of a term within a definition > > > Did not do > * Addressed the " Process" suffix suggested by Justin. There isn't > consensus on these changes, and I'm neutral on the matter > * change the Cast definition. I think it's important to express > that a cast has a FROM datatype as well as a TO > * anything host/server related as I couldn't see a consensus reached > > Other thoughts: > * Trivial definitions that are just see-other-definition are ok > with me, as the goal of this glossary is to aid in discovery of > term meanings, so knowing that two terms are interchangable is > itself helpful > > > It is my hope that this revision represents the final _structural_ > change to the glossary. New definitions and edits to existing > definitions will, of course, go on forever. Please find some minor suggestions in the attachment. They are based on Corey's last patch 0001-glossary-v4.patch. Kind regards, Jürgen --------------F9C692F1DD2795C4686EDE96 Content-Type: text/html; charset=utf-8 Content-Transfer-Encoding: 8bit
On 30.03.20 19:10, Corey Huinker wrote:


On Sun, Mar 29, 2020 at 5:29 AM Jürgen Purtz <juergen@purtz.de> wrote:
On 27.03.20 21:12, Justin Pryzby wrote:
> On Fri, Mar 20, 2020 at 11:32:25PM +0100, Jürgen Purtz wrote:
>>>> +    <glossterm>Archiver</glossterm>
>>> Can you change that to archiver process ?
>> I prefer the short term without the addition of 'process' - concerning
>> 'Archiver' as well as the other cases. But I'm not an native English
>> speaker.
> I didn't like it due to lack of context.
>
> What about "wal archiver" ?
>
> It occured to me when I read this.
> https://www.postgresql.org/message-id/20200327.163007.128069746774242774.horikyota.ntt%40gmail.com
>
"WAL archiver" is ok for me. In the current documentation we have 2
places with "WAL archiver" and 4 with "archiver"-only
(high-availability.sgml, monitoring.sgml).

"backend process" is an exception to the other terms because the
standalone term "backend" is sensibly used in diverse situations.

Kind regards, Jürgen

I've taken Alvarao's fixes and done my best to incorporate the feedback into a new patch, which Roger's (tech writer) reviewed yesterday.

The changes are too numerous to list, but the highlights are:

New definitions:
* All four ACID terms
* Vacuum (split off from Autovacuum)
* Tablespace
* WAL Archiver (replaces Archiver)

Changes to existing terms:
* Implemented most wording changes recommended by Justin
* all remaining links were either made into xrefs or edited out of existence
* de-tagged most second uses of of a term within a definition

Did not do
* Addressed the " Process" suffix suggested by Justin. There isn't consensus on these changes, and I'm neutral on the matter
* change the Cast definition. I think it's important to express that a cast has a FROM datatype as well as a TO
* anything host/server related as I couldn't see a consensus reached

Other thoughts:
* Trivial definitions that are just see-other-definition are ok with me, as the goal of this glossary is to aid in discovery of term meanings, so knowing that two terms are interchangable is itself helpful

It is my hope that this revision represents the final _structural_ change to the glossary. New definitions and edits to existing definitions will, of course, go on forever.

Please find some minor suggestions in the attachment. They are based on Corey's last patch 0001-glossary-v4.patch.

Kind regards, Jürgen


--------------F9C692F1DD2795C4686EDE96-- --------------7CB50E097477F47908D52839 Content-Type: text/x-patch; charset=UTF-8; name="0001-glossary-v4-01.patch" Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="0001-glossary-v4-01.patch" diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml index eab14f3c9b..623922a4c3 100644 --- a/doc/src/sgml/glossary.sgml +++ b/doc/src/sgml/glossary.sgml @@ -36,10 +36,10 @@ - Analytic + Analytic Function - A Function whose computed value can reference + A type of Functions whose result may be based on values found in nearby Rows of the same Result Set. @@ -59,12 +59,12 @@ into smaller components. + In reference to an operation: an event that cannot be completed in part; it must either entirely succeed or entirely fail. For example, a series of SQL statements can be combined into a Transaction, and that - transaction is said to be atomic. - Atomic. + transaction is said to be Atomic. @@ -73,7 +73,7 @@ Atomicity - One of the ACID properties. This is the state of + One of the ACID properties. This is the state of being Atomic in the operational/transactional sense. @@ -152,7 +152,7 @@ A process that continuously writes dirty pages from Shared Memory to the file system. It wakes up periodically, but - works only for a short period in order to distribute expensive + works only for a short period in order to distribute its expensive I/O activity over time, instead of generating fewer larger I/O peaks which could block other processes. @@ -220,7 +220,7 @@ Records to the file system and creates a special checkpoint record. This process is initiated when predefined conditions are met, such as a specified amount of time has passed, or - a certain volume of records have been collected. + a certain volume of records has been collected. @@ -303,7 +303,7 @@ An established line of communication between a client process - and a server process. If the two involved processes reside on the + and a Backend Process. If the two involved processes reside on the same Server, then the connection can either use TCP/IP or Unix-domain sockets. Otherwise, only TCP/IP can be used. @@ -470,7 +470,7 @@ A type of Constraint defined on one or more Columns in a Table which requires the value(s) in those Columns to - identify exactly one Row in the specified + identify exactly one Row in another (or the same) Table. @@ -643,7 +643,7 @@ Isolation - One of the ACID properties. This means that concurrently running + One of the ACID properties. This means that concurrently running Transactions affect the database exactly as if they had been executed sequentially. @@ -795,6 +795,7 @@ Partition + In reference to a Table: A Table that can be queried directly, or via a partitioned table, which is a collection of sub-tables, each capable of holding one defined @@ -802,9 +803,8 @@ table in the collection. - When referring to an Analytic - Function: a partition is a definition - that identifies which neighboring + In reference to a Analytic Function: + a partition is a definition that identifies which neighboring Rows can be considered by the function. @@ -865,13 +865,13 @@ Record - - See Tuple. - A single Row of a Table or other Relation. + + See Tuple. + @@ -880,6 +880,7 @@ A means of restricting data in one Relation + by a Foreign Key so that it must have matching data in another Relation. @@ -905,7 +906,7 @@ Replica - A Database that is paired with a + A Database that is paired with a Master database and is maintaining a copy of some or all of the Master Database's data. The primary @@ -934,7 +935,7 @@ Result Set - A data structure transmitted from a Server to + A data structure transmitted from a Backend Process to client program upon the completion of a SQL command, usually a SELECT but it can be an INSERT, UPDATE, or @@ -1068,8 +1069,8 @@ Select - The command used to query a Database. Normally, - SELECTs are not expected to modify the + The SQL command used to query a Database. + Normally, SELECTs are not expected to modify the Database in any way, but it is possible that Functions invoked within the query could have side effects that do modify data. @@ -1333,7 +1334,8 @@ The condition of having no duplicate values in the same - Relation. Often used in the concept of + Column of a Relation. + Often used in the concept of Unique Indexes. @@ -1361,9 +1363,9 @@ Update - A command used to modify Rows that may already - exist in a specified Table. It cannot create - or remove rows. + A SQL command used to modify Rows + that may already exist in a specified Table. + It cannot create or remove rows. For more information, see @@ -1402,7 +1404,7 @@ The process of removing outdated MVCC - Tuples from a Heap or + Tuples from a Heap or Index. This can be initiated through the use of the VACUUM command, but can also be handled automatically via Autovacuum processes. @@ -1436,7 +1438,7 @@ WAL Archiver - A process that saves copies of WAL Files, + A process that saves copies of WAL Files for the purposes of creating backups or keeping Replicas current. @@ -1461,7 +1463,7 @@ WAL Files is renamed and reused. - The sequence of WAL Records + The sequence of WAL Records represents the sequence of changes that have taken place in the Cluster. @@ -1522,7 +1524,7 @@ This process writes WAL Records from - Shared Memory to + Shared Memory to WAL Files. --------------7CB50E097477F47908D52839--