Date: Thu, 14 May 2020 20:03:04 -0500
From: Justin Pryzby <pryzby@telsasoft.com>
To: Alvaro Herrera <alvherre@2ndquadrant.com>
Cc: Erik Rijkers <er@xs4all.nl>, Laurenz Albe <laurenz.albe@cybertec.at>,
	Fabien COELHO <coelho@cri.ensmp.fr>,
	=?iso-8859-1?Q?J=FCrgen?= Purtz <juergen@purtz.de>,
	Peter Eisentraut <peter.eisentraut@2ndquadrant.com>,
	Corey Huinker <corey.huinker@gmail.com>,
	Roger Harkavy <rogerharkavy@gmail.com>,
	pgsql-hackers@postgresql.org, Michael Paquier <michael@paquier.xyz>
Subject: Re: Add A Glossary
Message-ID: <20200515010304.GN18456@telsasoft.com>
References: 
 <CADkLM=ekHJd3zCoO96bADd4-QnEr++E19MRxuHn5qmJLQpb70Q@mail.gmail.com>
 <d66ee81c-551d-6bc0-0836-28b01e9b827f@2ndquadrant.com>
 <280f7b1e-2e81-5d0e-2589-b5ea6313ad74@purtz.de>
 <20200405220715.GA20664@alvherre.pgsql>
 <686e65ba48801791816771e993ff5eebe571fac9.camel@cybertec.at>
 <7b9b469e804777ac9df4d37716db935e@xs4all.nl>
 <20200515000017.GA12687@alvherre.pgsql>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20200515000017.GA12687@alvherre.pgsql>
User-Agent: Mutt/1.9.4 (2018-02-28)
Precedence: bulk

On Thu, May 14, 2020 at 08:00:17PM -0400, Alvaro Herrera wrote:
> +   <glossterm>ACID</glossterm>
> +   <glossdef>
> +    <para>
> +     <glossterm linkend="glossary-atomicity">Atomicity</glossterm>,
> +     <glossterm linkend="glossary-consistency">consistency</glossterm>,
> +     <glossterm linkend="glossary-isolation">isolation</glossterm>, and
> +     <glossterm linkend="glossary-durability">durability</glossterm>.
> +     A set of properties of database transactions intended to guarantee validity
> +     in concurrent operation and even in event of errors, power failures, etc.

I would capitalize Consistency, Isolation, Durability, and say "These four
properties" or "This set of four properties" (althought that makes this sounds
more like a fun game of DBA jeopardy).

> +   <glossterm>Background writer (process)</glossterm>
>     <glossdef>
>      <para>
> -     A process that continuously writes dirty pages from
> +     A process that continuously writes dirty

I don't like "continuously"

> +     <glossterm linkend="glossary-data-page">data pages</glossterm> from
>  
> +  <glossentry id="glossary-bloat">
> +   <glossterm>Bloat</glossterm>
> +   <glossdef>
> +    <para>
> +     Space in data pages which does not contain relevant data,
> +     such as unused (free) space or outdated row versions.

"current row versions" instead of relevant ?

> +  <glossentry id="glossary-data-page">
> +   <glossterm>Data page</glossterm>
> +   <glossdef>
> +    <para>
> +     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 <glossterm linkend="glossary-shared-memory">shared buffers</glossterm>
> +     where they can be modified, becoming
> +     <firstterm>dirty</firstterm>.  They get clean by being written down

say "They become clean when written to disk"

> +     to disk.  New pages, which initially exist in memory only, are also
> +     dirty until written.

> +  <glossentry id="glossary-fork">
> +   <glossterm>Fork</glossterm>
> +   <glossdef>
> +    <para>
> +     Each of the separate segmented file sets that a relation stores its
> +     data in.  There exist a <firstterm>main fork</firstterm> and two secondary

"in which a relation's data is stored"

> +     forks: the <glossterm linkend="glossary-fsm">free space map</glossterm>
> +     <glossterm linkend="glossary-vm">visibility map</glossterm>.

missing "and" ?

> +  <glossentry id="glossary-fsm">
> +   <glossterm>Free space map (fork)</glossterm>
> +   <glossdef>
> +    <para>
> +     A storage structure that keeps metadata about each data page in a table's
> +     main storage space.

s/in/of/

just say "main fork"?

> The free space map entry for each space stores the

for each page ?

> +     amount of free space that's available for future tuples, and is structured
> +     so it is efficient to search for available space for a new tuple of a given
> +     size.

..to be efficiently searched to find free space..

>       The heap is realized within
> -     <glossterm linkend="glossary-file-segment">segment files</glossterm>.
> +     <glossterm linkend="glossary-file-segment">segmented files</glossterm>
> +     in the relation's <glossterm linkend="glossary-fork">main fork</glossterm>.

Hm, the files aren't segmented.  Say "one or more file segments per relation"

> +      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>.

Don't extensions have schemas ?

> +  <glossentry id="glossary-xid">
> +   <glossterm>Transaction ID</glossterm>
> +   <glossdef>
> +    <para>
> +     The numerical, unique, sequentially-assigned identifier that each
> +     transaction receives when it first causes a database modification.
> +     Frequently abbreviated <firstterm>xid</firstterm>.

abbreviated *as* xid

> +     approximately four billion write transactions IDs can be generated;
> +     to permit the system to run for longer than that would allow,

remove "would allow"

>      <para>
>       The process of removing outdated <glossterm linkend="glossary-tuple">tuple
>       versions</glossterm> from tables, and other closely related

actually tables or materialized views..

> +  <glossentry id="glossary-vm">
> +   <glossterm>Visibility map (fork)</glossterm>
> +   <glossdef>
> +    <para>
> +     A storage structure that keeps metadata about each data page
> +     in a table's main storage space.  The visibility map entry for

s/in/of/

main fork?

-- 
Justin