Received: from malur.postgresql.org ([217.196.149.56])
	by arkaria.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256)
	(Exim 4.92)
	(envelope-from <pgsql-hackers-owner+archive@lists.postgresql.org>)
	id 1jFQF7-0003f1-1o
	for pgsql-hackers@arkaria.postgresql.org; Fri, 20 Mar 2020 22:35:53 +0000
Received: from localhost ([127.0.0.1] helo=malur.postgresql.org)
	by malur.postgresql.org with esmtp (Exim 4.89)
	(envelope-from <pgsql-hackers-owner+archive@lists.postgresql.org>)
	id 1jFQF5-0006Nd-LG
	for pgsql-hackers@arkaria.postgresql.org; Fri, 20 Mar 2020 22:35:51 +0000
Received: from makus.postgresql.org ([2001:4800:3e1:1::229])
	by malur.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256)
	(Exim 4.89)
	(envelope-from <juergen@purtz.de>)
	id 1jFQBx-0001iO-LM
	for pgsql-hackers@lists.postgresql.org; Fri, 20 Mar 2020 22:32:37 +0000
Received: from mout.kundenserver.de ([212.227.126.134])
	by makus.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128)
	(Exim 4.92)
	(envelope-from <juergen@purtz.de>)
	id 1jFQBt-0005uZ-Uw
	for pgsql-hackers@postgresql.org; Fri, 20 Mar 2020 22:32:36 +0000
Received: from [192.168.178.43] ([77.190.92.158]) by mrelayeu.kundenserver.de
 (mreue010 [212.227.15.129]) with ESMTPSA (Nemesis) id
 1MfHUx-1jmrSL09MZ-00gnPy; Fri, 20 Mar 2020 23:32:26 +0100
From: =?UTF-8?Q?J=c3=bcrgen_Purtz?= <juergen@purtz.de>
Subject: Re: Add A Glossary
To: Justin Pryzby <pryzby@telsasoft.com>,
 Alvaro Herrera <alvherre@2ndquadrant.com>
Cc: Corey Huinker <corey.huinker@gmail.com>,
 Roger Harkavy <rogerharkavy@gmail.com>, pgsql-hackers@postgresql.org,
 Fabien COELHO <coelho@cri.ensmp.fr>, Michael Paquier <michael@paquier.xyz>
References: 
 <CADkLM=fwtE-TCU7sRnvaE74z12kOp_A+CdUwMr7aZt39pXbh6A@mail.gmail.com>
 <20200320001122.GA19602@alvherre.pgsql>
 <20200320195841.GA13662@telsasoft.com>
Message-ID: <64b49f34-eaf6-6de2-e951-0eb8d4afabc2@purtz.de>
Date: Fri, 20 Mar 2020 23:32:25 +0100
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: <20200320195841.GA13662@telsasoft.com>
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 8bit
Content-Language: en-US
X-Provags-ID: V03:K1:Fz311eVbHx7eGaR6M0jVuiULfxBwCqEmFVZs/7n3D4Oa0OVdaNk
 lx5nwBSykTDiXdcejwmAdTB4puswpuYJeiDFylnjcCh224Cp7YcHSlATERInGOFCfrs2YTJ
 fSMhdfgdmwc+uk6sK4voxseJLmqHq84iXaYSPMtCWnMiGxtC0HglqLU8d3gD85Aa8VUFrFM
 92+Nve+++DgadWEl6kR/w==
X-Spam-Flag: NO
X-UI-Out-Filterresults: notjunk:1;V03:K0:ZKfJqITmkoM=:viOR88o/MkYvhpJfhaxbe/
 wqxu878AM9CT4P/AuJOY0uG/FT+GFiDJp+46kQQBzmsiKrvzoIJd3jPEYzInv+/T20k8Mqbgq
 0RnJPriMKliEu/LyPqGInV0mRjHxSFvnkDGGh8PZ2BqCEnjzutYpFdind6o/aZBkE4UAi7Bks
 vQtEr0aihYSOvIDtvPfk44+EndqiAqaQzor8zfhb70lJRN+P+VoDTL5HtILud3fDBz64Brd/b
 eBjKmeRs0eO/DS1sINaAXEslRfS7fZRLwjH/AbIFtgTk8j+K+HSaQPo8D7tCVBWYH/gLi4ivv
 PmPdfFLvpMbGxx/He3aGIkloeJ5uEBF2yq+H8uwKSwWN4xH2rp0TyeRzjk8rcRX+UtCTE8TTA
 8FIwgQDVoRUDyP02HwCjxAjIhR99cj0s8+vRwvLIK12nSyHSFA/gzvGPOS1ldKgXCBuT6ebor
 csE6J/ZgdyUoVYGJaXEVdhWmq3URcS2a208/qV9yH7nqBMiTK6XT+TeIAGSlCpvLHekwJW+lv
 N4IAK1kRz5hVS3k6AjUqum0ToD3o9iToY4ZcZoIisKQqYjMM+zBMARgyOgQ6h5oOGfIDHap26
 ymMrKRkUkezIkRVNfTZOCEFODC/F9t61Pv7G/2vJZY2C46oxeTzocNvjlyb072PtX6dKwZRXM
 8NkPq659EdogFmIEwLHRAeSfSNILo4CBS6Z4E2NBaxR9cejIm+NHTnwbk6AO3fNaa30+lYT6k
 RoGmuLcuZCpqT1mmmmuSSxlEGAE3tXIfnvy1jyeGmkzkSZhe9rTnqpCCPpHoxlzOZ61pWf1fb
 aS8N2lu2rUwqokIwN+iDiPqOSHzrmqBwHuHBmzTlO8QZDcr8qUFd2XJ8u2PD35FZikT8qnn
List-Id: <pgsql-hackers.lists.postgresql.org>
List-Help: <https://lists.postgresql.org/manage/>
List-Subscribe: <https://lists.postgresql.org/manage/>
List-Post: <mailto:pgsql-hackers@lists.postgresql.org>
List-Owner: <mailto:pgsql-hackers-owner@lists.postgresql.org>
List-Archive: <https://www.postgresql.org/list/pgsql-hackers>
Precedence: bulk


On 20.03.20 20:58, Justin Pryzby wrote:
> On Thu, Mar 19, 2020 at 09:11:22PM -0300, Alvaro Herrera wrote:
>> +    <glossterm>Aggregate</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      To combine a collection of data values into a single value, whose
>> +      value may not be of the same type as the original values.
>> +      <glossterm>Aggregate</glossterm> <glossterm>Functions</glossterm>
>> +      combine multiple <glossterm>Rows</glossterm> that share a common set
>> +      of values into one <glossterm>Row</glossterm>, which means that the
>> +      only data visible in the values in common, and the aggregates of the
> IS the values in common ?
> (or, "is the shared values")
>
>> +    <glossterm>Analytic</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      A <glossterm>Function</glossterm> whose computed value can reference
>> +      values found in nearby <glossterm>Rows</glossterm> of the same
>> +      <glossterm>Result Set</glossterm>.
>> +    <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.


>> +    <glossterm>Atomic</glossterm>
> ..
>> +     <para>
>> +      In reference to an operation: An event that cannot be completed in
>> +      part: it must either entirely succeed or entirely fail. A series of
> Can you say: "an action which is not allowed to partially succed and then fail,
> ..."
>
>> +    <glossterm>Autovacuum</glossterm>
> Say autovacuum process ?
>
>> +    <glossdef>
>> +     <para>
>> +      Processes that remove outdated <acronym>MVCC</acronym>
> I would say "A set of processes that remove..."
>
>> +      <glossterm>Records</glossterm> of the <glossterm>Heap</glossterm> and
> I'm not sure, can you say "tuples" ?


This concerns the upcomming MVCC terms. We need a linguistic distinction 
between the different versions of 'records' or 'tuples'. In my 
understanding the term 'tuple' is nearer to a logical construct 
(relational algebra) and a 'record' some concrete implementation on 
disc. Therefor I prefer 'record' in this context.


>> +    <glossterm>Backend Process</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      Processes of an <glossterm>Instance</glossterm> which act on behalf of
> Say DATABASE instance


-1: The term 'database' is used inflationary. We shall restrict it to a 
few cases.


>> +    <glossterm>Backend Server</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      See <glossterm>Instance</glossterm>.
> same
>
>> +    <glossterm>Background Worker</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      Individual processes within an <glossterm>Instance</glossterm>, which
> same
>
>> +      run system- or user-supplied code. Typical use cases are processes
>> +      which handle parts of an <acronym>SQL</acronym> query to take
>> +      advantage of parallel execution on servers with multiple
>> +      <acronym>CPUs</acronym>.
> I would say "A typical use case is"
+1
>> +    <glossterm>Background Writer</glossterm>
> Add "process" ?
>
>> +    <glossdef>
>> +     <para>
>> +      Writes continuously dirty pages from <glossterm>Shared
> Say "Continuously writes"
+1
>> +      Memory</glossterm> to the file system. It starts periodically, but
> Hm, maybe "wakes up periodically"
+1
>> +    <glossterm>Cast</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      A conversion of a <glossterm>Datum</glossterm> from its current data
>> +      type to another data type.
> maybe just say
> A conversion of a <glossterm>Datum</glossterm> another data type.
>
>> +    <glossterm>Catalog</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      The <acronym>SQL</acronym> standard uses this standalone term to
>> +      indicate what is called a <glossterm>Database</glossterm> in
>> +      <productname>PostgreSQL</productname>'s terminology.
> Maybe remove "standalone" ?
>
>> +    <glossterm>Checkpointer</glossterm>
> Process
>
>> +      A process that writes dirty pages and <glossterm>WAL
>> +      Records</glossterm> to the file system and creates a special
> Does the chckpointer actually write WAL ?


YES, not only WAL Writer.


>> +      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.
> collected or written?
>
> I would say:
>> +      A checkpoint is usually initiated by
>> +      a specified amount of time having passed, or
>> +      a certain volume of records having been written.


+-0


>> +    <glossterm>Checkpoint</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      A <link linkend="sql-checkpoint"> Checkpoint</link> is a point in time
> Extra space
>
>> +   <glossentry id="glossary-connection">
>> +    <glossterm>Connection</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      A <acronym>TCP/IP</acronym> or socket line for inter-process
> I don't know if I've ever heard the phase "socket line"
> I guess you mean a unix socket.


+1


>> +    <glossterm>Constraint</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      A concept of restricting the values of data allowed within a
>> +      <glossterm>Table</glossterm>.
> Just say: "A restriction on the values..."?
>
>> +    <glossterm>Data Area</glossterm>
> Remove this ?  I've never heard this phrase before.


grep on *.sgml delivers 4 occurrences.


>> +    <glossdef>
>> +     <para>
>> +      The base directory on the filesystem of a
>> +      <glossterm>Server</glossterm> that contains all data files and
>> +      subdirectories associated with a <glossterm>Cluster</glossterm> with
>> +      the exception of tablespaces. The environment variable
> Should add an entry for "tablespace".


+1


>> +    <glossterm>Datum</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      The internal representation of a <acronym>SQL</acronym> data type.
> I'm not sure if should use "a SQL" or "an SQL", but not both.


grep | wc delivers 106 occurrences for "an SQL" and 63 for "a SQL". It 
depends on how people pronounce the term SQL: "an esquel" or "a sequel".


>> +    <glossterm>Delete</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      A <acronym>SQL</acronym> command whose purpose is to remove
> just say "which removes"


+1


>> +   <glossentry id="glossary-file-segment">
>> +    <glossterm>File Segment</glossterm>
>> +    <glossdef>
>> +     <para>
>> +       If a heap or index file grows in size over 1 GB, it will be split
> 1GB is the default "segment size", which you should define.


???


>> +   <glossentry id="glossary-foreign-data-wrapper">
>> +    <glossterm>Foreign Data Wrapper</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      A means of representing data that is not contained in the local
>> +      <glossterm>Database</glossterm> as if were in local
>> +      <glossterm>Table</glossterm>(s).
> I'd say:
>
> + A means of representing data as a <glossterm>Table</glossterm>(s) even though
> + it is not contained in the local <glossterm>Database</glossterm>
>
>
>> +   <glossentry id="glossary-foreign-key">
>> +    <glossterm>Foreign Key</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      A type of <glossterm>Constraint</glossterm> defined on one or more
>> +      <glossterm>Column</glossterm>s in a <glossterm>Table</glossterm> which
>> +      requires the value in those <glossterm>Column</glossterm>s to uniquely
>> +      identify a <glossterm>Row</glossterm> in the specified
>> +      <glossterm>Table</glossterm>.
> An FK doesn't require the values in its table to be unique, right ?
> I'd say something like: "..which enforces that the values in those Columns are
> also present in an(other) table."
> Reference Referential Integrity?
>
>> +    <glossterm>Function</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      Any pre-defined transformation of data. Many
>> +      <glossterm>Functions</glossterm> are already defined within
>> +      <productname>PostgreSQL</productname> itself, but can also be
>> +      user-defined.
> I would remove "pre-", since you mentioned that it can be user-defined.
>
>> +    <glossterm>Global SQL Object</glossterm>
>> +    <glossdef>
>> +     <para>
>> +     <!-- FIXME -->
>> +      Not all <glossterm>SQL Objects</glossterm> belong to a certain
>> +      <glossterm>Schema</glossterm>. Some belong to the complete
>> +      <glossterm>Database</glossterm>, or even to the complete
>> +      <glossterm>Cluster</glossterm>. These are referred to as
>> +      <glossterm>Global SQL Objects</glossterm>. Collations and Extensions
>> +      such as <glossterm>Foreign Data Wrappers</glossterm> reside at the
>> +      <glossterm>Database</glossterm> level; <glossterm>Database</glossterm>
>> +      names, <glossterm>Roles</glossterm>,
>> +      <glossterm>Tablespaces</glossterm>, <glossterm>Replication</glossterm>
>> +      origins, and subscriptions for logical
>> +      <glossterm>Replication</glossterm> at the
>> +      <glossterm>Cluster</glossterm> level.
> I think "complete" is the wrong world.
> I would say:
> "An object which is not specific to a given database, but instead shared across
> the entire Cluster".


This phrase seems to be too simple. We must differentiate between the 
different levels: schema, database, cluster. Possibly someone finds a 
better phrase.


>> +   <glossentry id="glossary-grant">
>> +    <glossterm>Grant</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      A <acronym>SQL</acronym> command that is used to enable
> I'd say "allow"
>
>> +   <glossentry id="glossary-heap">
>> +    <glossterm>Heap</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      Contains the original values of <glossterm>Row</glossterm> attributes
> I'm not sure what "original" means here ?


Yes, this may be misleading. I want to express, that values are stored 
in the heap (the 'original') and possibly repeated as a key in an index.


>> +      (i.e. the data). The <glossterm>Heap</glossterm> is realized within
>> +      <glossterm>Database</glossterm> files and mirrored in
>> +      <glossterm>Shared Memory</glossterm>.
> I wouldn't say mirrored, and probably just remove at least the part after "and".


+-0


>> +   <glossentry id="glossary-host">
>> +    <glossterm>Host</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      See <glossterm>Server</glossterm>.
> Or client.  Or proxy at some layer or other intermediate thing.  Maybe just
> remove this.


Sometimes the term "host" is used in a different meaning. Therefor we 
shall have this glossary entry for clarification that it shall be used 
only in the sense of a "server".


>> +   <glossentry id="glossary-index">
>> +    <glossterm>Index</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      A <glossterm>Relation</glossterm> that contains data derived from a
>> +      <glossterm>Table</glossterm> (or <glossterm>Relation</glossterm> such
>> +      as a <glossterm>Materialized View</glossterm>). It's internal
> Its
>
>> +      structure supports very fast retrieval of and access to the original
>> +      data.
>> +    <glossterm>Instance</glossterm>
>> +    <glossdef>
>> +     <para>
> ...
>> +     <para>
>> +      Many <glossterm>Instances</glossterm> can run on the same server as
>> +      long as they use different <acronym>IP</acronym> ports and manage
> I would say "as long as their TCP/IP ports or sockets don't conflict, and manage..."


+1


>> +    <glossterm>Join</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      A technique used with <command>SELECT</command> statements for
>> +      correlating data in one or more <glossterm>Relations</glossterm>.
> I would refer to this as a SQL keyword allowing to combine data from multiple
> relations.
>
>> +    <glossterm>Lock</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      A mechanism for one process temporarily preventing data from being
>> +      manipulated by any other process.
> I'd say:
>
> +      A mechanism by which a process protects simultaneous access to a resource
> +      by other processes.
>
> (I said "protects" since shared locks don't prevent all access, and it's easier
> than explaining "unsafe access").
>
>
>> +   <glossentry id="glossary-log-file">
>> +    <glossterm>Log File</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      <link linkend="logfile-maintenance">LOG files</link> contain readable
>> +      text lines about serious and non-serious events, e.g.: use of wrong
>> +      password, long-running queries, ... .
> Serious and non-serious?


ok, can be removed: 'events' only.


>> +    <glossterm>Log Writer</glossterm>
> process
>
>> +    <glossdef>
>> +     <para>
>> +      If activated and parameterized, the
> I don't know what parameterized means here


ok, unnecessary term. (There are parameters for the Log Writer process 
in the config file.)


>> +      <link linkend="runtime-config-logging">Log Writer</link> process
>> +      writes information about database events into the current
>> +      <glossterm>Log file</glossterm>. When reaching certain time- or
>> +      volume-dependent criterias, he <!-- FIXME "he"? --> creates a new
> I think criteria is the plural..


+1


>> +    <glossterm>Log Record</glossterm>
> Can we remove this ?
> Couple releases ago, "pg_xlog" was renamed to pg_wal.
> I'd prefer to avoid defining something called "Log Record" about WAL that's
> right next to text logs.


"... that's right next to text logs."  This is the problem, which shall 
be clarified. The rename of the directory does not affect the records 
which are written into the WAL files or are used for replication. The 
term "log record" is used in the documentation as well as in error messages.


>> +    <glossterm>Logged</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      A <glossterm>Table</glossterm> is considered
>> +      <glossterm>Logged</glossterm> if changes to it are sent to the
>> +      <glossterm>WAL Log</glossterm>. By default, all regular
>> +      <glossterm>Tables</glossterm> are <glossterm>Logged</glossterm>. A
>> +      <glossterm>Table</glossterm> can be speficied as unlogged either at
>> +      creation time or via the <command>ALTER TABLE</command> command. The
>> +      primary use of unlogged <glossterm>Tables</glossterm> is for storing
>> +      transient work data that must be shared across processes, but with a
>> +      final result stored in logged <glossterm>Tables</glossterm>.
>> +      <glossterm>Temporary Tables</glossterm> are always unlogged.
>> +     </para>
>> +    </glossdef>
>> +   </glossentry>
> Maybe it's be better to define "unlogged", since 1) logged is the default; and
> 2) it's right next to text logs.
>
>> +    <glossterm>Master</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      When two or more <glossterm>Databases</glossterm> are linked via
>> +      <glossterm>Replication</glossterm>, the <glossterm>Server</glossterm>
>> +      that is considered the authoritative source of information is called
>> +      the <glossterm>Master</glossterm>.
> I think it'd actually be the <<instance>> which is authoritative, in case they're
> running on the same <<Server>>


In this phase of the glossary we shall avoid the discussion about 
master/slave vs. primary/secondary. Some weeks ago we have seen many 
contributions without a clear result. In one of the next phases of the 
glossary we shall discuss all terms concerning replication separately.


>> +   <glossentry id="glossary-materialized">
>> +    <glossterm>Materialized</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      The act of storing information rather than just the means of accessing
> remove "means of" ?
>
>> +      the information. This term is used in <glossterm>Materialized
>> +      Views</glossterm> meaning that the data derived from the
>> +      <glossterm>View</glossterm> is actually stored on disk separate from
> separately
>
>> +      the sources of that data. When the term
>> +      <glossterm>Materialized</glossterm> is used in speaking about
>> +      mulit-step queries, it means that the data of a given step is stored
> multi
>
>> +      (in memory, but that storage may spill over onto disk).
>> +     </para>
>> +    </glossdef>
>> +   </glossentry>
>> +
>> +   <glossentry id="glossary-materialized-view">
>> +    <glossterm>Materialized View</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      A <glossterm>Relation</glossterm> that is defined in the same way that
>> +      a <glossterm>View</glossterm> is, but it stores data in the same way
> change "it stores" to stores
>
>> +   <glossentry id="glossary-partition">
>> +    <glossterm>Partition</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      <!-- FIXME should this use the style used in "atomic"? -->
>> +      a) A <glossterm>Table</glossterm> that can be queried independently by
>> +      its own name, but can also be queried via another
> just say "on its own" or "directly"
>
>> +      <glossterm>Table</glossterm>, a partitionend
> partitioned
> also, put it in parens, like "via another table (a partitioned table)..."
>
>> +      <glossterm>Table</glossterm>, which is a collection of
> Say "set" here since you later talk about "subsets" and sets.
>
>> +   <glossentry id="glossary-primary-key">
>> +    <glossterm>Primary Key</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      A special case of <glossterm>Unique Index</glossterm> defined on a
>> +      <glossterm>Table</glossterm> or other <glossterm>Relation</glossterm>
>> +      that also guarantees that all of the <glossterm>Attributes</glossterm>
>> +      within the <glossterm>Primary Key</glossterm> do not have
>> +      <glossterm>Null</glossterm> values.  As the name implies, there can be
>> +      only one <glossterm>Primary Key</glossterm> per
>> +      <glossterm>Table</glossterm>, though it is possible to have multiple
>> +      <glossterm>Unique Indexes</glossterm> that also have no
>> +      <glossterm>Null</glossterm>-capable <glossterm>Attributes</glossterm>.
> I would say "multiple >>unique indexes<< on >>attributes<< defined as not
> nullable.
>
>> +    <glossterm>Procedure</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      A defined set of instructions for manipulating data within a
>> +      <glossterm>Database</glossterm>. <glossterm>Procedure</glossterm> can
> "procedures" or "a procedure"
>
>> +    <glossterm>Record</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      See <link linkend="sql-revoke">Tupple</link>.
> Tupple is back.  And again below.
>
>> +      A single <glossterm>Row</glossterm> of a <glossterm>Table</glossterm>
>> +      or other Relation.
> I think it's commonly used to mean "an instance of a row" (in an MVCC sense),
> but maybe that's too much detail for here.
>
>> +    <glossterm>Referential Integrity</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      The means of restricting data in one <glossterm>Relation</glossterm>
> A means
>
>> +   <glossentry id="glossary-relation">
>> +    <glossterm>Relation</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      The generic term for all objects in a <glossterm>Database</glossterm>
> "A generic term for any object in a >>database<< that has a name and..."
>
>> +   <glossentry id="glossary-result-set">
>> +    <glossterm>Result Set</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      A data structure transmitted from a <glossterm>Server</glossterm> to
>> +      client program upon the completion of a <acronym>SQL</acronym>
>> +      command, usually a <command>SELECT</command> but it can be an
>> +      <command>INSERT</command>, <command>UPDATE</command>, or
>> +      <command>DELETE</command> command if the <literal>RETURNING</literal>
>> +      clause is specified.
> I'd remove everything in that sentence after "usually".
>
>> +    <glossterm>Revoke</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      A command to reduce access to a named set of
> s/reduce/prevent/ ?
>
>> +    <glossterm>Row</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      See <link linkend="sql-revoke">Tupple</link>.
> tuple
>
>> +   <glossentry id="glossary-savepoint">
>> +    <glossterm>Savepoint</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      A special mark (such as a timestamp) inside a
>> +      <glossterm>Transaction</glossterm>. Data modifications after this
>> +      point in time may be rolled back to the time of the savepoint.
> I don't think "timestamp" is a useful or accurate analogy for this.


+1


>> +    <glossterm>Schema</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      A <link linkend="ddl-schemas">schema</link> is a namespace for
>> +      <glossterm>SQL objects</glossterm>, which all reside in the same
>> +      <glossterm>database</glossterm>.  Each <glossterm>SQL
>> +      object</glossterm> must reside in exactly one
>> +      <glossterm>Schema</glossterm>.
>> +     </para>
>> +     <para>
>> +      In general, the names of <glossterm>SQL objects</glossterm> in the
>> +      schema are unique - even across different types of objects.  The lone
>> +      exception is the case of <glossterm>Unique</glossterm>
>> +      <glossterm>Constraint</glossterm>s, in which case there
>> +      <emphasis>must</emphasis> be a <glossterm>Unique Index</glossterm>
>> +      with the same name and <glossterm>Schema</glossterm> as the
>> +      <glossterm>Constraint</glossterm>.  There is no restriction on having
>> +      a name used in multiple <glossterm>Schema</glossterm>s.
> I think there's some confusion.  Constraints are not objects, right ?
>
> But, constraints do have an exception (not just unique constraints, though):
> the constraint is only unique on its table, not in its database/schema.
>
>      "pg_constraint_conrelid_contypid_conname_index" UNIQUE, btree (conrelid, contypid, conname) CLUSTER


Yes, you are right. But give me some time for a better suggestion.


>> +    <glossterm>Select</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      The command used to query a <glossterm>Database</glossterm>. Normally,
>> +      <command>SELECT</command>s are not expected to modify the
>> +      <glossterm>Database</glossterm> in any way, but it is possible that
>> +      <glossterm>Functions</glossterm> invoked within the query could have
>> +      side-effects that do modify data.  </para>
> I think there should be references to the sql-* pages for this and others.
>
>> +   <glossentry id="glossary-serializable">
>> +    <glossterm>Serializable</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      Transactions defined as <literal>SERIALIZABLE</literal> are unable to
>> +      see changes made within other transactions. In effect, for the
>> +      initializing session the entire <glossterm>Database</glossterm>
>> +      appears to be frozen duration such a
>> +      <glossterm>Transaction</glossterm>.
> Do you mean "for the duration of the >>Transaction<<"
>
>> +   <glossentry id="glossary-session">
>> +    <glossterm>Session</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      A <glossterm>Connection</glossterm> to the <glossterm>Database</glossterm>.
>> +     </para>
>> +     <para>
>> +      A description of the commands that were issued in the life cycle of a
>> +      particular <glossterm>Connection</glossterm> to the
>> +      <glossterm>Database</glossterm>.
> I'm not sure what this <para> means.
>
>> +    <glossterm>Sequence</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      <!-- sounds excessively complicated a definition -->
>> +      An <glossterm>Database</glossterm> object which represents the
> A not An
>
>> +      mathematical concept of a numerical integral sequence. It can be
>> +      thought of as a <glossterm>Table</glossterm> with exactly one
>> +      <glossterm>Row</glossterm> and one <glossterm>Column</glossterm>. The
>> +      value stored is known as the current value. A
>> +      <glossterm>Sequence</glossterm> has a defined direction (almost always
>> +      increasing) and an interval step (usually 1).  Whenever the
>> +      <literal>NEXTVAL</literal> pseudo-column of a
>> +      <glossterm>Sequence</glossterm> is accessed, the current value is moved
>> +      in the defined direction by the defined interval step, and that value
> say "given interval step"
>
>> +    <glossterm>Shared Memory</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      <acronym>RAM</acronym> which is used by the processes common to an
>> +      <glossterm>Instance</glossterm>. It mirrors parts of
>> +      <glossterm>Database</glossterm> files, provides an area for
>> +      <glossterm>WAL Records</glossterm>,
> Do we use shared_buffers for WAL ?


Yes, my information is that WAL records are part of the shared_buffers.


>> +   <glossentry id="glossary-table">
>> +    <glossterm>Table</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      A collection of <glossterm>Tuples</glossterm> (also known as
>> +      <glossterm>Rows</glossterm> or <glossterm>Records</glossterm>) having
>> +      a common data structure (the same number of
>> +      <glossterm>Attributes</glossterm>s, in the same order, having the same
> Attributes has two esses.
>
>> +      name and type per position). A <glossterm>Table</glossterm> is the
> I don't think you need to say here that the columns of a table all have the
> same type and order.


In my opinion this is an essential information.


>> +    <glossterm>Temporary Tables</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      <glossterm>Table</glossterm>s that exist either for the lifetime of a
>> +      <glossterm>Session</glossterm> or a
>> +      <glossterm>Transaction</glossterm>, as defined at creation time. The
> I would say "as specified at the time of its creation".
>
>> +    <glossterm>Transaction</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      A combination of one or more commands that must act as a single
> Remove "one or more"
>
>> +    <glossterm>Trigger</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      A <glossterm>Function</glossterm> which can be defined to execute
>> +      whenever a certain operation (<command>INSERT</command>,
>> +      <command>UPDATE</command>, or <command>DELTE</command>) is applied to
>> +      that <glossterm>Relation</glossterm>. A <glossterm>Trigger</glossterm>
> s/that/a/
>
>> +   <glossentry id="glossary-unique">
>> +    <glossterm>Unique</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      The condition of having no matching values in the same
> s/matching/duplicate/
>
>> +      <glossterm>Relation</glossterm>. Most often used in the concept of
> s/concept/context/
>
>> +   <glossentry id="glossary-update">
>> +    <glossterm>Update</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      A command used to modify <glossterm>Rows</glossterm> that already
> or 'may already'
>
>> +    <glossterm>WAL File</glossterm>
> ...
>> +     <para>
>> +      The sequence of <glossterm>WAL Records</glossterm> in combination with
>> +      the sequence of <glossterm>WAL Files</glossterm> represents the
> Remove "in combination with the sequence of >WAL Files<"
>
>> +    <glossentry id="glossary-wal-log">
>> +    <glossterm>WAL Log</glossterm>
> Can you just say WAL or "write-ahead log".


Sometimes the term "WAL log" is used in the documentation. But the 
preferred term is "WAL file". This glossary entry does nothing but 
points to the preferred term, which indicates that he shall be avoided 
in the future.


>> +    <glossdef>
>> +     <para>
>> +      A <glossterm>WAL Record</glossterm> contains either new or changed
>> +      <glossterm>Heap</glossterm> or <glossterm>Index</glossterm> data or
>> +      information about a <command>COMMIT</command>,
>> +      <command>ROLLBACK</command>, <command>SAVEPOINT</command>, or
>> +      <glossterm>Checkpointer</glossterm> operation. WAL records use a
>> +      non-printabe binary format.
> non-printable
+1
> Or just remove it.
> Or just remove the sentence.
>
>> +   <glossterm>WAL Writer</glossterm>
> process
>
>> +   <glossentry id="glossary-window-function">
>> +    <glossterm>Window Function</glossterm>
>> +    <glossdef>
>> +     <para>
>> +      A type of <glossterm>Function</glossterm> similar to an
>> +      <glossterm>Aggregate</glossterm> in that can derive its value from a
> in that IT
>
>> +      set of <glossterm>Rows</glossterm> in a <glossterm>Result
>> +      Set</glossterm>, but still retaining the original source data.


Kind regards, Jürgen