pg.ddx.io  pgsql-hackers@postgresql.org mailing list archive  

help / color / mirror / Atom feed

From: Alvaro Herrera <alvherre@2ndquadrant.com>
To: Justin Pryzby <pryzby@telsasoft.com>
To: Jürgen Purtz <juergen@purtz.de>
Cc: Erik Rijkers <er@xs4all.nl>
Cc: Laurenz Albe <laurenz.albe@cybertec.at>
Cc: Fabien COELHO <coelho@cri.ensmp.fr>
Cc: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
Cc: Corey Huinker <corey.huinker@gmail.com>
Cc: Roger Harkavy <rogerharkavy@gmail.com>
Cc: pgsql-hackers@postgresql.org, Michael Paquier <michael@paquier.xyz>
Cc: Pg Docs <pgsql-docs@lists.postgresql.org>
Subject: Re: Add A Glossary
Date: Thu, 18 Jun 2020 19:51:13 -0400
Message-ID: <20200618235113.GA1137@alvherre.pgsql> (raw)
In-Reply-To: <292d6f42-e31c-bc73-6cfb-9083bc2c07fc@purtz.de> <20200617003349.GN20404@telsasoft.com>

On 2020-Jun-16, Justin Pryzby wrote:
> On Tue, Jun 16, 2020 at 08:09:26PM -0400, Alvaro Herrera wrote:

Thanks for the review.  I merged all your suggestions.  This one:

> >        Most local objects belong to a specific
> > +      <glossterm linkend="glossary-schema">schema</glossterm> in their
> > +      containing database, such as
> > +      <glossterm linkend="glossary-relation">all types of relations</glossterm>,
> > +      <glossterm linkend="glossary-function">all types of functions</glossterm>,
> 
> Maybe say: >Relations< (all types), and >Functions< (all types)

led me down not one but two rabbit holes; first I realized that
"functions" is an insufficient term since procedures should also be
included but weren't, so I had to add the more generic term "routine"
and then modify the definitions of all routine types to mix in well.  I
think overall the quality of these definitions is improved as a result.

I also felt the need to revise the definition of "relations", so I did
that too; this made me change the definition of resultset too.

On 2020-Jun-17, Jürgen Purtz wrote:

> +1, with two formal changes:
> 
> -  Rearrangement of term "Data page" to meet alphabetical order.

To forestall these ordering issues (look, another rabbit hole), I
grepped the file for all glossterms and sorted that under en_US rules,
then reordered the terms to match that.  Turns out there were several
other ordering mistakes.

git grep '<glossterm>'  | sed -e 's/<[^>]*>\([^<]*\)<[^>]*>/\1/' > orig
LC_COLLATE=en_US.UTF-8 sort orig > sorted

(Eliminating the tags is important, otherwise the sort uses the tags
themselves to disambiguate)

> 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"?

Yes, an oversight, thanks.

I also added TPS, because I had already written it.

-- 
Álvaro Herrera                https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

Attachments:

  [text/x-diff] glossary-2.patch (25.6K, ../20200618235113.GA1137@alvherre.pgsql/2-glossary-2.patch)
  download | inline diff:
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
index 25b03f3b37..5274feabba 100644
--- a/doc/src/sgml/glossary.sgml
+++ b/doc/src/sgml/glossary.sgml
@@ -23,7 +23,7 @@
   </glossentry>
 
   <glossentry id="glossary-aggregate">
-   <glossterm>Aggregate function</glossterm>
+   <glossterm>Aggregate function (routine)</glossterm>
    <glossdef>
     <para>
      A <glossterm linkend="glossary-function">function</glossterm> that
@@ -39,6 +39,11 @@
    </glossdef>
   </glossentry>
 
+  <glossentry>
+   <glossterm>Analytic function</glossterm>
+   <glosssee otherterm="glossary-window-function" />
+  </glossentry>
+
   <glossentry id="glossary-analyze">
    <glossterm>Analyze (operation)</glossterm>
    <glossdef>
@@ -57,11 +62,6 @@
    </glossdef>
   </glossentry>
 
-  <glossentry>
-   <glossterm>Analytic function</glossterm>
-   <glosssee otherterm="glossary-window-function" />
-  </glossentry>
-
   <glossentry id="glossary-atomic">
    <glossterm>Atomic</glossterm>
    <glossdef>
@@ -389,40 +389,33 @@
    <glosssee otherterm="glossary-data-directory" />
   </glossentry>
 
-  <glossentry id="glossary-data-directory">
-   <glossterm>Data directory</glossterm>
+  <glossentry id="glossary-database">
+   <glossterm>Database</glossterm>
    <glossdef>
     <para>
-     The base directory on the filesystem of a
-     <glossterm linkend="glossary-server">server</glossterm> that contains all
-     data files and subdirectories associated with an
-     <glossterm linkend="glossary-instance">instance</glossterm> (with the
-     exception of <glossterm linkend="glossary-tablespace">tablespaces</glossterm>).
-     The environment variable <literal>PGDATA</literal> is commonly used to
-     refer to the
-     <glossterm linkend="glossary-data-directory">data directory</glossterm>.
-    </para>
-    <para>
-     An <glossterm linkend="glossary-instance">instance</glossterm>'s storage
-     space comprises the data directory plus any additional tablespaces.
+     A named collection of
+     <glossterm linkend="glossary-sql-object">local SQL objects</glossterm>.
     </para>
     <para>
      For more information, see
-     <xref linkend="storage-file-layout"/>.
+     <xref linkend="manage-ag-overview"/>.
     </para>
    </glossdef>
   </glossentry>
 
-  <glossentry id="glossary-database">
-   <glossterm>Database</glossterm>
+  <glossentry id="glossary-db-cluster">
+   <glossterm>Database cluster</glossterm>
    <glossdef>
     <para>
-     A named collection of
-     <glossterm linkend="glossary-sql-object">SQL objects</glossterm>.
+     A collection of databases and global SQL objects,
+     and their common static and dynamic metadata.
+     Sometimes referred to as a
+     <firstterm>cluster</firstterm>.
     </para>
     <para>
-     For more information, see
-     <xref linkend="manage-ag-overview"/>.
+     In <productname>PostgreSQL</productname>, the term
+     <firstterm>cluster</firstterm> is also sometimes used to refer to an instance.
+     (Don't confuse this term with the SQL command <command>CLUSTER</command>.)
     </para>
    </glossdef>
   </glossentry>
@@ -432,6 +425,31 @@
    <glosssee otherterm="glossary-instance" />
   </glossentry>
 
+  <glossentry id="glossary-data-directory">
+   <glossterm>Data directory</glossterm>
+   <glossdef>
+    <para>
+     The base directory on the filesystem of a
+     <glossterm linkend="glossary-server">server</glossterm> that contains all
+     data files and subdirectories associated with a
+     <glossterm linkend="glossary-db-cluster">database cluster</glossterm>
+     (with the exception of
+     <glossterm linkend="glossary-tablespace">tablespaces</glossterm>,
+     and optionally <glossterm linkend="glossary-wal">WAL</glossterm>).
+     The environment variable <literal>PGDATA</literal> is commonly used to
+     refer to the data directory.
+    </para>
+    <para>
+     A <glossterm linkend="glossary-db-cluster">cluster</glossterm>'s storage
+     space comprises the data directory plus any additional tablespaces.
+    </para>
+    <para>
+     For more information, see
+     <xref linkend="storage-file-layout"/>.
+    </para>
+   </glossdef>
+  </glossentry>
+
   <glossentry id="glossary-data-page">
    <glossterm>Data page</glossterm>
    <glossdef>
@@ -578,7 +596,7 @@
   </glossentry>
 
   <glossentry id="glossary-foreign-table">
-   <glossterm>Foreign table</glossterm>
+   <glossterm>Foreign table (relation)</glossterm>
    <glossdef>
     <para>
      A <glossterm linkend="glossary-relation">relation</glossterm> which appears to have
@@ -631,12 +649,20 @@
   </glossentry>
 
   <glossentry id="glossary-function">
-   <glossterm>Function</glossterm>
+   <glossterm>Function (routine)</glossterm>
    <glossdef>
     <para>
-     Any defined transformation of data. Many functions are already defined
-     within <productname>PostgreSQL</productname> itself, but user-defined
-     ones can also be added.
+     A type of routine that receives zero or more arguments, returns zero or more
+     output values, and is constrained to run within one transaction.
+     Functions are invoked as part of a query, for example via
+     <command>SELECT</command>.
+     Certain functions can return
+     <glossterm linkend="glossary-result-set">sets</glossterm>; those are
+     called <firstterm>set-returning functions</firstterm>.
+    </para>
+    <para>
+     Functions can also be used for
+     <glossterm linkend="glossary-trigger">triggers</glossterm> to invoke.
     </para>
     <para>
      For more information, see
@@ -689,13 +715,12 @@
   </glossentry>
 
   <glossentry id="glossary-index">
-   <glossterm>Index</glossterm>
+   <glossterm>Index (relation)</glossterm>
    <glossdef>
     <para>
      A <glossterm linkend="glossary-relation">relation</glossterm> that contains
      data derived from a <glossterm linkend="glossary-table">table</glossterm>
-     (or <glossterm linkend="glossary-relation">relation</glossterm> types
-     such as a <glossterm linkend="glossary-materialized-view">materialized view</glossterm>).
+     or <glossterm linkend="glossary-materialized-view">materialized view</glossterm>.
      Its internal structure supports fast retrieval of and access to the original
      data.
     </para>
@@ -724,14 +749,12 @@
    <glossterm>Instance</glossterm>
    <glossdef>
     <para>
-     A set of databases and accompanying global SQL objects that are stored in
-     the same <glossterm linkend="glossary-data-directory">data directory</glossterm>
-     in a single <glossterm linkend="glossary-server">server</glossterm>.
-     If running, one
+     A group of backend and auxiliary processes that communicate using
+     a common shared memory area.  One 
      <glossterm linkend="glossary-postmaster">postmaster process</glossterm>
-     manages a group of backend and auxiliary processes that communicate
-     using a common <glossterm linkend="glossary-shared-memory">shared memory</glossterm>
-     area.  Many instances can run on the same
+     manages the instance; one instance manages exactly one
+     <glossterm linkend="glossary-db-cluster">database cluster</glossterm>
+     with all its databases.  Many instances can run on the same
      <glossterm linkend="glossary-server">server</glossterm>
      as long as their <acronym>TCP</acronym> ports do not conflict.
     </para>
@@ -739,14 +762,10 @@
      The instance handles all key features of a <acronym>DBMS</acronym>:
      read and write access to files and shared memory,
      assurance of the <acronym>ACID</acronym> properties,
-     <glossterm linkend="glossary-connection">connections</glossterm> to client processes,
+     <glossterm linkend="glossary-connection">connections</glossterm> to
+     <glossterm linkend="glossary-client">client processes</glossterm>,
      privilege verification, crash recovery, replication, etc.
     </para>
-    <para>
-     In <productname>PostgreSQL</productname>, the term
-     <firstterm>cluster</firstterm> is also sometimes used to refer to an instance.
-     (Don't confuse this term with the SQL command <command>CLUSTER</command>.)
-    </para>
    </glossdef>
   </glossentry>
 
@@ -769,8 +788,10 @@
    <glossterm>Join</glossterm>
    <glossdef>
     <para>
-     An <acronym>SQL</acronym> keyword used in <command>SELECT</command> statements for
-     combining data from multiple <glossterm linkend="glossary-relation">relations</glossterm>.
+     An operation and <acronym>SQL</acronym> keyword used in
+     <glossterm linkend="glossary-query">queries</glossterm>
+     for combining data from multiple
+     <glossterm linkend="glossary-relation">relations</glossterm>.
     </para>
    </glossdef>
   </glossentry>
@@ -781,10 +802,10 @@
     <para>
      A means of identifying a <glossterm linkend="glossary-tuple">row</glossterm> within a
      <glossterm linkend="glossary-table">table</glossterm> or
-     <glossterm linkend="glossary-relation">relation</glossterm> by
+     other <glossterm linkend="glossary-relation">relation</glossterm> by
      values contained within one or more
      <glossterm linkend="glossary-attribute">attributes</glossterm>
-     in that table.
+     in that relation.
     </para>
    </glossdef>
   </glossentry>
@@ -813,15 +834,6 @@
    </glossdef>
   </glossentry>
 
-  <glossentry id="glossary-log-record">
-   <glossterm>Log record</glossterm>
-    <glossdef>
-     <para>
-      Archaic term for a <glossterm linkend="glossary-wal-record">WAL record</glossterm>.
-     </para>
-    </glossdef>
-  </glossentry>
-
   <glossentry id="glossary-logged">
    <glossterm>Logged</glossterm>
    <glossdef>
@@ -855,6 +867,15 @@
    </glossdef>
   </glossentry>
 
+  <glossentry id="glossary-log-record">
+   <glossterm>Log record</glossterm>
+    <glossdef>
+     <para>
+      Archaic term for a <glossterm linkend="glossary-wal-record">WAL record</glossterm>.
+     </para>
+    </glossdef>
+  </glossentry>
+
   <glossentry>
    <glossterm>Master (server)</glossterm>
    <glosssee otherterm="glossary-primary-server" />
@@ -883,12 +904,13 @@
   </glossentry>
 
   <glossentry id="glossary-materialized-view">
-   <glossterm>Materialized view</glossterm>
+   <glossterm>Materialized view (relation)</glossterm>
    <glossdef>
     <para>
      A <glossterm linkend="glossary-relation">relation</glossterm> that is
-     defined in the same way that a <glossterm linkend="glossary-view">view</glossterm>
-     is, but stores data in the same way that a
+     defined by a <command>SELECT</command> statement
+     (just like a <glossterm linkend="glossary-view">view</glossterm>),
+     but stores data in the same way that a
      <glossterm linkend="glossary-table">table</glossterm> does. It cannot be
      modified via <command>INSERT</command>, <command>UPDATE</command>, or
      <command>DELETE</command> operations.
@@ -949,6 +971,8 @@
     <para>
      One of several disjoint (not overlapping) subsets of a larger set.
     </para>
+   </glossdef>
+   <glossdef>
     <para>
      In reference to a
      <glossterm linkend="glossary-partitioned-table">partitioned table</glossterm>:
@@ -961,16 +985,18 @@
    </glossdef>
    <glossdef>
     <para>
-     In reference to a <glossterm linkend="glossary-window-function">window function</glossterm>:
+     In reference to a <glossterm linkend="glossary-window-function">window function</glossterm>
+     in a <glossterm linkend="glossary-query">query</glossterm>,
      a partition is a user-defined criterion that identifies which neighboring
-     <glossterm linkend="glossary-tuple">rows</glossterm> can be considered by the
-     function.
+     <glossterm linkend="glossary-tuple">rows</glossterm>
+     of the <glossterm linkend="glossary-result-set">query's result set</glossterm>
+     can be considered by the function.
     </para>
    </glossdef>
   </glossentry>
 
   <glossentry id="glossary-partitioned-table">
-   <glossterm>Partitioned table</glossterm>
+   <glossterm>Partitioned table (relation)</glossterm>
    <glossdef>
     <para>
      A <glossterm linkend="glossary-relation">relation</glossterm> that is
@@ -997,20 +1023,6 @@
    </glossdef>
   </glossentry>
 
-  <glossentry id="glossary-primary-server">
-   <glossterm>Primary (server)</glossterm>
-   <glossdef>
-    <para>
-     When two or more <glossterm linkend="glossary-database">databases</glossterm>
-     are linked via <glossterm linkend="glossary-replication">replication</glossterm>,
-     the <glossterm linkend="glossary-server">server</glossterm>
-     that is considered the authoritative source of information is called
-     the <firstterm>primary</firstterm>,
-     also known as a <firstterm>master</firstterm>.
-    </para>
-   </glossdef>
-  </glossentry>
-
   <glossentry id="glossary-primary-key">
    <glossterm>Primary key</glossterm>
    <glossdef>
@@ -1031,19 +1043,29 @@
    </glossdef>
   </glossentry>
 
+  <glossentry id="glossary-primary-server">
+   <glossterm>Primary (server)</glossterm>
+   <glossdef>
+    <para>
+     When two or more <glossterm linkend="glossary-database">databases</glossterm>
+     are linked via <glossterm linkend="glossary-replication">replication</glossterm>,
+     the <glossterm linkend="glossary-server">server</glossterm>
+     that is considered the authoritative source of information is called
+     the <firstterm>primary</firstterm>,
+     also known as a <firstterm>master</firstterm>.
+    </para>
+   </glossdef>
+  </glossentry>
+
   <glossentry id="glossary-procedure">
-   <glossterm>Procedure</glossterm>
+   <glossterm>Procedure (routine)</glossterm>
    <glossdef>
     <para>
-     A defined set of instructions for manipulating data within a
-     <glossterm linkend="glossary-database">database</glossterm>.
-     A <glossterm linkend="glossary-procedure">procedure</glossterm> can
-     be written in a variety of programming languages. They are
-     similar to <glossterm linkend="glossary-function">functions</glossterm>,
-     but are different in that they must be invoked via the <command>CALL</command>
-     command rather than the <command>SELECT</command> or <command>PERFORM</command>
-     commands, and they are allowed to make transactional statements such
+     A type of routine.
+     Their distinctive qualities are that they do not return values,
+     and that they are allowed to make transactional statements such
      as <command>COMMIT</command> and <command>ROLLBACK</command>.
+     They are invoked via the <command>CALL</command> command.
     </para>
     <para>
      For more information, see
@@ -1115,6 +1137,11 @@
      <glossterm linkend="glossary-index">indexes</glossterm> are all relations.
     </para>
     <para>
+     More generically, a relation is a set of tuples; for example,
+     the result of a query is also a relation.
+    </para>
+    <para>
+     In <productname>PostgreSQL</productname>,
      <firstterm>Class</firstterm> is an archaic synonym for
      <firstterm>relation</firstterm>.
     </para>
@@ -1155,16 +1182,23 @@
    <glossterm>Result set</glossterm>
    <glossdef>
     <para>
-     A data structure transmitted from a
-     <glossterm linkend="glossary-backend">backend process</glossterm> to
-     a <glossterm linkend="glossary-client">client</glossterm> upon the
-     completion of an <acronym>SQL</acronym>
-     command, usually a <command>SELECT</command> but it can be an
+     A <glossterm linkend="glossary-relation">relation</glossterm> transmitted
+     from a <glossterm linkend="glossary-backend">backend process</glossterm>
+     to a <glossterm linkend="glossary-client">client</glossterm> upon the
+     completion of an <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. The data structure consists of zero or more
-     <glossterm linkend="glossary-tuple">rows</glossterm> with the same ordered set of
-     <glossterm linkend="glossary-attribute">attributes</glossterm>.
+     clause is specified.
+    </para>
+    <para>
+     The fact that a result set is a relation means that a query can be used
+     in the definition of another query, becoming a
+     <firstterm>subquery</firstterm>.
+    </para>
+   </glossdef>
+   <glossdef>
+    <para>
     </para>
    </glossdef>
   </glossentry>
@@ -1216,6 +1250,27 @@
    </glossdef>
   </glossentry>
 
+  <glossentry id="glossary-routine">
+   <glossterm>Routine</glossterm>
+   <glossdef>
+    <para>
+     A defined set of instructions stored in the database system
+     that can be invoked for execution.
+     A routine can be written in a variety of programming
+     languages.  Routines can be
+     <glossterm linkend="glossary-function">functions</glossterm>
+     (including set-returning functions and
+     <glossterm linkend="glossary-trigger">trigger functions</glossterm>),
+     <glossterm linkend="glossary-aggregate">aggregates functions</glossterm>,
+     and <glossterm linkend="glossary-procedure">procedures</glossterm>.
+    </para>
+    <para>
+     Many routines are already defined within <productname>PostgreSQL</productname>
+     itself, but user-defined ones can also be added.
+    </para>
+   </glossdef>
+  </glossentry>
+
   <glossentry>
    <glossterm>Row</glossterm>
    <glosssee otherterm="glossary-tuple" />
@@ -1248,16 +1303,7 @@
      Each SQL object must reside in exactly one schema.
     </para>
     <para>
-     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.
-    </para>
-    <para>
-     All system-defined SQL objects reside in schema <literal>pg_catalog</literal>,
-     and commonly many user-defined SQL objects reside in the default schema
-     <literal>public</literal>,
-     but it is common and recommended that other schemas are created to hold
-     application-specific SQL objects.
+     All system-defined SQL objects reside in schema <literal>pg_catalog</literal>.
     </para>
    </glossdef>
    <glossdef>
@@ -1299,6 +1345,19 @@
    </glossdef>
   </glossentry>
 
+  <glossentry id="glossary-sequence">
+   <glossterm>Sequence (relation)</glossterm>
+   <glossdef>
+    <para>
+     A type of relation that is used to generate values.
+     Typically the generated values are sequential non-repeating numbers.
+     They are commonly used to generate surrogate
+     <glossterm linkend="glossary-primary-key">primary key</glossterm>
+     values.
+    </para>
+   </glossdef>
+  </glossentry>
+
 <!--  XXX should define all other isolation levels (and improve this definition)
   <glossentry id="glossary-serializable">
    <glossterm>Serializable (isolation level)</glossterm>
@@ -1339,19 +1398,6 @@
    </glossdef>
   </glossentry>
 
-  <glossentry id="glossary-sequence">
-   <glossterm>Sequence</glossterm>
-   <glossdef>
-    <para>
-     A type of relation that is used to generate values.
-     Typically the generated values are sequential non-repeating numbers.
-     They are commonly used to generate surrogate
-     <glossterm linkend="glossary-primary-key">primary key</glossterm>
-     values.
-    </para>
-   </glossdef>
-  </glossentry>
-
   <glossentry id="glossary-shared-memory">
    <glossterm>Shared memory</glossterm>
    <glossdef>
@@ -1378,33 +1424,43 @@
    </glossdef>
   </glossentry>
 
-  <glossentry>
-   <glossterm>Standby (server)</glossterm>
-   <glosssee otherterm="glossary-replica" />
-  </glossentry>
-
   <glossentry id="glossary-sql-object">
-   <glossterm>SQL Object</glossterm>
+   <glossterm>SQL object</glossterm>
     <glossdef>
      <para>
       Any object that can be created with a <command>CREATE</command>
       command.  Most objects are specific to one database, and are commonly
       known as <firstterm>local objects</firstterm>.
-      <glossterm linkend="glossary-role">Roles</glossterm>,
-      <glossterm linkend="glossary-tablespace">tablespaces</glossterm>,
-      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 <firstterm>global objects</firstterm>.
      </para>
      <para>
       Most local objects belong to a specific
-      <glossterm linkend="glossary-schema">schema</glossterm> in their containing database.
+      <glossterm linkend="glossary-schema">schema</glossterm> in their
+      containing database, such as
+      <glossterm linkend="glossary-relation">relations</glossterm> (all types),
+      <glossterm linkend="glossary-function">routines</glossterm> (all types),
+      data types, etc.
+      The name of such objects of the same type in the same schema
+      are enforced unique.
+     </para>
+     <para>
       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>.
-    </para>
+      The name of such objects of the same type are enforced unique
+      within the database.
+     </para>
+     <para>
+      Other object types, such as
+      <glossterm linkend="glossary-role">roles</glossterm>,
+      <glossterm linkend="glossary-tablespace">tablespaces</glossterm>,
+      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 <firstterm>global objects</firstterm>.
+      The names of such objects are enforced unique within the whole
+      database cluster.
+     </para>
     <para>
       For more information, see
       <xref linkend="manage-ag-overview"/>.
@@ -1421,6 +1477,11 @@
    </glossdef>
   </glossentry>
 
+  <glossentry>
+   <glossterm>Standby (server)</glossterm>
+   <glosssee otherterm="glossary-replica" />
+  </glossentry>
+
   <glossentry id="glossary-stats-collector">
    <glossterm>Stats collector</glossterm>
    <glossdef>
@@ -1489,8 +1550,8 @@
      which require storage beyond their definition in the
      <glossterm linkend="glossary-system-catalog">system catalog</glossterm>
      must belong to a single tablespace.
-     Initially, an instance contains a single usable tablespace which is
-     used as the default one for all SQL objects, called <literal>pg_default</literal>.
+     Initially, a database cluster contains a single usable tablespace which is
+     used as the default for all SQL objects, called <literal>pg_default</literal>.
     </para>
     <para>
      For more information, see
@@ -1577,6 +1638,18 @@
    </glossdef>
   </glossentry>
 
+  <glossentry id="glossary-tps">
+   <glossterm>Transactions per second (TPS)</glossterm>
+   <glossdef>
+    <para>
+     Average number of transactions that are executed per second,
+     totalled across all sessions active for a measured run.
+     This is used as a measure of the performance characteristics of
+     an instance.
+    </para>
+   </glossdef>
+  </glossentry>
+
   <glossentry id="glossary-trigger">
    <glossterm>Trigger</glossterm>
    <glossdef>
@@ -1818,28 +1891,32 @@
   </glossentry>
 
   <glossentry id="glossary-wal-writer">
-  <glossterm>WAL writer (process)</glossterm>
-  <glossdef>
-   <para>
-    A process that writes <glossterm linkend="glossary-wal-record">WAL records</glossterm>
-    from <glossterm linkend="glossary-shared-memory">shared memory</glossterm> to
-    <glossterm linkend="glossary-wal-file">WAL files</glossterm>.
-   </para>
-   <para>
-    For more information, see
-    <xref linkend="runtime-config-wal"/>.
-   </para>
-  </glossdef>
+   <glossterm>WAL writer (process)</glossterm>
+   <glossdef>
+    <para>
+     A process that writes <glossterm linkend="glossary-wal-record">WAL records</glossterm>
+     from <glossterm linkend="glossary-shared-memory">shared memory</glossterm> to
+     <glossterm linkend="glossary-wal-file">WAL files</glossterm>.
+    </para>
+    <para>
+     For more information, see
+     <xref linkend="runtime-config-wal"/>.
+    </para>
+   </glossdef>
   </glossentry>
 
   <glossentry id="glossary-window-function">
-   <glossterm>Window function</glossterm>
+   <glossterm>Window function (routine)</glossterm>
    <glossdef>
     <para>
-     A type of <glossterm linkend="glossary-function">function</glossterm> whose
-     result is based on values found in
-     <glossterm linkend="glossary-tuple">rows</glossterm> of the same
-     <glossterm linkend="glossary-partition">partition</glossterm>.
+     A type of <glossterm linkend="glossary-function">function</glossterm>
+     used in a <glossterm linkend="glossary-query">query</glossterm>
+     that applies to a <glossterm linkend="glossary-partition">partition</glossterm>
+     of the query's <glossterm linkend="glossary-result-set">result set</glossterm>;
+     the function's result is based on values found in
+     <glossterm linkend="glossary-tuple">rows</glossterm> of the same partition or frame.
+    </para>
+    <para>
      All <glossterm linkend="glossary-aggregate">aggregate functions</glossterm>
      can be used as window functions, but window functions can also be
      used to, for example, give ranks to each of the rows in the partition.
@@ -1857,8 +1934,8 @@
    <glossdef>
     <para>
      The journal that keeps track of the changes in the
-     <glossterm linkend="glossary-instance">instance</glossterm> as user- and
-     system-invoked operations take place.
+     <glossterm linkend="glossary-db-cluster">database cluster</glossterm>
+     as user- and system-invoked operations take place.
      It comprises many individual
      <glossterm linkend="glossary-wal-record">WAL records</glossterm> written
      sequentially to <glossterm linkend="glossary-wal-file">WAL files</glossterm>.

view thread (97+ messages)  latest in thread

Message-ID: <20200618235113.GA1137@alvherre.pgsql>
Permalink:  ../20200618235113.GA1137@alvherre.pgsql/
Also on:    postgresql.org/message-id/20200618235113.GA1137@alvherre.pgsql

copy link · copy postgr.es · copy git am

reply

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: pgsql-hackers@postgresql.org
  Cc: alvherre@2ndquadrant.com, pryzby@telsasoft.com, juergen@purtz.de, er@xs4all.nl, laurenz.albe@cybertec.at, coelho@cri.ensmp.fr, peter.eisentraut@2ndquadrant.com, corey.huinker@gmail.com, rogerharkavy@gmail.com, michael@paquier.xyz, pgsql-docs@lists.postgresql.org
  Subject: Re: Add A Glossary
  In-Reply-To: <20200618235113.GA1137@alvherre.pgsql>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox