public inbox for [email protected]
help / color / mirror / Atom feedAdd A Glossary
97+ messages / 12 participants
[nested] [flat]
* Add A Glossary
@ 2019-10-13 20:52 Corey Huinker <[email protected]>
0 siblings, 3 replies; 97+ messages in thread
From: Corey Huinker @ 2019-10-13 20:52 UTC (permalink / raw)
To: [email protected]
Attached is a v1 patch to add a Glossary to the appendix of our current
documentation.
I believe that our documentation needs a glossary for a few reasons:
1. It's hard to ask for help if you don't know the proper terminology of
the problem you're having.
2. Readers who are new to databases may not understand a few of the terms
that are used casually both in the documentation and in forums. This helps
to make our documentation a bit more useful as a teaching tool.
3. Readers whose primary language is not English may struggle to find the
correct search terms, and this glossary may help them grasp that a given
term has a usage in databases that is different from common English usage.
3b. If we are not able to find the resources to translate all of the
documentation into a given language, translating the glossary page would be
a good first step.
4. The glossary would be web-searchable, and draw viewers to the official
documentation.
5. adding link anchors to each term would make them cite-able, useful in
forum conversations.
A few notes about this patch:
1. It's obviously incomplete. There are more terms, a lot more, to add.
2. The individual definitions supplied are off-the-cuff, and should be
thoroughly reviewed.
3. The definitions as a whole should be reviewed by an actual tech writer
(one was initially involved but had to step back due to prior commitments),
and the definitions should be normalized in terms of voice, tone, audience,
etc.
4. My understanding of DocBook is not strong. The glossary vs glosslist tag
issue is a bit confusing to me, and I'm not sure if the glossary tag is
even appropriate for our needs.
5. I've made no effort at making each term an anchor, nor have I done any
CSS styling at all.
6. I'm not quite sure how to handle terms that have different definitions
in different contexts. Should that be two glossdefs following one
glossterm, or two separate def/term pairs?
Please review and share your thoughts.
Attachments:
[text/x-patch] 0001-add-glossary-page-with-sample-terms-and-definitions.patch (20.5K, 3-0001-add-glossary-page-with-sample-terms-and-definitions.patch)
download | inline diff:
From 343d5c18bf23f98341b510595e3e042e002242cb Mon Sep 17 00:00:00 2001
From: Corey Huinker <[email protected]>
Date: Sun, 13 Oct 2019 17:57:36 +0000
Subject: [PATCH] add glossary page with sample terms and definitions
---
doc/src/sgml/filelist.sgml | 1 +
doc/src/sgml/glossary.sgml | 618 ++++++++++++++++++++++++++++++++++++
doc/src/sgml/stylesheet.css | 2 +
3 files changed, 621 insertions(+)
create mode 100644 doc/src/sgml/glossary.sgml
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 3da2365ea9..504c8a6326 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -170,6 +170,7 @@
<!ENTITY limits SYSTEM "limits.sgml">
<!ENTITY acronyms SYSTEM "acronyms.sgml">
+<!ENTITY glossary SYSTEM "glossary.sgml">
<!ENTITY features-supported SYSTEM "features-supported.sgml">
<!ENTITY features-unsupported SYSTEM "features-unsupported.sgml">
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
new file mode 100644
index 0000000000..016eee2d76
--- /dev/null
+++ b/doc/src/sgml/glossary.sgml
@@ -0,0 +1,618 @@
+<!-- doc/src/sgml/glossary.sgml -->
+
+<appendix id="glossary">
+ <title>Glossary</title>
+
+ <para>
+ This is a list of terms and their in the context of <productname>PostgreSQL</productname> and databases in general.
+
+ <variablelist>
+
+ <varlistentry>
+ <term><glossaryterm>Aggregate</glossaryterm></term>
+ <listitem>
+ <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. Aggregate functions combine
+multiple rows that share a common set of values into one row, which means that
+the only data visible in the values in common, and the aggregates of the
+non-common data.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Analytic</glossaryterm></term>
+ <listitem>
+ <para>
+ A function whose computed value can reference values found in nearby rows
+of the same result set.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Atomic</glossaryterm></term>
+ <listitem>
+ <para>
+ In reference to the value of an Attribute or Datum: cannot be broken up
+into smaller components.
+ </para>
+ <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 SQL statements can
+be combined into a Transaction, and that transaction is said to be Atomic.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Attribute</glossaryterm></term>
+ <listitem>
+ <para>
+ A typed data element found within a Tuple or Relation or Table.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Cast</glossaryterm></term>
+ <listitem>
+ <para>
+ A conversion of a Datum from its current data type to another data type.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Check Constraint</glossaryterm></term>
+ <listitem>
+ <para>
+ A type of constraint defined on a relation which restricts the values
+allowed in one or more Attributes. The check constraint can make reference to
+any Attribute in the Relation, but cannot reference other rows of the same
+relation or other relations.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Column</glossaryterm></term>
+ <listitem>
+ <para>
+ An Attribute found in a Table or View.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Commit</glossaryterm></term>
+ <listitem>
+ <para>
+ The act of finalizing a Transaction within the database.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Concurrency</glossaryterm></term>
+ <listitem>
+ <para>
+ The concept that multiple independent operations can be happening within
+the database at the same time.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Constraint</glossaryterm></term>
+ <listitem>
+ <para>
+ A method of restricting the values of data allowed within a Table.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Datum</glossaryterm></term>
+ <listitem>
+ <para>
+ The internal representation of a SQL Datatype.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Delete</glossaryterm></term>
+ <listitem>
+ <para>
+ A SQL command whose purpose is to remove rows from a given Table or
+relation.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Foreign Data Wrapper</glossaryterm></term>
+ <listitem>
+ <para>
+ A means of representing data that is not contained in the local database
+as if were in local tables. With a Foreign Data Wrapper it is possible to define
+a Foreign Server and Foreign Tables.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Foreign Key</glossaryterm></term>
+ <listitem>
+ <para>
+ A type of Constraint defined on one or more columns in a Table which requires the
+value in those columns to uniquely identify a row in the specified table.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Foreign Server</glossaryterm></term>
+ <listitem>
+ <para>
+ A named collection of Foreign Tables which all use the same Foreign Data
+Wrapper and have other configured attributes in common.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Foreign Table</glossaryterm></term>
+ <listitem>
+ <para>
+ A relation which appears to have Rows and Columns like a regular Table,
+but when queried will instead forward the request for data through its Foreign
+Data Wrapper, which will return results structured according to the definition
+of the Foreign Table.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Function</glossaryterm></term>
+ <listitem>
+ <para>
+ Any pre-defined tranformation of data. Many functions are already defined
+within PostgreSQL itsel, but can also be user-defined.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Grant</glossaryterm></term>
+ <listitem>
+ <para>
+ A SQL command that is used to enable Users or Roles to access specific
+objects within the database.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Index</glossaryterm></term>
+ <listitem>
+ <para>
+ A relation that contains data derived from a Table (or Relation like a
+Materialized View) that stores the data in a way that makes specific values
+easier to retrieve.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Insert</glossaryterm></term>
+ <listitem>
+ <para>
+ A SQL command used to add new data into a Table.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Join</glossaryterm></term>
+ <listitem>
+ <para>
+ A Join is a technique used with Select statements for correlating data in
+one Data Set (usually a Table) with another.
+ TODO
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Key</glossaryterm></term>
+ <listitem>
+ <para>
+ A Key is a means of identifying a row within a Table or Relation by values
+contained within one or more Attributes in that Table.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Lock</glossaryterm></term>
+ <listitem>
+ <para>
+ A mechanism for one process temporarily preventing data from being
+manipulated by any other process.
+ TODO
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Logged</glossaryterm></term>
+ <listitem>
+ <para>
+ A table is considered Logged if changes to the table are send to the WAL
+log. By default, all regular tables are logged. A table can be speficied as
+unlogged either at creation time or via the ALTER TABLE command. The primary use
+of unlogged tables is for storing transient work data that must be shared across
+processes, but with a final result stored in logged tables. Temporary tables are
+always unlogged.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Master</glossaryterm></term>
+ <listitem>
+ <para>
+ When two or more databases are linked via replication, the server that is
+considered the authoritative source of information is called the Master.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Materialized</glossaryterm></term>
+ <listitem>
+ <para>
+ The act of storing information rather than just the means of accessing the
+information. This term is used in Materialized Views meaning that the data
+derived from the view is actually stored on disk separate from the sources of
+that data. When materialized is used in speaking about mulit-step queries, it
+means that the data of a given step is stored (in memory, but that storage may
+spill over onto disk)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Materialized View</glossaryterm></term>
+ <listitem>
+ <para>
+ A Relation that is defined in the same way that a View is, but it stores
+data in the same way that a Table does. it cannot be modified via INSERT,
+UPDATE, or DELETE operations.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Null</glossaryterm></term>
+ <listitem>
+ <para>
+ A concept of non-existence that is a central tenet of Relational Database
+Theory. It represents the absence of value.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Partition</glossaryterm></term>
+ <listitem>
+ <para>
+ A Table that can be queried independently by its own name, but can also be
+queried via another table, a partitioend table, which is a collection of
+sub-tables, each capable of holding one defined subset of information that does
+not overlap with any other table in the set of tables.
+ </para>
+ <para>
+ A defined boundary used in an Analytic function to identify which
+neighboring rows can be considered by the function for this particular row.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Primary Key</glossaryterm></term>
+ <listitem>
+ <para>
+ A Unique Index defined on a Table or other Relation that also guarantees
+that all of the Attributes within the Primary Key do not have null values.
+As the name implies, there can be only one Primary Key per table, though it is
+possible to have multiple Unique Indexes that also have no null-capable
+attributes.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Procedure</glossaryterm></term>
+ <listitem>
+ <para>
+ A defined set of instructions for manipulating data within a database.
+Procedures can be written in a variety of programming languages. They may appear
+like Functions but are different in that they must be invoked via the CALL
+command rather than the SELECT or PERFORM commands, and they are allowed to make
+transactional statements like COMMIT and ROLLBACK.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Record</glossaryterm></term>
+ <listitem>
+ <para>
+ A data structure that consists of one or more Attributes in a defined
+order.
+ <para>
+ A single row of a Table or other Relation.
+ </para>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Referential Integrity</glossaryterm></term>
+ <listitem>
+ <para>
+ The means of restricting data in one Relation such that it must have
+matching data in another Relation.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Relation</glossaryterm></term>
+ <listitem>
+ <para>
+ The generic term for all objects in a database that have a name and a
+list of attributes defined in a specific order. Tables, Views, Foreign Tables,
+Materialized Views and Indexes are all Relations.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Replica</glossaryterm></term>
+ <listitem>
+ <para>
+ 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 reasons for doing this
+are to allow for greater access to that data, and to maintain availability of
+the data in the even that the master becomes unavailable.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Revoke</glossaryterm></term>
+ <listitem>
+ <para>
+ A command to reduce access to a named set of database objects for a named
+list of users and Roles.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Role</glossaryterm></term>
+ <listitem>
+ <para>
+ A collection of access privileges to the database. Roles are themselves a
+privilege that can be granted to other roles. This is often done for convenience
+or to ensure completeness when multiple Users need the same privileges.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Rollback</glossaryterm></term>
+ <listitem>
+ <para>
+ A command to undo all of the operations performed since the beginning of a
+transaction.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Row</glossaryterm></term>
+ <listitem>
+ <para>
+ A tuple or record found within a Relation or a Result Set. This term is
+often used interchangably with Record and Tuple.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Schema</glossaryterm></term>
+ <listitem>
+ <para>
+ A named collection of database objects organized to facilitate clarity or
+security. Most often used like a namespace is used in programming languages.
+All objects belong to exactly one schema, most commonly "public", the default
+schema.
+ </para>
+ <para>
+ More generically, the term Schema is used to mean all data descriptions
+(table definitions, constraints, comments) for a given database.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Select</glossaryterm></term>
+ <listitem>
+ <para>
+ The 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Serializable</glossaryterm></term>
+ <listitem>
+ <para>
+ Database sessions in a transaction defined as SERIALIZABLE are unable to see changes made
+to the database by other sessions. In effect, the entire database appears to be
+frozen in time for the duration of the transaction.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Session</glossaryterm></term>
+ <listitem>
+ <para>
+ A connection to the database.
+ </para>
+ <para>
+ A description of the commands that were issued in the life cycle of a
+particular connection to the database.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Table</glossaryterm></term>
+ <listitem>
+ <para>
+ A collection of tuples (also known as rows or records) having a common data structure (the same number of columns, in the same order, having the same type). A table is the most common form of relation in <productname>PostgreSQL</productname>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Temporary</glossaryterm></term>
+ <listitem>
+ <para>
+ Temporary tables are tables that exist either for the lifetime of a
+Session or a Transaction, as defined at creation time. The data in them is not
+visible to other Sessions, and is not logged. Temporary tables are most often
+used to store intermediate data for a multi-step data transformation.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Transaction</glossaryterm></term>
+ <listitem>
+ <para>
+ A combination of one or more commands that must act as a single Atomic
+command: they all succeed or fail together, and their effects are not visible to
+other sessions until the transaction is complete.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Trigger</glossaryterm></term>
+ <listitem>
+ <para>
+ A function which can be defined to execute whenever a certain operation
+(Insert, Update, or Delete) is applied to that Relation. A trigger executes
+within the same transaction as the statement which invoked it, and if the
+function fails then the invoking statement also fails.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Tuple</glossaryterm></term>
+ <listitem>
+ <para>
+ A collection of Attributes in a fixed order. That order may be defined by
+the Table where the Tuple is found, in which case the Tuple is often called a
+Row or Record. It may also be defined by the structure of a Result Set.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Unique</glossaryterm></term>
+ <listitem>
+ <para>
+ The condition of having no matching values in the same Relation. Most
+often used in the concept of Unique Indexes.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Unlogged</glossaryterm></term>
+ <listitem>
+ <para>
+ A relation that is unlogged will not have changes reflected in the WAL
+log, which would enable those changes to be duplicated on a replica, and also
+enables the change to survive a database crash.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Update</glossaryterm></term>
+ <listitem>
+ <para>
+ A command used to modify rows that already exist in a specified table. It
+cannot create rows nor can it remove rows.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>User</glossaryterm></term>
+ <listitem>
+ <para>
+ A specific case of a Role that is entitled to access (log into) the
+database.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>User Mapping</glossaryterm></term>
+ <listitem>
+ <para>
+ The translation of user credentials in the local database to credentials
+in a remote data system defined by a Foreign Data Wrapper.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>View</glossaryterm></term>
+ <listitem>
+ <para>
+ A Relation that is defined by a Select Statement, but has no storage of its own. Any
+time a query references a View, the definition of the view is substituted into
+the query as if the user had typed that subquery instead of the name of the
+view.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><glossaryterm>Window Function</glossaryterm></term>
+ <listitem>
+ <para>
+ A type of function similar to an aggregate in that can derive its value
+from a set of rows in a result set, but still retaining the original source
+data.
+ </para>
+ </listitem>
+ </varlistentry>
+
+</appendix>
diff --git a/doc/src/sgml/stylesheet.css b/doc/src/sgml/stylesheet.css
index 1a66c789d5..e51752aca2 100644
--- a/doc/src/sgml/stylesheet.css
+++ b/doc/src/sgml/stylesheet.css
@@ -101,6 +101,8 @@ var { font-family: monospace; font-style: italic; }
/* Konqueror's standard style for ACRONYM is italic. */
acronym { font-style: inherit; }
+glossaryterm { font-style: inherit; }
+
.option { white-space: nowrap; }
/* make images not too wide on larger screens */
--
2.17.1
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2019-11-09 08:19 Fabien COELHO <[email protected]>
parent: Corey Huinker <[email protected]>
2 siblings, 1 reply; 97+ messages in thread
From: Fabien COELHO @ 2019-11-09 08:19 UTC (permalink / raw)
To: Corey Huinker <[email protected]>; +Cc: [email protected]
Hello Corey,
My 0.02€:
On principle, I'm fine with having a glossary, i.e. word definitions,
which are expected to be rather stable in the long run.
I'm wondering whether the effort would not be made redundant by other
on-line effort such as wikipedia, wiktionary, stackoverflow, standards,
whatever.
When explaining something, the teacher I am usually provides some level of
example. This may or may not be appropriate there.
ISTM that there should be pointers to relevant sections in the
documentation, for instance "Analytics" provided definition suggests
pointing to windowing functions.
There is significant redundancy involved, because a lot of term would be
defined in other sections anyway.
There should be cross references, eg "Column" definition talks about
Attribute, Table & View, which should be linked to.
I'd consider making SQL keywords uppercase.
Developing that is a significant undertaking. Do we have the available
energy?
Patch generates a warning on "git apply".
sh> git apply ...
... terms-and-definitions.patch:159: tab in indent. [...]
warning: 1 line adds whitespace errors.
"Record" def as nested <para> for some unclear reason.
Basically the redacted definitions look pretty clear and well written to
the non-native English speaker I am.
On Sun, 13 Oct 2019, Corey Huinker wrote:
> Date: Sun, 13 Oct 2019 16:52:05 -0400
> From: Corey Huinker <[email protected]>
> To: [email protected]
> Subject: Add A Glossary
>
> Attached is a v1 patch to add a Glossary to the appendix of our current
> documentation.
>
> I believe that our documentation needs a glossary for a few reasons:
>
> 1. It's hard to ask for help if you don't know the proper terminology of
> the problem you're having.
>
> 2. Readers who are new to databases may not understand a few of the terms
> that are used casually both in the documentation and in forums. This helps
> to make our documentation a bit more useful as a teaching tool.
>
> 3. Readers whose primary language is not English may struggle to find the
> correct search terms, and this glossary may help them grasp that a given
> term has a usage in databases that is different from common English usage.
>
> 3b. If we are not able to find the resources to translate all of the
> documentation into a given language, translating the glossary page would be
> a good first step.
>
> 4. The glossary would be web-searchable, and draw viewers to the official
> documentation.
>
> 5. adding link anchors to each term would make them cite-able, useful in
> forum conversations.
>
>
> A few notes about this patch:
>
> 1. It's obviously incomplete. There are more terms, a lot more, to add.
>
> 2. The individual definitions supplied are off-the-cuff, and should be
> thoroughly reviewed.
>
> 3. The definitions as a whole should be reviewed by an actual tech writer
> (one was initially involved but had to step back due to prior commitments),
> and the definitions should be normalized in terms of voice, tone, audience,
> etc.
>
> 4. My understanding of DocBook is not strong. The glossary vs glosslist tag
> issue is a bit confusing to me, and I'm not sure if the glossary tag is
> even appropriate for our needs.
>
> 5. I've made no effort at making each term an anchor, nor have I done any
> CSS styling at all.
>
> 6. I'm not quite sure how to handle terms that have different definitions
> in different contexts. Should that be two glossdefs following one
> glossterm, or two separate def/term pairs?
>
> Please review and share your thoughts.
>
--
Fabien Coelho - CRI, MINES ParisTech
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2019-11-25 07:55 Michael Paquier <[email protected]>
parent: Fabien COELHO <[email protected]>
0 siblings, 1 reply; 97+ messages in thread
From: Michael Paquier @ 2019-11-25 07:55 UTC (permalink / raw)
To: Fabien COELHO <[email protected]>; +Cc: Corey Huinker <[email protected]>; [email protected]
On Sat, Nov 09, 2019 at 09:19:16AM +0100, Fabien COELHO wrote:
> On principle, I'm fine with having a glossary, i.e. word definitions, which
> are expected to be rather stable in the long run.
>
> I'm wondering whether the effort would not be made redundant by other
> on-line effort such as wikipedia, wiktionary, stackoverflow, standards,
> whatever.
>
> When explaining something, the teacher I am usually provides some level of
> example. This may or may not be appropriate there.
That's exactly a good reason for being a reviewer here. You have
quite some insight here.
> I'd consider making SQL keywords uppercase.
>
> Developing that is a significant undertaking. Do we have the available
> energy?
It seems like this could be a good idea, still the patch has been
waiting on his author for more than two weeks now, so I have marked it
as returned with feedback.
--
Michael
Attachments:
[application/pgp-signature] signature.asc (833B, 2-signature.asc)
download
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-02-12 04:22 Corey Huinker <[email protected]>
parent: Michael Paquier <[email protected]>
0 siblings, 1 reply; 97+ messages in thread
From: Corey Huinker @ 2020-02-12 04:22 UTC (permalink / raw)
To: Michael Paquier <[email protected]>; +Cc: Fabien COELHO <[email protected]>; [email protected]; Roger Harkavy <[email protected]>
>
> It seems like this could be a good idea, still the patch has been
> waiting on his author for more than two weeks now, so I have marked it
> as returned with feedback.
>
In light of feedback, I enlisted the help of an actual technical writer
(Roger Harkavy, CCed) and we eventually found the time to take a second
pass at this.
Attached is a revised patch.
Attachments:
[text/x-patch] 0001-add-glossary-page-with-initial-definitions.patch (23.3K, 3-0001-add-glossary-page-with-initial-definitions.patch)
download | inline diff:
From f087e44fe4db7996880cf4df982297018d444363 Mon Sep 17 00:00:00 2001
From: Corey Huinker <[email protected]>
Date: Wed, 12 Feb 2020 04:17:59 +0000
Subject: [PATCH] add glossary page with initial definitions
---
doc/src/sgml/filelist.sgml | 1 +
doc/src/sgml/glossary.sgml | 540 +++++++++++++++++++++++++++++++++++++
doc/src/sgml/postgres.sgml | 1 +
3 files changed, 542 insertions(+)
create mode 100644 doc/src/sgml/glossary.sgml
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 3da2365ea9..504c8a6326 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -170,6 +170,7 @@
<!ENTITY limits SYSTEM "limits.sgml">
<!ENTITY acronyms SYSTEM "acronyms.sgml">
+<!ENTITY glossary SYSTEM "glossary.sgml">
<!ENTITY features-supported SYSTEM "features-supported.sgml">
<!ENTITY features-unsupported SYSTEM "features-unsupported.sgml">
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
new file mode 100644
index 0000000000..1b881690fa
--- /dev/null
+++ b/doc/src/sgml/glossary.sgml
@@ -0,0 +1,540 @@
+<!-- doc/src/sgml/glossary.sgml -->
+
+<appendix id="glossary">
+ <title>Glossary</title>
+ <para>
+ This is a list of terms and their definitions in the context of <productname>PostgreSQL</productname> and databases in general.
+ </para>
+ <glosslist>
+ <glossentry>
+ <glossterm>Aggregate</glossterm>
+ <glossdef>
+ <para>
+ The act of combining a defined collection of data values into a single value that may not be the same type as the original values. Aggregate <glossterm>functions</glossterm> are most often used with Grouping operations which define the separate sets of data by the common values shared within those sets.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Analytic</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>function</glossterm> whose computed value can reference values found in nearby <glossterm>rows</glossterm> of the same result set.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Atomic</glossterm>
+ <glossdef>
+ <para>
+ When referring to the value of an <glossterm>attribute</glossterm> or <glossterm>datum</glossterm>: cannot be broken up into smaller components.
+ </para>
+ <para>
+ When referring to an operation: An event that cannot be partially completed; it must either completely succeed or completely fail. A series of <acronym>SQL</acronym> statements can be combined into a <glossterm>transaction</glossterm>, and that transaction is described as atomic.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Attribute</glossterm>
+ <glossdef>
+ <para>
+ A typed data element found within a <glossterm>tuple</glossterm> or <glossterm>relation</glossterm> or <glossterm>table</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>BYTEA</glossterm>
+ <glossdef>
+ <para>
+ A data type for storing binary data. It is roughly analogous to the <literal>BLOB</literal> data type in other database products.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Cast</glossterm>
+ <glossdef>
+ <para>
+ The act of converting of a <glossterm>datum</glossterm> from its current data type to another data type.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Check Constraint</glossterm>
+ <glossdef>
+ <para>
+ A type of <glossterm>constraint</glossterm> defined for a <glossterm>relation</glossterm> which restricts the values allowed in one or more <glossterm>attribute</glossterm>s. The check constraint can make reference to any attribute in the relation, but cannot reference other rows of the same relation or other relations.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Column</glossterm>
+ <glossdef>
+ <para>
+ An <glossterm>attribute</glossterm> found in a <glossterm>table</glossterm> or <glossterm>view</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Commit</glossterm>
+ <glossdef>
+ <para>
+ The act of finalizing a <glossterm>transaction</glossterm> within the database.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Concurrency</glossterm>
+ <glossdef>
+ <para>
+ The concept that multiple independent operations can be happening within the database at the same time.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Constraint</glossterm>
+ <glossdef>
+ <para>
+ A method of restricting the values of data allowed within a <glossterm>relation</glossterm>. Constraints can currently be of the following types: <glossterm>Check Constraint</glossterm>, <glossterm>Unique Constraint</glossterm>, and <glossterm>Exclusion Constraint</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Datum</glossterm>
+ <glossdef>
+ <para>
+ The internal representation of a <acronym>SQL</acronym> datatype.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Delete</glossterm>
+ <glossdef>
+ <para>
+ A <acronym>SQL</acronym> command that removes rows from a given <glossterm>table</glossterm> or <glossterm>relation</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Exclusion Constraint</glossterm>
+ <glossdef>
+ <para>
+ Exclusion constraints define both a set of <glossterm>column</glossterm>s for matching <glossterm>row</glossterm>s, and rules where values in one row would conflict with values in another.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Foreign Data Wrapper</glossterm>
+ <glossdef>
+ <para>
+ A means of representing data outside the local database so that it appears as if it were in local tables. With a Foreign Data Wrapper it is possible to define a <glossterm>Foreign Server</glossterm> and <glossterm>Foreign Tables</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Foreign Key</glossterm>
+ <glossdef>
+ <para>
+ A type of <glossterm>constraint</glossterm> defined on one or more columns 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 table.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Foreign Server</glossterm>
+ <glossdef>
+ <para>
+ A named collection of <glossterm>Foreign Table</glossterm>s which all use the same <glossterm>Foreign Data Wrapper</glossterm> and have other configured <glossterm>attribute</glossterm>s in common.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Foreign Table</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>relation</glossterm> which appears to have <glossterm>row</glossterm>s and <glossterm>column</glossterm>s like a regular <glossterm>table</glossterm>, but when queried will instead forward the request for data through its <glossterm>Foreign Data Wrapper</glossterm>, which will return results structured according to the definition of the Foreign Table.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Function</glossterm>
+ <glossdef>
+ <para>
+ Any pre-defined transformation of data. Many functions are already defined within <productname>PostgreSQL</productname> itself, but user-defined <glossterm>function</glossterm>s can be added.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Grant</glossterm>
+ <glossdef>
+ <para>
+ A <acronym>SQL</acronym> command that is used to enable <glossterm>user</glossterm>s or <glossterm>role</glossterm>s to access specific objects within the database.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Index</glossterm>
+ <glossdef>
+ <para>
+ A relation that contains data derived from a <glossterm>table</glossterm> (or a <glossterm>relation</glossterm> such as a <glossterm>materialized view</glossterm>) that stores the data in a way that makes specific values easier to retrieve.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Insert</glossterm>
+ <glossdef>
+ <para>
+ A <acronym>SQL</acronym> command used to add new data into a <glossterm>table</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Join</glossterm>
+ <glossdef>
+ <para>
+ A technique used with <command>SELECT</command> statements to correlate data in one data set (usually a <glossterm>table</glossterm>) with the data set already defined up to the current point in the <command>SELECT</command> statement.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Key</glossterm>
+ <glossdef>
+ <para>
+ A means of identifying a <glossterm>row</glossterm> within a <glossterm>table</glossterm> or <glossterm>relation</glossterm> using values contained within one or more <glossterm>attribute</glossterm>s in that table.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Lock</glossterm>
+ <glossdef>
+ <para>
+ A mechanism that enables one process to perform actions on a defined <glossterm>object</glossterm> or set of <glossterm>row</glossterm>s within that object while preventing other processes from querying and/or modifying them.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Logged</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>table</glossterm> is considered logged if changes to the table are sent to the <acronym>WAL</acronym>. By default, all regular tables are logged. A table can be defined as unlogged either at creation time or via the <command>ALTER TABLE</command> command. The primary use of unlogged tables is for storing transient work data that must be shared across processes, but with a final result stored in logged tables. <glossterm>Temporary</glossterm> tables are always unlogged.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Master</glossterm>
+ <glossdef>
+ <para>
+ The server that is considered the authoritative source of information for databases that are linked via replication.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Materialized</glossterm>
+ <glossdef>
+ <para>
+ The state of being stored information rather than just a defined means of accessing the information. This term is used in <glossterm>Materialized View</glossterm>s, meaning that the data derived from the <glossterm>view</glossterm> is actually stored on disk separate from the sources of that data. When materialized is used in describing multi-step queries, it means that the data of a given step is stored (in memory, but that storage may spill over onto disk).
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <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 that a <glossterm>table</glossterm> does. It cannot be modified via <command>INSERT</command>, <command>UPDATE</command>, or <command>DELETE</command> operations.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Null</glossterm>
+ <glossdef>
+ <para>
+ A concept of non-existence that is a central tenet of relational database theory. It represents the absence of value.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Partition</glossterm>
+ <glossdef>
+ <para>
+ A member of a collection of <glossterm>table</glossterm>s organized to act as if it were itself a single unified table. Each partition is defined to hold a specific subset of data for the partitioned table that cannot overlap with any other partition in that partitioned table. Therefore, no <glossterm>row</glossterm> of data can belong in more than one partition.
+ </para>
+ <para>
+ Partitions have a name and can be queried directly through that name, but they can also be queried implicitly by querying the name of the partitioned table.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Primary Key</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>unique</glossterm> <glossterm>index</glossterm> defined on a <glossterm>table</glossterm> or other <glossterm>relation</glossterm> that also guarantees that all of the <glossterm>attribute</glossterm>s within the <glossterm>Primary Key</glossterm> do not have null values. As the name implies, there can be only one Primary Key per table, though it is possible to have multiple unique indexes that also have no <glossterm>null</glossterm>-capable attributes.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Procedure</glossterm>
+ <glossdef>
+ <para>
+ A defined set of instructions for manipulating data within a database. Procedures can be written in a variety of programming languages. They may appear like <glossterm>function</glossterm>s 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 like <command>COMMIT</command> and <command>ROLLBACK</command>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Record</glossterm>
+ <glossdef>
+ <para>
+ A data structure that consists of one or more <glossterm>attribute</glossterm>s in a defined order. A record that belongs to a table or other relation is more commonly called a <glossterm>row</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Referential Integrity</glossterm>
+ <glossdef>
+ <para>
+ The means of restricting data in one <glossterm>relation</glossterm> so that it must have matching data in another relation.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Relation</glossterm>
+ <glossdef>
+ <para>
+ The generic term for all objects in a database that have a name and a list of attributes defined in a specific order. <glossterm>Table</glossterm>s, <glossterm>view</glossterm>s, <glossterm>foreign table</glossterm>s, <glossterm>materialized view</glossterm>s and <glossterm>index</glossterm>es are all Relations.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Replica</glossterm>
+ <glossdef>
+ <para>
+ A database that is paired with a <glossterm>master</glossterm> database and maintains a copy of some or all of the master database's data. The primary reasons for doing this are to allow for greater access to that data, and to maintain availability of the data in the event that the master becomes unavailable.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Revoke</glossterm>
+ <glossdef>
+ <para>
+ A command to reduce access to a named set of database objects for a named list of <glossterm>user</glossterm>s and <glossterm>role</glossterm>s.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Role</glossterm>
+ <glossdef>
+ <para>
+ A collection of access privileges for the database. Roles are themselves a privilege that can be granted to other roles. This is often done for convenience or to ensure completeness when multiple <glossterm>user</glossterm>s need the same privileges.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Rollback</glossterm>
+ <glossdef>
+ <para>
+ A command to undo all of the operations performed since the beginning of a <glossterm>transaction</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Row</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>tuple</glossterm> or <glossterm>record</glossterm> found within a <glossterm>relation</glossterm> or result set. This term is often used interchangably with Tuple and Record.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Schema</glossterm>
+ <glossdef>
+ <para>
+ A named collection of database objects organized to facilitate clarity or security. Most often used in the same way a namespace is used in programming languages. All objects belong to exactly one schema, most commonly <literal>public</literal>, the default schema.
+ </para>
+ <para>
+ More generically, the term Schema is used to mean all data descriptions (<glossterm>table</glossterm> definitions, <glossterm>constraint</glossterm>s, comments) for a given database.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Select</glossterm>
+ <glossdef>
+ <para>
+ The command used to query a database. Normally, <command>SELECT</command> commands are not expected to modify the database in any way, but it is possible that <glossterm>Functions</glossterm> invoked within the query could have side effects that do modify data.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Serializable</glossterm>
+ <glossdef>
+ <para>
+ Database <glossterm>session</glossterm>s in a <glossterm>transaction</glossterm> defined as <literal>SERIALIZABLE</literal> are unable to see changes made to the database by other sessions. In effect, the entire database appears to be frozen in time for the duration of the transaction.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Session</glossterm>
+ <glossdef>
+ <para>
+ A connection to the database. Can also be used to describe a series of commands that were issued in the life cycle of a particular connection to the database.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Table</glossterm>
+ <glossdef>
+ <para>
+ A collection of <glossterm>tuple</glossterm>s (also known as <glossterm>row</glossterm>s or <glossterm>record</glossterm>s) having a common data structure (the same number of <glossterm>column</glossterm>s, in the same order, having the same type). A table is the most common form of relation in <productname>PostgreSQL</productname>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Temporary</glossterm>
+ <glossdef>
+ <para>
+ Temporary <glossterm>table</glossterm>s are tables that exist either for the lifetime of a <glossterm>session</glossterm> or a <glossterm>transaction</glossterm>, as defined at creation time. The data in them is not visible to other sessions, and is not logged. Temporary tables are most often used to store intermediate data for a multi-step data transformation.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Transaction</glossterm>
+ <glossdef>
+ <para>
+ A combination of one or more commands that must act as a single <glossterm>atomic</glossterm> command: they all succeed or fail together, and their effects are not visible to other <glossterm>session</glossterm>s until the <glossterm>transaction</glossterm> is complete.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <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>DELETE</command>) is applied to that <glossterm>relation</glossterm>. A trigger executes within the same <glossterm>transaction</glossterm> as the statement which invoked it, and if the function fails then the invoking statement also fails.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Tuple</glossterm>
+ <glossdef>
+ <para>
+ A collection of <glossterm>attribute</glossterm>s in a fixed order. That order may be defined by the <glossterm>table</glossterm> where the Tuple is found, in which case the Tuple is often called a <glossterm>row</glossterm> or <glossterm>record</glossterm>. It may also be defined by the structure of a result set.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Unique</glossterm>
+ <glossdef>
+ <para>
+ The state of having a set of columns with no matching values in the same <glossterm>relation</glossterm>. Most often used in the concept of unique indexes.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Unique Constraint</glossterm>
+ <glossdef>
+ <para>
+ A rule that defines a set of <glossterm>column</glossterm>s for which no two <glossterm>row</glossterm>s in the <glossterm>table</glossterm> can share the same set of values.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Unlogged</glossterm>
+ <glossdef>
+ <para>
+ A relation that is unlogged will not have changes reflected in the <acronym>WAL</acronym>, which would enable those changes to be duplicated on a <glossterm>replica</glossterm>, and also enables the change to survive a database crash.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Update</glossterm>
+ <glossdef>
+ <para>
+ A command used to modify <glossterm>row</glossterm>s that already exist in a specified <glossterm>table</glossterm>. It cannot create <glossterm>row</glossterm>s nor can it remove them.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>User</glossterm>
+ <glossdef>
+ <para>
+ A specific case of a <glossterm>role</glossterm> that is entitled to access (log into) the database.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>User Mapping</glossterm>
+ <glossdef>
+ <para>
+ The translation of <glossterm>user</glossterm> credentials in the local database to credentials in a remote data system defined by a <glossterm>Foreign Data Wrapper</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>View</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>relation</glossterm> that is defined by a <command>SELECT</command> statement, but has no storage of its own. Any time a query references a View, the definition of the View is substituted into the query as if the user had typed that subquery instead of the name of the View.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Window Function</glossterm>
+ <glossdef>
+ <para>
+ A type of <glossterm>function</glossterm> similar to an <glossterm>aggregate</glossterm> in that it can derive its value from a set of <glossterm>row</glossterm>s in a result set, but still retaining the original source data.
+ </para>
+ </glossdef>
+ </glossentry>
+ </glosslist>
+</appendix>
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index e59cba7997..2183e33bea 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -278,6 +278,7 @@
&docguide;
&limits;
&acronyms;
+ &glossary;
</part>
--
2.17.1
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-03-10 15:37 Corey Huinker <[email protected]>
parent: Corey Huinker <[email protected]>
0 siblings, 1 reply; 97+ messages in thread
From: Corey Huinker @ 2020-03-10 15:37 UTC (permalink / raw)
To: [email protected]; +Cc: Fabien COELHO <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Michael Paquier <[email protected]>
This latest version is an attempt at merging the work of Jürgen Purtz into
what I had posted earlier. There was relatively little overlap in the terms
we had chosen to define.
Each glossary definition now has a reference id (good idea Jürgen), the
form of which is "glossary-term". So we can link to the glossary from
outside if we so choose.
I encourage everyone to read the definitions, and suggest fixes to any
inaccuracies or awkward phrasings. Mostly, though, I'm seeking feedback on
the structure itself, and hoping to get that committed.
On Tue, Feb 11, 2020 at 11:22 PM Corey Huinker <[email protected]>
wrote:
> It seems like this could be a good idea, still the patch has been
>> waiting on his author for more than two weeks now, so I have marked it
>> as returned with feedback.
>>
>
> In light of feedback, I enlisted the help of an actual technical writer
> (Roger Harkavy, CCed) and we eventually found the time to take a second
> pass at this.
>
> Attached is a revised patch.
>
>
Attachments:
[text/x-patch] 0001-add-glossary-page.patch (47.3K, 3-0001-add-glossary-page.patch)
download | inline diff:
From 690473e51fc442c55c1744f69813795fce9d22dc Mon Sep 17 00:00:00 2001
From: coreyhuinker <[email protected]>
Date: Tue, 10 Mar 2020 11:26:29 -0400
Subject: [PATCH] add glossary page
---
doc/src/sgml/filelist.sgml | 1 +
doc/src/sgml/glossary.sgml | 1008 ++++++++++++++++++++++++++++++++++++
doc/src/sgml/postgres.sgml | 1 +
3 files changed, 1010 insertions(+)
create mode 100644 doc/src/sgml/glossary.sgml
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 3da2365ea9..504c8a6326 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -170,6 +170,7 @@
<!ENTITY limits SYSTEM "limits.sgml">
<!ENTITY acronyms SYSTEM "acronyms.sgml">
+<!ENTITY glossary SYSTEM "glossary.sgml">
<!ENTITY features-supported SYSTEM "features-supported.sgml">
<!ENTITY features-unsupported SYSTEM "features-unsupported.sgml">
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
new file mode 100644
index 0000000000..851e9debe6
--- /dev/null
+++ b/doc/src/sgml/glossary.sgml
@@ -0,0 +1,1008 @@
+<appendix id="glossary">
+ <title>Glossary</title>
+ <para>
+ This is a list of terms and their in the context of <productname>PostgreSQL</productname> and <glossterm>Database</glossterm>s in general.
+ </para>
+ <glosslist>
+ <glossentry id="glossary-aggregate">
+ <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 non-common data.
+ </para>
+ <para>
+ For more information, see <link linkend="functions-aggregate">Aggregate Functions</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-analytic">
+ <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>.
+ </para>
+ <para>
+ For more information, see <link linkend="tutorial-window">Window Functions</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-archiver">
+ <glossterm>Archiver</glossterm>
+ <glossdef>
+ <para>
+ A process that backs up <glossterm>WAL Files</glossterm> in order to reclaim space on the file system.
+ </para>
+ <para>
+ For more information, see <link linkend="continuous-archiving">Backup and Restore: Continuous Archiving and Point-in-Time Recovery (PITR)</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-atomic">
+ <glossterm>Atomic</glossterm>
+ <glossdef>
+ <para>
+ In reference to the value of an <glossterm>Attribute</glossterm> or <glossterm>Datum</glossterm>: cannot be broken up into smaller components.
+ </para>
+ <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 <acronym>SQL</acronym> statements can be combined into a <glossterm>Transaction</glossterm>, and that <glossterm>transaction</glossterm> is said to be <glossterm>Atomic</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-attribute">
+ <glossterm>Attribute</glossterm>
+ <glossdef>
+ <para>
+ A typed data element found within a <glossterm>Tuple</glossterm> or <glossterm>Relation</glossterm> or <glossterm>Table</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-autovacuum">
+ <glossterm>Autovacuum</glossterm>
+ <glossdef>
+ <para>
+ Processes that remove outdated <acronym>MVCC</acronym> <glossterm>Records</glossterm> of the <glossterm>Heap</glossterm> and <glossterm>Index</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="routine-vacuuming">Routine Database Maintenance Tasks: Routine Vacuuming</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-backend-process">
+ <glossterm>Backend Process</glossterm>
+ <glossdef>
+ <para>
+ Processes of an <glossterm>Instance</glossterm> which act on behalf of client <glossterm>Connections</glossterm> and handle their requests.
+ </para>
+ <para>
+ (Don't confuse this term with the similar terms <glossterm>Background Worker</glossterm> or <glossterm>Background Writer</glossterm>).
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-backend-server">
+ <glossterm>Backend Server</glossterm>
+ <glossdef>
+ <para>
+ See <glossterm>Instance</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-background-worker">
+ <glossterm>Background Worker</glossterm>
+ <glossdef>
+ <para>
+ Individual processes within an <glossterm>Instance</glossterm>, which 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>.
+ </para>
+ <para>
+ For more information, see <link linkend="bgworker">Background Worker Processes</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-background-writer">
+ <glossterm>Background Writer</glossterm>
+ <glossdef>
+ <para>
+ Writes continuously dirty pages from <glossterm>Shared Memory</glossterm> to the file system. It starts periodically, but works only for a short period in order to distribute
+expensive <acronym>I/O</acronym> activity over time instead of generating fewer large <acronym>I/O</acronym> peaks which could block other processes.
+ </para>
+ <para>
+ For more information, see <link linkend="runtime-config-resource">Server Configuration: Resource Consumption</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-cast">
+ <glossterm>Cast</glossterm>
+ <glossdef>
+ <para>
+ A conversion of a <glossterm>Datum</glossterm> from its current data type to another data type.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-catalog">
+ <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.
+ </para>
+ <para>
+ For more information, see <link linkend="manage-ag-overview">Managing Databases: Overview</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-check-constraint">
+ <glossterm>Check Constraint</glossterm>
+ <glossdef>
+ <para>
+ A type of <glossterm>Constraint</glossterm> defined on a <glossterm>Relation</glossterm> which restricts the values
+allowed in one or more <glossterm>Attributes</glossterm>. The <glossterm>Check Constraint</glossterm> can make reference to
+any <glossterm>Attribute</glossterm> in the <glossterm>Relation</glossterm>, but cannot reference other <glossterm>Rows</glossterm> of the same <glossterm>Relation</glossterm> or other <glossterm>Relations</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="ddl-constraints">Constraints</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-checkpointer">
+ <glossterm>Checkpointer</glossterm>
+ <glossdef>
+ <para>
+ A process that writes dirty pages and <glossterm>WAL Records</glossterm> 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.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-cluster">
+ <glossterm>Cluster</glossterm>
+ <glossdef>
+ <para>
+ A group of <glossterm>Database</glossterm>s plus their <glossterm>Global SQL Objects</glossterm>. The <glossterm>Cluster</glossterm> is managed by exactly one <glossterm>Instance</glossterm>. A newly created <glossterm>Cluster</glossterm> will have three <glossterm>Databases</glossterm> created automatically. They are <literal>template0</literal>, <literal>template1</literal>, and <literal>postgres</literal>. It is expected that an application will create one or more additional <glossterm>Databases</glossterm> aside from these three.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-column">
+ <glossterm>Column</glossterm>
+ <glossdef>
+ <para>
+ An <glossterm>Attribute</glossterm> found in a <glossterm>Table</glossterm> or <glossterm>View</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-commit">
+ <glossterm>Commit</glossterm>
+ <glossdef>
+ <para>
+ The act of finalizing a <glossterm>Transaction</glossterm> within the <glossterm>Database</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-commit">SQL Commands: COMMIT</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-concurrency">
+ <glossterm>Concurrency</glossterm>
+ <glossdef>
+ <para>
+ The concept that multiple independent operations can be happening within the <glossterm>Database</glossterm> at the same time.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-connection">
+ <glossterm>Connection</glossterm>
+ <glossdef>
+ <para>
+ A <acronym>TCP/IP</acronym> or socket line for inter-process communication. If the two involved processes reside on different servers, <acronym>TCP/IP</acronym> must be used. Otherwise both techniques are possible.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-constraint">
+ <glossterm>Constraint</glossterm>
+ <glossdef>
+ <para>
+ A method of restricting the values of data allowed within a <glossterm>Table</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="ddl-constraints">Constraints</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-data-area">
+ <glossterm>Data Area</glossterm>
+ <glossdef>
+ <para>
+ See <glossterm>Data Directory</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-data-directory">
+ <glossterm>Data Directory</glossterm>
+ <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>. The name for this directory in configuration files is <productname>PGDATA</productname>.
+ </para>
+ <para>
+ For more information, see <link linkend="storage-file-layout">Database Physical Storage: Database File Layout</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-database">
+ <glossterm>Database</glossterm>
+ <glossdef>
+ <para>
+ A named collection of <glossterm>SQL Objects</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="manage-ag-overview">Managing Databases: Overview</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-database-server">
+ <glossterm>Database Server</glossterm>
+ <glossdef>
+ <para>
+ See <glossterm>Instance</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-datum">
+ <glossterm>Datum</glossterm>
+ <glossdef>
+ <para>
+ The internal representation of a <acronym>SQL</acronym> data type.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-delete">
+ <glossterm>Delete</glossterm>
+ <glossdef>
+ <para>
+ A <acronym>SQL</acronym> command whose purpose is to remove <glossterm>Rows</glossterm> from a given <glossterm>Table</glossterm> or <glossterm>Relation</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-delete">SQL Commands: DELETE</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-file-segment">
+ <glossterm>File Segment</glossterm>
+ <glossdef>
+ <para>
+ If a <glossterm>Database</glossterm> object grows in size past a designated limit, it may be
+split into multiple physical files. These files are called <glossterm>File Segments</glossterm>.
+ </para>
+ <para>
+ (Don't confuse this term with the similar term <glossterm>WAL Segment</glossterm>).
+ </para>
+ <para>
+ For more information, see <link linkend="storage-file-layout">Database Physical Storage: Database File Layout</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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). With a Foreign Data Wrapper it is possible to define a <glossterm>Foreign Server</glossterm> and <glossterm>Foreign Tables</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-createforeigndatawrapper">SQL Commands: CREATE FOREIGN DATA WRAPPER</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-foreign-server">
+ <glossterm>Foreign Server</glossterm>
+ <glossdef>
+ <para>
+ A named collection of <glossterm>Foreign Tables</glossterm> which all use the same <glossterm>Foreign Data Wrapper</glossterm> and have other configuration values in common.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-createserver">SQL Commands: CREATE SERVER</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-foreign-table">
+ <glossterm>Foreign Table</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Relation</glossterm> which appears to have <glossterm>Rows</glossterm> and <glossterm>Columns</glossterm> similar to a regular <glossterm>Table</glossterm>, but will forward requests for data through its <glossterm>Foreign Data Wrapper</glossterm>, which will return <glossterm>Result Sets</glossterm> structured according to the definition of the <glossterm>Foreign Table</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-createforeigntable">SQL Commands: CREATE FOREIGN TABLE</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-function">
+ <glossterm>Function</glossterm>
+ <glossdef>
+ <para>
+ Any pre-defined tranformation of data. Many <glossterm>Functions</glossterm> are already defined within <productname>PostgreSQL</productname> itself, but can also be user-defined.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-createfunction">SQL Commands: CREATE FUNCTION</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-global-sql-object">
+ <glossterm>Global SQL Object</glossterm>
+ <glossdef>
+ <para>
+ Not all objects belong to a certain <glossterm>Schema</glossterm>, or to their <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.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-grant">
+ <glossterm>Grant</glossterm>
+ <glossdef>
+ <para>
+ A <acronym>SQL</acronym> command that is used to enable <glossterm>Users</glossterm> or <glossterm>Roles</glossterm> to access specific objects within the <glossterm>Database</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-grant">SQL Commands: GRANT</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-heap">
+ <glossterm>Heap</glossterm>
+ <glossdef>
+ <para>
+ Contains the original values of <glossterm>Row</glossterm> attributes (i.e. the data). The <glossterm>Heap</glossterm> is realized within <glossterm>Database</glossterm> files and mirrored in <glossterm>Shared Memory</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="host">
+ <glossterm>Host</glossterm>
+ <glossdef>
+ <para>
+ See <glossterm>Server</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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>) that stores the data in a way that makes specific values easier to retrieve.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-createindex">SQL Commands: CREATE INDEX</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-insert">
+ <glossterm>Insert</glossterm>
+ <glossdef>
+ <para>
+ A <acronym>SQL</acronym> command used to add new data into a <glossterm>Table</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-insert">SQL Commands: INSERT</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-instance">
+ <glossterm>Instance</glossterm>
+ <glossdef>
+ <para>
+ An <glossterm>Instance</glossterm> is a group of processes plus their common <glossterm>Shared Memory</glossterm> running on a single <glossterm>Server</glossterm>. The <glossterm>Instance</glossterm> handles all key features of a <acronym>DBMS</acronym>: read and write access to files and <glossterm>Shared Memory</glossterm>, assurance of the <acronym>ACID</acronym> paradigm, <acronym>MVCC</acronym>, <glossterm>Connections</glossterm> to client programms, backup, recovery, replication, privileges, etc.
+ </para>
+ <para>
+ An <glossterm>Instance</glossterm> manages exactly one <glossterm>Cluster</glossterm>.
+ </para>
+ <para>
+ Many <glossterm>Instances</glossterm> can run on the same server as long as they use different <acronym>IP</acronym> ports and manage different <glossterm>Cluster</glossterm>s. Different <glossterm>Instances</glossterm> on a server may use the same or different versions of <productname>PostgreSQL</productname>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-join">
+ <glossterm>Join</glossterm>
+ <glossdef>
+ <para>
+ A technique used with <command>SELECT</command> statements for correlating data in one or more <glossterm>Relations</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-key">
+ <glossterm>Key</glossterm>
+ <glossdef>
+ <para>
+ A means of identifying a <glossterm>Row</glossterm> within a <glossterm>Table</glossterm> or <glossterm>Relation</glossterm> by values contained within one or more <glossterm>Attributes</glossterm> in that <glossterm>Table</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-lock">
+ <glossterm>Lock</glossterm>
+ <glossdef>
+ <para>
+ A mechanism for one process temporarily preventing data from being manipulated by any other process.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="log-record">
+ <glossterm>Log Record</glossterm>
+ <glossdef>
+ <para>
+ See <glossterm>WAL Record</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-logged">
+ <glossterm>Logged</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Table</glossterm> is considered <glossterm>Logged</glossterm> if changes to the <glossterm>Table</glossterm> 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>
+
+ <glossentry id="glossary-master">
+ <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>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-materialized">
+ <glossterm>Materialized</glossterm>
+ <glossdef>
+ <para>
+ The act of storing information rather than just the means of accessing 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 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 (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 that a <glossterm>Table</glossterm> does. it cannot be modified via <command>INSERT</command>, <command>UPDATE</command>, or <command>DELETE</command> operations.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-creatematerializedview">SQL Commands: CREATE MATERIALIZED VIEW</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-null">
+ <glossterm>Null</glossterm>
+ <glossdef>
+ <para>
+ A concept of non-existence that is a central tenet of Relational Database Theory. It represents the absence of value.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-partition">
+ <glossterm>Partition</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Table</glossterm> that can be queried independently by its own name, but can also be queried via another <glossterm>Table</glossterm>, a partitioend <glossterm>Table</glossterm>, which is a collection of sub-<glossterm>Table</glossterm>s, each capable of holding one defined subset of information that does not overlap with any other <glossterm>Table</glossterm> in the set of <glossterm>Table</glossterm>s.
+ </para>
+ <para>
+ A defined boundary used in an <glossterm>Analytic</glossterm> <glossterm>Function</glossterm> to identify which neighboring <glossterm>Rows</glossterm> can be considered by the <glossterm>Function</glossterm> for this particular <glossterm>Row</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-postmaster">
+ <glossterm>Postmaster</glossterm>
+ <glossdef>
+ <para>
+ The very first process of an <glossterm>Instance</glossterm>. It starts the other processes and creates <glossterm>Backend Processes</glossterm> on demand.
+ </para>
+ <para>
+ For more information, see <link linkend="server-start">Server Setup and Operation: Starting the Database Server</link>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-procedure">
+ <glossterm>Procedure</glossterm>
+ <glossdef>
+ <para>
+ A defined set of instructions for manipulating data within a <glossterm>Database</glossterm>. <glossterm>Procedure</glossterm> can be written in a variety of programming languages. They may seem similar to <glossterm>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 as <command>COMMIT</command> and <command>ROLLBACK</command>.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-createprocedure">SQL Commands: CREATE PROCEDURE</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-record">
+ <glossterm>Record</glossterm>
+ <glossdef>
+ <para>
+ A data structure that consists of one or more <glossterm>Attributes</glossterm> in a defined order.
+ </para>
+ <para>
+ A single <glossterm>Row</glossterm> of a <glossterm>Table</glossterm> or other Relation.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-referential-integrity">
+ <glossterm>Referential Integrity</glossterm>
+ <glossdef>
+ <para>
+ The means of restricting data in one <glossterm>Relation</glossterm> such that it must have matching data in another <glossterm>Relation</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-relation">
+ <glossterm>Relation</glossterm>
+ <glossdef>
+ <para>
+ The generic term for all objects in a <glossterm>Database</glossterm> that have a name and a list of <glossterm>Attributes</glossterm> defined in a specific order. <glossterm>Tables</glossterm>, <glossterm>Views</glossterm>, <glossterm>Foreign Tables</glossterm>, <glossterm>Materialized Views</glossterm>, and <glossterm>Indexes</glossterm> are all <glossterm>Relations</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-replica">
+ <glossterm>Replica</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Database</glossterm> that is paired with a Master <glossterm>Database</glossterm> and is maintaining a copy of some or all of the Master <glossterm>Database</glossterm>'s data. The primary reasons for doing this are to allow for greater access to that data, and to maintain availability of the data in the even that the <glossterm>Master</glossterm> becomes unavailable.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-replication">
+ <glossterm>Replication</glossterm>
+ <glossdef>
+ <para>
+ The act of reproducing data on one <glossterm>Server</glossterm> into another called a <glossterm>Replica</glossterm>. This can take the form of Physical <glossterm>Replication</glossterm>, where all file changes from one <glossterm>Server</glossterm> are copied verbatim, or Logical <glossterm>Replication</glossterm> where a defined subset of data changes are conveyed.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-result-set">
+ <glossterm>Result Set</glossterm>
+ <glossdef>
+ <para>
+ A data structure tranmitted 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. The data structure consists of zero or more <glossterm>Rows</glossterm> with the same ordered set of <glossterm>Attributes</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-revoke">
+ <glossterm>Revoke</glossterm>
+ <glossdef>
+ <para>
+ A command to reduce access to a named set of <glossterm>Database</glossterm> objects for a named list of <glossterm>Users</glossterm> and <glossterm>Roles</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-revoke">SQL Commands: REVOKE</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-role">
+ <glossterm>Role</glossterm>
+ <glossdef>
+ <para>
+ A collection of access privileges to the <glossterm>Database</glossterm>. <glossterm>Roles</glossterm> are themselves a privilege that can be granted to other roles. This is often done for convenience or to ensure completeness when multiple Users need the same privileges.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-createrole">SQL Commands: CREATE ROLE</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-rollback">
+ <glossterm>Rollback</glossterm>
+ <glossdef>
+ <para>
+ A command to undo all of the operations performed since the beginning of a <glossterm>Transaction</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-rollback">SQL Commands: ROLLBACK</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-row">
+ <glossterm>Row</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Tuple</glossterm> or <glossterm>Record</glossterm> found within a <glossterm>Relation</glossterm> or a <glossterm>Result Set</glossterm>. This term is often used interchangably with <glossterm>Record</glossterm> and <glossterm>Tuple</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-savepoint">SQL Commands: SAVEPOINT</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-schema">
+ <glossterm>Schema</glossterm>
+ <glossdef>
+ <para>
+ A means of organizing a collection of objects residing in the same <glossterm>Database</glossterm> to facilitate clarity or security. <glossterm>Schema</glossterm>s are most often used in the same way that a namespace is used in programming languages. All objects belong to exactly one <glossterm>Schema</glossterm>, most commonly "public", the default <glossterm>Schema</glossterm>.
+ </para>
+ <para>
+ More generically, the term <glossterm>Schema</glossterm> is used to mean all data descriptions (<glossterm>Table</glossterm> definitions, <glossterm>Constraint</glossterm>s, comments) for a given <glossterm>Database</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-segment">
+ <glossterm>Segment</glossterm>
+ <glossdef>
+ <para>
+ See <glossterm>File Segment</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-select">
+ <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>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-serializable">
+ <glossterm>Serializable</glossterm>
+ <glossdef>
+ <para>
+ <glossterm>Database</glossterm> <glossterm>Session</glossterm>s in a transaction defined as <literal>SERIALIZABLE</literal> are unable to see changes made to the <glossterm>Database</glossterm> by other sessions. In effect, the entire <glossterm>Database</glossterm> appears to be frozen in time for the duration of the <glossterm>Transaction</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-server">
+ <glossterm>Server</glossterm>
+ <glossdef>
+ <para>
+ The term <glossterm>Server</glossterm> denotes real hardware, a container, or a Virtual Machine.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-sequence">
+ <glossterm>Sequence</glossterm>
+ <glossdef>
+ <para>
+ An <glossterm>Database</glossterm> object which represents the mathematical concept of a generic numerical sequence. It can be thought of as a <glossterm>Table</glossterm> with exactly one <glossterm>Row</glossterm> and one <glossterm>Column</glossterm>. The value stores is know 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 curent value is moved in the defined direction by the defined interval step, and that value is returned to the invoking query, and the current value of the sequence is updated to reflect the new value. The value can be updated multiple times in a single query, the net effect being that each row selected will have a different value. Values taken from a <glossterm>Sequence</glossterm> are never reverted even in the case of a <glossterm>Rollback</glossterm>, which means that the <glossterm>Sequence</glossterm> will never emit the same number twice, and thus is the normal way of generating values to be put in a <glossterm>Primary Key</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-createsequence">SQL Commands: CREATE SEQUENCE</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-shared-memory">
+ <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>, and stores additional common information. Note that <glossterm>Shared Memory</glossterm> belongs to the complete <glossterm>Instance</glossterm>, not to a single <glossterm>Database</glossterm>.
+ </para>
+ <para>
+ <glossterm>Shared Memory</glossterm> is organized into pages. If a page is modified, it is called a dirty page until it is written back to the file system.
+ </para>
+ <para>
+ For more information, see <link linkend="runtime-config-resource-memory">Server Configuration: Resource Consumption</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-sql-object">
+ <glossterm>SQL Object</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Table</glossterm>, <glossterm>View</glossterm>, <glossterm>Materialized View</glossterm>, <glossterm>Index</glossterm>, <glossterm>Constraint</glossterm>, <glossterm>Sequence</glossterm>, <glossterm>Function</glossterm>, <glossterm>Procedure</glossterm>, <glossterm>Trigger</glossterm>, data type, or operator. Every <glossterm>SQL Object</glossterm> belongs to exactly one <glossterm>Schema</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="manage-ag-overview">Managing Databases: Overview</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-stats-collector">
+ <glossterm>Stats Collector</glossterm>
+ <glossdef>
+ <para>
+ This process collects statistical information about the <glossterm>Cluster</glossterm>'s activities.
+ </para>
+ <para>
+ For more information, see <link linkend="monitoring-stats">Monitoring Database Activity: The Statistics Collector</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-system-catalog">
+ <glossterm>System Catalog</glossterm>
+ <glossdef>
+ <para>
+ A collection of <glossterm>Table</glossterm>s and <glossterm>View</glossterm>s which describe the structure of all <acronym>SQL</acronym> objects of the <glossterm>Database</glossterm> and the <glossterm>Global SQL Objects</glossterm> of the <glossterm>Cluster</glossterm>. The <glossterm>System Catalog</glossterm> resides in the schema <literal>pg_catalog</literal>. Main parts are mirrored as <glossterm>Views</glossterm> in the <glossterm>Schema</glossterm> <literal>information_schema</literal>.
+ </para>
+ <para>
+ For more information, see <link linkend="ddl-schemas">Data Definition: Schemas</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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 name and type). A <glossterm>Table</glossterm> is the most common form of <glossterm>Relation</glossterm> in <productname>PostgreSQL</productname>.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-createtable">SQL Commands: CREATE TABLE</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-temporary-tables">
+ <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 data in them is not visible to other <glossterm>Sessions</glossterm>, and is not <glossterm>Logged</glossterm>. <glossterm>Temporary Tables</glossterm> are most often used to store intermediate data for a multi-step data transformation.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-createtable">SQL Commands: CREATE TABLE</link>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-transaction">
+ <glossterm>Transaction</glossterm>
+ <glossdef>
+ <para>
+ A combination of one or more commands that must act as a single <glossterm>Atomic</glossterm> command: they all succeed or fail together, and their effects are not visible to other sessions until the <glossterm>Transaction</glossterm> is complete.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-trigger">
+ <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> executes within the same <glossterm>Transaction</glossterm> as the statement which invoked it, and if the <glossterm>Function</glossterm> fails then the invoking statement also fails.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-createtrigger">SQL Commands: CREATE TRIGGER</link>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-tuple">
+ <glossterm>Tuple</glossterm>
+ <glossdef>
+ <para>
+ A collection of <glossterm>Attributes</glossterm> in a fixed order. That order may be defined by the <glossterm>Table</glossterm> where the <glossterm>Tuple</glossterm> is found, in which case the <glossterm>Tuple</glossterm> is often called a <glossterm>Row</glossterm> or <glossterm>Record</glossterm>. It may also be defined by the structure of a <glossterm>Result Set</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-unique">
+ <glossterm>Unique</glossterm>
+ <glossdef>
+ <para>
+ The condition of having no matching values in the same <glossterm>Relation</glossterm>. Most often used in the concept of <glossterm>Unique Indexes</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-unlogged">
+ <glossterm>Unlogged</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Relation</glossterm> that is unlogged will not have changes reflected in the <glossterm>WAL Log</glossterm>,
+which would enable those changes to be duplicated on a <glossterm>Replica</glossterm>, and also enables the change to survive a <glossterm>Database</glossterm> crash.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-update">
+ <glossterm>Update</glossterm>
+ <glossdef>
+ <para>
+ A command used to modify <glossterm>Rows</glossterm> that already exist in a specified <glossterm>Table</glossterm>. It
+cannot create <glossterm>Rows</glossterm> nor can it remove <glossterm>Rows</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-update">SQL Commands: UPDATE</link>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-user">
+ <glossterm>User</glossterm>
+ <glossdef>
+ <para>
+ A specific case of a <glossterm>Role</glossterm> that is entitled to access (log into) the <glossterm>Database</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-user-mapping">
+ <glossterm>User Mapping</glossterm>
+ <glossdef>
+ <para>
+ The translation of user credentials in the local <glossterm>Database</glossterm> to credentials in a remote data system defined by a <glossterm>Foreign Data Wrapper</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-createusermapping">SQL Commands: CREATE USER MAPPING</link>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-view">
+ <glossterm>View</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Relation</glossterm> that is defined by a <command>SELECT</command> statement, but has no storage of its own. Any time a query references a <glossterm>View</glossterm>, the definition of the <glossterm>View</glossterm> is substituted into the query as if the user had typed that subquery instead of the name of the <glossterm>View</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-createview">SQL Commands: CREATE VIEW</link>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-wal-file">
+ <glossterm>WAL File</glossterm>
+ <glossdef>
+ <para>
+ <glossterm>WAL Records</glossterm> are continously written to the end of the current <glossterm>WAL File</glossterm>. <glossterm>WAL Files</glossterm> as well as <glossterm>WAL Records</glossterm> belong to the complete <glossterm>Cluster</glossterm>, not to a single <glossterm>Database</glossterm>. After a <glossterm>WAL File</glossterm> is full, a new <glossterm>WAL File</glossterm> is created or, under certain conditions, one of the previous <glossterm>WAL Files</glossterm> is renamed and reused.
+ </para>
+ <para>
+ The sequence of <glossterm>WAL Records</glossterm> in combination with the sequence of <glossterm>WAL Files</glossterm> represents the sequence of changes that have taken place in the <glossterm>Cluster</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="wal-internals">Reliability and the Write-Ahead Log: WAL Internals</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-wal-log">
+ <glossterm>WAL Log</glossterm>
+ <glossdef>
+ <para>
+ See <glossterm>WAL File</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-wal-record">
+ <glossterm>WAL Record</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>WAL Record</glossterm> contains either new or changed <glossterm>Heap</glossterm> or <glossterm>Index</glossterm> data or other binary information about a <command>COMMIT</command>, <command>ROLLBACK</command>, <command>SAVEPOINT</command>, or <glossterm>Checkpointer</glossterm> operation.
+ </para>
+ <para>
+ For more information, see <link linkend="wal-internals">Reliability and the Write-Ahead Log: WAL Internals</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-wal-segment">
+ <glossterm>WAL Segment</glossterm>
+ <glossdef>
+ <para>
+ See <glossterm>WAL File</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-wal-segment-file">
+ <glossterm>WAL Segment File</glossterm>
+ <glossdef>
+ <para>
+ See <glossterm>WAL File</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-wal-writer">
+ <glossterm>WAL Writer</glossterm>
+ <glossdef>
+ <para>
+ This process writes <glossterm>WAL Records</glossterm> from <glossterm>Shared Memory</glossterm> to <glossterm>WAL Files</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="runtime-config-wal">Server Configuration: Write Ahead Log</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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 set of <glossterm>Rows</glossterm> in a <glossterm>Result Set</glossterm>, but still retaining the original source
+data.
+ </para>
+ <para>
+ For more information, see <link linkend="tutorial-window">Window Functions</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+ </glosslist>
+</appendix>
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index e59cba7997..2183e33bea 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -278,6 +278,7 @@
&docguide;
&limits;
&acronyms;
+ &glossary;
</part>
--
2.20.1
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-03-11 13:40 Roger Harkavy <[email protected]>
parent: Corey Huinker <[email protected]>
0 siblings, 1 reply; 97+ messages in thread
From: Roger Harkavy @ 2020-03-11 13:40 UTC (permalink / raw)
To: Corey Huinker <[email protected]>; +Cc: [email protected]; Fabien COELHO <[email protected]>; [email protected]; Michael Paquier <[email protected]>
Hello, everyone, I'm Roger, the tech writer who worked with Corey on the
glossary file. I just thought I'd announce that I am also on the list, and
I'm looking forward to any questions or comments people may have. Thanks!
On Tue, Mar 10, 2020 at 11:37 AM Corey Huinker <[email protected]>
wrote:
> This latest version is an attempt at merging the work of Jürgen Purtz into
> what I had posted earlier. There was relatively little overlap in the terms
> we had chosen to define.
>
> Each glossary definition now has a reference id (good idea Jürgen), the
> form of which is "glossary-term". So we can link to the glossary from
> outside if we so choose.
>
> I encourage everyone to read the definitions, and suggest fixes to any
> inaccuracies or awkward phrasings. Mostly, though, I'm seeking feedback on
> the structure itself, and hoping to get that committed.
>
>
> On Tue, Feb 11, 2020 at 11:22 PM Corey Huinker <[email protected]>
> wrote:
>
>> It seems like this could be a good idea, still the patch has been
>>> waiting on his author for more than two weeks now, so I have marked it
>>> as returned with feedback.
>>>
>>
>> In light of feedback, I enlisted the help of an actual technical writer
>> (Roger Harkavy, CCed) and we eventually found the time to take a second
>> pass at this.
>>
>> Attached is a revised patch.
>>
>>
>
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-03-11 16:50 Jürgen Purtz <[email protected]>
parent: Roger Harkavy <[email protected]>
0 siblings, 2 replies; 97+ messages in thread
From: Jürgen Purtz @ 2020-03-11 16:50 UTC (permalink / raw)
To: Corey Huinker <[email protected]>; +Cc: Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
I made changes on top of 0001-add-glossary-page.patch which was supplied
by C. Huinker. This affects not only terms proposed by me but also his
original terms. If my changes are not obvious, please let me know and I
will describe my motivation.
Please note especially lines marked with question marks.
It will be helpful for diff-ing to restrict the length of lines in the
SGML files to 71 characters (as usual).
J. Purtz
Attachments:
[text/x-patch] 0002-add-glossary-page.patch (24.1K, 2-0002-add-glossary-page.patch)
download | inline diff:
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
index 851e9debe6..52169b86a2 100644
--- a/doc/src/sgml/glossary.sgml
+++ b/doc/src/sgml/glossary.sgml
@@ -1,7 +1,7 @@
<appendix id="glossary">
<title>Glossary</title>
<para>
- This is a list of terms and their in the context of <productname>PostgreSQL</productname> and <glossterm>Database</glossterm>s in general.
+ This is a list of terms and their meaning in the context of <productname>PostgreSQL</productname> and <glossterm>Database</glossterm>s in general.
</para>
<glosslist>
<glossentry id="glossary-aggregate">
@@ -44,7 +44,7 @@
<glossterm>Atomic</glossterm>
<glossdef>
<para>
- In reference to the value of an <glossterm>Attribute</glossterm> or <glossterm>Datum</glossterm>: cannot be broken up into smaller components.
+ In reference to the value of an <glossterm>Attribute</glossterm> or <glossterm>Datum</glossterm>: cannot be broken down into smaller components.
</para>
<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 <acronym>SQL</acronym> statements can be combined into a <glossterm>Transaction</glossterm>, and that <glossterm>transaction</glossterm> is said to be <glossterm>Atomic</glossterm>.
@@ -56,7 +56,7 @@
<glossterm>Attribute</glossterm>
<glossdef>
<para>
- A typed data element found within a <glossterm>Tuple</glossterm> or <glossterm>Relation</glossterm> or <glossterm>Table</glossterm>.
+ An element with a certain name and data type found within a <glossterm>Tuple</glossterm> or <glossterm>Table</glossterm>.
</para>
</glossdef>
</glossentry>
@@ -164,12 +164,30 @@ any <glossterm>Attribute</glossterm> in the <glossterm>Relation</glossterm>, but
</glossdef>
</glossentry>
+ <glossentry id="glossary-checkpoint">
+ <glossterm>Checkpoint</glossterm>
+ <glossdef>
+ <para>
+ A <link linkend="sql-checkpoint">
+ Checkpoint</link>
+ is a point in time when all older dirty
+ pages of the <glossterm>Shared Memory</glossterm>,
+ all older <glossterm>WAL records</glossterm>, and a
+ special <glossterm>Checkpoint record</glossterm>
+ have been written and flushed to disk.
+ </para>
+ </glossdef>
+ </glossentry>
+
<glossentry id="glossary-cluster">
<glossterm>Cluster</glossterm>
<glossdef>
<para>
A group of <glossterm>Database</glossterm>s plus their <glossterm>Global SQL Objects</glossterm>. The <glossterm>Cluster</glossterm> is managed by exactly one <glossterm>Instance</glossterm>. A newly created <glossterm>Cluster</glossterm> will have three <glossterm>Databases</glossterm> created automatically. They are <literal>template0</literal>, <literal>template1</literal>, and <literal>postgres</literal>. It is expected that an application will create one or more additional <glossterm>Databases</glossterm> aside from these three.
</para>
+ <para>
+ Don't confuse the <productname>PostgreSQL</productname> specific term <glossterm>Cluster</glossterm> with the SQL command <literal>Cluster</literal>.
+ </para>
</glossdef>
</glossentry>
@@ -198,7 +216,7 @@ any <glossterm>Attribute</glossterm> in the <glossterm>Relation</glossterm>, but
<glossterm>Concurrency</glossterm>
<glossdef>
<para>
- The concept that multiple independent operations can be happening within the <glossterm>Database</glossterm> at the same time.
+ The concept that multiple independent operations happen within the <glossterm>Database</glossterm> at the same time.
</para>
</glossdef>
</glossentry>
@@ -216,7 +234,7 @@ any <glossterm>Attribute</glossterm> in the <glossterm>Relation</glossterm>, but
<glossterm>Constraint</glossterm>
<glossdef>
<para>
- A method of restricting the values of data allowed within a <glossterm>Table</glossterm>.
+ A concept of restricting the values of data allowed within a <glossterm>Table</glossterm>.
</para>
<para>
For more information, see <link linkend="ddl-constraints">Constraints</link>.
@@ -238,7 +256,7 @@ any <glossterm>Attribute</glossterm> in the <glossterm>Relation</glossterm>, but
<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>. The name for this directory in configuration files is <productname>PGDATA</productname>.
+ files and subdirectories associated with a <glossterm>Cluster</glossterm> with the exception of tablespaces. The environment variable <literal>PGDATA</literal> often - but not always - referes to the <glossterm>Data Directory</glossterm>.
</para>
<para>
For more information, see <link linkend="storage-file-layout">Database Physical Storage: Database File Layout</link>.
@@ -250,7 +268,7 @@ files and subdirectories associated with a <glossterm>Cluster</glossterm>. The n
<glossterm>Database</glossterm>
<glossdef>
<para>
- A named collection of <glossterm>SQL Objects</glossterm>.
+ A named collection of <glossterm>SQL Objects</glossterm>.
</para>
<para>
For more information, see <link linkend="manage-ag-overview">Managing Databases: Overview</link>.
@@ -292,14 +310,13 @@ files and subdirectories associated with a <glossterm>Cluster</glossterm>. The n
<glossterm>File Segment</glossterm>
<glossdef>
<para>
- If a <glossterm>Database</glossterm> object grows in size past a designated limit, it may be
-split into multiple physical files. These files are called <glossterm>File Segments</glossterm>.
+ If a heap or index file grows in size over 1 GB, it will be split into multiple physical files. These files are called <glossterm>File Segments</glossterm>.
</para>
<para>
- (Don't confuse this term with the similar term <glossterm>WAL Segment</glossterm>).
+ For more information, see <link linkend="storage-file-layout">Database Physical Storage: Database File Layout</link>.
</para>
<para>
- For more information, see <link linkend="storage-file-layout">Database Physical Storage: Database File Layout</link>.
+ (Don't confuse this term with the similar term <glossterm>WAL Segment</glossterm>).
</para>
</glossdef>
</glossentry>
@@ -353,7 +370,7 @@ split into multiple physical files. These files are called <glossterm>File Segme
<glossterm>Function</glossterm>
<glossdef>
<para>
- Any pre-defined tranformation of data. Many <glossterm>Functions</glossterm> are already defined within <productname>PostgreSQL</productname> itself, but can also be user-defined.
+ Any pre-defined transformation of data. Many <glossterm>Functions</glossterm> are already defined within <productname>PostgreSQL</productname> itself, but can also be user-defined.
</para>
<para>
For more information, see <link linkend="sql-createfunction">SQL Commands: CREATE FUNCTION</link>.
@@ -365,7 +382,7 @@ split into multiple physical files. These files are called <glossterm>File Segme
<glossterm>Global SQL Object</glossterm>
<glossdef>
<para>
- Not all objects belong to a certain <glossterm>Schema</glossterm>, or to their <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.
+ 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.
</para>
</glossdef>
</glossentry>
@@ -391,7 +408,7 @@ split into multiple physical files. These files are called <glossterm>File Segme
</glossdef>
</glossentry>
- <glossentry id="host">
+ <glossentry id="glossary-host">
<glossterm>Host</glossterm>
<glossdef>
<para>
@@ -404,7 +421,7 @@ split into multiple physical files. These files are called <glossterm>File Segme
<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>) that stores the data in a way that makes specific values easier to retrieve.
+ 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 structure supports very fast retrieval of and access to the original data.
</para>
<para>
For more information, see <link linkend="sql-createindex">SQL Commands: CREATE INDEX</link>.
@@ -466,7 +483,33 @@ split into multiple physical files. These files are called <glossterm>File Segme
</glossdef>
</glossentry>
- <glossentry id="log-record">
+ <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, ... .
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-log-writer">
+ <glossterm>Log Writer</glossterm>
+ <glossdef>
+ <para>
+ If activated and parameterized, the
+ <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 creates
+ a new <glossterm>Log file</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-log-record">
<glossterm>Log Record</glossterm>
<glossdef>
<para>
@@ -528,10 +571,10 @@ data in the same way that a <glossterm>Table</glossterm> does. it cannot be modi
<glossterm>Partition</glossterm>
<glossdef>
<para>
- A <glossterm>Table</glossterm> that can be queried independently by its own name, but can also be queried via another <glossterm>Table</glossterm>, a partitioend <glossterm>Table</glossterm>, which is a collection of sub-<glossterm>Table</glossterm>s, each capable of holding one defined subset of information that does not overlap with any other <glossterm>Table</glossterm> in the set of <glossterm>Table</glossterm>s.
+ a) A <glossterm>Table</glossterm> that can be queried independently by its own name, but can also be queried via another <glossterm>Table</glossterm>, a partitionend <glossterm>Table</glossterm>, which is a collection of sub-<glossterm>Table</glossterm>s, each capable of holding one defined subset of information that does not overlap with any other <glossterm>Table</glossterm> in the set of <glossterm>Table</glossterm>s.
</para>
<para>
- A defined boundary used in an <glossterm>Analytic</glossterm> <glossterm>Function</glossterm> to identify which neighboring <glossterm>Rows</glossterm> can be considered by the <glossterm>Function</glossterm> for this particular <glossterm>Row</glossterm>.
+ b) A defined boundary used in an <glossterm>Analytic</glossterm> <glossterm>Function</glossterm> to identify which neighboring <glossterm>Rows</glossterm> can be considered by the <glossterm>Function</glossterm> for this particular <glossterm>Row</glossterm>.
</para>
</glossdef>
</glossentry>
@@ -573,7 +616,7 @@ data in the same way that a <glossterm>Table</glossterm> does. it cannot be modi
<glossterm>Record</glossterm>
<glossdef>
<para>
- A data structure that consists of one or more <glossterm>Attributes</glossterm> in a defined order.
+ See <link linkend="sql-revoke">Tupple</link>.
</para>
<para>
A single <glossterm>Row</glossterm> of a <glossterm>Table</glossterm> or other Relation.
@@ -603,7 +646,7 @@ data in the same way that a <glossterm>Table</glossterm> does. it cannot be modi
<glossterm>Replica</glossterm>
<glossdef>
<para>
- A <glossterm>Database</glossterm> that is paired with a Master <glossterm>Database</glossterm> and is maintaining a copy of some or all of the Master <glossterm>Database</glossterm>'s data. The primary reasons for doing this are to allow for greater access to that data, and to maintain availability of the data in the even that the <glossterm>Master</glossterm> becomes unavailable.
+ A <glossterm>Database</glossterm> that is paired with a Master <glossterm>Database</glossterm> and is maintaining a copy of some or all of the Master <glossterm>Database</glossterm>'s data. The primary reasons for doing this are to allow for greater access to that data, and to maintain availability of the data in the event that the <glossterm>Master</glossterm> becomes unavailable.
</para>
</glossdef>
</glossentry>
@@ -621,7 +664,7 @@ data in the same way that a <glossterm>Table</glossterm> does. it cannot be modi
<glossterm>Result Set</glossterm>
<glossdef>
<para>
- A data structure tranmitted 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. The data structure consists of zero or more <glossterm>Rows</glossterm> with the same ordered set of <glossterm>Attributes</glossterm>.
+ 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. The data structure consists of zero or more <glossterm>Rows</glossterm> with the same ordered set of <glossterm>Attributes</glossterm>.
</para>
</glossdef>
</glossentry>
@@ -666,7 +709,7 @@ data in the same way that a <glossterm>Table</glossterm> does. it cannot be modi
<glossterm>Row</glossterm>
<glossdef>
<para>
- A <glossterm>Tuple</glossterm> or <glossterm>Record</glossterm> found within a <glossterm>Relation</glossterm> or a <glossterm>Result Set</glossterm>. This term is often used interchangably with <glossterm>Record</glossterm> and <glossterm>Tuple</glossterm>.
+ See <link linkend="sql-revoke">Tupple</link>.
</para>
</glossdef>
</glossentry>
@@ -687,7 +730,22 @@ data in the same way that a <glossterm>Table</glossterm> does. it cannot be modi
<glossterm>Schema</glossterm>
<glossdef>
<para>
- A means of organizing a collection of objects residing in the same <glossterm>Database</glossterm> to facilitate clarity or security. <glossterm>Schema</glossterm>s are most often used in the same way that a namespace is used in programming languages. All objects belong to exactly one <glossterm>Schema</glossterm>, most commonly "public", the default <glossterm>Schema</glossterm>.
+ 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>
+ The names of <glossterm>SQL objects</glossterm> in the
+ schema are unique - even across different types of objects.
+ Same object names can only be used in different schemas.
+ </para>
+ <para>
+ Many <glossterm>SQL objects</glossterm> reside in the default
+ <glossterm>Schema</glossterm> <literal>public</literal>, but it
+ is expected that more schemas are created to hold application
+ specific <glossterm>SQL objects</glossterm>.
</para>
<para>
More generically, the term <glossterm>Schema</glossterm> is used to mean all data descriptions (<glossterm>Table</glossterm> definitions, <glossterm>Constraint</glossterm>s, comments) for a given <glossterm>Database</glossterm>.
@@ -717,7 +775,7 @@ data in the same way that a <glossterm>Table</glossterm> does. it cannot be modi
<glossterm>Serializable</glossterm>
<glossdef>
<para>
- <glossterm>Database</glossterm> <glossterm>Session</glossterm>s in a transaction defined as <literal>SERIALIZABLE</literal> are unable to see changes made to the <glossterm>Database</glossterm> by other sessions. In effect, the entire <glossterm>Database</glossterm> appears to be frozen in time for the duration of the <glossterm>Transaction</glossterm>.
+ 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>. (??? Isn't it the other way round: changes done by serializable transactions are not seen by other transactions ???)
</para>
</glossdef>
</glossentry>
@@ -747,7 +805,7 @@ data in the same way that a <glossterm>Table</glossterm> does. it cannot be modi
<glossterm>Sequence</glossterm>
<glossdef>
<para>
- An <glossterm>Database</glossterm> object which represents the mathematical concept of a generic numerical sequence. It can be thought of as a <glossterm>Table</glossterm> with exactly one <glossterm>Row</glossterm> and one <glossterm>Column</glossterm>. The value stores is know 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 curent value is moved in the defined direction by the defined interval step, and that value is returned to the invoking query, and the current value of the sequence is updated to reflect the new value. The value can be updated multiple times in a single query, the net effect being that each row selected will have a different value. Values taken from a <glossterm>Sequence</glossterm> are never reverted even in the case of a <glossterm>Rollback</glossterm>, which means that the <glossterm>Sequence</glossterm> will never emit the same number twice, and thus is the normal way of generating values to be put in a <glossterm>Primary Key</glossterm>.
+ An <glossterm>Database</glossterm> object which represents the 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 curent value is moved in the defined direction by the defined interval step, and that value is returned to the invoking query, and the current value of the sequence is updated to reflect the new value. The value can be updated multiple times in a single query, the net effect being that each row selected will have a different value. Values taken from a <glossterm>Sequence</glossterm> are never reverted even in the case of a <glossterm>Rollback</glossterm>, which means that the <glossterm>Sequence</glossterm> will never emit the same number twice, and thus is the normal way of generating values to be put in a <glossterm>Primary Key</glossterm>.
</para>
<para>
For more information, see <link linkend="sql-createsequence">SQL Commands: CREATE SEQUENCE</link>.
@@ -810,7 +868,7 @@ data in the same way that a <glossterm>Table</glossterm> does. it cannot be modi
<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 name and type). A <glossterm>Table</glossterm> is the most common form of <glossterm>Relation</glossterm> in <productname>PostgreSQL</productname>.
+ 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 name and type per position). A <glossterm>Table</glossterm> is the most common form of <glossterm>Relation</glossterm> in <productname>PostgreSQL</productname>.
</para>
<para>
For more information, see <link linkend="sql-createtable">SQL Commands: CREATE TABLE</link>.
@@ -834,7 +892,7 @@ data in the same way that a <glossterm>Table</glossterm> does. it cannot be modi
<glossterm>Transaction</glossterm>
<glossdef>
<para>
- A combination of one or more commands that must act as a single <glossterm>Atomic</glossterm> command: they all succeed or fail together, and their effects are not visible to other sessions until the <glossterm>Transaction</glossterm> is complete.
+ A combination of one or more commands that must act as a single <glossterm>Atomic</glossterm> command: they all succeed or fail together, and their effects are not visible to other sessions until the <glossterm>Transaction</glossterm> is complete. (??? non repeatable read, phantom read, serialization ananomaly are possible ???)
</para>
</glossdef>
</glossentry>
@@ -873,8 +931,8 @@ data in the same way that a <glossterm>Table</glossterm> does. it cannot be modi
<glossterm>Unlogged</glossterm>
<glossdef>
<para>
- A <glossterm>Relation</glossterm> that is unlogged will not have changes reflected in the <glossterm>WAL Log</glossterm>,
-which would enable those changes to be duplicated on a <glossterm>Replica</glossterm>, and also enables the change to survive a <glossterm>Database</glossterm> crash.
+ Changes to an unlogged <glossterm>Relation</glossterm> are not reflected in the <glossterm>WAL Log</glossterm>.
+ This disables replication and crash recovery for such <glossterm>Relations</glossterm>.
</para>
</glossdef>
</glossentry>
@@ -953,7 +1011,7 @@ cannot create <glossterm>Rows</glossterm> nor can it remove <glossterm>Rows</glo
<glossterm>WAL Record</glossterm>
<glossdef>
<para>
- A <glossterm>WAL Record</glossterm> contains either new or changed <glossterm>Heap</glossterm> or <glossterm>Index</glossterm> data or other binary information about a <command>COMMIT</command>, <command>ROLLBACK</command>, <command>SAVEPOINT</command>, or <glossterm>Checkpointer</glossterm> operation.
+ 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.
</para>
<para>
For more information, see <link linkend="wal-internals">Reliability and the Write-Ahead Log: WAL Internals</link>.
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-03-11 16:56 Corey Huinker <[email protected]>
parent: Jürgen Purtz <[email protected]>
1 sibling, 0 replies; 97+ messages in thread
From: Corey Huinker @ 2020-03-11 16:56 UTC (permalink / raw)
To: Jürgen Purtz <[email protected]>; +Cc: Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
On Wed, Mar 11, 2020 at 12:50 PM Jürgen Purtz <[email protected]> wrote:
> I made changes on top of 0001-add-glossary-page.patch which was supplied
> by C. Huinker. This affects not only terms proposed by me but also his
> original terms. If my changes are not obvious, please let me know and I
> will describe my motivation.
>
> Please note especially lines marked with question marks.
>
> It will be helpful for diff-ing to restrict the length of lines in the
> SGML files to 71 characters (as usual).
>
> J. Purtz
>
A new person replied off-list with some suggested edits, all of which
seemed pretty good. I'll incorporate them myself if that person chooses to
remain off-list.
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-03-11 17:23 Corey Huinker <[email protected]>
parent: Jürgen Purtz <[email protected]>
1 sibling, 2 replies; 97+ messages in thread
From: Corey Huinker @ 2020-03-11 17:23 UTC (permalink / raw)
To: Jürgen Purtz <[email protected]>; +Cc: Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
>
> It will be helpful for diff-ing to restrict the length of lines in the
> SGML files to 71 characters (as usual).
I did it that way for the following reasons
1. It aids grep-ability
2. The committers seem to be moving towards that for SQL strings, mostly
for reason #1
3. I recall that the code is put through a linter as one of the final steps
before release, I assumed that the SGML gets the same.
4. Even if #3 is false, its easy enough to do manually for me to do for
this one file once we've settled on the text of the definitions.
As for the changes, most things seem fine, I specifically like:
* Checkpoint - looks good
* yes, PGDATA should have been a literal
* Partition - the a/b split works for me
* Unlogged - it reads better
I'm not so sure on / responses to your ???s:
* The statement that names of schema objects are unique isn't *strictly* true,
just *mostly* true. Take the case of a unique constraints. The constraint
has a name and the unique index has the same name, to the point where
adding a unique constraint using an existing index renames that index to
conform to the constraint name.
* Serializable "other way around" question - It's both. Outside the
transaction you can't see changes made inside another transaction (though
you can be blocked by them), and inside serializable you can't see any
changes made since you started. Does that make sense? Were you asking a
different question?
* Transaction - yes, all those things could be "visible" or they could be
"side effects". It may be best to leave the over-simplified definition in
place, and add a "For more information see <<linref to
tutorial-transactions>>
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-03-11 17:36 Corey Huinker <[email protected]>
parent: Corey Huinker <[email protected]>
1 sibling, 0 replies; 97+ messages in thread
From: Corey Huinker @ 2020-03-11 17:36 UTC (permalink / raw)
To: Jürgen Purtz <[email protected]>; +Cc: Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
>
>
> * Transaction - yes, all those things could be "visible" or they could be
> "side effects". It may be best to leave the over-simplified definition in
> place, and add a "For more information see <<linref to
> tutorial-transactions>>
>
transaction-iso would be a better linkref in this case
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-03-13 04:18 Jürgen Purtz <[email protected]>
parent: Corey Huinker <[email protected]>
1 sibling, 1 reply; 97+ messages in thread
From: Jürgen Purtz @ 2020-03-13 04:18 UTC (permalink / raw)
To: Corey Huinker <[email protected]>; +Cc: Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
> The statement that names of schema objects are unique isn't
> /strictly/ true, just /mostly/ true. Take the case of a unique
> constraints.
Concerning CONSTRAINTS you are right. Constraints seems to be an exception:
* Their name belongs to a schema, but are not necessarily unique
within this context:
https://www.postgresql.org/docs/current/catalog-pg-constraint.html.
* There is a UNIQUE index within the system catalog pg_constraints:
"pg_constraint_conrelid_contypid_conname_index" UNIQUE, btree
(conrelid, contypid, conname), which expresses that names are unique
within the context of a table/constraint-type. Nevertheless tests
have shown that some stronger restrictions exists across
table-boarders (,which seems to be implemented in CREATE statements
- or as a consequence of your mentioned correlation between
constraint and index ?).
I hope that there are no more such exception to the global rule 'object
names in a schema are unique':
https://www.postgresql.org/docs/current/sql-createschema.html
This facts must be mentioned as a short note in glossary and in more
detail in the later patch about the architecture.
J. Purtz
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-03-19 02:34 Corey Huinker <[email protected]>
parent: Jürgen Purtz <[email protected]>
0 siblings, 1 reply; 97+ messages in thread
From: Corey Huinker @ 2020-03-19 02:34 UTC (permalink / raw)
To: Jürgen Purtz <[email protected]>; +Cc: Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
On Fri, Mar 13, 2020 at 12:18 AM Jürgen Purtz <[email protected]> wrote:
>
> The statement that names of schema objects are unique isn't *strictly* true,
> just *mostly* true. Take the case of a unique constraints.
>
> Concerning CONSTRAINTS you are right. Constraints seems to be an exception:
>
> - Their name belongs to a schema, but are not necessarily unique
> within this context:
> https://www.postgresql.org/docs/current/catalog-pg-constraint.html.
> - There is a UNIQUE index within the system catalog pg_constraints: "pg_constraint_conrelid_contypid_conname_index"
> UNIQUE, btree (conrelid, contypid, conname), which expresses that
> names are unique within the context of a table/constraint-type.
> Nevertheless tests have shown that some stronger restrictions exists across
> table-boarders (,which seems to be implemented in CREATE statements - or as
> a consequence of your mentioned correlation between constraint and index ?).
>
> I hope that there are no more such exception to the global rule 'object
> names in a schema are unique':
> https://www.postgresql.org/docs/current/sql-createschema.html
>
> This facts must be mentioned as a short note in glossary and in more
> detail in the later patch about the architecture.
>
>
> I did what I could to address the near uniqueness, as well as incorporate
your earlier edits into this new, squashed patch attached.
Attachments:
[text/x-patch] 0001-add-glossary-page-with-revisions.patch (49.4K, 3-0001-add-glossary-page-with-revisions.patch)
download | inline diff:
From dbce6922194eb4ad8de57e81e182b9a6eebf859e Mon Sep 17 00:00:00 2001
From: coreyhuinker <[email protected]>
Date: Tue, 10 Mar 2020 11:26:29 -0400
Subject: [PATCH] add glossary page with revisions
---
doc/src/sgml/filelist.sgml | 1 +
doc/src/sgml/glossary.sgml | 1072 ++++++++++++++++++++++++++++++++++++
doc/src/sgml/postgres.sgml | 1 +
3 files changed, 1074 insertions(+)
create mode 100644 doc/src/sgml/glossary.sgml
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 3da2365ea9..504c8a6326 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -170,6 +170,7 @@
<!ENTITY limits SYSTEM "limits.sgml">
<!ENTITY acronyms SYSTEM "acronyms.sgml">
+<!ENTITY glossary SYSTEM "glossary.sgml">
<!ENTITY features-supported SYSTEM "features-supported.sgml">
<!ENTITY features-unsupported SYSTEM "features-unsupported.sgml">
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
new file mode 100644
index 0000000000..d28bfb6fcf
--- /dev/null
+++ b/doc/src/sgml/glossary.sgml
@@ -0,0 +1,1072 @@
+<appendix id="glossary">
+ <title>Glossary</title>
+ <para>
+ This is a list of terms and their meaning in the context of <productname>PostgreSQL</productname> and <glossterm>Database</glossterm>s in general.
+ </para>
+ <glosslist>
+ <glossentry id="glossary-aggregate">
+ <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 non-common data.
+ </para>
+ <para>
+ For more information, see <link linkend="functions-aggregate">Aggregate Functions</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-analytic">
+ <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>.
+ </para>
+ <para>
+ For more information, see <link linkend="tutorial-window">Window Functions</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-archiver">
+ <glossterm>Archiver</glossterm>
+ <glossdef>
+ <para>
+ A process that backs up <glossterm>WAL Files</glossterm> in order to reclaim space on the file system.
+ </para>
+ <para>
+ For more information, see <link linkend="continuous-archiving">Backup and Restore: Continuous Archiving and Point-in-Time Recovery (PITR)</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-atomic">
+ <glossterm>Atomic</glossterm>
+ <glossdef>
+ <para>
+ In reference to the value of an <glossterm>Attribute</glossterm> or <glossterm>Datum</glossterm>: cannot be broken down into smaller components.
+ </para>
+ <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 <acronym>SQL</acronym> statements can be combined into a <glossterm>Transaction</glossterm>, and that <glossterm>transaction</glossterm> is said to be <glossterm>Atomic</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-attribute">
+ <glossterm>Attribute</glossterm>
+ <glossdef>
+ <para>
+ An element with a certain name and data type found within a <glossterm>Tuple</glossterm> or <glossterm>Table</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-autovacuum">
+ <glossterm>Autovacuum</glossterm>
+ <glossdef>
+ <para>
+ Processes that remove outdated <acronym>MVCC</acronym> <glossterm>Records</glossterm> of the <glossterm>Heap</glossterm> and <glossterm>Index</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="routine-vacuuming">Routine Database Maintenance Tasks: Routine Vacuuming</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-backend-process">
+ <glossterm>Backend Process</glossterm>
+ <glossdef>
+ <para>
+ Processes of an <glossterm>Instance</glossterm> which act on behalf of client <glossterm>Connections</glossterm> and handle their requests.
+ </para>
+ <para>
+ (Don't confuse this term with the similar terms <glossterm>Background Worker</glossterm> or <glossterm>Background Writer</glossterm>).
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-backend-server">
+ <glossterm>Backend Server</glossterm>
+ <glossdef>
+ <para>
+ See <glossterm>Instance</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-background-worker">
+ <glossterm>Background Worker</glossterm>
+ <glossdef>
+ <para>
+ Individual processes within an <glossterm>Instance</glossterm>, which 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>.
+ </para>
+ <para>
+ For more information, see <link linkend="bgworker">Background Worker Processes</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-background-writer">
+ <glossterm>Background Writer</glossterm>
+ <glossdef>
+ <para>
+ Writes continuously dirty pages from <glossterm>Shared Memory</glossterm> to the file system. It starts periodically, but works only for a short period in order to distribute
+expensive <acronym>I/O</acronym> activity over time instead of generating fewer large <acronym>I/O</acronym> peaks which could block other processes.
+ </para>
+ <para>
+ For more information, see <link linkend="runtime-config-resource">Server Configuration: Resource Consumption</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-cast">
+ <glossterm>Cast</glossterm>
+ <glossdef>
+ <para>
+ A conversion of a <glossterm>Datum</glossterm> from its current data type to another data type.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-catalog">
+ <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.
+ </para>
+ <para>
+ For more information, see <link linkend="manage-ag-overview">Managing Databases: Overview</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-check-constraint">
+ <glossterm>Check Constraint</glossterm>
+ <glossdef>
+ <para>
+ A type of <glossterm>Constraint</glossterm> defined on a <glossterm>Relation</glossterm> which restricts the values
+allowed in one or more <glossterm>Attributes</glossterm>. The <glossterm>Check Constraint</glossterm> can make reference to
+any <glossterm>Attribute</glossterm> in the <glossterm>Relation</glossterm>, but cannot reference other <glossterm>Rows</glossterm> of the same <glossterm>Relation</glossterm> or other <glossterm>Relations</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="ddl-constraints">Constraints</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-checkpointer">
+ <glossterm>Checkpointer</glossterm>
+ <glossdef>
+ <para>
+ A process that writes dirty pages and <glossterm>WAL Records</glossterm> 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.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-checkpoint">
+ <glossterm>Checkpoint</glossterm>
+ <glossdef>
+ <para>
+ A <link linkend="sql-checkpoint">
+ Checkpoint</link>
+ is a point in time when all older dirty
+ pages of the <glossterm>Shared Memory</glossterm>,
+ all older <glossterm>WAL records</glossterm>, and a
+ special <glossterm>Checkpoint record</glossterm>
+ have been written and flushed to disk.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-cluster">
+ <glossterm>Cluster</glossterm>
+ <glossdef>
+ <para>
+ A group of <glossterm>Database</glossterm>s plus their <glossterm>Global SQL Objects</glossterm>. The <glossterm>Cluster</glossterm> is managed by exactly one <glossterm>Instance</glossterm>. A newly created <glossterm>Cluster</glossterm> will have three <glossterm>Databases</glossterm> created automatically. They are <literal>template0</literal>, <literal>template1</literal>, and <literal>postgres</literal>. It is expected that an application will create one or more additional <glossterm>Databases</glossterm> aside from these three.
+ </para>
+ <para>
+ Don't confuse the <productname>PostgreSQL</productname> specific term <glossterm>Cluster</glossterm> with the SQL command <literal>Cluster</literal>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-column">
+ <glossterm>Column</glossterm>
+ <glossdef>
+ <para>
+ An <glossterm>Attribute</glossterm> found in a <glossterm>Table</glossterm> or <glossterm>View</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-commit">
+ <glossterm>Commit</glossterm>
+ <glossdef>
+ <para>
+ The act of finalizing a <glossterm>Transaction</glossterm> within the <glossterm>Database</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-commit">SQL Commands: COMMIT</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-concurrency">
+ <glossterm>Concurrency</glossterm>
+ <glossdef>
+ <para>
+ The concept that multiple independent operations happen within the <glossterm>Database</glossterm> at the same time.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-connection">
+ <glossterm>Connection</glossterm>
+ <glossdef>
+ <para>
+ A <acronym>TCP/IP</acronym> or socket line for inter-process communication. If the two involved processes reside on different servers, <acronym>TCP/IP</acronym> must be used. Otherwise both techniques are possible.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-constraint">
+ <glossterm>Constraint</glossterm>
+ <glossdef>
+ <para>
+ A concept of restricting the values of data allowed within a <glossterm>Table</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="ddl-constraints">Constraints</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-data-area">
+ <glossterm>Data Area</glossterm>
+ <glossdef>
+ <para>
+ See <glossterm>Data Directory</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-data-directory">
+ <glossterm>Data Directory</glossterm>
+ <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 <literal>PGDATA</literal> often - but not always - referes to the <glossterm>Data Directory</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="storage-file-layout">Database Physical Storage: Database File Layout</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-database">
+ <glossterm>Database</glossterm>
+ <glossdef>
+ <para>
+ A named collection of <glossterm>SQL Objects</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="manage-ag-overview">Managing Databases: Overview</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-database-server">
+ <glossterm>Database Server</glossterm>
+ <glossdef>
+ <para>
+ See <glossterm>Instance</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-datum">
+ <glossterm>Datum</glossterm>
+ <glossdef>
+ <para>
+ The internal representation of a <acronym>SQL</acronym> data type.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-delete">
+ <glossterm>Delete</glossterm>
+ <glossdef>
+ <para>
+ A <acronym>SQL</acronym> command whose purpose is to remove <glossterm>Rows</glossterm> from a given <glossterm>Table</glossterm> or <glossterm>Relation</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-delete">SQL Commands: DELETE</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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 into multiple physical files. These files are called <glossterm>File Segments</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="storage-file-layout">Database Physical Storage: Database File Layout</link>.
+ </para>
+ <para>
+ (Don't confuse this term with the similar term <glossterm>WAL Segment</glossterm>).
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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). With a Foreign Data Wrapper it is possible to define a <glossterm>Foreign Server</glossterm> and <glossterm>Foreign Tables</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-createforeigndatawrapper">SQL Commands: CREATE FOREIGN DATA WRAPPER</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-foreign-server">
+ <glossterm>Foreign Server</glossterm>
+ <glossdef>
+ <para>
+ A named collection of <glossterm>Foreign Tables</glossterm> which all use the same <glossterm>Foreign Data Wrapper</glossterm> and have other configuration values in common.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-createserver">SQL Commands: CREATE SERVER</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-foreign-table">
+ <glossterm>Foreign Table</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Relation</glossterm> which appears to have <glossterm>Rows</glossterm> and <glossterm>Columns</glossterm> similar to a regular <glossterm>Table</glossterm>, but will forward requests for data through its <glossterm>Foreign Data Wrapper</glossterm>, which will return <glossterm>Result Sets</glossterm> structured according to the definition of the <glossterm>Foreign Table</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-createforeigntable">SQL Commands: CREATE FOREIGN TABLE</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-function">
+ <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.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-createfunction">SQL Commands: CREATE FUNCTION</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-global-sql-object">
+ <glossterm>Global SQL Object</glossterm>
+ <glossdef>
+ <para>
+ 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.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-grant">
+ <glossterm>Grant</glossterm>
+ <glossdef>
+ <para>
+ A <acronym>SQL</acronym> command that is used to enable <glossterm>Users</glossterm> or <glossterm>Roles</glossterm> to access specific objects within the <glossterm>Database</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-grant">SQL Commands: GRANT</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-heap">
+ <glossterm>Heap</glossterm>
+ <glossdef>
+ <para>
+ Contains the original values of <glossterm>Row</glossterm> attributes (i.e. the data). The <glossterm>Heap</glossterm> is realized within <glossterm>Database</glossterm> files and mirrored in <glossterm>Shared Memory</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-host">
+ <glossterm>Host</glossterm>
+ <glossdef>
+ <para>
+ See <glossterm>Server</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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 structure supports very fast retrieval of and access to the original data.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-createindex">SQL Commands: CREATE INDEX</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-insert">
+ <glossterm>Insert</glossterm>
+ <glossdef>
+ <para>
+ A <acronym>SQL</acronym> command used to add new data into a <glossterm>Table</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-insert">SQL Commands: INSERT</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-instance">
+ <glossterm>Instance</glossterm>
+ <glossdef>
+ <para>
+ An <glossterm>Instance</glossterm> is a group of processes plus their common <glossterm>Shared Memory</glossterm> running on a single <glossterm>Server</glossterm>. The <glossterm>Instance</glossterm> handles all key features of a <acronym>DBMS</acronym>: read and write access to files and <glossterm>Shared Memory</glossterm>, assurance of the <acronym>ACID</acronym> paradigm, <acronym>MVCC</acronym>, <glossterm>Connections</glossterm> to client programms, backup, recovery, replication, privileges, etc.
+ </para>
+ <para>
+ An <glossterm>Instance</glossterm> manages exactly one <glossterm>Cluster</glossterm>.
+ </para>
+ <para>
+ Many <glossterm>Instances</glossterm> can run on the same server as long as they use different <acronym>IP</acronym> ports and manage different <glossterm>Cluster</glossterm>s. Different <glossterm>Instances</glossterm> on a server may use the same or different versions of <productname>PostgreSQL</productname>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-join">
+ <glossterm>Join</glossterm>
+ <glossdef>
+ <para>
+ A technique used with <command>SELECT</command> statements for correlating data in one or more <glossterm>Relations</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-key">
+ <glossterm>Key</glossterm>
+ <glossdef>
+ <para>
+ A means of identifying a <glossterm>Row</glossterm> within a <glossterm>Table</glossterm> or <glossterm>Relation</glossterm> by values contained within one or more <glossterm>Attributes</glossterm> in that <glossterm>Table</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-lock">
+ <glossterm>Lock</glossterm>
+ <glossdef>
+ <para>
+ A mechanism for one process temporarily preventing data from being manipulated by any other process.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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, ... .
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-log-writer">
+ <glossterm>Log Writer</glossterm>
+ <glossdef>
+ <para>
+ If activated and parameterized, the
+ <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 creates
+ a new <glossterm>Log file</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-log-record">
+ <glossterm>Log Record</glossterm>
+ <glossdef>
+ <para>
+ See <glossterm>WAL Record</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-logged">
+ <glossterm>Logged</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Table</glossterm> is considered <glossterm>Logged</glossterm> if changes to the <glossterm>Table</glossterm> 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>
+
+ <glossentry id="glossary-master">
+ <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>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-materialized">
+ <glossterm>Materialized</glossterm>
+ <glossdef>
+ <para>
+ The act of storing information rather than just the means of accessing 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 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 (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 that a <glossterm>Table</glossterm> does. it cannot be modified via <command>INSERT</command>, <command>UPDATE</command>, or <command>DELETE</command> operations.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-creatematerializedview">SQL Commands: CREATE MATERIALIZED VIEW</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-null">
+ <glossterm>Null</glossterm>
+ <glossdef>
+ <para>
+ A concept of non-existence that is a central tenet of Relational Database Theory. It represents the absence of value.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-partition">
+ <glossterm>Partition</glossterm>
+ <glossdef>
+ <para>
+ a) A <glossterm>Table</glossterm> that can be queried independently by its own name, but can also be queried via another <glossterm>Table</glossterm>, a partitionend <glossterm>Table</glossterm>, which is a collection of sub-<glossterm>Table</glossterm>s, each capable of holding one defined subset of information that does not overlap with any other <glossterm>Table</glossterm> in the set of <glossterm>Table</glossterm>s.
+ </para>
+ <para>
+ b) A defined boundary used in an <glossterm>Analytic</glossterm> <glossterm>Function</glossterm> to identify which neighboring <glossterm>Rows</glossterm> can be considered by the <glossterm>Function</glossterm> for this particular <glossterm>Row</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-postmaster">
+ <glossterm>Postmaster</glossterm>
+ <glossdef>
+ <para>
+ The very first process of an <glossterm>Instance</glossterm>. It starts the other processes and creates <glossterm>Backend Processes</glossterm> on demand.
+ </para>
+ <para>
+ For more information, see <link linkend="server-start">Server Setup and Operation: Starting the Database Server</link>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-procedure">
+ <glossterm>Procedure</glossterm>
+ <glossdef>
+ <para>
+ A defined set of instructions for manipulating data within a <glossterm>Database</glossterm>. <glossterm>Procedure</glossterm> can be written in a variety of programming languages. They may seem similar to <glossterm>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 as <command>COMMIT</command> and <command>ROLLBACK</command>.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-createprocedure">SQL Commands: CREATE PROCEDURE</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-record">
+ <glossterm>Record</glossterm>
+ <glossdef>
+ <para>
+ See <link linkend="sql-revoke">Tupple</link>.
+ </para>
+ <para>
+ A single <glossterm>Row</glossterm> of a <glossterm>Table</glossterm> or other Relation.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-referential-integrity">
+ <glossterm>Referential Integrity</glossterm>
+ <glossdef>
+ <para>
+ The means of restricting data in one <glossterm>Relation</glossterm> such that it must have matching data in another <glossterm>Relation</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-relation">
+ <glossterm>Relation</glossterm>
+ <glossdef>
+ <para>
+ The generic term for all objects in a <glossterm>Database</glossterm> that have a name and a list of <glossterm>Attributes</glossterm> defined in a specific order. <glossterm>Tables</glossterm>, <glossterm>Views</glossterm>, <glossterm>Foreign Tables</glossterm>, <glossterm>Materialized Views</glossterm>, and <glossterm>Indexes</glossterm> are all <glossterm>Relations</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-replica">
+ <glossterm>Replica</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Database</glossterm> that is paired with a Master <glossterm>Database</glossterm> and is maintaining a copy of some or all of the Master <glossterm>Database</glossterm>'s data. The primary reasons for doing this are to allow for greater access to that data, and to maintain availability of the data in the event that the <glossterm>Master</glossterm> becomes unavailable.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-replication">
+ <glossterm>Replication</glossterm>
+ <glossdef>
+ <para>
+ The act of reproducing data on one <glossterm>Server</glossterm> into another called a <glossterm>Replica</glossterm>. This can take the form of Physical <glossterm>Replication</glossterm>, where all file changes from one <glossterm>Server</glossterm> are copied verbatim, or Logical <glossterm>Replication</glossterm> where a defined subset of data changes are conveyed.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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. The data structure consists of zero or more <glossterm>Rows</glossterm> with the same ordered set of <glossterm>Attributes</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-revoke">
+ <glossterm>Revoke</glossterm>
+ <glossdef>
+ <para>
+ A command to reduce access to a named set of <glossterm>Database</glossterm> objects for a named list of <glossterm>Users</glossterm> and <glossterm>Roles</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-revoke">SQL Commands: REVOKE</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-role">
+ <glossterm>Role</glossterm>
+ <glossdef>
+ <para>
+ A collection of access privileges to the <glossterm>Database</glossterm>. <glossterm>Roles</glossterm> are themselves a privilege that can be granted to other roles. This is often done for convenience or to ensure completeness when multiple Users need the same privileges.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-createrole">SQL Commands: CREATE ROLE</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-rollback">
+ <glossterm>Rollback</glossterm>
+ <glossdef>
+ <para>
+ A command to undo all of the operations performed since the beginning of a <glossterm>Transaction</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-rollback">SQL Commands: ROLLBACK</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-row">
+ <glossterm>Row</glossterm>
+ <glossdef>
+ <para>
+ See <link linkend="sql-revoke">Tupple</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-savepoint">SQL Commands: SAVEPOINT</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-schema">
+ <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.
+ </para>
+ <para>
+ Many <glossterm>SQL objects</glossterm> reside in the default
+ <glossterm>Schema</glossterm> <literal>public</literal>, but it
+ is expected that more schemas are created to hold application
+ specific <glossterm>SQL objects</glossterm>.
+ </para>
+ <para>
+ More generically, the term <glossterm>Schema</glossterm> is used to mean all data descriptions (<glossterm>Table</glossterm> definitions, <glossterm>Constraint</glossterm>s, comments) for a given <glossterm>Database</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-segment">
+ <glossterm>Segment</glossterm>
+ <glossdef>
+ <para>
+ See <glossterm>File Segment</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-select">
+ <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>
+ </glossdef>
+ </glossentry>
+
+ <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>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-server">
+ <glossterm>Server</glossterm>
+ <glossdef>
+ <para>
+ The term <glossterm>Server</glossterm> denotes real hardware, a container, or a Virtual Machine.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-sequence">
+ <glossterm>Sequence</glossterm>
+ <glossdef>
+ <para>
+ An <glossterm>Database</glossterm> object which represents the 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 curent value is moved in the defined direction by the defined interval step, and that value is returned to the invoking query, and the current value of the sequence is updated to reflect the new value. The value can be updated multiple times in a single query, the net effect being that each row selected will have a different value. Values taken from a <glossterm>Sequence</glossterm> are never reverted even in the case of a <glossterm>Rollback</glossterm>, which means that the <glossterm>Sequence</glossterm> will never emit the same number twice, and thus is the normal way of generating values to be put in a <glossterm>Primary Key</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-createsequence">SQL Commands: CREATE SEQUENCE</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-shared-memory">
+ <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>, and stores additional common information. Note that <glossterm>Shared Memory</glossterm> belongs to the complete <glossterm>Instance</glossterm>, not to a single <glossterm>Database</glossterm>.
+ </para>
+ <para>
+ <glossterm>Shared Memory</glossterm> is organized into pages. If a page is modified, it is called a dirty page until it is written back to the file system.
+ </para>
+ <para>
+ For more information, see <link linkend="runtime-config-resource-memory">Server Configuration: Resource Consumption</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-sql-object">
+ <glossterm>SQL Object</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Table</glossterm>, <glossterm>View</glossterm>, <glossterm>Materialized View</glossterm>, <glossterm>Index</glossterm>, <glossterm>Constraint</glossterm>, <glossterm>Sequence</glossterm>, <glossterm>Function</glossterm>, <glossterm>Procedure</glossterm>, <glossterm>Trigger</glossterm>, data type, or operator. Every <glossterm>SQL Object</glossterm> belongs to exactly one <glossterm>Schema</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="manage-ag-overview">Managing Databases: Overview</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-stats-collector">
+ <glossterm>Stats Collector</glossterm>
+ <glossdef>
+ <para>
+ This process collects statistical information about the <glossterm>Cluster</glossterm>'s activities.
+ </para>
+ <para>
+ For more information, see <link linkend="monitoring-stats">Monitoring Database Activity: The Statistics Collector</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-system-catalog">
+ <glossterm>System Catalog</glossterm>
+ <glossdef>
+ <para>
+ A collection of <glossterm>Table</glossterm>s and <glossterm>View</glossterm>s which describe the structure of all <acronym>SQL</acronym> objects of the <glossterm>Database</glossterm> and the <glossterm>Global SQL Objects</glossterm> of the <glossterm>Cluster</glossterm>. The <glossterm>System Catalog</glossterm> resides in the schema <literal>pg_catalog</literal>. Main parts are mirrored as <glossterm>Views</glossterm> in the <glossterm>Schema</glossterm> <literal>information_schema</literal>.
+ </para>
+ <para>
+ For more information, see <link linkend="ddl-schemas">Data Definition: Schemas</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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 name and type per position). A <glossterm>Table</glossterm> is the most common form of <glossterm>Relation</glossterm> in <productname>PostgreSQL</productname>.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-createtable">SQL Commands: CREATE TABLE</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-temporary-tables">
+ <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 data in them is not visible to other <glossterm>Sessions</glossterm>, and is not <glossterm>Logged</glossterm>. <glossterm>Temporary Tables</glossterm> are most often used to store intermediate data for a multi-step data transformation.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-createtable">SQL Commands: CREATE TABLE</link>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-transaction">
+ <glossterm>Transaction</glossterm>
+ <glossdef>
+ <para>
+ A combination of one or more commands that must act as a single <glossterm>Atomic</glossterm> command: they all succeed or fail together, and their effects are not visible to other sessions until the <glossterm>Transaction</glossterm> is complete.
+ </para>
+ <para>
+ For more information, see <link linkend="transaction-iso">Transaction Isolation</link>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-trigger">
+ <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> executes within the same <glossterm>Transaction</glossterm> as the statement which invoked it, and if the <glossterm>Function</glossterm> fails then the invoking statement also fails.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-createtrigger">SQL Commands: CREATE TRIGGER</link>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-tuple">
+ <glossterm>Tuple</glossterm>
+ <glossdef>
+ <para>
+ A collection of <glossterm>Attributes</glossterm> in a fixed order. That order may be defined by the <glossterm>Table</glossterm> where the <glossterm>Tuple</glossterm> is found, in which case the <glossterm>Tuple</glossterm> is often called a <glossterm>Row</glossterm> or <glossterm>Record</glossterm>. It may also be defined by the structure of a <glossterm>Result Set</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-unique">
+ <glossterm>Unique</glossterm>
+ <glossdef>
+ <para>
+ The condition of having no matching values in the same <glossterm>Relation</glossterm>. Most often used in the concept of <glossterm>Unique Indexes</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-unlogged">
+ <glossterm>Unlogged</glossterm>
+ <glossdef>
+ <para>
+ Changes to an unlogged <glossterm>Relation</glossterm> are not reflected in the <glossterm>WAL Log</glossterm>.
+ This disables replication and crash recovery for such <glossterm>Relations</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-update">
+ <glossterm>Update</glossterm>
+ <glossdef>
+ <para>
+ A command used to modify <glossterm>Rows</glossterm> that already exist in a specified <glossterm>Table</glossterm>. It
+cannot create <glossterm>Rows</glossterm> nor can it remove <glossterm>Rows</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-update">SQL Commands: UPDATE</link>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-user">
+ <glossterm>User</glossterm>
+ <glossdef>
+ <para>
+ A specific case of a <glossterm>Role</glossterm> that is entitled to access (log into) the <glossterm>Database</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-user-mapping">
+ <glossterm>User Mapping</glossterm>
+ <glossdef>
+ <para>
+ The translation of user credentials in the local <glossterm>Database</glossterm> to credentials in a remote data system defined by a <glossterm>Foreign Data Wrapper</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-createusermapping">SQL Commands: CREATE USER MAPPING</link>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-view">
+ <glossterm>View</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Relation</glossterm> that is defined by a <command>SELECT</command> statement, but has no storage of its own. Any time a query references a <glossterm>View</glossterm>, the definition of the <glossterm>View</glossterm> is substituted into the query as if the user had typed that subquery instead of the name of the <glossterm>View</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="sql-createview">SQL Commands: CREATE VIEW</link>
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-wal-file">
+ <glossterm>WAL File</glossterm>
+ <glossdef>
+ <para>
+ <glossterm>WAL Records</glossterm> are continously written to the end of the current <glossterm>WAL File</glossterm>. <glossterm>WAL Files</glossterm> as well as <glossterm>WAL Records</glossterm> belong to the complete <glossterm>Cluster</glossterm>, not to a single <glossterm>Database</glossterm>. After a <glossterm>WAL File</glossterm> is full, a new <glossterm>WAL File</glossterm> is created or, under certain conditions, one of the previous <glossterm>WAL Files</glossterm> is renamed and reused.
+ </para>
+ <para>
+ The sequence of <glossterm>WAL Records</glossterm> in combination with the sequence of <glossterm>WAL Files</glossterm> represents the sequence of changes that have taken place in the <glossterm>Cluster</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="wal-internals">Reliability and the Write-Ahead Log: WAL Internals</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-wal-log">
+ <glossterm>WAL Log</glossterm>
+ <glossdef>
+ <para>
+ See <glossterm>WAL File</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-wal-record">
+ <glossterm>WAL Record</glossterm>
+ <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.
+ </para>
+ <para>
+ For more information, see <link linkend="wal-internals">Reliability and the Write-Ahead Log: WAL Internals</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-wal-segment">
+ <glossterm>WAL Segment</glossterm>
+ <glossdef>
+ <para>
+ See <glossterm>WAL File</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-wal-segment-file">
+ <glossterm>WAL Segment File</glossterm>
+ <glossdef>
+ <para>
+ See <glossterm>WAL File</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-wal-writer">
+ <glossterm>WAL Writer</glossterm>
+ <glossdef>
+ <para>
+ This process writes <glossterm>WAL Records</glossterm> from <glossterm>Shared Memory</glossterm> to <glossterm>WAL Files</glossterm>.
+ </para>
+ <para>
+ For more information, see <link linkend="runtime-config-wal">Server Configuration: Write Ahead Log</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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 set of <glossterm>Rows</glossterm> in a <glossterm>Result Set</glossterm>, but still retaining the original source
+data.
+ </para>
+ <para>
+ For more information, see <link linkend="tutorial-window">Window Functions</link>.
+ </para>
+ </glossdef>
+ </glossentry>
+ </glosslist>
+</appendix>
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index e59cba7997..2183e33bea 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -278,6 +278,7 @@
&docguide;
&limits;
&acronyms;
+ &glossary;
</part>
--
2.20.1
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-03-20 00:11 Alvaro Herrera <[email protected]>
parent: Corey Huinker <[email protected]>
0 siblings, 3 replies; 97+ messages in thread
From: Alvaro Herrera @ 2020-03-20 00:11 UTC (permalink / raw)
To: Corey Huinker <[email protected]>; +Cc: Jürgen Purtz <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
I gave this a look. I first reformatted it so I could read it; that's
0001. Second I changed all the long <link> items into <xref>s, which
are shorter and don't have to repeat the title of the refered to page.
(Of course, this changes the link to be in the same style as every other
link in our documentation; some people don't like it. But it's our
style.)
There are some mistakes. "Tupple" is most glaring one -- not just the
typo but also the fact that it goes to sql-revoke. A few definitions
we'll want to modify. Nothing too big. In general I like this work and
I think we should have it in pg13.
Please bikeshed the definition of your favorite term, and suggest what
other terms to add. No pointing out of mere typos yet, please.
I think we should have the terms Consistency, Isolation, Durability.
--
Álvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-03-20 01:41 Corey Huinker <[email protected]>
parent: Alvaro Herrera <[email protected]>
2 siblings, 1 reply; 97+ messages in thread
From: Corey Huinker @ 2020-03-20 01:41 UTC (permalink / raw)
To: Alvaro Herrera <[email protected]>; +Cc: Jürgen Purtz <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
On Thu, Mar 19, 2020 at 8:11 PM Alvaro Herrera <[email protected]>
wrote:
> I gave this a look. I first reformatted it so I could read it; that's
> 0001. Second I changed all the long <link> items into <xref>s, which
>
Thanks! I didn't know about xrefs, that is a big improvement.
> are shorter and don't have to repeat the title of the refered to page.
> (Of course, this changes the link to be in the same style as every other
> link in our documentation; some people don't like it. But it's our
> style.)
>
> There are some mistakes. "Tupple" is most glaring one -- not just the
> typo but also the fact that it goes to sql-revoke. A few definitions
> we'll want to modify. Nothing too big. In general I like this work and
> I think we should have it in pg13.
>
> Please bikeshed the definition of your favorite term, and suggest what
> other terms to add. No pointing out of mere typos yet, please.
>
Jürgen mentioned off-list that the man page doesn't build. I was going to
look into that, but if anyone has more familiarity with that, I'm listening.
> I think we should have the terms Consistency, Isolation, Durability.
>
+1
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-03-20 15:48 Corey Huinker <[email protected]>
parent: Corey Huinker <[email protected]>
0 siblings, 1 reply; 97+ messages in thread
From: Corey Huinker @ 2020-03-20 15:48 UTC (permalink / raw)
To: Alvaro Herrera <[email protected]>; +Cc: Jürgen Purtz <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
>
> Jürgen mentioned off-list that the man page doesn't build. I was going to
>> look into that, but if anyone has more familiarity with that, I'm listening.
>>
>
Looking at this some more, I'm not sure anything needs to be done for man
pages. man1 is for executables, man3 seems to be dblink and SPI, and man7
is all SQL commands. This isn't any of those. The only possible thing left
would be how to render the text of a <glossterm>foo</glossterm, and so I
looked to see what we do in man pages for acronyms, and the answer appears
to be "nothing":
postgres/doc/src$ git grep acronym | grep -v '\/acronym'
sgml/filelist.sgml:<!ENTITY acronyms SYSTEM "acronyms.sgml">
sgml/postgres.sgml: &acronyms;
sgml/release.sgml:[A-Z][A-Z_ ]+[A-Z_] <command>, <literal>,
<envar>, <acronym>
sgml/stylesheet.css:acronym { font-style: inherit; }
filelist.sgml, postgres.sgml, ans stylesheet.css already have the
corresponding change, and the release.sgml is just an incidental mention of
acronym.
Of course I could be missing something.
>
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-03-20 17:51 Alvaro Herrera <[email protected]>
parent: Corey Huinker <[email protected]>
0 siblings, 2 replies; 97+ messages in thread
From: Alvaro Herrera @ 2020-03-20 17:51 UTC (permalink / raw)
To: Corey Huinker <[email protected]>; +Cc: Jürgen Purtz <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
On 2020-Mar-20, Corey Huinker wrote:
> > Jürgen mentioned off-list that the man page doesn't build. I was going to
> > look into that, but if anyone has more familiarity with that, I'm listening.
> Looking at this some more, I'm not sure anything needs to be done for man
> pages.
Yeah, I don't think he was saying that we needed to do anything to
produce a glossary man page; rather that the "make man" command failed.
I tried it here, and indeed it failed. But on further investigation,
after a "make maintainer-clean" it no longer failed. I'm not sure what
to make of it, but it seems that this patch needn't concern itself with
that.
I gave a read through the first few actual definitions. It's a much
slower work than I thought! Attached you'll find the first few edits
that I propose.
Looking at the definition of "Aggregate" it seemed weird to have it
stand as a verb infinitive. I looked up other glossaries, found this
one
https://www.gartner.com/en/information-technology/glossary?glossaryletter=T
and realized that when they do verbs, they put the present participle
(-ing) form. So I changed it to "Aggregating", and split out the
"Aggregate function" into its own term.
In Atomic, there seemed to be excessive use of <glossterm> in the
definitions. Style guides seem to suggest to do that only the first
time you use a term in a definition. I removed some markup.
I'm not sure about some terms such as "analytic" and "backend server".
I put them in XML comments for now.
The other changes should be self-explanatory.
It's hard to review work from a professional tech writer. I'm under the
constant impression that I'm ruining somebody's perfect end product,
making a fool of myself.
--
Álvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Attachments:
[text/x-diff] glossary-3.patch (7.7K, 2-glossary-3.patch)
download | inline diff:
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
index 612ce6e5f4..05fca33d9b 100644
--- a/doc/src/sgml/glossary.sgml
+++ b/doc/src/sgml/glossary.sgml
@@ -6,25 +6,34 @@
systems in general.
</para>
<glosslist>
- <glossentry id="glossary-aggregate">
- <glossterm>Aggregate</glossterm>
+ <glossentry id="glossary-aggregating">
+ <glossterm>Aggregating</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
- non-common data.
+ The act of combining a collection of data (input) values into
+ a single output value, which may not be of the same type as the
+ input values.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-aggregate">
+ <glossterm>Aggregate Function</glossterm>
+ <glossdef>
+ A <glossterm>Function</glossterm> that combines multiple input values,
+ for example by counting, averaging or adding them all together,
+ yielding a single output value.
</para>
<para>
For more information, see
<xref linkend="functions-aggregate"/>.
</para>
+ <para>
+ See also <glossterm>Window Function</glossterm>.
</glossdef>
</glossentry>
+<!--
<glossentry id="glossary-analytic">
<glossterm>Analytic</glossterm>
<glossdef>
@@ -39,13 +48,15 @@
</para>
</glossdef>
</glossentry>
+-->
<glossentry id="glossary-archiver">
<glossterm>Archiver</glossterm>
<glossdef>
<para>
- A process that backs up <glossterm>WAL Files</glossterm> in order to
- reclaim space on the file system.
+ A process that saves aside copies of <glossterm>WAL Files</glossterm>,
+ for the purposes of creating backup copies or keeping
+ <glossterm>Replicas</glossterm> current.
</para>
<para>
For more information, see
@@ -59,16 +70,15 @@
<glossdef>
<para>
In reference to the value of an <glossterm>Attribute</glossterm> or
- <glossterm>Datum</glossterm>: cannot be broken down into smaller
- components.
+ <glossterm>Datum</glossterm>: the property that it cannot be broken down
+ into smaller components.
</para>
<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
<acronym>SQL</acronym> statements can be combined into a
<glossterm>Transaction</glossterm>, and that
- <glossterm>transaction</glossterm> is said to be
- <glossterm>Atomic</glossterm>.
+ transaction is said to be atomic.
</para>
</glossdef>
</glossentry>
@@ -112,6 +122,7 @@
</glossdef>
</glossentry>
+<!--
<glossentry id="glossary-backend-server">
<glossterm>Backend Server</glossterm>
<glossdef>
@@ -120,6 +131,7 @@
</para>
</glossdef>
</glossentry>
+-->
<glossentry id="glossary-background-worker">
<glossterm>Background Worker</glossterm>
@@ -142,8 +154,9 @@
<glossterm>Background Writer</glossterm>
<glossdef>
<para>
- Writes continuously dirty pages from <glossterm>Shared
- Memory</glossterm> to the file system. It starts periodically, but
+ A process that continuously writes dirty pages from
+ <glossterm>Shared Memory</glossterm> to the file system.
+ It starts periodically, but
works only for a short period in order to distribute expensive
<acronym>I/O</acronym> activity over time instead of generating fewer
large <acronym>I/O</acronym> peaks which could block other processes.
@@ -218,10 +231,9 @@
<glossterm>Checkpoint</glossterm>
<glossdef>
<para>
- A <link linkend="sql-checkpoint"> Checkpoint</link> is a point in time
- when all older dirty pages of the <glossterm>Shared
- Memory</glossterm>, all older <glossterm>WAL records</glossterm>, and
- a special <glossterm>Checkpoint record</glossterm> have been written
+ A point in time when all older dirty pages of the
+ <glossterm>Shared Memory</glossterm>, all older <glossterm>WAL records</glossterm>,
+ and a special <glossterm>Checkpoint record</glossterm> have been written
and flushed to disk.
</para>
</glossdef>
@@ -543,8 +555,8 @@
<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
+ <glossterm>Table</glossterm> (or other kind of <glossterm>Relation</glossterm>
+ such as a <glossterm>Materialized View</glossterm>). Its internal
structure supports very fast retrieval of and access to the original
data.
</para>
@@ -815,7 +827,7 @@
<glossterm>Record</glossterm>
<glossdef>
<para>
- See <link linkend="sql-revoke">Tupple</link>.
+ See <glossterm>Tuple</glossterm>.
</para>
<para>
A single <glossterm>Row</glossterm> of a <glossterm>Table</glossterm>
@@ -944,7 +956,7 @@
<glossterm>Row</glossterm>
<glossdef>
<para>
- See <link linkend="sql-revoke">Tupple</link>.
+ See <glossterm>Tuple</glossterm>.
</para>
</glossdef>
</glossentry>
@@ -1194,9 +1206,9 @@
<glossterm>Session</glossterm> or a
<glossterm>Transaction</glossterm>, as defined at creation time. The
data in them is not visible to other <glossterm>Sessions</glossterm>,
- and is not <glossterm>Logged</glossterm>. <glossterm>Temporary
- Tables</glossterm> are most often used to store intermediate data for
- a multi-step data transformation.
+ and is not <glossterm>Logged</glossterm>.
+ <glossterm>Temporary Tables</glossterm> are often used to store
+ intermediate data for a multi-step data transformation.
</para>
<para>
For more information, see
@@ -1227,8 +1239,9 @@
<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>
+ <command>UPDATE</command>, <command>DELETE</command>,
+ <command>TRUNCATE</command>) is applied to a <glossterm>Relation</glossterm>.
+ A <glossterm>Trigger</glossterm>
executes within the same <glossterm>Transaction</glossterm> as the
statement which invoked it, and if the <glossterm>Function</glossterm>
fails then the invoking statement also fails.
@@ -1249,8 +1262,8 @@
the <glossterm>Tuple</glossterm> is found, in which case the
<glossterm>Tuple</glossterm> is often called a
<glossterm>Row</glossterm> or <glossterm>Record</glossterm>. It may
- also be defined by the structure of a <glossterm>Result
- Set</glossterm>.
+ also be defined by the structure of a
+ <glossterm>Result Set</glossterm>.
</para>
</glossdef>
</glossentry>
@@ -1260,7 +1273,7 @@
<glossdef>
<para>
The condition of having no matching values in the same
- <glossterm>Relation</glossterm>. Most often used in the concept of
+ <glossterm>Relation</glossterm>. Often used in the concept of
<glossterm>Unique Indexes</glossterm>.
</para>
</glossdef>
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-03-20 18:08 Roger Harkavy <[email protected]>
parent: Alvaro Herrera <[email protected]>
1 sibling, 0 replies; 97+ messages in thread
From: Roger Harkavy @ 2020-03-20 18:08 UTC (permalink / raw)
To: Alvaro Herrera <[email protected]>; +Cc: Corey Huinker <[email protected]>; Jürgen Purtz <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
Alvaro, I know that you are joking, but I want to impress on everyone:
please don't feel like anyone here is breaking anything when it comes to
modifying the content and structure of this glossary.
I do have technical writing experience, but everyone else here is a subject
matter expert when it comes to the world of databases and how this one in
particular functions.
On Fri, Mar 20, 2020 at 1:51 PM Alvaro Herrera <[email protected]>
wrote:
> On 2020-Mar-20, Corey Huinker wrote:
>
> > > Jürgen mentioned off-list that the man page doesn't build. I was going
> to
> > > look into that, but if anyone has more familiarity with that, I'm
> listening.
>
> > Looking at this some more, I'm not sure anything needs to be done for man
> > pages.
>
> Yeah, I don't think he was saying that we needed to do anything to
> produce a glossary man page; rather that the "make man" command failed.
> I tried it here, and indeed it failed. But on further investigation,
> after a "make maintainer-clean" it no longer failed. I'm not sure what
> to make of it, but it seems that this patch needn't concern itself with
> that.
>
> I gave a read through the first few actual definitions. It's a much
> slower work than I thought! Attached you'll find the first few edits
> that I propose.
>
> Looking at the definition of "Aggregate" it seemed weird to have it
> stand as a verb infinitive. I looked up other glossaries, found this
> one
> https://www.gartner.com/en/information-technology/glossary?glossaryletter=T
> and realized that when they do verbs, they put the present participle
> (-ing) form. So I changed it to "Aggregating", and split out the
> "Aggregate function" into its own term.
>
> In Atomic, there seemed to be excessive use of <glossterm> in the
> definitions. Style guides seem to suggest to do that only the first
> time you use a term in a definition. I removed some markup.
>
> I'm not sure about some terms such as "analytic" and "backend server".
> I put them in XML comments for now.
>
> The other changes should be self-explanatory.
>
> It's hard to review work from a professional tech writer. I'm under the
> constant impression that I'm ruining somebody's perfect end product,
> making a fool of myself.
>
> --
> Álvaro Herrera https://www.2ndQuadrant.com/
> PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
>
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-03-20 18:16 Corey Huinker <[email protected]>
parent: Alvaro Herrera <[email protected]>
1 sibling, 1 reply; 97+ messages in thread
From: Corey Huinker @ 2020-03-20 18:16 UTC (permalink / raw)
To: Alvaro Herrera <[email protected]>; +Cc: Jürgen Purtz <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
>
> It's hard to review work from a professional tech writer. I'm under the
> constant impression that I'm ruining somebody's perfect end product,
> making a fool of myself.
If it makes you feel better, it's a mix of definitions I wrote that Roger
proofed and restructured, ones that Jürgen had written for a separate
effort which then got a Roger-pass, and then some edits of my own and some
by Jürgen which I merged without consulting Roger.
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-03-20 19:58 Justin Pryzby <[email protected]>
parent: Alvaro Herrera <[email protected]>
2 siblings, 2 replies; 97+ messages in thread
From: Justin Pryzby @ 2020-03-20 19:58 UTC (permalink / raw)
To: Alvaro Herrera <[email protected]>; +Cc: Corey Huinker <[email protected]>; Jürgen Purtz <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
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 ?
> + <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" ?
> + <glossterm>Backend Process</glossterm>
> + <glossdef>
> + <para>
> + Processes of an <glossterm>Instance</glossterm> which act on behalf of
Say DATABASE instance
> + <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"
> + <glossterm>Background Writer</glossterm>
Add "process" ?
> + <glossdef>
> + <para>
> + Writes continuously dirty pages from <glossterm>Shared
Say "Continuously writes"
> + Memory</glossterm> to the file system. It starts periodically, but
Hm, maybe "wakes up periodically"
> + <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 ?
> + 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.
> + <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.
> + <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.
> + <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".
> + <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.
> + <glossterm>Delete</glossterm>
> + <glossdef>
> + <para>
> + A <acronym>SQL</acronym> command whose purpose is to remove
just say "which removes"
> + <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".
> + <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 ?
> + (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".
> + <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.
> + <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..."
> + <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?
> + <glossterm>Log Writer</glossterm>
process
> + <glossdef>
> + <para>
> + If activated and parameterized, the
I don't know what parameterized means here
> + <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..
> + <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.
> + <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>>
> + <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.
> + <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
> + <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 ?
> + <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.
> + <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".
> + <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
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.
--
Justin
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-03-20 22:32 Jürgen Purtz <[email protected]>
parent: Corey Huinker <[email protected]>
0 siblings, 1 reply; 97+ messages in thread
From: Jürgen Purtz @ 2020-03-20 22:32 UTC (permalink / raw)
To: Corey Huinker <[email protected]>; Alvaro Herrera <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>; Justin Pryzby <[email protected]>
man pages: Sorry, if I confused someone with my poor English. I just
want to express in my 'offline' mail that we don't have to worry about
man page generation. The patch doesn't affect files in the /ref
subdirectory from where man pages are created.
review process: Yes, it will be time-consumptive and it may be a hard
job because of a) the patch has multiple authors with divergent writing
styles and b) the terms affect different fundamental issues: SQL basics
and PG basics. Concerning PG basics in the past we used a wide range of
similar terms with different meanings as well as different terms for the
same matter - within our documentation as well as in secondary
publications. The terms "backend server" / "instance" are such an
example and there shall be a clear decision in favor of one of the two.
Presumably we will see more discussions about the question which one is
the preferred term (remember the discussion concerning the terms
master/slave, primary/secondary some weeks ago).
ongoing: Intermediate questions for clarifications are welcome.
Kind regards, Jürgen
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-03-20 22:32 Jürgen Purtz <[email protected]>
parent: Justin Pryzby <[email protected]>
1 sibling, 2 replies; 97+ messages in thread
From: Jürgen Purtz @ 2020-03-20 22:32 UTC (permalink / raw)
To: Justin Pryzby <[email protected]>; Alvaro Herrera <[email protected]>; +Cc: Corey Huinker <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
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
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-03-20 23:03 Justin Pryzby <[email protected]>
parent: Jürgen Purtz <[email protected]>
1 sibling, 1 reply; 97+ messages in thread
From: Justin Pryzby @ 2020-03-20 23:03 UTC (permalink / raw)
To: Jürgen Purtz <[email protected]>; +Cc: Alvaro Herrera <[email protected]>; Corey Huinker <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
On Fri, Mar 20, 2020 at 11:32:25PM +0100, Jürgen Purtz wrote:
> > > + <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.
>
> ???
"A <<Table>> or other >>Relation<<" is larger than a >Cluster's< segment size
is stored in multiple physical files. This avoids file size limitations which
vary across operating systems."
https://www.postgresql.org/docs/devel/runtime-config-preset.html
ts=# SELECT name, setting, unit, category, short_desc FROM pg_settings WHERE name~'block_size|segment_size';
name | setting | unit | category | short_desc
------------------+----------+------+----------------+----------------------------------------------
block_size | 8192 | | Preset Options | Shows the size of a disk block.
segment_size | 131072 | 8kB | Preset Options | Shows the number of pages per disk file.
wal_block_size | 8192 | | Preset Options | Shows the block size in the write ahead log.
wal_segment_size | 16777216 | B | Preset Options | Shows the size of write ahead log segments.
> > > + <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.
Maybe "this is the content of rows/attributes in >>Tables<< or other >>Relations<<".
or "this is the data store for ..."
> > > + <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".
I think that suggests just removing "host" and consistently saying "server".
--
Justin
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-03-21 03:45 Corey Huinker <[email protected]>
parent: Jürgen Purtz <[email protected]>
0 siblings, 0 replies; 97+ messages in thread
From: Corey Huinker @ 2020-03-21 03:45 UTC (permalink / raw)
To: Jürgen Purtz <[email protected]>; +Cc: Alvaro Herrera <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>; Justin Pryzby <[email protected]>
On Fri, Mar 20, 2020 at 6:32 PM Jürgen Purtz <[email protected]> wrote:
> man pages: Sorry, if I confused someone with my poor English. I just
> want to express in my 'offline' mail that we don't have to worry about
> man page generation. The patch doesn't affect files in the /ref
> subdirectory from where man pages are created.
>
It wasn't your poor English - everyone else understood what you meant. I
had wondered if our docs went into man page format as well, so my research
was still time well spent.
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-03-21 14:08 Jürgen Purtz <[email protected]>
parent: Justin Pryzby <[email protected]>
0 siblings, 1 reply; 97+ messages in thread
From: Jürgen Purtz @ 2020-03-21 14:08 UTC (permalink / raw)
To: Justin Pryzby <[email protected]>; Alvaro Herrera <[email protected]>; Corey Huinker <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
On 21.03.20 00:03, Justin Pryzby wrote:
>>>> + <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".
> I think that suggests just removing "host" and consistently saying "server".
"server", "host", "database server": All three terms are used
intensively in the documentation. When we define glossary terms, we
should also take into account the consequences for those parts.
"database server" is the most diffuse. E.g.: In 'config.sgml' he is used
in the sense of some hardware or VM "... If you have a dedicated
database server with 1GB or more of RAM ..." as well as in the sense of
an instance "... To start the database server on the command prompt
...". Additionally the term is completely misleading. In both cases we
do not mean something which is related to a database but something which
is related to a cluster.
In the past, people accepted such blurs. My - minimal - intention is to
raise awareness of such ambiguities, or - better - to clearly define the
situation in the glossary. But this is only a first step. The second
step shall be a rework of the documentation to use the preferred terms
defined in the glossary. Because there will be a time gap between the
two steps, we may want to be a little chatty in the glossary and define
ambiguous terms as shown in the following example:
---
Server: The term "Server" denotes .... .
Host: An outdated term which will be replaced by
<xref-to-the-glossary>Server</xref> over time.
Database Server: An outdated term which sometimes denotes a
<xref-to-the-glossary>Server</xref> and sometimes an
<xref-to-the-glossary>Instance</xref>.
---
This is a pattern for all terms which we currently described with the
phrase "See ...". Later, after reviewing the documentation by
eliminating the non-preferred terms, the glossary entries with "An
outdated term ..." can be dropped.
In the last days we have seen many huge and small proposals. I think, it
will be helpful to summarize this work by waiting for a patch from
Alvaro containing everything it deems useful from his point of view.
Kind regards, Jürgen
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-03-21 15:15 Justin Pryzby <[email protected]>
parent: Jürgen Purtz <[email protected]>
0 siblings, 0 replies; 97+ messages in thread
From: Justin Pryzby @ 2020-03-21 15:15 UTC (permalink / raw)
To: Jürgen Purtz <[email protected]>; +Cc: Alvaro Herrera <[email protected]>; Corey Huinker <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
On Sat, Mar 21, 2020 at 03:08:30PM +0100, Jürgen Purtz wrote:
> On 21.03.20 00:03, Justin Pryzby wrote:
> > > > > + <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".
> > I think that suggests just removing "host" and consistently saying "server".
>
> "server", "host", "database server": All three terms are used intensively in
> the documentation. When we define glossary terms, we should also take into
> account the consequences for those parts.
The documentation uses "host", but doesn't always mean "server".
$ git grep -Fw host doc/src/
doc/src/sgml/backup.sgml: that you can perform this backup procedure from any remote host that has
pg_hba appears to be all about client "hosts".
FATAL: no pg_hba.conf entry for host "123.123.123.123", user "andym", database "testdb"
--
Justin
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-03-24 18:26 Peter Eisentraut <[email protected]>
parent: Alvaro Herrera <[email protected]>
2 siblings, 0 replies; 97+ messages in thread
From: Peter Eisentraut @ 2020-03-24 18:26 UTC (permalink / raw)
To: Alvaro Herrera <[email protected]>; Corey Huinker <[email protected]>; +Cc: Jürgen Purtz <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
On 2020-03-20 01:11, Alvaro Herrera wrote:
> I gave this a look. I first reformatted it so I could read it; that's
> 0001. Second I changed all the long <link> items into <xref>s, which
> are shorter and don't have to repeat the title of the refered to page.
> (Of course, this changes the link to be in the same style as every other
> link in our documentation; some people don't like it. But it's our
> style.)
AFAICT, all the <link> elements in this patch should be changed to <xref>.
If there is something undesirable about the output style, we can change
that, but it's not this patch's job to make up its own rules.
--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-03-24 18:46 Robert Haas <[email protected]>
parent: Justin Pryzby <[email protected]>
1 sibling, 2 replies; 97+ messages in thread
From: Robert Haas @ 2020-03-24 18:46 UTC (permalink / raw)
To: Justin Pryzby <[email protected]>; +Cc: Alvaro Herrera <[email protected]>; Corey Huinker <[email protected]>; Jürgen Purtz <[email protected]>; Roger Harkavy <[email protected]>; [email protected] <[email protected]>; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
On Fri, Mar 20, 2020 at 3:58 PM Justin Pryzby <[email protected]> wrote:
> > + 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.
> An FK doesn't require the values in its table to be unique, right ?
I believe it does require that the values are unique.
> I think there's some confusion. Constraints are not objects, right ?
I think constraints are definitely objects. They have names and you
can, for example, COMMENT on them.
> Do we use shared_buffers for WAL ?
No.
(I have not reviewed the patch; these are just a few comments on your comments.)
--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-03-24 19:27 Corey Huinker <[email protected]>
parent: Robert Haas <[email protected]>
1 sibling, 0 replies; 97+ messages in thread
From: Corey Huinker @ 2020-03-24 19:27 UTC (permalink / raw)
To: Robert Haas <[email protected]>; +Cc: Justin Pryzby <[email protected]>; Alvaro Herrera <[email protected]>; Jürgen Purtz <[email protected]>; Roger Harkavy <[email protected]>; [email protected] <[email protected]>; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
>
>
> > > + Records</glossterm> to the file system and creates a special
> >
> > Does the chckpointer actually write WAL ?
>
> Yes.
>
> > An FK doesn't require the values in its table to be unique, right ?
>
> I believe it does require that the values are unique.
>
> > I think there's some confusion. Constraints are not objects, right ?
>
> I think constraints are definitely objects. They have names and you
> can, for example, COMMENT on them.
>
> > Do we use shared_buffers for WAL ?
>
> No.
>
> (I have not reviewed the patch; these are just a few comments on your
> comments.)
>
>
I'm going to be coalescing the feedback into an updated patch very soon
(tonight/tomorrow), so please keep the feedback on the text/wording coming
until then.
If anyone has a first attempt at all the ACID definitions, I'd love to see
those as well.
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-03-24 19:40 Jürgen Purtz <[email protected]>
parent: Robert Haas <[email protected]>
1 sibling, 1 reply; 97+ messages in thread
From: Jürgen Purtz @ 2020-03-24 19:40 UTC (permalink / raw)
To: Robert Haas <[email protected]>; +Cc: Justin Pryzby <[email protected]>; Alvaro Herrera <[email protected]>; Corey Huinker <[email protected]>; Roger Harkavy <[email protected]>; [email protected] <[email protected]>; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
On 24.03.20 19:46, Robert Haas wrote:
>> Do we use shared_buffers for WAL ?
> No.
What's about the explanation in
https://www.postgresql.org/docs/12/runtime-config-wal.html :
"wal_buffers (integer) The amount of shared memory used for WAL data
that has not yet been written to disk. The default setting of -1 selects
a size equal to 1/32nd (about 3%) of shared_buffers, ... " ? My
understanding was, that the parameter wal_buffers grabs some of the
existing shared_buffers for its own purpose. Is this a
misinterpretation? Are shared_buffers and wal_buffers two different
shared memory areas?
Kind regards, Jürgen
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-03-24 19:58 Robert Haas <[email protected]>
parent: Jürgen Purtz <[email protected]>
0 siblings, 0 replies; 97+ messages in thread
From: Robert Haas @ 2020-03-24 19:58 UTC (permalink / raw)
To: Jürgen Purtz <[email protected]>; +Cc: Justin Pryzby <[email protected]>; Alvaro Herrera <[email protected]>; Corey Huinker <[email protected]>; Roger Harkavy <[email protected]>; [email protected] <[email protected]>; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
On Tue, Mar 24, 2020 at 3:40 PM Jürgen Purtz <[email protected]> wrote:
> On 24.03.20 19:46, Robert Haas wrote:
> Do we use shared_buffers for WAL ?
>
> No.
>
> What's about the explanation in https://www.postgresql.org/docs/12/runtime-config-wal.html : "wal_buffers (integer) The amount of shared memory used for WAL data that has not yet been written to disk. The default setting of -1 selects a size equal to 1/32nd (about 3%) of shared_buffers, ... " ? My understanding was, that the parameter wal_buffers grabs some of the existing shared_buffers for its own purpose. Is this a misinterpretation? Are shared_buffers and wal_buffers two different shared memory areas?
Yes. The code adds up the shared memory requests from all of the
different subsystems and then allocates one giant chunk of shared
memory which is divided up between them. The overwhelming majority of
that memory goes into shared_buffers, but not all of it. You can use
the new pg_get_shmem_allocations() function to see how it's used. For
example, with shared_buffers=4GB:
rhaas=# select name, pg_size_pretty(size) from
pg_get_shmem_allocations() order by size desc limit 10;
name | pg_size_pretty
----------------------+----------------
Buffer Blocks | 4096 MB
Buffer Descriptors | 32 MB
<anonymous> | 32 MB
XLOG Ctl | 16 MB
Buffer IO Locks | 16 MB
Checkpointer Data | 12 MB
Checkpoint BufferIds | 10 MB
clog | 2067 kB
| 1876 kB
subtrans | 261 kB
(10 rows)
rhaas=# select count(*), pg_size_pretty(sum(size)) from
pg_get_shmem_allocations();
count | pg_size_pretty
-------+----------------
54 | 4219 MB
(1 row)
So, in this configuration, there whole shared memory segment is
4219MB, of which 4096MB is allocated to shared_buffers and the rest to
dozens of smaller allocations, with 1876 kB left over that might get
snapped up later by an extension that wants some shared memory.
--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-03-27 20:12 Justin Pryzby <[email protected]>
parent: Jürgen Purtz <[email protected]>
1 sibling, 1 reply; 97+ messages in thread
From: Justin Pryzby @ 2020-03-27 20:12 UTC (permalink / raw)
To: Jürgen Purtz <[email protected]>; +Cc: Alvaro Herrera <[email protected]>; Corey Huinker <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
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
--
Justin
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-03-29 09:29 Jürgen Purtz <[email protected]>
parent: Justin Pryzby <[email protected]>
0 siblings, 1 reply; 97+ messages in thread
From: Jürgen Purtz @ 2020-03-29 09:29 UTC (permalink / raw)
To: Justin Pryzby <[email protected]>; +Cc: Alvaro Herrera <[email protected]>; Corey Huinker <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
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
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-03-30 17:10 Corey Huinker <[email protected]>
parent: Jürgen Purtz <[email protected]>
0 siblings, 2 replies; 97+ messages in thread
From: Corey Huinker @ 2020-03-30 17:10 UTC (permalink / raw)
To: Jürgen Purtz <[email protected]>; +Cc: Justin Pryzby <[email protected]>; Alvaro Herrera <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
On Sun, Mar 29, 2020 at 5:29 AM Jürgen Purtz <[email protected]> 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.
Attachments:
[text/x-patch] 0001-glossary-v4.patch (52.8K, 3-0001-glossary-v4.patch)
download | inline diff:
From 8a163603102f51a3eddfb05c51baf3b840c5d7f7 Mon Sep 17 00:00:00 2001
From: coreyhuinker <[email protected]>
Date: Mon, 30 Mar 2020 13:08:27 -0400
Subject: [PATCH] glossary v4
---
doc/src/sgml/filelist.sgml | 1 +
doc/src/sgml/glossary.sgml | 1551 ++++++++++++++++++++++++++++++++++++
doc/src/sgml/postgres.sgml | 1 +
3 files changed, 1553 insertions(+)
create mode 100644 doc/src/sgml/glossary.sgml
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 1043d0f7ab..cf21ef857e 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -170,6 +170,7 @@
<!ENTITY limits SYSTEM "limits.sgml">
<!ENTITY acronyms SYSTEM "acronyms.sgml">
+<!ENTITY glossary SYSTEM "glossary.sgml">
<!ENTITY color SYSTEM "color.sgml">
<!ENTITY features-supported SYSTEM "features-supported.sgml">
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
new file mode 100644
index 0000000000..eab14f3c9b
--- /dev/null
+++ b/doc/src/sgml/glossary.sgml
@@ -0,0 +1,1551 @@
+<appendix id="glossary">
+ <title>Glossary</title>
+ <para>
+ This is a list of terms and their meaning in the context of
+ <productname>PostgreSQL</productname> and relational database
+ systems in general.
+ </para>
+ <glosslist>
+ <glossentry id="glossary-aggregating">
+ <glossterm>Aggregating</glossterm>
+ <glossdef>
+ <para>
+ The act of combining a collection of data (input) values into
+ a single output value, which may not be of the same type as the
+ input values.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-aggregate">
+ <glossterm>Aggregate Function</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Function</glossterm> that combines multiple input values,
+ for example by counting, averaging or adding them all together,
+ yielding a single output value.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="functions-aggregate"/>.
+ </para>
+ <para>
+ See also <glossterm>Window Function</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-analytic">
+ <glossterm>Analytic</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Function</glossterm> whose computed value can reference
+ values found in nearby <glossterm>Row</glossterm>s of the same
+ <glossterm>Result Set</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="tutorial-window"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-atomic">
+ <glossterm>Atomic</glossterm>
+ <glossdef>
+ <para>
+ In reference to the value of an <glossterm>Attribute</glossterm> or
+ <glossterm>Datum</glossterm>: an item that cannot be broken down
+ into smaller components.
+ </para>
+ <para>
+ 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 <acronym>SQL</acronym> statements can be
+ combined into a <glossterm>Transaction</glossterm>, and that
+ transaction is said to be atomic.
+ <glossterm>Atomic</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-atomicity">
+ <glossterm>Atomicity</glossterm>
+ <glossdef>
+ <para>
+ One of the <acronym>ACID</acronym> properties. This is the state of
+ being <glossterm>Atomic</glossterm> in the operational/transactional sense.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-attribute">
+ <glossterm>Attribute</glossterm>
+ <glossdef>
+ <para>
+ An element with a certain name and data type found within a
+ <glossterm>Tuple</glossterm> or <glossterm>Table</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-autovacuum">
+ <glossterm>Autovacuum</glossterm>
+ <glossdef>
+ <para>
+ <glossterm>Background Worker</glossterm> processes that routinely
+ perform <glossterm>Vacuum</glossterm> operations.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="routine-vacuuming"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-backend-process">
+ <glossterm>Backend Process</glossterm>
+ <glossdef>
+ <para>
+ Processes of an <glossterm>Instance</glossterm> which act on behalf of
+ client <glossterm>Connection</glossterm>s and handle their requests.
+ </para>
+ <para>
+ (Don't confuse this term with the similar terms <glossterm>Background
+ Worker</glossterm> or <glossterm>Background Writer</glossterm>).
+ </para>
+ </glossdef>
+ </glossentry>
+
+<!--
+ <glossentry id="glossary-backend-server">
+ <glossterm>Backend Server</glossterm>
+ <glossdef>
+ <para>
+ See <glossterm>Instance</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+-->
+
+ <glossentry id="glossary-background-worker">
+ <glossterm>Background Worker</glossterm>
+ <glossdef>
+ <para>
+ Individual processes within an <glossterm>Instance</glossterm>, which
+ run system- or user-supplied code. A typical use case is a process
+ which handles parts of an <acronym>SQL</acronym> query to take
+ advantage of parallel execution on servers with multiple
+ <acronym>CPU</acronym>s.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="bgworker"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-background-writer">
+ <glossterm>Background Writer</glossterm>
+ <glossdef>
+ <para>
+ A process that continuously writes dirty pages from
+ <glossterm>Shared Memory</glossterm> to the file system.
+ It wakes up periodically, but
+ works only for a short period in order to distribute expensive
+ <acronym>I/O</acronym> activity over time, instead of generating fewer
+ larger <acronym>I/O</acronym> peaks which could block other processes.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="runtime-config-resource"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-cast">
+ <glossterm>Cast</glossterm>
+ <glossdef>
+ <para>
+ A conversion of a <glossterm>Datum</glossterm> from its current data
+ type to another data type.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-catalog">
+ <glossterm>Catalog</glossterm>
+ <glossdef>
+ <para>
+ The <acronym>SQL</acronym> standard uses this term to
+ indicate what is called a <glossterm>Database</glossterm> in
+ <productname>PostgreSQL</productname>'s terminology.
+ </para>
+ <para>
+ This should not be confused with the
+ <glossterm>System Catalog</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="manage-ag-overview"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-check-constraint">
+ <glossterm>Check Constraint</glossterm>
+ <glossdef>
+ <para>
+ A type of <glossterm>Constraint</glossterm> defined on a
+ <glossterm>Relation</glossterm> which restricts the values allowed in
+ one or more <glossterm>Attribute</glossterm>s. The <glossterm>Check
+ Constraint</glossterm> can make reference to any
+ attribute in the
+ <glossterm>Relation</glossterm>, but cannot reference other
+ <glossterm>Row</glossterm>s of the same
+ relation or other relations.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="ddl-constraints"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-checkpointer">
+ <glossterm>Checkpointer</glossterm>
+ <glossdef>
+ <para>
+ A process that writes dirty pages and <glossterm>WAL
+ Record</glossterm>s 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.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-checkpoint">
+ <glossterm>Checkpoint</glossterm>
+ <glossdef>
+ <para>
+ A point in time when all older dirty pages of the
+ <glossterm>Shared Memory</glossterm>, all older <glossterm>WAL Record</glossterm>s,
+ and a special <glossterm>Checkpoint record</glossterm> have been written
+ and flushed to disk.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-checkpoint"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-cluster">
+ <glossterm>Cluster</glossterm>
+ <glossdef>
+ <para>
+ A group of <glossterm>Database</glossterm>s plus their
+ <glossterm>Global SQL Object</glossterm>s. The
+ <glossterm>Cluster</glossterm> is managed by exactly one
+ <glossterm>Instance</glossterm>. A newly created
+ <glossterm>Cluster</glossterm> will have three
+ <glossterm>Database</glossterm>s created automatically. They are
+ <literal>template0</literal>, <literal>template1</literal>, and
+ <literal>postgres</literal>. It is expected that an application will
+ create one or more additional <glossterm>Database</glossterm>s aside
+ from these three.
+ </para>
+ <para>
+ Don't confuse the <productname>PostgreSQL</productname>-specific term
+ <glossterm>Cluster</glossterm> with the SQL command
+ <literal>CLUSTER</literal>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-column">
+ <glossterm>Column</glossterm>
+ <glossdef>
+ <para>
+ An <glossterm>Attribute</glossterm> found in a
+ <glossterm>Table</glossterm> or <glossterm>View</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-commit">
+ <glossterm>Commit</glossterm>
+ <glossdef>
+ <para>
+ The act of finalizing a <glossterm>Transaction</glossterm> within the
+ <glossterm>Database</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-commit"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-concurrency">
+ <glossterm>Concurrency</glossterm>
+ <glossdef>
+ <para>
+ The concept that multiple independent operations happen within the
+ <glossterm>Database</glossterm> at the same time.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-connection">
+ <glossterm>Connection</glossterm>
+ <glossdef>
+ <para>
+ An established line of communication between a client process
+ and a server process. If the two involved processes reside on the
+ same <glossterm>Server</glossterm>, then the connection can either use
+ <acronym>TCP/IP</acronym> or Unix-domain sockets. Otherwise,
+ only <acronym>TCP/IP</acronym> can be used.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="runtime-config-connection"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-consistency">
+ <glossterm>Consistency</glossterm>
+ <glossdef>
+ <para>
+ One of the <acronym>ACID</acronym> properties. This means that the database
+ is always in compliance with its own rules such as <glossterm>Table</glossterm>
+ structure, <glossterm>Constraint</glossterm>s,
+ <glossterm>Uniqueness</glossterm>, etc.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-constraint">
+ <glossterm>Constraint</glossterm>
+ <glossdef>
+ <para>
+ A restriction on the values of data allowed within a
+ <glossterm>Table</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="ddl-constraints"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-data-area">
+ <glossterm>Data Area</glossterm>
+ <glossdef>
+ <para>
+ See <glossterm>Data Directory</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-data-directory">
+ <glossterm>Data Directory</glossterm>
+ <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 <glossterm>Tablespace</glossterm>s. The environment
+ variable <literal>PGDATA</literal> often — but not always —
+ refers to the <glossterm>Data Directory</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="storage-file-layout"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-database">
+ <glossterm>Database</glossterm>
+ <glossdef>
+ <para>
+ A named collection of <glossterm>SQL Object</glossterm>s.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="manage-ag-overview"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-database-server">
+ <glossterm>Database Server</glossterm>
+ <glossdef>
+ <para>
+ See <glossterm>Instance</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-datum">
+ <glossterm>Datum</glossterm>
+ <glossdef>
+ <para>
+ The internal representation of a <acronym>SQL</acronym> data type.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-delete">
+ <glossterm>Delete</glossterm>
+ <glossdef>
+ <para>
+ A <acronym>SQL</acronym> command which removes
+ <glossterm>Row</glossterm>s from a given <glossterm>Table</glossterm>
+ or <glossterm>Relation</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-delete"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-durability">
+ <glossterm>Durability</glossterm>
+ <glossdef>
+ <para>
+ One of the <acronym>ACID</acronym> properties. This is the assurance that once a
+ <glossterm>Transaction</glossterm> has been <glossterm>Committed</glossterm>, the
+ data will remain even after a system failure or crash.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-file-segment">
+ <glossterm>File Segment</glossterm>
+ <glossdef>
+ <para>
+ A physical file which stores data for a given
+ <glossterm>Heap</glossterm> or <glossterm>Index</glossterm> object.
+ <glossterm>File Segment</glossterm>s are limited in size by a
+ configuration value and if that size is exceeded, it will be split
+ into multiple physical files.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="storage-file-layout"/>.
+ </para>
+ <para>
+ (Don't confuse this term with the similar term
+ <glossterm>WAL Segment</glossterm>).
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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> so that it appears as if were in local
+ <glossterm>Table</glossterm>(s). With a Foreign Data Wrapper it is
+ possible to define a <glossterm>Foreign Server</glossterm> and
+ <glossterm>Foreign Table</glossterm>s.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createforeigndatawrapper"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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(s) in those <glossterm>Column</glossterm>s to
+ identify exactly one <glossterm>Row</glossterm> in the specified
+ <glossterm>Table</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-foreign-server">
+ <glossterm>Foreign Server</glossterm>
+ <glossdef>
+ <para>
+ A named collection of <glossterm>Foreign Table</glossterm>s which all
+ use the same <glossterm>Foreign Data Wrapper</glossterm> and have
+ other configuration values in common.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createserver"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-foreign-table">
+ <glossterm>Foreign Table</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Relation</glossterm> which appears to have
+ <glossterm>Row</glossterm>s and <glossterm>Column</glossterm>s similar
+ to a regular <glossterm>Table</glossterm>, but will forward requests
+ for data through its <glossterm>Foreign Data Wrapper</glossterm>,
+ which will return <glossterm>Result Set</glossterm>s structured
+ according to the definition of the <glossterm>Foreign Table</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createforeigntable"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-function">
+ <glossterm>Function</glossterm>
+ <glossdef>
+ <para>
+ Any defined transformation of data. Many
+ <glossterm>Function</glossterm>s are already defined within
+ <productname>PostgreSQL</productname> itself, but user-defined
+ ones can also be added.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createfunction"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-global-sql-object">
+ <glossterm>Global SQL Object</glossterm>
+ <glossdef>
+ <para>
+ <glossterm>SQL Object</glossterm>s which do not belong to a specific
+ <glossterm>Schema</glossterm>.
+ </para>
+ <para>
+ Objects that exist at the <glossterm>Database</glossterm> level
+ include Extensions such as
+ <glossterm>Foreign Data Wrapper</glossterm>s.
+ </para>
+ <para>
+ Objects that exist at the <glossterm>Cluster</glossterm> level
+ include <glossterm>Role</glossterm>s,
+ <glossterm>Tablespace</glossterm>s,
+ <glossterm>Replication</glossterm> origins, and subscriptions
+ for logical replication.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-grant">
+ <glossterm>Grant</glossterm>
+ <glossdef>
+ <para>
+ A <acronym>SQL</acronym> command that is used to allow
+ <glossterm>User</glossterm>s or <glossterm>Role</glossterm>s to access
+ specific objects within the <glossterm>Database</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-grant"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-heap">
+ <glossterm>Heap</glossterm>
+ <glossdef>
+ <para>
+ Contains the values of <glossterm>Row</glossterm> attributes
+ (i.e. the data). The <glossterm>Heap</glossterm> is realized within
+ <glossterm>Database</glossterm> files.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-host">
+ <glossterm>Host</glossterm>
+ <glossdef>
+ <para>
+ See <glossterm>Server</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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> types
+ such as a <glossterm>Materialized View</glossterm>). Its internal
+ structure supports fast retrieval of and access to the original
+ data.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createindex"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-insert">
+ <glossterm>Insert</glossterm>
+ <glossdef>
+ <para>
+ A <acronym>SQL</acronym> command used to add new data into a
+ <glossterm>Table</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-insert"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-instance">
+ <glossterm>Instance</glossterm>
+ <glossdef>
+ <para>
+ An <glossterm>Instance</glossterm> is a group of processes plus their
+ common <glossterm>Shared Memory</glossterm> running on a single
+ <glossterm>Server</glossterm>. The <glossterm>Instance</glossterm>
+ handles all key features of a <acronym>DBMS</acronym>: read and write
+ access to files and shared memory, assurance of
+ the <acronym>ACID</acronym> paradigm, <acronym>MVCC</acronym>,
+ <glossterm>Connection</glossterm>s to client programs, backup,
+ recovery, replication, privileges, etc.
+ </para>
+ <para>
+ An <glossterm>Instance</glossterm> manages exactly one
+ <glossterm>Cluster</glossterm>.
+ </para>
+ <para>
+ Many <glossterm>Instance</glossterm>s can run on the same server as
+ long as their <acronym>TCP/IP</acronym> ports do not conflict.
+ Different instances on a server may use the
+ same or different versions of <productname>PostgreSQL</productname>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-isolation">
+ <glossterm>Isolation</glossterm>
+ <glossdef>
+ <para>
+ One of the <acronym>ACID</acronym> properties. This means that concurrently running
+ <glossterm>Transaction</glossterm>s affect the database exactly as if they had been
+ executed sequentially.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-join">
+ <glossterm>Join</glossterm>
+ <glossdef>
+ <para>
+ A <acronym>SQL</acronym> keyword used in <command>SELECT</command> statements for
+ combining data from multiple <glossterm>Relation</glossterm>s.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-key">
+ <glossterm>Key</glossterm>
+ <glossdef>
+ <para>
+ A means of identifying a <glossterm>Row</glossterm> within a
+ <glossterm>Table</glossterm> or <glossterm>Relation</glossterm> by
+ values contained within one or more <glossterm>Attribute</glossterm>s
+ in that <glossterm>Table</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-lock">
+ <glossterm>Lock</glossterm>
+ <glossdef>
+ <para>
+ A mechanism that allows a process to limit or prevent simultaneous
+ access to a resource.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-log-file">
+ <glossterm>Log File</glossterm>
+ <glossdef>
+ <para>
+ <glossterm>Log File</glossterm>s contain human-readable text lines about
+ events. Examples include login failures, long-running queries, etc.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="logfile-maintenance"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-log-writer">
+ <glossterm>Log Writer</glossterm>
+ <glossdef>
+ <para>
+ If activated and parameterized, the
+ <glossterm>Log Writer</glossterm> process
+ writes information about database events into the current
+ <glossterm>Log File</glossterm>. When reaching certain time- or
+ volume-dependent criteria, a new log file is created.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="runtime-config-logging"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-log-record">
+ <glossterm>Log Record</glossterm>
+ <glossdef>
+ <para>
+ Archaic term for a <glossterm>WAL Record</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-logged">
+ <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>Table</glossterm>s are <glossterm>Logged</glossterm>. A
+ table can be specified as <glossterm>Unlogged</glossterm> either at
+ creation time or via the <command>ALTER TABLE</command> command.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-master">
+ <glossterm>Master</glossterm>
+ <glossdef>
+ <para>
+ When two or more <glossterm>Database</glossterm>s are linked via
+ <glossterm>Replication</glossterm>, the <glossterm>Server</glossterm>
+ that is considered the authoritative source of information is called
+ the <glossterm>Master</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-materialized">
+ <glossterm>Materialized</glossterm>
+ <glossdef>
+ <para>
+ The act of storing information rather than just the method of accessing
+ the information. This term is used in <glossterm>Materialized
+ View</glossterm>s, meaning that the data derived from the
+ <glossterm>View</glossterm> is actually stored on disk separately from
+ the sources of that data. When using the term
+ <glossterm>Materialized</glossterm> to refer to
+ multi-step queries, it means that the data of a given step is stored
+ 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 stores data in the same way
+ that a <glossterm>Table</glossterm> does. It cannot be modified via
+ <command>INSERT</command>, <command>UPDATE</command>, or
+ <command>DELETE</command> operations.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-creatematerializedview"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-null">
+ <glossterm>Null</glossterm>
+ <glossdef>
+ <para>
+ A concept of non-existence that is a central tenet of Relational
+ Database Theory. It represents the absence of value.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-partition">
+ <glossterm>Partition</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Table</glossterm> that can be queried directly,
+ or via a partitioned table, which is a collection of
+ sub-tables, each capable of holding one defined
+ subset of information that does not overlap with any other
+ table in the collection.
+ </para>
+ <para>
+ When referring to an <glossterm>Analytic</glossterm>
+ <glossterm>Function</glossterm>: a partition is a definition
+ that identifies which neighboring
+ <glossterm>Row</glossterm>s can be considered by the
+ function.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-postmaster">
+ <glossterm>Postmaster</glossterm>
+ <glossdef>
+ <para>
+ The very first process of an <glossterm>Instance</glossterm>. It
+ starts the other processes and creates
+ <glossterm>Backend Process</glossterm>es on demand.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="server-start"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-primary-key">
+ <glossterm>Primary Key</glossterm>
+ <glossdef>
+ <para>
+ A special case of a <glossterm>Unique Index</glossterm> defined on a
+ <glossterm>Table</glossterm> or other <glossterm>Relation</glossterm>
+ that also guarantees that all of the <glossterm>Attribute</glossterm>s
+ 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
+ table, though it is possible to have multiple
+ unique indexes that also have no null-capable attributes.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-procedure">
+ <glossterm>Procedure</glossterm>
+ <glossdef>
+ <para>
+ A defined set of instructions for manipulating data within a
+ <glossterm>Database</glossterm>. A <glossterm>Procedure</glossterm> can
+ be written in a variety of programming languages. They may seem
+ similar to <glossterm>Function</glossterm>s, 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
+ as <command>COMMIT</command> and <command>ROLLBACK</command>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createprocedure"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-record">
+ <glossterm>Record</glossterm>
+ <glossdef>
+ <para>
+ See <glossterm>Tuple</glossterm>.
+ </para>
+ <para>
+ A single <glossterm>Row</glossterm> of a <glossterm>Table</glossterm>
+ or other <glossterm>Relation</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-referential-integrity">
+ <glossterm>Referential Integrity</glossterm>
+ <glossdef>
+ <para>
+ A means of restricting data in one <glossterm>Relation</glossterm>
+ so that it must have matching data in another
+ <glossterm>Relation</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-relation">
+ <glossterm>Relation</glossterm>
+ <glossdef>
+ <para>
+ The generic term for all objects in a <glossterm>Database</glossterm>
+ that have a name and a list of <glossterm>Attribute</glossterm>s
+ defined in a specific order. <glossterm>Table</glossterm>s,
+ <glossterm>View</glossterm>s, <glossterm>Foreign Table</glossterm>s,
+ <glossterm>Materialized View</glossterm>s, and
+ <glossterm>Index</glossterm>es are all
+ <glossterm>Relation</glossterm>s.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-replica">
+ <glossterm>Replica</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Database</glossterm> that is paired with a
+ <glossterm>Master</glossterm>
+ database and is maintaining a copy of some or
+ all of the Master <glossterm>Database</glossterm>'s data. The primary
+ reasons for doing this are to allow for greater access to that data,
+ and to maintain availability of the data in the event that the
+ <glossterm>Master</glossterm> becomes unavailable.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-replication">
+ <glossterm>Replication</glossterm>
+ <glossdef>
+ <para>
+ The act of reproducing data on one <glossterm>Server</glossterm> onto
+ another server called a <glossterm>Replica</glossterm>. This can take the
+ form of Physical <glossterm>Replication</glossterm>, where all file
+ changes from one server are copied verbatim,
+ or Logical <glossterm>Replication</glossterm> where a defined subset
+ of data changes are conveyed.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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. The data structure consists of zero or more
+ <glossterm>Row</glossterm>s with the same ordered set of
+ <glossterm>Attribute</glossterm>s.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-revoke">
+ <glossterm>Revoke</glossterm>
+ <glossdef>
+ <para>
+ A command to prevent access to a named set of
+ <glossterm>Database</glossterm> objects for a named list of
+ <glossterm>User</glossterm>s and <glossterm>Role</glossterm>s.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-revoke"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-role">
+ <glossterm>Role</glossterm>
+ <glossdef>
+ <para>
+ A collection of access privileges to the
+ <glossterm>Database</glossterm>. <glossterm>Role</glossterm>s are
+ themselves a privilege that can be granted to other roles. This is
+ often done for convenience or to ensure completeness when multiple
+ <glossterm>User</glossterm>s need the same privileges.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createrole"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-rollback">
+ <glossterm>Rollback</glossterm>
+ <glossdef>
+ <para>
+ A command to undo all of the operations performed since the beginning
+ of a <glossterm>Transaction</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-rollback"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-row">
+ <glossterm>Row</glossterm>
+ <glossdef>
+ <para>
+ See <glossterm>Tuple</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-savepoint">
+ <glossterm>Savepoint</glossterm>
+ <glossdef>
+ <para>
+ A special mark inside the sequence of steps in a
+ <glossterm>Transaction</glossterm>. Data modifications after this
+ point in time may be reverted to the time of the savepoint.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-savepoint"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-schema">
+ <glossterm>Schema</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Schema</glossterm> is a namespace for
+ <glossterm>SQL object</glossterm>s, 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 Object</glossterm>s 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 reusing
+ a name in multiple <glossterm>Schema</glossterm>s.
+ </para>
+ <para>
+ Many <glossterm>SQL Object</glossterm>s reside in the default
+ <glossterm>Schema</glossterm> <literal>public</literal>, but it is
+ expected that more schemas are created to hold application-specific
+ <glossterm>SQL Object</glossterm>s.
+ </para>
+ <para>
+ More generically, the term <glossterm>Schema</glossterm> is used to
+ mean all data descriptions (<glossterm>Table</glossterm> definitions,
+ <glossterm>Constraint</glossterm>s, comments) for a given
+ <glossterm>Database</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="ddl-schemas"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-segment">
+ <glossterm>Segment</glossterm>
+ <glossdef>
+ <para>
+ See <glossterm>File Segment</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-select">
+ <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>Function</glossterm>s invoked within the query could have
+ side effects that do modify data.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-select"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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 for the duration of the
+ <glossterm>Transaction</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-server">
+ <glossterm>Server</glossterm>
+ <glossdef>
+ <para>
+ The term <glossterm>Server</glossterm> denotes real hardware, a
+ container, or a Virtual Machine.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-session">
+ <glossterm>Session</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Connection</glossterm> to the <glossterm>Database</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-sequence">
+ <glossterm>Sequence</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Database</glossterm> object which represents the
+ 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 (usually
+ 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, that value
+ is returned to the invoking query, and the current value of the
+ sequence is updated to reflect the new value. The value can be updated
+ multiple times in a single query, the net effect being that each row
+ selected will have a different value. Values taken from a
+ <glossterm>Sequence</glossterm> are never reverted, even in the case of
+ a <glossterm>Rollback</glossterm>, which means that the
+ <glossterm>Sequence</glossterm> will never generate the same number twice,
+ which makes it useful for generating
+ <glossterm>Primary Key</glossterm> values.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createsequence"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-shared-memory">
+ <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 Record</glossterm>s, and stores additional common
+ information. Note that <glossterm>Shared Memory</glossterm> belongs to
+ the complete <glossterm>Instance</glossterm>, not to a single
+ <glossterm>Database</glossterm>.
+ </para>
+ <para>
+ <glossterm>Shared Memory</glossterm> is organized into pages. If a
+ page is modified, it is called a dirty page until it is written back
+ to the file system.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="runtime-config-resource-memory"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-sql-object">
+ <glossterm>SQL Object</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Table</glossterm>, <glossterm>View</glossterm>,
+ <glossterm>Materialized View</glossterm>,
+ <glossterm>Index</glossterm>, <glossterm>Constraint</glossterm>,
+ <glossterm>Sequence</glossterm>, <glossterm>Function</glossterm>,
+ <glossterm>Procedure</glossterm>, <glossterm>Trigger</glossterm>,
+ data type, or operator. Every <glossterm>SQL Object</glossterm>
+ belongs to exactly one <glossterm>Schema</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="manage-ag-overview"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-stats-collector">
+ <glossterm>Stats Collector</glossterm>
+ <glossdef>
+ <para>
+ This process collects statistical information about the
+ <glossterm>Cluster</glossterm>'s activities.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="monitoring-stats"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-system-catalog">
+ <glossterm>System Catalog</glossterm>
+ <glossdef>
+ <para>
+ A collection of <glossterm>Table</glossterm>s and
+ <glossterm>View</glossterm>s which describe the structure of all
+ <acronym>SQL</acronym> objects of the <glossterm>Database</glossterm>
+ and the <glossterm>Global SQL Object</glossterm>s of the
+ <glossterm>Cluster</glossterm>. The <glossterm>System
+ Catalog</glossterm> resides in the schema
+ <literal>pg_catalog</literal>. Main parts are mirrored as
+ <glossterm>View</glossterm>s in the <glossterm>Schema</glossterm>
+ <literal>information_schema</literal>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="ddl-schemas"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-table">
+ <glossterm>Table</glossterm>
+ <glossdef>
+ <para>
+ A collection of <glossterm>Tuple</glossterm>s (also known as
+ <glossterm>Row</glossterm>s or <glossterm>Record</glossterm>s) having
+ a common data structure (the same number of
+ <glossterm>Attribute</glossterm>s, in the same order, having the same
+ name and type per position). A <glossterm>Table</glossterm> is the
+ most common form of <glossterm>Relation</glossterm> in
+ <productname>PostgreSQL</productname>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createtable"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-tablespace">
+ <glossterm>Tablespace</glossterm>
+ <glossdef>
+ <para>
+ A named location on the server filesystem. All <glossterm>SQL Object</glossterm>s
+ which require storage beyond their definition in the
+ <glossterm>System Catalog</glossterm>
+ must belong to a single tablespace.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="manage-ag-tablespaces"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-temporary-tables">
+ <glossterm>Temporary Table</glossterm>
+ <glossdef>
+ <para>
+ <glossterm>Table</glossterm>s that exist either for the lifetime of a
+ <glossterm>Session</glossterm> or a
+ <glossterm>Transaction</glossterm>, as specified at the time of creation. The
+ data in them is not visible to other sessions,
+ and is not <glossterm>Logged</glossterm>.
+ <glossterm>Temporary Table</glossterm>s are often used to store
+ intermediate data for a multi-step operation.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createtable"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-transaction">
+ <glossterm>Transaction</glossterm>
+ <glossdef>
+ <para>
+ A combination of commands that must act as a single
+ <glossterm>Atomic</glossterm> command: they all succeed or all fail
+ as a single unit, and their effects are not visible to other
+ <glossterm>Session</glossterm>s until
+ the <glossterm>Transaction</glossterm> is complete.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="transaction-iso"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-trigger">
+ <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>, <command>DELETE</command>,
+ <command>TRUNCATE</command>) is applied to a <glossterm>Relation</glossterm>.
+ A <glossterm>Trigger</glossterm>
+ executes within the same <glossterm>Transaction</glossterm> as the
+ statement which invoked it, and if the <glossterm>Function</glossterm>
+ fails, then the invoking statement also fails.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createtrigger"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-tuple">
+ <glossterm>Tuple</glossterm>
+ <glossdef>
+ <para>
+ A collection of <glossterm>Attribute</glossterm>s in a fixed order.
+ That order may be defined by the <glossterm>Table</glossterm> where
+ the <glossterm>Tuple</glossterm> is found, in which case the
+ <glossterm>Tuple</glossterm> is often called a
+ <glossterm>Row</glossterm> or <glossterm>Record</glossterm>. It may
+ also be defined by the structure of a
+ <glossterm>Result Set</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-unique">
+ <glossterm>Unique</glossterm>
+ <glossdef>
+ <para>
+ The condition of having no duplicate values in the same
+ <glossterm>Relation</glossterm>. Often used in the concept of
+ <glossterm>Unique Index</glossterm>es.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-unlogged">
+ <glossterm>Unlogged</glossterm>
+ <glossdef>
+ <para>
+ Changes to an unlogged <glossterm>Relation</glossterm> are not
+ reflected in the <glossterm>WAL Log</glossterm>. This disables
+ replication and crash recovery for these relations.
+ </para>
+ <para>
+ The primary use of unlogged tables is for storing
+ transient work data that must be shared across processes.
+ </para>
+ <para>
+ <glossterm>Temporary Table</glossterm>s are always unlogged.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-update">
+ <glossterm>Update</glossterm>
+ <glossdef>
+ <para>
+ A command used to modify <glossterm>Row</glossterm>s that may already
+ exist in a specified <glossterm>Table</glossterm>. It cannot create
+ or remove rows.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-update"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-user">
+ <glossterm>User</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Role</glossterm> that has the <literal>LOGIN</literal>
+ privilege is said to be a <glossterm>User</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-user-mapping">
+ <glossterm>User Mapping</glossterm>
+ <glossdef>
+ <para>
+ The translation of login credentials in the local
+ <glossterm>Database</glossterm> to credentials in a remote data system
+ defined by a <glossterm>Foreign Data Wrapper</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createusermapping"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-vacuum">
+ <glossterm>Vacuum</glossterm>
+ <glossdef>
+ <para>
+ The process of removing outdated <acronym>MVCC</acronym>
+ <glossterm>Tuple</glossterm>s from a <glossterm>Heap</glossterm> or
+ <glossterm>Index</glossterm>. This can be initiated through the use of
+ the <command>VACUUM</command> command, but can also be handled automatically
+ via <glossterm>Autovacuum</glossterm> processes.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-vacuum"/> .
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-view">
+ <glossterm>View</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Relation</glossterm> that is defined by a
+ <command>SELECT</command> statement, but has no storage of its own.
+ Any time a query references a <glossterm>View</glossterm>, the
+ definition of the <glossterm>View</glossterm> is substituted into the
+ query as if the user had typed that subquery instead of the name of
+ the <glossterm>View</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createview"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-wal-archiver">
+ <glossterm>WAL Archiver</glossterm>
+ <glossdef>
+ <para>
+ A process that saves copies of <glossterm>WAL File</glossterm>s,
+ for the purposes of creating backups or keeping
+ <glossterm>Replica</glossterm>s current.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="continuous-archiving"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-wal-file">
+ <glossterm>WAL File</glossterm>
+ <glossdef>
+ <para>
+ <glossterm>WAL Record</glossterm>s are continously written to the end
+ of the current <glossterm>WAL File</glossterm>. WAL files
+ as well as WAL records belong
+ to the complete <glossterm>Cluster</glossterm>, not to a single
+ <glossterm>Database</glossterm>. After a WAL file
+ is full, a new WAL file is
+ created, or, under certain conditions, one of the previous
+ <glossterm>WAL File</glossterm>s is renamed and reused.
+ </para>
+ <para>
+ The sequence of <glossterm>WAL Record</glossterm>s
+ represents the sequence of changes that have taken place in the
+ <glossterm>Cluster</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="wal-internals"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-wal-log">
+ <glossterm>WAL Log</glossterm>
+ <glossdef>
+ <para>
+ See <glossterm>WAL File</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-wal-record">
+ <glossterm>WAL Record</glossterm>
+ <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-printable binary format.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="wal-internals"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-wal-segment">
+ <glossterm>WAL Segment</glossterm>
+ <glossdef>
+ <para>
+ See <glossterm>WAL File</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-wal-segment-file">
+ <glossterm>WAL Segment File</glossterm>
+ <glossdef>
+ <para>
+ See <glossterm>WAL File</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-wal-writer">
+ <glossterm>WAL Writer</glossterm>
+ <glossdef>
+ <para>
+ This process writes <glossterm>WAL Record</glossterm>s from
+ <glossterm>Shared Memory</glossterm> to
+ <glossterm>WAL File</glossterm>s.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="runtime-config-wal"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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 it can derive its value from a
+ set of <glossterm>Row</glossterm>s in a <glossterm>Result
+ Set</glossterm>, while retaining the original source data.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="tutorial-window"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+ </glosslist>
+</appendix>
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index 1f7bd32878..ba3d626102 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -278,6 +278,7 @@
&docguide;
&limits;
&acronyms;
+ &glossary;
&color;
</part>
--
2.20.1
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-03-31 14:13 Jürgen Purtz <[email protected]>
parent: Corey Huinker <[email protected]>
1 sibling, 1 reply; 97+ messages in thread
From: Jürgen Purtz @ 2020-03-31 14:13 UTC (permalink / raw)
To: Corey Huinker <[email protected]>; +Cc: Justin Pryzby <[email protected]>; Alvaro Herrera <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
On 30.03.20 19:10, Corey Huinker wrote:
>
>
> On Sun, Mar 29, 2020 at 5:29 AM Jürgen Purtz <[email protected]
> <mailto:[email protected]>> 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
Attachments:
[text/x-patch] 0001-glossary-v4-01.patch (8.9K, 3-0001-glossary-v4-01.patch)
download | inline diff:
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 @@
</glossentry>
<glossentry id="glossary-analytic">
- <glossterm>Analytic</glossterm>
+ <glossterm>Analytic Function</glossterm>
<glossdef>
<para>
- A <glossterm>Function</glossterm> whose computed value can reference
+ A type of <glossterm>Function</glossterm>s whose result may be based on
values found in nearby <glossterm>Row</glossterm>s of the same
<glossterm>Result Set</glossterm>.
</para>
@@ -59,12 +59,12 @@
into smaller components.
</para>
<para>
+ <!-- better wording ??? '... cannot be partially processed; ...' -->
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 <acronym>SQL</acronym> statements can be
combined into a <glossterm>Transaction</glossterm>, and that
- transaction is said to be atomic.
- <glossterm>Atomic</glossterm>.
+ transaction is said to be <glossterm>Atomic</glossterm>.
</para>
</glossdef>
</glossentry>
@@ -73,7 +73,7 @@
<glossterm>Atomicity</glossterm>
<glossdef>
<para>
- One of the <acronym>ACID</acronym> properties. This is the state of
+ One of the <acronym>ACID</acronym> properties. This is the state of
being <glossterm>Atomic</glossterm> in the operational/transactional sense.
</para>
</glossdef>
@@ -152,7 +152,7 @@
A process that continuously writes dirty pages from
<glossterm>Shared Memory</glossterm> 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
<acronym>I/O</acronym> activity over time, instead of generating fewer
larger <acronym>I/O</acronym> peaks which could block other processes.
</para>
@@ -220,7 +220,7 @@
Record</glossterm>s 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.
</para>
</glossdef>
</glossentry>
@@ -303,7 +303,7 @@
<glossdef>
<para>
An established line of communication between a client process
- and a server process. If the two involved processes reside on the
+ and a <glossterm>Backend Process</glossterm>. If the two involved processes reside on the
same <glossterm>Server</glossterm>, then the connection can either use
<acronym>TCP/IP</acronym> or Unix-domain sockets. Otherwise,
only <acronym>TCP/IP</acronym> can be used.
@@ -470,7 +470,7 @@
A type of <glossterm>Constraint</glossterm> defined on one or more
<glossterm>Column</glossterm>s in a <glossterm>Table</glossterm> which
requires the value(s) in those <glossterm>Column</glossterm>s to
- identify exactly one <glossterm>Row</glossterm> in the specified
+ identify exactly one <glossterm>Row</glossterm> in another (or the same)
<glossterm>Table</glossterm>.
</para>
</glossdef>
@@ -643,7 +643,7 @@
<glossterm>Isolation</glossterm>
<glossdef>
<para>
- One of the <acronym>ACID</acronym> properties. This means that concurrently running
+ One of the <acronym>ACID</acronym> properties. This means that concurrently running
<glossterm>Transaction</glossterm>s affect the database exactly as if they had been
executed sequentially.
</para>
@@ -795,6 +795,7 @@
<glossterm>Partition</glossterm>
<glossdef>
<para>
+ In reference to a <glossterm>Table</glossterm>:
A <glossterm>Table</glossterm> 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.
</para>
<para>
- When referring to an <glossterm>Analytic</glossterm>
- <glossterm>Function</glossterm>: a partition is a definition
- that identifies which neighboring
+ In reference to a <glossterm>Analytic Function</glossterm>:
+ a partition is a definition that identifies which neighboring
<glossterm>Row</glossterm>s can be considered by the
function.
</para>
@@ -865,13 +865,13 @@
<glossentry id="glossary-record">
<glossterm>Record</glossterm>
<glossdef>
- <para>
- See <glossterm>Tuple</glossterm>.
- </para>
<para>
A single <glossterm>Row</glossterm> of a <glossterm>Table</glossterm>
or other <glossterm>Relation</glossterm>.
</para>
+ <para>
+ See <glossterm>Tuple</glossterm>.
+ </para>
</glossdef>
</glossentry>
@@ -880,6 +880,7 @@
<glossdef>
<para>
A means of restricting data in one <glossterm>Relation</glossterm>
+ by a <glossterm>Foreign Key</glossterm>
so that it must have matching data in another
<glossterm>Relation</glossterm>.
</para>
@@ -905,7 +906,7 @@
<glossterm>Replica</glossterm>
<glossdef>
<para>
- A <glossterm>Database</glossterm> that is paired with a
+ A <glossterm>Database</glossterm> that is paired with a
<glossterm>Master</glossterm>
database and is maintaining a copy of some or
all of the Master <glossterm>Database</glossterm>'s data. The primary
@@ -934,7 +935,7 @@
<glossterm>Result Set</glossterm>
<glossdef>
<para>
- A data structure transmitted from a <glossterm>Server</glossterm> to
+ A data structure transmitted from a <glossterm>Backend Process</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
@@ -1068,8 +1069,8 @@
<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
+ The <acronym>SQL</acronym> 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>Function</glossterm>s invoked within the query could have
side effects that do modify data.
@@ -1333,7 +1334,8 @@
<glossdef>
<para>
The condition of having no duplicate values in the same
- <glossterm>Relation</glossterm>. Often used in the concept of
+ <glossterm>Column</glossterm> of a <glossterm>Relation</glossterm>.
+ Often used in the concept of
<glossterm>Unique Index</glossterm>es.
</para>
</glossdef>
@@ -1361,9 +1363,9 @@
<glossterm>Update</glossterm>
<glossdef>
<para>
- A command used to modify <glossterm>Row</glossterm>s that may already
- exist in a specified <glossterm>Table</glossterm>. It cannot create
- or remove rows.
+ A <acronym>SQL</acronym> command used to modify <glossterm>Row</glossterm>s
+ that may already exist in a specified <glossterm>Table</glossterm>.
+ It cannot create or remove rows.
</para>
<para>
For more information, see
@@ -1402,7 +1404,7 @@
<glossdef>
<para>
The process of removing outdated <acronym>MVCC</acronym>
- <glossterm>Tuple</glossterm>s from a <glossterm>Heap</glossterm> or
+ <glossterm>Tuple</glossterm>s from a <glossterm>Heap</glossterm> or
<glossterm>Index</glossterm>. This can be initiated through the use of
the <command>VACUUM</command> command, but can also be handled automatically
via <glossterm>Autovacuum</glossterm> processes.
@@ -1436,7 +1438,7 @@
<glossterm>WAL Archiver</glossterm>
<glossdef>
<para>
- A process that saves copies of <glossterm>WAL File</glossterm>s,
+ A process that saves copies of <glossterm>WAL File</glossterm>s
for the purposes of creating backups or keeping
<glossterm>Replica</glossterm>s current.
</para>
@@ -1461,7 +1463,7 @@
<glossterm>WAL File</glossterm>s is renamed and reused.
</para>
<para>
- The sequence of <glossterm>WAL Record</glossterm>s
+ The sequence of <glossterm>WAL Record</glossterm>s
represents the sequence of changes that have taken place in the
<glossterm>Cluster</glossterm>.
</para>
@@ -1522,7 +1524,7 @@
<glossdef>
<para>
This process writes <glossterm>WAL Record</glossterm>s from
- <glossterm>Shared Memory</glossterm> to
+ <glossterm>Shared Memory</glossterm> to
<glossterm>WAL File</glossterm>s.
</para>
<para>
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-03-31 17:58 Justin Pryzby <[email protected]>
parent: Jürgen Purtz <[email protected]>
0 siblings, 1 reply; 97+ messages in thread
From: Justin Pryzby @ 2020-03-31 17:58 UTC (permalink / raw)
To: Jürgen Purtz <[email protected]>; +Cc: Corey Huinker <[email protected]>; Alvaro Herrera <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
On Tue, Mar 31, 2020 at 04:13:00PM +0200, Jürgen Purtz wrote:
> Please find some minor suggestions in the attachment. They are based on
> Corey's last patch 0001-glossary-v4.patch.
> @@ -220,7 +220,7 @@
> Record</glossterm>s 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.
I think you're correct in that "volume" is singular. But I think "collected"
is the wrong world. I suggested "written".
> <para>
> - One of the <acronym>ACID</acronym> properties. This means that concurrently running
> + One of the <acronym>ACID</acronym> properties. This means that concurrently running
These could maybe say "required" or "essential" >ACID< properties
> <para>
> + In reference to a <glossterm>Table</glossterm>:
> A <glossterm>Table</glossterm> that can be queried directly,
Maybe: "In reference to a >Relation<: A table which can be queried directly,"
> table in the collection.
> </para>
> <para>
> - When referring to an <glossterm>Analytic</glossterm>
> - <glossterm>Function</glossterm>: a partition is a definition
> - that identifies which neighboring
> + In reference to a <glossterm>Analytic Function</glossterm>:
s/a/an/
> @@ -1333,7 +1334,8 @@
> <glossdef>
> <para>
> The condition of having no duplicate values in the same
> - <glossterm>Relation</glossterm>. Often used in the concept of
> + <glossterm>Column</glossterm> of a <glossterm>Relation</glossterm>.
> + Often used in the concept of
s/concept/context/, but I said that before, so maybe it was rejected.
--
Justin
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-03-31 18:07 Justin Pryzby <[email protected]>
parent: Corey Huinker <[email protected]>
1 sibling, 1 reply; 97+ messages in thread
From: Justin Pryzby @ 2020-03-31 18:07 UTC (permalink / raw)
To: Corey Huinker <[email protected]>; +Cc: Jürgen Purtz <[email protected]>; Alvaro Herrera <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
On Mon, Mar 30, 2020 at 01:10:19PM -0400, Corey Huinker wrote:
> + <glossentry id="glossary-aggregating">
> + <glossterm>Aggregating</glossterm>
> + <glossdef>
> + <para>
> + The act of combining a collection of data (input) values into
> + a single output value, which may not be of the same type as the
> + input values.
I think we maybe already tried to address this ; but could we define a noun
form ? But not "aggregate" since it's the same word as the verb form. I think
it would maybe be best to merge with "aggregate function", below.
> + <glossentry id="glossary-consistency">
> + <glossterm>Consistency</glossterm>
> + <glossdef>
> + <para>
> + One of the <acronym>ACID</acronym> properties. This means that the database
> + is always in compliance with its own rules such as <glossterm>Table</glossterm>
> + structure, <glossterm>Constraint</glossterm>s,
I don't think the definition of "compliance" is good. The state of being
consistent means an absense of corruption more than that an absense of data
integrity issues (which could be caused by corruption).
> + <glossentry id="glossary-datum">
> + <glossterm>Datum</glossterm>
> + <glossdef>
> + <para>
> + The internal representation of a <acronym>SQL</acronym> data type.
Could you say "..used by PostgreSQL" ?
> + <glossterm>File Segment</glossterm>
> + <glossdef>
> + <para>
> + A physical file which stores data for a given
> + <glossterm>Heap</glossterm> or <glossterm>Index</glossterm> object.
> + <glossterm>File Segment</glossterm>s are limited in size by a
> + configuration value and if that size is exceeded, it will be split
> + into multiple physical files.
Say "if an object exceeds that size, then it will be stored across multiple
physical files".
> + which handles parts of an <acronym>SQL</acronym> query to take
...
> + A <acronym>SQL</acronym> command used to add new data into a
I mentioned before, please be consistent: "A SQL or An SQL".
> + </para>
> + <para>
> + Many <glossterm>Instance</glossterm>s can run on the same server as
Say "multiple" not many.
> + <glossentry id="glossary-join">
> + <glossterm>Join</glossterm>
> + <glossdef>
> + <para>
> + A <acronym>SQL</acronym> keyword used in <command>SELECT</command> statements for
> + combining data from multiple <glossterm>Relation</glossterm>s.
Could you add a link to the docs ?
> + <glossentry id="glossary-log-writer">
> + <glossterm>Log Writer</glossterm>
> + <glossdef>
> + <para>
> + If activated and parameterized, the
I still don't know what parameterized means here.
> + <glossentry id="glossary-system-catalog">
> + <glossterm>System Catalog</glossterm>
> + <glossdef>
> + <para>
> + A collection of <glossterm>Table</glossterm>s and
> + <glossterm>View</glossterm>s which describe the structure of all
> + <acronym>SQL</acronym> objects of the <glossterm>Database</glossterm>
I would say "... a PostgreSQL >Database<"
> + and the <glossterm>Global SQL Object</glossterm>s of the
> + <glossterm>Cluster</glossterm>. The <glossterm>System
> + Catalog</glossterm> resides in the schema
> + <literal>pg_catalog</literal>. Main parts are mirrored as
> + <glossterm>View</glossterm>s in the <glossterm>Schema</glossterm>
> + <literal>information_schema</literal>.
I wouldn't say "mirror": Some information is also exposed as >Views< in the
>information_schema< >Schema<.
> + <glossentry id="glossary-tablespace">
> + <glossterm>Tablespace</glossterm>
> + <glossdef>
> + <para>
> + A named location on the server filesystem. All <glossterm>SQL Object</glossterm>s
> + which require storage beyond their definition in the
> + <glossterm>System Catalog</glossterm>
> + must belong to a single tablespace.
Remove "single" as it sounds like we only support one.
> + <glossterm>Transaction</glossterm>
> + <glossdef>
> + <para>
> + A combination of commands that must act as a single
> + <glossterm>Atomic</glossterm> command: they all succeed or all fail
> + as a single unit, and their effects are not visible to other
> + <glossterm>Session</glossterm>s until
> + the <glossterm>Transaction</glossterm> is complete.
s/complete/commited/ ?
> + <glossentry id="glossary-unique">
> + <glossterm>Unique</glossterm>
> + <glossdef>
> + <para>
> + The condition of having no duplicate values in the same
> + <glossterm>Relation</glossterm>. Often used in the concept of
s/concept/context/
> + <glossterm>Vacuum</glossterm>
> + <glossdef>
> + <para>
> + The process of removing outdated <acronym>MVCC</acronym>
Maybe say "tuples which were deleted or obsoleted by an UPDATE".
But maybe you're trying to use generic language.
--
Justin
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-03-31 18:09 Justin Pryzby <[email protected]>
parent: Corey Huinker <[email protected]>
2 siblings, 1 reply; 97+ messages in thread
From: Justin Pryzby @ 2020-03-31 18:09 UTC (permalink / raw)
To: Corey Huinker <[email protected]>; +Cc: [email protected]
On Sun, Oct 13, 2019 at 04:52:05PM -0400, Corey Huinker wrote:
> 1. It's obviously incomplete. There are more terms, a lot more, to add.
How did you come up with the initial list of terms ?
Here's some ideas; I'm *not* suggesting to include all of everything, but
hopefully start with a coherent, self-contained list.
grep -roh '<firstterm>[^<]*' doc/src/ |sed 's/.*/\L&/' |sort |uniq -c |sort -nr |less
Maybe also:
object identifier
operator classes
operator family
visibility map
--
Justin
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-03-31 19:26 Corey Huinker <[email protected]>
parent: Justin Pryzby <[email protected]>
0 siblings, 1 reply; 97+ messages in thread
From: Corey Huinker @ 2020-03-31 19:26 UTC (permalink / raw)
To: Justin Pryzby <[email protected]>; +Cc: [email protected]
On Tue, Mar 31, 2020 at 2:09 PM Justin Pryzby <[email protected]> wrote:
> On Sun, Oct 13, 2019 at 04:52:05PM -0400, Corey Huinker wrote:
> > 1. It's obviously incomplete. There are more terms, a lot more, to add.
>
> How did you come up with the initial list of terms ?
>
1. I asked some newer database people to come up with a list of terms that
they used.
2. I then added some more terms that seemed obvious given that first list.
3. That combined list was long on general database concepts and theory, and
short on administration concepts
4. Then Jürgen suggested that we integrate his working list of terms, very
much focused on internals, so I did that.
5. Everything after that was applying suggested edits and new terms.
> Here's some ideas; I'm *not* suggesting to include all of everything, but
> hopefully start with a coherent, self-contained list.
>
I don't think this list will ever be complete. It will always be a work in
progress. I'd prefer to get the general structure of a glossary committed
in the short term, and we're free to follow up with edits that focus on the
wording.
>
> grep -roh '<firstterm>[^<]*' doc/src/ |sed 's/.*/\L&/' |sort |uniq -c
> |sort -nr |less
>
> Maybe also:
> object identifier
> operator classes
> operator family
> visibility map
>
Just so I can prioritize my work, which of these things, along with your
suggestions in previous emails, would you say is a barrier to considering
this ready for a committer?
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-04-01 07:34 Jürgen Purtz <[email protected]>
parent: Justin Pryzby <[email protected]>
0 siblings, 1 reply; 97+ messages in thread
From: Jürgen Purtz @ 2020-04-01 07:34 UTC (permalink / raw)
To: Corey Huinker <[email protected]>; +Cc: Justin Pryzby <[email protected]>; Alvaro Herrera <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
On 31.03.20 19:58, Justin Pryzby wrote:
> On Tue, Mar 31, 2020 at 04:13:00PM +0200, Jürgen Purtz wrote:
>> Please find some minor suggestions in the attachment. They are based on
>> Corey's last patch 0001-glossary-v4.patch.
>> @@ -220,7 +220,7 @@
>> Record</glossterm>s 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.
> I think you're correct in that "volume" is singular. But I think "collected"
> is the wrong world. I suggested "written".
>
"collected" is not optimal. I suggest "created". Please avoid "written",
the WAL records will be written when the Checkpointer is running, not
before. So:
"a certain volume of <glossterm>WAL records<glossterm> has been
collected."
Every thing else is ok for me.
Kind regards, Jürgen
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-04-01 07:34 Jürgen Purtz <[email protected]>
parent: Justin Pryzby <[email protected]>
0 siblings, 0 replies; 97+ messages in thread
From: Jürgen Purtz @ 2020-04-01 07:34 UTC (permalink / raw)
To: Corey Huinker <[email protected]>; +Cc: Justin Pryzby <[email protected]>; Alvaro Herrera <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
On 31.03.20 20:07, Justin Pryzby wrote:
> On Mon, Mar 30, 2020 at 01:10:19PM -0400, Corey Huinker wrote:
>> + <glossentry id="glossary-aggregating">
>> + <glossterm>Aggregating</glossterm>
>> + <glossdef>
>> + <para>
>> + The act of combining a collection of data (input) values into
>> + a single output value, which may not be of the same type as the
>> + input values.
> I think we maybe already tried to address this ; but could we define a noun
> form ? But not "aggregate" since it's the same word as the verb form. I think
> it would maybe be best to merge with "aggregate function", below.
Yes, combine the two. Or remove "aggregating" at all.
> + <glossentry id="glossary-log-writer">
>> + <glossterm>Log Writer</glossterm>
>> + <glossdef>
>> + <para>
>> + If activated and parameterized, the
> I still don't know what parameterized means here.
Remove "and parameterized". The Log Writer always has (default) parameters.
Every thing else is ok for me.
Kind regards, Jürgen
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-04-02 00:09 Alvaro Herrera <[email protected]>
parent: Jürgen Purtz <[email protected]>
0 siblings, 2 replies; 97+ messages in thread
From: Alvaro Herrera @ 2020-04-02 00:09 UTC (permalink / raw)
To: Jürgen Purtz <[email protected]>; +Cc: Corey Huinker <[email protected]>; Justin Pryzby <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
On 2020-Apr-01, Jürgen Purtz wrote:
>
> On 31.03.20 19:58, Justin Pryzby wrote:
> > On Tue, Mar 31, 2020 at 04:13:00PM +0200, Jürgen Purtz wrote:
> > > Please find some minor suggestions in the attachment. They are based on
> > > Corey's last patch 0001-glossary-v4.patch.
> > > @@ -220,7 +220,7 @@
> > > Record</glossterm>s 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.
> > I think you're correct in that "volume" is singular. But I think "collected"
> > is the wrong world. I suggested "written".
> >
> "collected" is not optimal. I suggest "created". Please avoid "written", the
> WAL records will be written when the Checkpointer is running, not before.
Actually, you're mistaken; the checkpointer hardly writes any WAL
records. In fact, it only writes *one* wal record, which is the
checkpoint record itself. All the other wal records are written either
by the backends that produce it, or by the wal writer process. By the
time the checkpoint runs, the wal records are long expected to be written.
Anyway I changed a lot of terms again, as well as changing the way the
terms are marked up -- for two reasons:
1. I didn't like the way the WAL-related entries were structured. I
created a new entry called "Write-Ahead Log", which explains what WAL
is; this replaces the term "WAL Log", which is redundant (since the L in
WAL stands for "log" already). I kept the id as glossary-wal, though,
because it's shorter and *shrug*. The definition uses the terms "wal
record" and "wal file", which I also rewrote.
2. I found out that "see xyz" and "see also" have bespoke markup in
Docbook -- <glosssee> and <glossseealso>. I changed some glossentries
to use those, removing some glossdefs and changing a couple of paras to
glossseealsos. I also removed all "id" properties from glossentries
that are just <glosssee>, because I think it's a mistake to have
references to entries that will make the reader look up a different
term; for me as a reader that's annoying, and I don't like to annoy
people.
While at it, I again came across "analytic", which is a term we don't
use much, so I made it a glosssee for "window function"; and while at it
I realized we didn't clearly explain what a window was. So I added
"window frame" for that. I considered adding the term "partition" which
is used in this context, but decided it wasn't necessary.
I also added "(process)" to terms that define processes. So
now we have "checkpointer (process)" and so on.
I rewrote the definition for "atomic" once again. Made it two
glossdefs, because I can. If you don't like this, I can undo.
I added "recycling".
I still have to go through some other defs.
--
Álvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Attachments:
[text/x-diff] 0001-glossary-v5.patch (51.1K, 2-0001-glossary-v5.patch)
download | inline diff:
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 1043d0f7ab..cf21ef857e 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -170,6 +170,7 @@
<!ENTITY limits SYSTEM "limits.sgml">
<!ENTITY acronyms SYSTEM "acronyms.sgml">
+<!ENTITY glossary SYSTEM "glossary.sgml">
<!ENTITY color SYSTEM "color.sgml">
<!ENTITY features-supported SYSTEM "features-supported.sgml">
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
new file mode 100644
index 0000000000..3c417f2fd3
--- /dev/null
+++ b/doc/src/sgml/glossary.sgml
@@ -0,0 +1,1526 @@
+<appendix id="glossary">
+ <title>Glossary</title>
+ <para>
+ This is a list of terms and their meaning in the context of
+ <productname>PostgreSQL</productname> and relational database
+ systems in general.
+ </para>
+
+ <glosslist>
+ <glossentry id="glossary-aggregating">
+ <glossterm>Aggregating</glossterm>
+ <glossdef>
+ <para>
+ The act of combining a collection of data (input) values into
+ a single output value, which may not be of the same type as the
+ input values.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-aggregate">
+ <glossterm>Aggregate Function</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm linkend="glossary-function">function</glossterm> that
+ combines multiple input values,
+ for example by counting, averaging or adding them all together,
+ yielding a single output value.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="functions-aggregate"/>.
+ </para>
+ <glossseealso otherterm="glossary-window-function" />
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Analytic Function</glossterm>
+ <glosssee otherterm="glossary-window-function" />
+ </glossentry>
+
+ <glossentry id="glossary-atomic">
+ <glossterm>Atomic</glossterm>
+ <glossdef>
+ <para>
+ In reference to a <glossterm linkend="glossary-datum">datum</glossterm>:
+ the fact that its value that cannot be broken down into smaller
+ components.
+ </para>
+ </glossdef>
+ <glossdef>
+ <para>
+ In reference to a
+ <glossterm linkend="glossary-transaction">database transaction</glossterm>:
+ the fact that all the operations in the transaction either complete as
+ a whole, or none of them become visible.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-atomicity">
+ <glossterm>Atomicity</glossterm>
+ <glossdef>
+ <para>
+ One of the <acronym>ACID</acronym> properties. This is the state of
+ being <glossterm>Atomic</glossterm> in the operational/transactional sense.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-attribute">
+ <glossterm>Attribute</glossterm>
+ <glossdef>
+ <para>
+ An element with a certain name and data type found within a
+ <glossterm>Tuple</glossterm> or <glossterm>Table</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-autovacuum">
+ <glossterm>Autovacuum</glossterm>
+ <glossdef>
+ <para>
+ Background processes that routinely perform
+ <glossterm>Vacuum</glossterm> and <glossterm>Analyze</glossterm>
+ operations.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="routine-vacuuming"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-backend-process">
+ <glossterm>Backend Process</glossterm>
+ <glossdef>
+ <para>
+ Processes of an <glossterm>Instance</glossterm> which act on behalf of
+ client <glossterm>Connection</glossterm>s and handle their requests.
+ </para>
+ <para>
+ (Don't confuse this term with the similar terms
+ <glossterm>Background Worker</glossterm> or
+ <glossterm>Background Writer</glossterm>).
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-background-worker">
+ <glossterm>Background Worker</glossterm>
+ <glossdef>
+ <para>
+ Individual processes within an <glossterm>Instance</glossterm>, which
+ run system- or user-supplied code. A typical use case is a process
+ which handles parts of an <acronym>SQL</acronym> query to take
+ advantage of parallel execution on servers with multiple
+ <acronym>CPU</acronym>s.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="bgworker"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-background-writer">
+ <glossterm>Background Writer</glossterm>
+ <glossdef>
+ <para>
+ A process that continuously writes dirty pages from
+ <glossterm>Shared Memory</glossterm> to the file system.
+ It wakes up periodically, but
+ works only for a short period in order to distribute its expensive
+ <acronym>I/O</acronym> activity over time, instead of generating fewer
+ larger <acronym>I/O</acronym> peaks which could block other processes.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="runtime-config-resource"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-cast">
+ <glossterm>Cast</glossterm>
+ <glossdef>
+ <para>
+ A conversion of a <glossterm>Datum</glossterm> from its current data
+ type to another data type.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-catalog">
+ <glossterm>Catalog</glossterm>
+ <glossdef>
+ <para>
+ The <acronym>SQL</acronym> standard uses this term to
+ indicate what is called a <glossterm>Database</glossterm> in
+ <productname>PostgreSQL</productname>'s terminology.
+ </para>
+ <para>
+ This should not be confused with the
+ <glossterm>System Catalog</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="manage-ag-overview"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-check-constraint">
+ <glossterm>Check Constraint</glossterm>
+ <glossdef>
+ <para>
+ A type of <glossterm>Constraint</glossterm> defined on a
+ <glossterm>Relation</glossterm> which restricts the values allowed in
+ one or more <glossterm>Attribute</glossterm>s. The <glossterm>Check
+ Constraint</glossterm> can make reference to any
+ attribute in the
+ <glossterm>Relation</glossterm>, but cannot reference other
+ <glossterm>Row</glossterm>s of the same
+ relation or other relations.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="ddl-constraints"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-checkpointer">
+ <glossterm>Checkpointer (process)</glossterm>
+ <glossdef>
+ <para>
+ A process that writes dirty pages to the file system and creates a special
+ checkpoint WAL 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 has been collected.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-checkpoint">
+ <glossterm>Checkpoint</glossterm>
+ <glossdef>
+ <para>
+ A point in time when all older dirty pages of the
+ <glossterm>Shared Memory</glossterm>, all older <glossterm>WAL Record</glossterm>s,
+ and a special <glossterm>Checkpoint record</glossterm> have been written
+ and flushed to disk.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-checkpoint"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-cluster">
+ <glossterm>Cluster</glossterm>
+ <glossdef>
+ <para>
+ A group of <glossterm>Database</glossterm>s plus their
+ <glossterm>Global SQL Object</glossterm>s. The
+ <glossterm>Cluster</glossterm> is managed by exactly one
+ <glossterm>Instance</glossterm>. A newly created
+ <glossterm>Cluster</glossterm> will have three
+ <glossterm>Database</glossterm>s created automatically. They are
+ <literal>template0</literal>, <literal>template1</literal>, and
+ <literal>postgres</literal>. It is expected that an application will
+ create one or more additional <glossterm>Database</glossterm>s aside
+ from these three.
+ </para>
+ <para>
+ Don't confuse the <productname>PostgreSQL</productname>-specific term
+ <glossterm>Cluster</glossterm> with the SQL command
+ <literal>CLUSTER</literal>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-column">
+ <glossterm>Column</glossterm>
+ <glossdef>
+ <para>
+ An <glossterm>Attribute</glossterm> found in a
+ <glossterm>Table</glossterm> or <glossterm>View</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-commit">
+ <glossterm>Commit</glossterm>
+ <glossdef>
+ <para>
+ The act of finalizing a <glossterm>Transaction</glossterm> within the
+ <glossterm>Database</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-commit"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-concurrency">
+ <glossterm>Concurrency</glossterm>
+ <glossdef>
+ <para>
+ The concept that multiple independent operations happen within the
+ <glossterm>Database</glossterm> at the same time.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-connection">
+ <glossterm>Connection</glossterm>
+ <glossdef>
+ <para>
+ An established line of communication between a client process
+ and a <glossterm>Backend Process</glossterm>. If the two involved processes reside on the
+ same <glossterm>Server</glossterm>, then the connection can either use
+ <acronym>TCP/IP</acronym> or Unix-domain sockets. Otherwise,
+ only <acronym>TCP/IP</acronym> can be used.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="runtime-config-connection"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-consistency">
+ <glossterm>Consistency</glossterm>
+ <glossdef>
+ <para>
+ One of the <acronym>ACID</acronym> properties. This means that the database
+ is always in compliance with its own rules such as <glossterm>Table</glossterm>
+ structure, <glossterm>Constraint</glossterm>s,
+ <glossterm>Uniqueness</glossterm>, etc.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-constraint">
+ <glossterm>Constraint</glossterm>
+ <glossdef>
+ <para>
+ A restriction on the values of data allowed within a
+ <glossterm>Table</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="ddl-constraints"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Data Area</glossterm>
+ <glosssee otherterm="glossary-data-directory" />
+ </glossentry>
+
+ <glossentry id="glossary-data-directory">
+ <glossterm>Data Directory</glossterm>
+ <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 <glossterm>Tablespace</glossterm>s. The environment
+ variable <literal>PGDATA</literal> often — but not always —
+ refers to the <glossterm>Data Directory</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="storage-file-layout"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-database">
+ <glossterm>Database</glossterm>
+ <glossdef>
+ <para>
+ A named collection of <glossterm>SQL Object</glossterm>s.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="manage-ag-overview"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Database Server</glossterm>
+ <glosssee otherterm="glossary-instance" />
+ </glossentry>
+
+ <glossentry id="glossary-datum">
+ <glossterm>Datum</glossterm>
+ <glossdef>
+ <para>
+ The internal representation of one value of a <acronym>SQL</acronym>
+ data type.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-delete">
+ <glossterm>Delete</glossterm>
+ <glossdef>
+ <para>
+ A <acronym>SQL</acronym> command which removes
+ <glossterm>Row</glossterm>s from a given <glossterm>Table</glossterm>
+ or <glossterm>Relation</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-delete"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-durability">
+ <glossterm>Durability</glossterm>
+ <glossdef>
+ <para>
+ One of the <acronym>ACID</acronym> properties. This is the assurance that once a
+ <glossterm>Transaction</glossterm> has been <glossterm>Committed</glossterm>, the
+ data will remain even after a system failure or crash.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-file-segment">
+ <glossterm>File Segment</glossterm>
+ <glossdef>
+ <para>
+ A physical file which stores data for a given
+ <glossterm>Heap</glossterm> or <glossterm>Index</glossterm> object.
+ <glossterm>File Segment</glossterm>s are limited in size by a
+ configuration value and if that size is exceeded, it will be split
+ into multiple physical files.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="storage-file-layout"/>.
+ </para>
+ <para>
+ (Don't confuse this term with the similar term
+ <glossterm>WAL Segment</glossterm>).
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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> so that it appears as if were in local
+ <glossterm>Table</glossterm>(s). With a Foreign Data Wrapper it is
+ possible to define a <glossterm>Foreign Server</glossterm> and
+ <glossterm>Foreign Table</glossterm>s.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createforeigndatawrapper"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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(s) in those <glossterm>Column</glossterm>s to
+ identify exactly one <glossterm>Row</glossterm> in another (or the same)
+ <glossterm>Table</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-foreign-server">
+ <glossterm>Foreign Server</glossterm>
+ <glossdef>
+ <para>
+ A named collection of <glossterm>Foreign Table</glossterm>s which all
+ use the same <glossterm>Foreign Data Wrapper</glossterm> and have
+ other configuration values in common.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createserver"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-foreign-table">
+ <glossterm>Foreign Table</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Relation</glossterm> which appears to have
+ <glossterm>Row</glossterm>s and <glossterm>Column</glossterm>s similar
+ to a regular <glossterm>Table</glossterm>, but will forward requests
+ for data through its <glossterm>Foreign Data Wrapper</glossterm>,
+ which will return <glossterm>Result Set</glossterm>s structured
+ according to the definition of the <glossterm>Foreign Table</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createforeigntable"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-function">
+ <glossterm>Function</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.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createfunction"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-global-sql-object">
+ <glossterm>Global SQL Object</glossterm>
+ <glossdef>
+ <para>
+ <glossterm>SQL Object</glossterm>s which do not belong to a specific
+ <glossterm>Schema</glossterm>.
+ </para>
+ <para>
+ Objects that exist at the <glossterm>Database</glossterm> level
+ include Extensions such as
+ <glossterm>Foreign Data Wrapper</glossterm>s.
+ </para>
+ <para>
+ Objects that exist at the <glossterm>Cluster</glossterm> level
+ include <glossterm>Role</glossterm>s,
+ <glossterm>Tablespace</glossterm>s,
+ <glossterm>Replication</glossterm> origins, and subscriptions
+ for logical replication.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-grant">
+ <glossterm>Grant</glossterm>
+ <glossdef>
+ <para>
+ A <acronym>SQL</acronym> command that is used to allow
+ <glossterm>User</glossterm>s or <glossterm>Role</glossterm>s to access
+ specific objects within the <glossterm>Database</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-grant"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-heap">
+ <glossterm>Heap</glossterm>
+ <glossdef>
+ <para>
+ Contains the values of <glossterm>Row</glossterm> attributes
+ (i.e. the data). The <glossterm>Heap</glossterm> is realized within
+ <glossterm>Database</glossterm> files.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Host</glossterm>
+ <glosssee otherterm="glossary-server" />
+ </glossentry>
+
+ <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> types
+ such as a <glossterm>Materialized View</glossterm>). Its internal
+ structure supports fast retrieval of and access to the original
+ data.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createindex"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-insert">
+ <glossterm>Insert</glossterm>
+ <glossdef>
+ <para>
+ A <acronym>SQL</acronym> command used to add new data into a
+ <glossterm>Table</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-insert"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-instance">
+ <glossterm>Instance</glossterm>
+ <glossdef>
+ <para>
+ An <glossterm>Instance</glossterm> is a group of processes plus their
+ common <glossterm>Shared Memory</glossterm> running on a single
+ <glossterm>Server</glossterm>. The <glossterm>Instance</glossterm>
+ handles all key features of a <acronym>DBMS</acronym>: read and write
+ access to files and shared memory, assurance of
+ the <acronym>ACID</acronym> paradigm, <acronym>MVCC</acronym>,
+ <glossterm>Connection</glossterm>s to client programs, backup,
+ recovery, replication, privileges, etc.
+ </para>
+ <para>
+ An <glossterm>Instance</glossterm> manages exactly one
+ <glossterm>Cluster</glossterm>.
+ </para>
+ <para>
+ Many <glossterm>Instance</glossterm>s can run on the same server as
+ long as their <acronym>TCP/IP</acronym> ports do not conflict.
+ Different instances on a server may use the
+ same or different versions of <productname>PostgreSQL</productname>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-isolation">
+ <glossterm>Isolation</glossterm>
+ <glossdef>
+ <para>
+ One of the <acronym>ACID</acronym> properties. This means that concurrently running
+ <glossterm>Transaction</glossterm>s affect the database exactly as if they had been
+ executed sequentially.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-join">
+ <glossterm>Join</glossterm>
+ <glossdef>
+ <para>
+ A <acronym>SQL</acronym> keyword used in <command>SELECT</command> statements for
+ combining data from multiple <glossterm>Relation</glossterm>s.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-key">
+ <glossterm>Key</glossterm>
+ <glossdef>
+ <para>
+ A means of identifying a <glossterm>Row</glossterm> within a
+ <glossterm>Table</glossterm> or <glossterm>Relation</glossterm> by
+ values contained within one or more <glossterm>Attribute</glossterm>s
+ in that <glossterm>Table</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-lock">
+ <glossterm>Lock</glossterm>
+ <glossdef>
+ <para>
+ A mechanism that allows a process to limit or prevent simultaneous
+ access to a resource.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-log-file">
+ <glossterm>Log File</glossterm>
+ <glossdef>
+ <para>
+ <glossterm>Log File</glossterm>s contain human-readable text lines about
+ events. Examples include login failures, long-running queries, etc.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="logfile-maintenance"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-logger">
+ <glossterm>Logger (process)</glossterm>
+ <glossdef>
+ <para>
+ If activated, the
+ <glossterm>Logger</glossterm> process
+ writes information about database events into the current
+ <glossterm>Log File</glossterm>. When reaching certain time- or
+ volume-dependent criteria, a new log file is created.
+ Also called <firstterm>syslogger</firstterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="runtime-config-logging"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-log-record">
+ <glossterm>Log Record</glossterm>
+ <glossdef>
+ <para>
+ Archaic term for a <glossterm>WAL Record</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-logged">
+ <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>Table</glossterm>s are <glossterm>Logged</glossterm>. A
+ table can be specified as <glossterm>Unlogged</glossterm> either at
+ creation time or via the <command>ALTER TABLE</command> command.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-master">
+ <glossterm>Master</glossterm>
+ <glossdef>
+ <para>
+ When two or more <glossterm>Database</glossterm>s are linked via
+ <glossterm>Replication</glossterm>, the <glossterm>Server</glossterm>
+ that is considered the authoritative source of information is called
+ the <glossterm>Master</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-materialized">
+ <glossterm>Materialized</glossterm>
+ <glossdef>
+ <para>
+ The act of storing information rather than just the method of accessing
+ the information. This term is used in <glossterm>Materialized
+ View</glossterm>s, meaning that the data derived from the
+ <glossterm>View</glossterm> is actually stored on disk separately from
+ the sources of that data. When using the term
+ <glossterm>Materialized</glossterm> to refer to
+ multi-step queries, it means that the data of a given step is stored
+ 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 stores data in the same way
+ that a <glossterm>Table</glossterm> does. It cannot be modified via
+ <command>INSERT</command>, <command>UPDATE</command>, or
+ <command>DELETE</command> operations.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-creatematerializedview"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-null">
+ <glossterm>Null</glossterm>
+ <glossdef>
+ <para>
+ A concept of non-existence that is a central tenet of Relational
+ Database Theory. It represents the absence of value.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-partition">
+ <glossterm>Partition</glossterm>
+ <glossdef>
+ <para>
+ In reference to a <glossterm>Table</glossterm>:
+ A <glossterm>Table</glossterm> that can be queried directly,
+ or via a partitioned table, which is a collection of
+ sub-tables, each capable of holding one defined
+ subset of information that does not overlap with any other
+ table in the collection.
+ </para>
+ <para>
+ In reference to a <glossterm>Analytic Function</glossterm>:
+ a partition is a definition that identifies which neighboring
+ <glossterm>Row</glossterm>s can be considered by the
+ function.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-postmaster">
+ <glossterm>Postmaster</glossterm>
+ <glossdef>
+ <para>
+ The very first process of an <glossterm>Instance</glossterm>. It
+ starts the other processes and creates
+ <glossterm>Backend Process</glossterm>es on demand.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="server-start"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-primary-key">
+ <glossterm>Primary Key</glossterm>
+ <glossdef>
+ <para>
+ A special case of a <glossterm>Unique Index</glossterm> defined on a
+ <glossterm>Table</glossterm> or other <glossterm>Relation</glossterm>
+ that also guarantees that all of the <glossterm>Attribute</glossterm>s
+ 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
+ table, though it is possible to have multiple
+ unique indexes that also have no null-capable attributes.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-procedure">
+ <glossterm>Procedure</glossterm>
+ <glossdef>
+ <para>
+ A defined set of instructions for manipulating data within a
+ <glossterm>Database</glossterm>. A <glossterm>Procedure</glossterm> can
+ be written in a variety of programming languages. They may seem
+ similar to <glossterm>Function</glossterm>s, 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
+ as <command>COMMIT</command> and <command>ROLLBACK</command>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createprocedure"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Record</glossterm>
+ <glosssee otherterm="glossary-tuple" />
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Recycling</glossterm>
+ <glosssee otherterm="glossary-wal-file" />
+ </glossentry>
+
+ <glossentry id="glossary-referential-integrity">
+ <glossterm>Referential Integrity</glossterm>
+ <glossdef>
+ <para>
+ A means of restricting data in one <glossterm>Relation</glossterm>
+ by a <glossterm>Foreign Key</glossterm>
+ so that it must have matching data in another
+ <glossterm>Relation</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-relation">
+ <glossterm>Relation</glossterm>
+ <glossdef>
+ <para>
+ The generic term for all objects in a <glossterm>Database</glossterm>
+ that have a name and a list of <glossterm>Attribute</glossterm>s
+ defined in a specific order. <glossterm>Table</glossterm>s,
+ <glossterm>View</glossterm>s, <glossterm>Foreign Table</glossterm>s,
+ <glossterm>Materialized View</glossterm>s, and
+ <glossterm>Index</glossterm>es are all
+ <glossterm>Relation</glossterm>s.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-replica">
+ <glossterm>Replica</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Database</glossterm> that is paired with a
+ <glossterm>Master</glossterm>
+ database and is maintaining a copy of some or
+ all of the Master <glossterm>Database</glossterm>'s data. The primary
+ reasons for doing this are to allow for greater access to that data,
+ and to maintain availability of the data in the event that the
+ <glossterm>Master</glossterm> becomes unavailable.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-replication">
+ <glossterm>Replication</glossterm>
+ <glossdef>
+ <para>
+ The act of reproducing data on one <glossterm>Server</glossterm> onto
+ another server called a <glossterm>Replica</glossterm>. This can take the
+ form of Physical <glossterm>Replication</glossterm>, where all file
+ changes from one server are copied verbatim,
+ or Logical <glossterm>Replication</glossterm> where a defined subset
+ of data changes are conveyed.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-result-set">
+ <glossterm>Result Set</glossterm>
+ <glossdef>
+ <para>
+ A data structure transmitted from a <glossterm>Backend Process</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. The data structure consists of zero or more
+ <glossterm>Row</glossterm>s with the same ordered set of
+ <glossterm>Attribute</glossterm>s.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-revoke">
+ <glossterm>Revoke</glossterm>
+ <glossdef>
+ <para>
+ A command to prevent access to a named set of
+ <glossterm>Database</glossterm> objects for a named list of
+ <glossterm>User</glossterm>s and <glossterm>Role</glossterm>s.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-revoke"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-role">
+ <glossterm>Role</glossterm>
+ <glossdef>
+ <para>
+ A collection of access privileges to the
+ <glossterm>Database</glossterm>. <glossterm>Role</glossterm>s are
+ themselves a privilege that can be granted to other roles. This is
+ often done for convenience or to ensure completeness when multiple
+ <glossterm>User</glossterm>s need the same privileges.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createrole"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-rollback">
+ <glossterm>Rollback</glossterm>
+ <glossdef>
+ <para>
+ A command to undo all of the operations performed since the beginning
+ of a <glossterm>Transaction</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-rollback"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Row</glossterm>
+ <glosssee otherterm="glossary-tuple" />
+ </glossentry>
+
+ <glossentry id="glossary-savepoint">
+ <glossterm>Savepoint</glossterm>
+ <glossdef>
+ <para>
+ A special mark inside the sequence of steps in a
+ <glossterm>Transaction</glossterm>. Data modifications after this
+ point in time may be reverted to the time of the savepoint.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-savepoint"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-schema">
+ <glossterm>Schema</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Schema</glossterm> is a namespace for
+ <glossterm>SQL object</glossterm>s, 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 Object</glossterm>s 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 reusing
+ a name in multiple <glossterm>Schema</glossterm>s.
+ </para>
+ <para>
+ Many <glossterm>SQL Object</glossterm>s reside in the default
+ <glossterm>Schema</glossterm> <literal>public</literal>, but it is
+ expected that more schemas are created to hold application-specific
+ <glossterm>SQL Object</glossterm>s.
+ </para>
+ <para>
+ More generically, the term <glossterm>Schema</glossterm> is used to
+ mean all data descriptions (<glossterm>Table</glossterm> definitions,
+ <glossterm>Constraint</glossterm>s, comments) for a given
+ <glossterm>Database</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="ddl-schemas"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Segment</glossterm>
+ <glosssee otherterm="glossary-file-segment" />
+ </glossentry>
+
+ <glossentry id="glossary-select">
+ <glossterm>Select</glossterm>
+ <glossdef>
+ <para>
+ The <acronym>SQL</acronym> 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>Function</glossterm>s invoked within the query could have
+ side effects that do modify data.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-select"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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 for the duration of the
+ <glossterm>Transaction</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-server">
+ <glossterm>Server</glossterm>
+ <glossdef>
+ <para>
+ The term <glossterm>Server</glossterm> denotes real hardware, a
+ container, or a Virtual Machine.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-session">
+ <glossterm>Session</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Connection</glossterm> to the <glossterm>Database</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-sequence">
+ <glossterm>Sequence</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Database</glossterm> object which represents the
+ 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 (usually
+ 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, that value
+ is returned to the invoking query, and the current value of the
+ sequence is updated to reflect the new value. The value can be updated
+ multiple times in a single query, the net effect being that each row
+ selected will have a different value. Values taken from a
+ <glossterm>Sequence</glossterm> are never reverted, even in the case of
+ a <glossterm>Rollback</glossterm>, which means that the
+ <glossterm>Sequence</glossterm> will never generate the same number twice,
+ which makes it useful for generating
+ <glossterm>Primary Key</glossterm> values.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createsequence"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-shared-memory">
+ <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 Record</glossterm>s, and stores additional common
+ information. Note that <glossterm>Shared Memory</glossterm> belongs to
+ the complete <glossterm>Instance</glossterm>, not to a single
+ <glossterm>Database</glossterm>.
+ </para>
+ <para>
+ <glossterm>Shared Memory</glossterm> is organized into pages. If a
+ page is modified, it is called a dirty page until it is written back
+ to the file system.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="runtime-config-resource-memory"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-sql-object">
+ <glossterm>SQL Object</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Table</glossterm>, <glossterm>View</glossterm>,
+ <glossterm>Materialized View</glossterm>,
+ <glossterm>Index</glossterm>, <glossterm>Constraint</glossterm>,
+ <glossterm>Sequence</glossterm>, <glossterm>Function</glossterm>,
+ <glossterm>Procedure</glossterm>, <glossterm>Trigger</glossterm>,
+ data type, or operator. Every <glossterm>SQL Object</glossterm>
+ belongs to exactly one <glossterm>Schema</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="manage-ag-overview"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-stats-collector">
+ <glossterm>Stats Collector</glossterm>
+ <glossdef>
+ <para>
+ This process collects statistical information about the
+ <glossterm>Cluster</glossterm>'s activities.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="monitoring-stats"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-system-catalog">
+ <glossterm>System Catalog</glossterm>
+ <glossdef>
+ <para>
+ A collection of <glossterm>Table</glossterm>s and
+ <glossterm>View</glossterm>s which describe the structure of all
+ <acronym>SQL</acronym> objects of the <glossterm>Database</glossterm>
+ and the <glossterm>Global SQL Object</glossterm>s of the
+ <glossterm>Cluster</glossterm>. The <glossterm>System
+ Catalog</glossterm> resides in the schema
+ <literal>pg_catalog</literal>. Main parts are mirrored as
+ <glossterm>View</glossterm>s in the <glossterm>Schema</glossterm>
+ <literal>information_schema</literal>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="ddl-schemas"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-table">
+ <glossterm>Table</glossterm>
+ <glossdef>
+ <para>
+ A collection of <glossterm>Tuple</glossterm>s (also known as
+ <glossterm>Row</glossterm>s or <glossterm>Record</glossterm>s) having
+ a common data structure (the same number of
+ <glossterm>Attribute</glossterm>s, in the same order, having the same
+ name and type per position). A <glossterm>Table</glossterm> is the
+ most common form of <glossterm>Relation</glossterm> in
+ <productname>PostgreSQL</productname>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createtable"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-tablespace">
+ <glossterm>Tablespace</glossterm>
+ <glossdef>
+ <para>
+ A named location on the server filesystem. All <glossterm>SQL Object</glossterm>s
+ which require storage beyond their definition in the
+ <glossterm>System Catalog</glossterm>
+ must belong to a single tablespace.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="manage-ag-tablespaces"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-temporary-tables">
+ <glossterm>Temporary Table</glossterm>
+ <glossdef>
+ <para>
+ <glossterm>Table</glossterm>s that exist either for the lifetime of a
+ <glossterm>Session</glossterm> or a
+ <glossterm>Transaction</glossterm>, as specified at the time of creation. The
+ data in them is not visible to other sessions,
+ and is not <glossterm>Logged</glossterm>.
+ <glossterm>Temporary Table</glossterm>s are often used to store
+ intermediate data for a multi-step operation.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createtable"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-transaction">
+ <glossterm>Transaction</glossterm>
+ <glossdef>
+ <para>
+ A combination of commands that must act as a single
+ <glossterm>Atomic</glossterm> command: they all succeed or all fail
+ as a single unit, and their effects are not visible to other
+ <glossterm>Session</glossterm>s until
+ the <glossterm>Transaction</glossterm> is complete.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="transaction-iso"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-trigger">
+ <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>, <command>DELETE</command>,
+ <command>TRUNCATE</command>) is applied to a <glossterm>Relation</glossterm>.
+ A <glossterm>Trigger</glossterm>
+ executes within the same <glossterm>Transaction</glossterm> as the
+ statement which invoked it, and if the <glossterm>Function</glossterm>
+ fails, then the invoking statement also fails.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createtrigger"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-tuple">
+ <glossterm>Tuple</glossterm>
+ <glossdef>
+ <para>
+ A collection of <glossterm>Attribute</glossterm>s in a fixed order.
+ That order may be defined by the <glossterm>Table</glossterm> where
+ the <glossterm>Tuple</glossterm> is found, in which case the
+ <glossterm>Tuple</glossterm> is often called a
+ <glossterm>Row</glossterm> or <glossterm>Record</glossterm>. It may
+ also be defined by the structure of a
+ <glossterm>Result Set</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-unique">
+ <glossterm>Unique</glossterm>
+ <glossdef>
+ <para>
+ The condition of having no duplicate values in the same
+ <glossterm>Column</glossterm> of a <glossterm>Relation</glossterm>.
+ Often used in the concept of
+ <glossterm>Unique Index</glossterm>es.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-unlogged">
+ <glossterm>Unlogged</glossterm>
+ <glossdef>
+ <para>
+ Changes to an unlogged <glossterm>Relation</glossterm> are not
+ reflected in the <glossterm>WAL Log</glossterm>. This disables
+ replication and crash recovery for these relations.
+ </para>
+ <para>
+ The primary use of unlogged tables is for storing
+ transient work data that must be shared across processes.
+ </para>
+ <para>
+ <glossterm>Temporary Table</glossterm>s are always unlogged.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-update">
+ <glossterm>Update</glossterm>
+ <glossdef>
+ <para>
+ A <acronym>SQL</acronym> command used to modify <glossterm>Row</glossterm>s
+ that may already exist in a specified <glossterm>Table</glossterm>.
+ It cannot create or remove rows.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-update"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-user">
+ <glossterm>User</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Role</glossterm> that has the <literal>LOGIN</literal>
+ privilege is said to be a <glossterm>User</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-user-mapping">
+ <glossterm>User Mapping</glossterm>
+ <glossdef>
+ <para>
+ The translation of login credentials in the local
+ <glossterm>Database</glossterm> to credentials in a remote data system
+ defined by a <glossterm>Foreign Data Wrapper</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createusermapping"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-vacuum">
+ <glossterm>Vacuum</glossterm>
+ <glossdef>
+ <para>
+ The process of removing outdated <acronym>MVCC</acronym>
+ <glossterm>Tuple</glossterm>s from a <glossterm>Heap</glossterm> or
+ <glossterm>Index</glossterm>. This can be initiated through the use of
+ the <command>VACUUM</command> command, but can also be handled automatically
+ via <glossterm>Autovacuum</glossterm> processes.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-vacuum"/> .
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-view">
+ <glossterm>View</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Relation</glossterm> that is defined by a
+ <command>SELECT</command> statement, but has no storage of its own.
+ Any time a query references a <glossterm>View</glossterm>, the
+ definition of the <glossterm>View</glossterm> is substituted into the
+ query as if the user had typed that subquery instead of the name of
+ the <glossterm>View</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createview"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-wal-archiver">
+ <glossterm>WAL Archiver (process)</glossterm>
+ <glossdef>
+ <para>
+ A process that saves copies of <glossterm>WAL File</glossterm>s
+ for the purposes of creating backups or keeping
+ <glossterm>Replica</glossterm>s current.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="continuous-archiving"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-wal-file">
+ <glossterm>WAL File</glossterm>
+ <glossdef>
+ <para>
+ Each of the numerically-numbered files that provide storage space for
+ <glossterm linkend="glossary-wal">WAL</glossterm>.
+ The files are all of the same predefined size
+ and are written in sequential order, interspersing changes
+ as they occur in multiple simultaneous sessions.
+ If the system crashes, the files are read in order, and each of the
+ changes are replayed to restore the system to the state as it was
+ before the crash.
+ </para>
+ <para>
+ Each WAL file can be released after a
+ <glossterm linkend="glossary-checkpoint">checkpoint</glossterm>
+ writes all the changes in it to the corresponding data files.
+ Releasing the file can be done either by deleting it, or by changing its
+ name so that it will be used in the future, which is called
+ <firstterm>recycling</firstterm>.
+ </para>
+
+ <para>
+ For more information, see
+ <xref linkend="wal-internals"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>WAL</glossterm>
+ <glosssee otherterm="glossary-wal" />
+ </glossentry>
+
+ <glossentry id="glossary-wal-record">
+ <glossterm>WAL Record</glossterm>
+ <glossdef>
+ <para>
+ A low-level description of an individual data change.
+ It contains sufficient information for the data change to be
+ re-executed (<firstterm>replayed</firstterm>) in case a system failure
+ causes the change to be lost.
+ WAL records use a non-printable binary format.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="wal-internals"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>WAL Segment</glossterm>
+ <glosssee otherterm="glossary-wal-file" />
+ </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 id="linkend-shared-memory">shared memory</glossterm> to
+ <glossterm id="linkend-wal-file">WAL files</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="runtime-config-wal"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-window-frame">
+ <glossterm>Window frame</glossterm>
+ <glossdef>
+ <para>
+ In a result set, a subset of neighboring rows that match some user
+ specified criteria form a window frame.
+ For example, in a query that returns employees across several departments,
+ the employees from each specific department can form one window frame.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-window-function">
+ <glossterm>Window Function</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-window-frame">window frame</glossterm>.
+ 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 window frame.
+ Also known as <firstterm>analytic functions</firstterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="tutorial-window"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-wal">
+ <glossterm>Write-Ahead Log</glossterm>
+ <glossdef>
+ <para>
+ The journal that keeps track of the changes in the
+ <glossterm>Instance</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>.
+ </para>
+ </glossdef>
+ </glossentry>
+ </glosslist>
+</appendix>
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index 1f7bd32878..ba3d626102 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -278,6 +278,7 @@
&docguide;
&limits;
&acronyms;
+ &glossary;
&color;
</part>
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-04-02 01:09 Justin Pryzby <[email protected]>
parent: Corey Huinker <[email protected]>
0 siblings, 1 reply; 97+ messages in thread
From: Justin Pryzby @ 2020-04-02 01:09 UTC (permalink / raw)
To: Corey Huinker <[email protected]>; +Cc: [email protected]
On Tue, Mar 31, 2020 at 03:26:02PM -0400, Corey Huinker wrote:
> Just so I can prioritize my work, which of these things, along with your
> suggestions in previous emails, would you say is a barrier to considering
> this ready for a committer?
To answer your off-list inquiry, I'm not likely to mark it "ready" myself.
I don't know if any of these would be a "blocker" for someone else.
> > Here's some ideas; I'm *not* suggesting to include all of everything, but
> > hopefully start with a coherent, self-contained list.
>
> > grep -roh '<firstterm>[^<]*' doc/src/ |sed 's/.*/\L&/' |sort |uniq -c
> > |sort -nr |less
I looked through that list and found these that might be good to include now or
in the future. Probably all of these need language polishing; I'm not
requesting you to just copy them in just to say they're there.
join: concept of combining columns from two tables or other relations. The
result of joining a table with N rows to another table with M rows might have
up to N*M rows (if every row from the first table "joins to" every row on the
second table).
normalized: A database schema is said to be "normalized" if its redundancy has
been removed. Typically a "normalized" schema has a larger number of tables,
which include ID columns, and queries typically involve joining together
multiple tables.
query: a request send by a client to a server, usually to return results or to
modify data on the server;
query plan: the particular procedure by which the database server executes a
query. A simple query involving a single table could might be planned using a
sequential scan or an index scan. For a complex query involving multiple
tables joined togther, the optimizer attempts to determine the
cheapest/fastest/best way to execute the query, by joining tables in the
optimal order, and with the optimal join strategy.
planner/optimizer: ...
transaction isolation:
psql: ...
synchronous: An action is said to be "synchronous" if it does not return to its
requestor until its completion;
bind parameters: arguments to a SQL query that are sent separately from the
query text. For example, the query text "SELECT * FROM tbl WHERE col=$1" might
be executed for some certain value of the $1 parameter. If parameters are sent
"in-line" as a part of the query text, they need to be properly
quoted/escaped/sanitized, to avoid accidental or malicious misbehavior if the
input contains special characters like semicolons or quotes.
> > Maybe also:
> > object identifier
> > operator classes
> > operator family
> > visibility map
--
Justin
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-04-02 01:41 Alvaro Herrera <[email protected]>
parent: Justin Pryzby <[email protected]>
0 siblings, 1 reply; 97+ messages in thread
From: Alvaro Herrera @ 2020-04-02 01:41 UTC (permalink / raw)
To: Justin Pryzby <[email protected]>; +Cc: Corey Huinker <[email protected]>; [email protected]
On 2020-Apr-01, Justin Pryzby wrote:
> planner/optimizer: ...
I propose we define "planner" and make "optimizer" a <glosssee> entry.
I further propose not to define the term "normalized", at least not for
now. That seems a very deep rabbit hole.
--
Álvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-04-02 03:34 Corey Huinker <[email protected]>
parent: Alvaro Herrera <[email protected]>
1 sibling, 0 replies; 97+ messages in thread
From: Corey Huinker @ 2020-04-02 03:34 UTC (permalink / raw)
To: Alvaro Herrera <[email protected]>; +Cc: Jürgen Purtz <[email protected]>; Justin Pryzby <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
>
> 2. I found out that "see xyz" and "see also" have bespoke markup in
> Docbook -- <glosssee> and <glossseealso>. I changed some glossentries
> to use those, removing some glossdefs and changing a couple of paras to
> glossseealsos. I also removed all "id" properties from glossentries
> that are just <glosssee>, because I think it's a mistake to have
> references to entries that will make the reader look up a different
> term; for me as a reader that's annoying, and I don't like to annoy
> people.
>
+1 These structural enhancements are great. I'm fine with removing the id
from just-glossee, and glad that we're keeping the entry to aid discovery.
> I rewrote the definition for "atomic" once again. Made it two
> glossdefs, because I can. If you don't like this, I can undo.
>
+1 Splitting this into two definitions, one for each context, is the most
sensible thing and I don't know why I didn't do that in the first place.
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-04-02 03:44 Corey Huinker <[email protected]>
parent: Alvaro Herrera <[email protected]>
0 siblings, 1 reply; 97+ messages in thread
From: Corey Huinker @ 2020-04-02 03:44 UTC (permalink / raw)
To: Alvaro Herrera <[email protected]>; +Cc: Justin Pryzby <[email protected]>; [email protected]
>
> I propose we define "planner" and make "optimizer" a <glosssee> entry.
>
I have no objection to more entries, or edits to entries, but am concerned
that the process leads to someone having to manually merge several
start-from-scratch patches, with no clear sense of when we'll be done. I
may make sense to appoint an edit-collector.
> I further propose not to define the term "normalized", at least not for
> now. That seems a very deep rabbit hole.
>
+1 I think we appointed a guy named Xeno to work on that definition. He
says he's getting close...
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-04-02 08:43 Alvaro Herrera <[email protected]>
parent: Corey Huinker <[email protected]>
0 siblings, 0 replies; 97+ messages in thread
From: Alvaro Herrera @ 2020-04-02 08:43 UTC (permalink / raw)
To: Corey Huinker <[email protected]>; +Cc: Justin Pryzby <[email protected]>; [email protected]
On 2020-Apr-01, Corey Huinker wrote:
> > I propose we define "planner" and make "optimizer" a <glosssee> entry.
>
> I have no objection to more entries, or edits to entries, but am concerned
> that the process leads to someone having to manually merge several
> start-from-scratch patches, with no clear sense of when we'll be done. I
> may make sense to appoint an edit-collector.
I added "query planner" (please suggest edits) and "query" (using
Justin's def) and edited the defs of the ACID terms a little bit (in
particular moved the definition of atomic transaction to "atomicity"
from "atomic", and made the latter reference the former instead of the
other way around). Also removed "Aggregating" as suggested upthread. I
moved "master" over to "primary (server)", keeping the ref; we don't use
the former much.
There's only one "serious" mistake in the defs AFAICS which is that of
"global objects". Only roles, tablespace, databases are global objects.
Objects that are not in a schema (extensions, etc) are not "global" in
that sense.
I think all <glossterm> used in definitions should have linkend.
I hope to get this committed today, but I'm going to sleep now so if you
want to suggest further edits, now's the time. I think the terms
proposed by Justin are good to have -- please discuss the defs he
proposed -- only "normalized" I'd rather stay away from.
Thanks,
--
Álvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Attachments:
[text/x-diff] 0001-glossary-v6.patch (53.3K, 2-0001-glossary-v6.patch)
download | inline diff:
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 1043d0f7ab..cf21ef857e 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -170,6 +170,7 @@
<!ENTITY limits SYSTEM "limits.sgml">
<!ENTITY acronyms SYSTEM "acronyms.sgml">
+<!ENTITY glossary SYSTEM "glossary.sgml">
<!ENTITY color SYSTEM "color.sgml">
<!ENTITY features-supported SYSTEM "features-supported.sgml">
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
new file mode 100644
index 0000000000..fb4934d322
--- /dev/null
+++ b/doc/src/sgml/glossary.sgml
@@ -0,0 +1,1580 @@
+<appendix id="glossary">
+ <title>Glossary</title>
+ <para>
+ This is a list of terms and their meaning in the context of
+ <productname>PostgreSQL</productname> and relational database
+ systems in general.
+ </para>
+
+ <glosslist>
+ <glossentry id="glossary-aggregate">
+ <glossterm>Aggregate Function</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm linkend="glossary-function">function</glossterm> that
+ combines (<firstterm>aggregates</firstterm>) multiple input values,
+ for example by counting, averaging or adding,
+ yielding a single output value.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="functions-aggregate"/>.
+ </para>
+ <glossseealso otherterm="glossary-window-function" />
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-analyze">
+ <glossterm>Analyze (operation)</glossterm>
+ <glossdef>
+ <para>
+ The process of collecting statistics from data in
+ <glossterm linkend="glossary-table">tables</glossterm>
+ and other <glossterm linkend="glossary-relation">relations</glossterm>
+ to help the <glossterm linkend="glossary-planner">query planner</glossterm>
+ to make decisions about how to execute
+ <glossterm linkend="glossary-query">queries</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Analytic Function</glossterm>
+ <glosssee otherterm="glossary-window-function" />
+ </glossentry>
+
+ <glossentry id="glossary-atomic">
+ <glossterm>Atomic</glossterm>
+ <glossdef>
+ <para>
+ In reference to a <glossterm linkend="glossary-datum">datum</glossterm>:
+ the fact that its value that cannot be broken down into smaller
+ components.
+ </para>
+ </glossdef>
+ <glossdef>
+ <para>
+ In reference to a
+ <glossterm linkend="glossary-transaction">database transaction</glossterm>:
+ see <glossterm linkend="glossary-atomicity">atomicity</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-atomicity">
+ <glossterm>Atomicity</glossterm>
+ <glossdef>
+ <para>
+ The property of a <glossterm linkend="glossary-transaction">transaction</glossterm>
+ that either all its operations complete as a single unit or none do.
+ This is one of the <acronym>ACID</acronym> properties.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-attribute">
+ <glossterm>Attribute</glossterm>
+ <glossdef>
+ <para>
+ An element with a certain name and data type found within a
+ <glossterm linkend="glossary-tuple">tuple</glossterm> or
+ <glossterm linkend="glossary-table">table</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-autovacuum">
+ <glossterm>Autovacuum</glossterm>
+ <glossdef>
+ <para>
+ Background processes that routinely perform
+ <glossterm>Vacuum</glossterm> and <glossterm>Analyze</glossterm>
+ operations.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="routine-vacuuming"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-backend">
+ <glossterm>Backend (process)</glossterm>
+ <glossdef>
+ <para>
+ Processes of an <glossterm>Instance</glossterm> which act on behalf of
+ client <glossterm>Connection</glossterm>s and handle their requests.
+ </para>
+ <para>
+ (Don't confuse this term with the similar terms
+ <glossterm>Background Worker</glossterm> or
+ <glossterm>Background Writer</glossterm>).
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-background-worker">
+ <glossterm>Background Worker (process)</glossterm>
+ <glossdef>
+ <para>
+ Individual processes within an <glossterm>Instance</glossterm>, which
+ run system- or user-supplied code. A typical use case is a process
+ which handles parts of an <acronym>SQL</acronym> query to take
+ advantage of parallel execution on servers with multiple
+ <acronym>CPU</acronym>s.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="bgworker"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-background-writer">
+ <glossterm>Background Writer (process)</glossterm>
+ <glossdef>
+ <para>
+ A process that continuously writes dirty pages from
+ <glossterm>Shared Memory</glossterm> to the file system.
+ It wakes up periodically, but
+ works only for a short period in order to distribute its expensive
+ <acronym>I/O</acronym> activity over time, instead of generating fewer
+ larger <acronym>I/O</acronym> peaks which could block other processes.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="runtime-config-resource"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-cast">
+ <glossterm>Cast</glossterm>
+ <glossdef>
+ <para>
+ A conversion of a <glossterm>Datum</glossterm> from its current data
+ type to another data type.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-catalog">
+ <glossterm>Catalog</glossterm>
+ <glossdef>
+ <para>
+ The <acronym>SQL</acronym> standard uses this term to
+ indicate what is called a <glossterm>Database</glossterm> in
+ <productname>PostgreSQL</productname>'s terminology.
+ </para>
+ <para>
+ This should not be confused with the
+ <glossterm>System Catalog</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="manage-ag-overview"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-check-constraint">
+ <glossterm>Check Constraint</glossterm>
+ <glossdef>
+ <para>
+ A type of <glossterm>Constraint</glossterm> defined on a
+ <glossterm>Relation</glossterm> which restricts the values allowed in
+ one or more <glossterm>Attribute</glossterm>s. The
+ <glossterm>Check Constraint</glossterm> can make reference to any
+ attribute in the <glossterm>Relation</glossterm>, but cannot reference
+ other <glossterm>Row</glossterm>s of the same
+ relation or other relations.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="ddl-constraints"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-checkpointer">
+ <glossterm>Checkpointer (process)</glossterm>
+ <glossdef>
+ <para>
+ A process that writes dirty pages to the file system and creates a special
+ checkpoint WAL 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 has been written.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-checkpoint">
+ <glossterm>Checkpoint</glossterm>
+ <glossdef>
+ <para>
+ A point in time when all older dirty pages of the
+ <glossterm>Shared Memory</glossterm>, all older <glossterm>WAL Record</glossterm>s,
+ and a special <firstterm>Checkpoint record</firstterm>
+ have been written and flushed to disk.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-checkpoint"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Class</glossterm>
+ <glosssee otherterm="glossary-relation" />
+ </glossentry>
+
+ <glossentry id="glossary-cluster">
+ <glossterm>Cluster</glossterm>
+ <glossdef>
+ <para>
+ A group of <glossterm>Database</glossterm>s plus their
+ <glossterm>Global SQL Object</glossterm>s. The
+ <glossterm>Cluster</glossterm> is managed by exactly one
+ <glossterm>Instance</glossterm>. A newly created
+ <glossterm>Cluster</glossterm> will have three
+ <glossterm>Database</glossterm>s created automatically. They are
+ <literal>template0</literal>, <literal>template1</literal>, and
+ <literal>postgres</literal>. It is expected that an application will
+ create one or more additional <glossterm>Database</glossterm>s aside
+ from these three.
+ </para>
+ <para>
+ Don't confuse the <productname>PostgreSQL</productname>-specific term
+ <glossterm>Cluster</glossterm> with the SQL command
+ <literal>CLUSTER</literal>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-column">
+ <glossterm>Column</glossterm>
+ <glossdef>
+ <para>
+ An <glossterm>Attribute</glossterm> found in a
+ <glossterm>Table</glossterm> or <glossterm>View</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-commit">
+ <glossterm>Commit</glossterm>
+ <glossdef>
+ <para>
+ The act of finalizing a <glossterm linkend="glossary-transaction">transaction</glossterm>
+ within the <glossterm>Database</glossterm>, which makes it visible to other
+ transactions and assures its
+ <glossterm linkend="glossary-durability">durability</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-commit"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-concurrency">
+ <glossterm>Concurrency</glossterm>
+ <glossdef>
+ <para>
+ The concept that multiple independent operations happen within the
+ <glossterm>Database</glossterm> at the same time.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-connection">
+ <glossterm>Connection</glossterm>
+ <glossdef>
+ <para>
+ An established line of communication between a client process
+ and a <glossterm linkend="glossary-backend">backend</glossterm>,
+ usually over a network.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="runtime-config-connection"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-consistency">
+ <glossterm>Consistency</glossterm>
+ <glossdef>
+ <para>
+ The property that the data in the <glossterm linkend="glossary-database">database</glossterm>
+ is always in compliance with its own rules such as <glossterm>Table</glossterm>
+ structure, <glossterm>Constraint</glossterm>s,
+ <glossterm linkend="glossary-unique">uniqueness</glossterm>, etc.
+ This is one of the <acronym>ACID</acronym> properties.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-constraint">
+ <glossterm>Constraint</glossterm>
+ <glossdef>
+ <para>
+ A restriction on the values of data allowed within a
+ <glossterm>Table</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="ddl-constraints"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Data Area</glossterm>
+ <glosssee otherterm="glossary-data-directory" />
+ </glossentry>
+
+ <glossentry id="glossary-data-directory">
+ <glossterm>Data Directory</glossterm>
+ <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 <glossterm>Tablespace</glossterm>s. The environment
+ variable <literal>PGDATA</literal> often — but not always —
+ refers to the <glossterm>Data Directory</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="storage-file-layout"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-database">
+ <glossterm>Database</glossterm>
+ <glossdef>
+ <para>
+ A named collection of <glossterm>SQL Object</glossterm>s.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="manage-ag-overview"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Database Server</glossterm>
+ <glosssee otherterm="glossary-instance" />
+ </glossentry>
+
+ <glossentry id="glossary-datum">
+ <glossterm>Datum</glossterm>
+ <glossdef>
+ <para>
+ The internal representation of one value of a <acronym>SQL</acronym>
+ data type.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-delete">
+ <glossterm>Delete</glossterm>
+ <glossdef>
+ <para>
+ A <acronym>SQL</acronym> command which removes
+ <glossterm>Row</glossterm>s from a given <glossterm>Table</glossterm>
+ or <glossterm>Relation</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-delete"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-durability">
+ <glossterm>Durability</glossterm>
+ <glossdef>
+ <para>
+ The assurance that once a <glossterm linkend="glossary-transaction">transaction</glossterm>
+ has been <glossterm>Committed</glossterm>, the changes remain even after
+ a system failure or crash.
+ This is one of the <acronym>ACID</acronym> properties.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-file-segment">
+ <glossterm>File Segment</glossterm>
+ <glossdef>
+ <para>
+ A physical file which stores data for a given
+ <glossterm>Heap</glossterm> or <glossterm>Index</glossterm> object.
+ <glossterm>File Segment</glossterm>s are limited in size by a
+ configuration value and if that size is exceeded, it will be split
+ into multiple physical files.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="storage-file-layout"/>.
+ </para>
+ <para>
+ (Don't confuse this term with the similar term
+ <glossterm>WAL Segment</glossterm>).
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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> so that it appears as if were in local
+ <glossterm>Table</glossterm>(s). With a Foreign Data Wrapper it is
+ possible to define a <glossterm>Foreign Server</glossterm> and
+ <glossterm>Foreign Table</glossterm>s.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createforeigndatawrapper"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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(s) in those <glossterm>Column</glossterm>s to
+ identify exactly one <glossterm>Row</glossterm> in another (or the same)
+ <glossterm>Table</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-foreign-server">
+ <glossterm>Foreign Server</glossterm>
+ <glossdef>
+ <para>
+ A named collection of <glossterm>Foreign Table</glossterm>s which all
+ use the same <glossterm>Foreign Data Wrapper</glossterm> and have
+ other configuration values in common.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createserver"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-foreign-table">
+ <glossterm>Foreign Table</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Relation</glossterm> which appears to have
+ <glossterm>Row</glossterm>s and <glossterm>Column</glossterm>s similar
+ to a regular <glossterm>Table</glossterm>, but will forward requests
+ for data through its <glossterm>Foreign Data Wrapper</glossterm>,
+ which will return <glossterm>Result Set</glossterm>s structured
+ according to the definition of the <glossterm>Foreign Table</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createforeigntable"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-function">
+ <glossterm>Function</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.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createfunction"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-global-sql-object">
+ <glossterm>Global SQL Object</glossterm>
+ <glossdef>
+ <para>
+ <glossterm>SQL Object</glossterm>s which do not belong to a specific
+ <glossterm>Schema</glossterm>.
+ </para>
+ <para>
+ Objects that exist at the <glossterm>Database</glossterm> level
+ include Extensions such as
+ <glossterm>Foreign Data Wrapper</glossterm>s.
+ </para>
+ <para>
+ Objects that exist at the <glossterm>Cluster</glossterm> level
+ include <glossterm>Role</glossterm>s,
+ <glossterm>Tablespace</glossterm>s,
+ <glossterm>Replication</glossterm> origins, and subscriptions
+ for logical replication.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-grant">
+ <glossterm>Grant</glossterm>
+ <glossdef>
+ <para>
+ A <acronym>SQL</acronym> command that is used to allow
+ <glossterm>User</glossterm>s or <glossterm>Role</glossterm>s to access
+ specific objects within the <glossterm>Database</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-grant"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-heap">
+ <glossterm>Heap</glossterm>
+ <glossdef>
+ <para>
+ Contains the values of <glossterm>Row</glossterm> attributes
+ (i.e. the data). The <glossterm>Heap</glossterm> is realized within
+ <glossterm>Database</glossterm> files.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Host</glossterm>
+ <glosssee otherterm="glossary-server" />
+ </glossentry>
+
+ <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> types
+ such as a <glossterm>Materialized View</glossterm>). Its internal
+ structure supports fast retrieval of and access to the original
+ data.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createindex"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-insert">
+ <glossterm>Insert</glossterm>
+ <glossdef>
+ <para>
+ A <acronym>SQL</acronym> command used to add new data into a
+ <glossterm>Table</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-insert"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-instance">
+ <glossterm>Instance</glossterm>
+ <glossdef>
+ <para>
+ An <glossterm>Instance</glossterm> is a group of processes plus their
+ common <glossterm>Shared Memory</glossterm> running on a single
+ <glossterm>Server</glossterm>. The <glossterm>Instance</glossterm>
+ handles all key features of a <acronym>DBMS</acronym>: read and write
+ access to files and shared memory, assurance of
+ the <acronym>ACID</acronym> paradigm, <acronym>MVCC</acronym>,
+ <glossterm>Connection</glossterm>s to client programs, backup,
+ recovery, replication, privileges, etc.
+ </para>
+ <para>
+ An <glossterm>Instance</glossterm> manages exactly one
+ <glossterm>Cluster</glossterm>.
+ </para>
+ <para>
+ Many <glossterm>Instance</glossterm>s can run on the same server as
+ long as their <acronym>TCP/IP</acronym> ports do not conflict.
+ Different instances on a server may use the
+ same or different versions of <productname>PostgreSQL</productname>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-isolation">
+ <glossterm>Isolation</glossterm>
+ <glossdef>
+ <para>
+ The property that the effects of a transaction are not visible to
+ <glossterm linkend="glossary-concurrency">concurrent transactions</glossterm>
+ before it commits.
+ This is one of the <acronym>ACID</acronym> properties.
+ </para>
+ <para>
+ For more information, see <xref linkend="transaction-iso" />.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-join">
+ <glossterm>Join</glossterm>
+ <glossdef>
+ <para>
+ A <acronym>SQL</acronym> keyword used in <command>SELECT</command> statements for
+ combining data from multiple <glossterm>Relation</glossterm>s.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-key">
+ <glossterm>Key</glossterm>
+ <glossdef>
+ <para>
+ A means of identifying a <glossterm>Row</glossterm> within a
+ <glossterm>Table</glossterm> or <glossterm>Relation</glossterm> by
+ values contained within one or more <glossterm>Attribute</glossterm>s
+ in that <glossterm>Table</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-lock">
+ <glossterm>Lock</glossterm>
+ <glossdef>
+ <para>
+ A mechanism that allows a process to limit or prevent simultaneous
+ access to a resource.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-log-file">
+ <glossterm>Log File</glossterm>
+ <glossdef>
+ <para>
+ <glossterm>Log File</glossterm>s contain human-readable text lines about
+ events. Examples include login failures, long-running queries, etc.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="logfile-maintenance"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-logger">
+ <glossterm>Logger (process)</glossterm>
+ <glossdef>
+ <para>
+ If activated, the
+ <glossterm>Logger</glossterm> process
+ writes information about database events into the current
+ <glossterm>Log File</glossterm>. When reaching certain time- or
+ volume-dependent criteria, a new log file is created.
+ Also called <firstterm>syslogger</firstterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="runtime-config-logging"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-log-record">
+ <glossterm>Log Record</glossterm>
+ <glossdef>
+ <para>
+ Archaic term for a <glossterm>WAL Record</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-logged">
+ <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>Table</glossterm>s are <glossterm>Logged</glossterm>. A
+ table can be specified as <glossterm>Unlogged</glossterm> either at
+ creation time or via the <command>ALTER TABLE</command> command.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Master (server)</glossterm>
+ <glosssee otherterm="glossary-primary-server" />
+ </glossentry>
+
+ <glossentry id="glossary-materialized">
+ <glossterm>Materialized</glossterm>
+ <glossdef>
+ <para>
+ The act of storing information rather than just the method of accessing
+ the information. This term is used in <glossterm>Materialized
+ View</glossterm>s, meaning that the data derived from the
+ <glossterm>View</glossterm> is actually stored on disk separately from
+ the sources of that data. When using the term
+ <glossterm>Materialized</glossterm> to refer to
+ multi-step queries, it means that the data of a given step is stored
+ 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 stores data in the same way
+ that a <glossterm>Table</glossterm> does. It cannot be modified via
+ <command>INSERT</command>, <command>UPDATE</command>, or
+ <command>DELETE</command> operations.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-creatematerializedview"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-null">
+ <glossterm>Null</glossterm>
+ <glossdef>
+ <para>
+ A concept of non-existence that is a central tenet of Relational
+ Database Theory. It represents the absence of value.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Optimizer</glossterm>
+ <glosssee otherterm="glossary-planner" />
+ </glossentry>
+
+ <glossentry id="glossary-partition">
+ <glossterm>Partition</glossterm>
+ <glossdef>
+ <para>
+ In reference to a <glossterm>Table</glossterm>:
+ A <glossterm>Table</glossterm> that can be queried directly,
+ or via a partitioned table, which is a collection of
+ sub-tables, each capable of holding one defined
+ subset of information that does not overlap with any other
+ table in the collection.
+ </para>
+ <para>
+ In reference to a <glossterm>Analytic Function</glossterm>:
+ a partition is a definition that identifies which neighboring
+ <glossterm>Row</glossterm>s can be considered by the
+ function.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-postmaster">
+ <glossterm>Postmaster (process)</glossterm>
+ <glossdef>
+ <para>
+ The very first process of an <glossterm>Instance</glossterm>. It
+ starts and manages the other auxiliary processes and creates
+ <glossterm linkend="glossary-backend">backend processes</glossterm>
+ on demand.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="server-start"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-primary-server">
+ <glossterm>Primary (server)</glossterm>
+ <glossdef>
+ <para>
+ When two or more <glossterm>Database</glossterm>s are linked via
+ <glossterm>Replication</glossterm>, the <glossterm>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>
+ <para>
+ A special case of a <glossterm>Unique Index</glossterm> defined on a
+ <glossterm>Table</glossterm> or other <glossterm>Relation</glossterm>
+ that also guarantees that all of the <glossterm>Attribute</glossterm>s
+ 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
+ table, though it is possible to have multiple
+ unique indexes that also have no null-capable attributes.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-procedure">
+ <glossterm>Procedure</glossterm>
+ <glossdef>
+ <para>
+ A defined set of instructions for manipulating data within a
+ <glossterm>Database</glossterm>. A <glossterm>Procedure</glossterm> can
+ be written in a variety of programming languages. They may seem
+ similar to <glossterm>Function</glossterm>s, 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
+ as <command>COMMIT</command> and <command>ROLLBACK</command>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createprocedure"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-query">
+ <glossterm>Query</glossterm>
+ <glossdef>
+ <para>
+ A request sent by a client to a <glossterm linkend="glossary-backend">backend</glossterm>,
+ usually to return results or to modify data on the database.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-planner">
+ <glossterm>Query Planner</glossterm>
+ <glossdef>
+ <para>
+ The part of <productname>PostgreSQL</productname> that is devoted to
+ determining (<firstterm>planning</firstterm>) the most efficient way to
+ execute <glossterm linkend="glossary-query">queries</glossterm>.
+ Also known as <firstterm>query optimizer</firstterm>,
+ <firstterm>optimizer</firstterm>, or simply <firstterm>planner</firstterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Record</glossterm>
+ <glosssee otherterm="glossary-tuple" />
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Recycling</glossterm>
+ <glosssee otherterm="glossary-wal-file" />
+ </glossentry>
+
+ <glossentry id="glossary-referential-integrity">
+ <glossterm>Referential Integrity</glossterm>
+ <glossdef>
+ <para>
+ A means of restricting data in one <glossterm>Relation</glossterm>
+ by a <glossterm>Foreign Key</glossterm>
+ so that it must have matching data in another
+ <glossterm>Relation</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-relation">
+ <glossterm>Relation</glossterm>
+ <glossdef>
+ <para>
+ The generic term for all objects in a <glossterm>Database</glossterm>
+ that have a name and a list of <glossterm>Attribute</glossterm>s
+ defined in a specific order. <glossterm>Table</glossterm>s,
+ <glossterm>View</glossterm>s, <glossterm>Foreign Table</glossterm>s,
+ <glossterm>Materialized View</glossterm>s, and
+ <glossterm>Index</glossterm>es are all relations.
+ </para>
+ <para>
+ <firstterm>Class</firstterm> is an archaic synonym for
+ <firstterm>relation</firstterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-replica">
+ <glossterm>Replica</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Database</glossterm> that is paired with a
+ <glossterm linkend="glossary-primary-server">primary</glossterm>
+ database and is maintaining a copy of some or
+ all of the primary <glossterm>Database</glossterm>'s data. The foremost
+ reasons for doing this are to allow for greater access to that data,
+ and to maintain availability of the data in the event that the
+ <glossterm>primary</glossterm> becomes unavailable.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-replication">
+ <glossterm>Replication</glossterm>
+ <glossdef>
+ <para>
+ The act of reproducing data on one <glossterm>Server</glossterm> onto
+ another server called a <glossterm>Replica</glossterm>. This can take the
+ form of <firstterm>physical replication</firstterm>, where all file
+ changes from one server are copied verbatim,
+ or <firstterm>logical replication</firstterm> where a defined subset
+ of data changes are conveyed using a higher-level representation.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-result-set">
+ <glossterm>Result Set</glossterm>
+ <glossdef>
+ <para>
+ A data structure transmitted from a <glossterm>Backend Process</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. The data structure consists of zero or more
+ <glossterm>Row</glossterm>s with the same ordered set of
+ <glossterm>Attribute</glossterm>s.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-revoke">
+ <glossterm>Revoke</glossterm>
+ <glossdef>
+ <para>
+ A command to prevent access to a named set of
+ <glossterm>Database</glossterm> objects for a named list of
+ <glossterm>User</glossterm>s and <glossterm>Role</glossterm>s.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-revoke"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-role">
+ <glossterm>Role</glossterm>
+ <glossdef>
+ <para>
+ A collection of access privileges to the
+ <glossterm>Database</glossterm>. <glossterm>Role</glossterm>s are
+ themselves a privilege that can be granted to other roles. This is
+ often done for convenience or to ensure completeness when multiple
+ <glossterm>User</glossterm>s need the same privileges.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createrole"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-rollback">
+ <glossterm>Rollback</glossterm>
+ <glossdef>
+ <para>
+ A command to undo all of the operations performed since the beginning
+ of a <glossterm>Transaction</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-rollback"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Row</glossterm>
+ <glosssee otherterm="glossary-tuple" />
+ </glossentry>
+
+ <glossentry id="glossary-savepoint">
+ <glossterm>Savepoint</glossterm>
+ <glossdef>
+ <para>
+ A special mark inside the sequence of steps in a
+ <glossterm>Transaction</glossterm>. Data modifications after this
+ point in time may be reverted to the time of the savepoint.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-savepoint"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-schema">
+ <glossterm>Schema</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Schema</glossterm> is a namespace for
+ <glossterm>SQL object</glossterm>s, 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 Object</glossterm>s 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 reusing
+ a name in multiple <glossterm>Schema</glossterm>s.
+ </para>
+ <para>
+ Many <glossterm>SQL Object</glossterm>s reside in the default
+ <glossterm>Schema</glossterm> <literal>public</literal>, but it is
+ expected that more schemas are created to hold application-specific
+ <glossterm>SQL Object</glossterm>s.
+ </para>
+ <para>
+ More generically, the term <glossterm>Schema</glossterm> is used to
+ mean all data descriptions (<glossterm>Table</glossterm> definitions,
+ <glossterm>Constraint</glossterm>s, comments) for a given
+ <glossterm>Database</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="ddl-schemas"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Segment</glossterm>
+ <glosssee otherterm="glossary-file-segment" />
+ </glossentry>
+
+ <glossentry id="glossary-select">
+ <glossterm>Select</glossterm>
+ <glossdef>
+ <para>
+ The <acronym>SQL</acronym> 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>Function</glossterm>s invoked within the query could have
+ side effects that do modify data.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-select"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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 for the duration of the
+ <glossterm>Transaction</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-server">
+ <glossterm>Server</glossterm>
+ <glossdef>
+ <para>
+ A computer on which <productname>PostgreSQL</productname>
+ <glossterm linkend="glossary-instance">instances</glossterm> run.
+ The term <firstterm>server</firstterm> denotes real hardware, a
+ container, or a Virtual Machine.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-session">
+ <glossterm>Session</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Connection</glossterm> to the <glossterm>Database</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-sequence">
+ <glossterm>Sequence</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Database</glossterm> object which represents the
+ 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 (usually
+ 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, that value
+ is returned to the invoking query, and the current value of the
+ sequence is updated to reflect the new value. The value can be updated
+ multiple times in a single query, the net effect being that each row
+ selected will have a different value. Values taken from a
+ <glossterm>Sequence</glossterm> are never reverted, even in the case of
+ a <glossterm>Rollback</glossterm>, which means that the
+ <glossterm>Sequence</glossterm> will never generate the same number twice,
+ which makes it useful for generating
+ <glossterm>Primary Key</glossterm> values.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createsequence"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-shared-memory">
+ <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 Record</glossterm>s, and stores additional common
+ information. Note that <glossterm>Shared Memory</glossterm> belongs to
+ the complete <glossterm>Instance</glossterm>, not to a single
+ <glossterm>Database</glossterm>.
+ </para>
+ <para>
+ <glossterm>Shared Memory</glossterm> is organized into pages. If a
+ page is modified, it is called a dirty page until it is written back
+ to the file system.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="runtime-config-resource-memory"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-sql-object">
+ <glossterm>SQL Object</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Table</glossterm>, <glossterm>View</glossterm>,
+ <glossterm>Materialized View</glossterm>,
+ <glossterm>Index</glossterm>, <glossterm>Constraint</glossterm>,
+ <glossterm>Sequence</glossterm>, <glossterm>Function</glossterm>,
+ <glossterm>Procedure</glossterm>, <glossterm>Trigger</glossterm>,
+ data type, or operator. Every <glossterm>SQL Object</glossterm>
+ belongs to exactly one <glossterm>Schema</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="manage-ag-overview"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-stats-collector">
+ <glossterm>Stats Collector</glossterm>
+ <glossdef>
+ <para>
+ This process collects statistical information about the
+ <glossterm>Cluster</glossterm>'s activities.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="monitoring-stats"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-system-catalog">
+ <glossterm>System Catalog</glossterm>
+ <glossdef>
+ <para>
+ A collection of <glossterm>Table</glossterm>s and
+ <glossterm>View</glossterm>s which describe the structure of all
+ <acronym>SQL</acronym> objects of the <glossterm>Database</glossterm>
+ and the <glossterm>Global SQL Object</glossterm>s of the
+ <glossterm>Cluster</glossterm>. The <glossterm>System
+ Catalog</glossterm> resides in the schema
+ <literal>pg_catalog</literal>. Main parts are mirrored as
+ <glossterm>View</glossterm>s in the <glossterm>Schema</glossterm>
+ <literal>information_schema</literal>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="ddl-schemas"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-table">
+ <glossterm>Table</glossterm>
+ <glossdef>
+ <para>
+ A collection of <glossterm>Tuple</glossterm>s (also known as
+ <glossterm>Row</glossterm>s or <glossterm>Record</glossterm>s) having
+ a common data structure (the same number of
+ <glossterm>Attribute</glossterm>s, in the same order, having the same
+ name and type per position). A <glossterm>Table</glossterm> is the
+ most common form of <glossterm>Relation</glossterm> in
+ <productname>PostgreSQL</productname>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createtable"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-tablespace">
+ <glossterm>Tablespace</glossterm>
+ <glossdef>
+ <para>
+ A named location on the server filesystem. All <glossterm>SQL Object</glossterm>s
+ which require storage beyond their definition in the
+ <glossterm>System Catalog</glossterm>
+ must belong to a single tablespace.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="manage-ag-tablespaces"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-temporary-tables">
+ <glossterm>Temporary Table</glossterm>
+ <glossdef>
+ <para>
+ <glossterm>Table</glossterm>s that exist either for the lifetime of a
+ <glossterm>Session</glossterm> or a
+ <glossterm>Transaction</glossterm>, as specified at the time of creation. The
+ data in them is not visible to other sessions,
+ and is not <glossterm>Logged</glossterm>.
+ <glossterm>Temporary Table</glossterm>s are often used to store
+ intermediate data for a multi-step operation.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createtable"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-transaction">
+ <glossterm>Transaction</glossterm>
+ <glossdef>
+ <para>
+ A combination of commands that must act as a single
+ <glossterm>Atomic</glossterm> command: they all succeed or all fail
+ as a single unit, and their effects are not visible to other
+ <glossterm>Session</glossterm>s until
+ the <glossterm>Transaction</glossterm> is complete.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="transaction-iso"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-trigger">
+ <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>, <command>DELETE</command>,
+ <command>TRUNCATE</command>) is applied to a <glossterm>Relation</glossterm>.
+ A <glossterm>Trigger</glossterm>
+ executes within the same <glossterm>Transaction</glossterm> as the
+ statement which invoked it, and if the <glossterm>Function</glossterm>
+ fails, then the invoking statement also fails.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createtrigger"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-tuple">
+ <glossterm>Tuple</glossterm>
+ <glossdef>
+ <para>
+ A collection of <glossterm>Attribute</glossterm>s in a fixed order.
+ That order may be defined by the <glossterm>Table</glossterm> where
+ the <glossterm>Tuple</glossterm> is found, in which case the
+ <glossterm>Tuple</glossterm> is often called a
+ <glossterm>Row</glossterm> or <glossterm>Record</glossterm>. It may
+ also be defined by the structure of a
+ <glossterm>Result Set</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-unique">
+ <glossterm>Unique</glossterm>
+ <glossdef>
+ <para>
+ The condition of having no duplicate values in the same
+ <glossterm>Column</glossterm> of a <glossterm>Relation</glossterm>.
+ Often used in the concept of
+ <glossterm>Unique Index</glossterm>es.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-unlogged">
+ <glossterm>Unlogged</glossterm>
+ <glossdef>
+ <para>
+ Changes to an unlogged <glossterm>Relation</glossterm> are not
+ reflected in the <glossterm>WAL Log</glossterm>. This disables
+ replication and crash recovery for these relations.
+ </para>
+ <para>
+ The primary use of unlogged tables is for storing
+ transient work data that must be shared across processes.
+ </para>
+ <para>
+ <glossterm>Temporary Table</glossterm>s are always unlogged.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-update">
+ <glossterm>Update</glossterm>
+ <glossdef>
+ <para>
+ A <acronym>SQL</acronym> command used to modify <glossterm>Row</glossterm>s
+ that may already exist in a specified <glossterm>Table</glossterm>.
+ It cannot create or remove rows.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-update"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-user">
+ <glossterm>User</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Role</glossterm> that has the <literal>LOGIN</literal>
+ privilege is said to be a <glossterm>User</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-user-mapping">
+ <glossterm>User Mapping</glossterm>
+ <glossdef>
+ <para>
+ The translation of login credentials in the local
+ <glossterm>Database</glossterm> to credentials in a remote data system
+ defined by a <glossterm>Foreign Data Wrapper</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createusermapping"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-vacuum">
+ <glossterm>Vacuum</glossterm>
+ <glossdef>
+ <para>
+ The process of removing outdated <acronym>MVCC</acronym>
+ <glossterm>Tuple</glossterm>s from a <glossterm>Heap</glossterm> or
+ <glossterm>Index</glossterm>. This can be initiated through the use of
+ the <command>VACUUM</command> command, but can also be handled automatically
+ via <glossterm>Autovacuum</glossterm> processes.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-vacuum"/> .
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-view">
+ <glossterm>View</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm>Relation</glossterm> that is defined by a
+ <command>SELECT</command> statement, but has no storage of its own.
+ Any time a query references a <glossterm>View</glossterm>, the
+ definition of the <glossterm>View</glossterm> is substituted into the
+ query as if the user had typed that subquery instead of the name of
+ the <glossterm>View</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createview"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-wal-archiver">
+ <glossterm>WAL Archiver (process)</glossterm>
+ <glossdef>
+ <para>
+ A process that saves copies of <glossterm>WAL File</glossterm>s
+ for the purposes of creating backups or keeping
+ <glossterm>Replica</glossterm>s current.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="continuous-archiving"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-wal-file">
+ <glossterm>WAL File</glossterm>
+ <glossdef>
+ <para>
+ Each of the numerically-numbered files that provide storage space for
+ <glossterm linkend="glossary-wal">WAL</glossterm>.
+ The files are all of the same predefined size
+ and are written in sequential order, interspersing changes
+ as they occur in multiple simultaneous sessions.
+ If the system crashes, the files are read in order, and each of the
+ changes are replayed to restore the system to the state as it was
+ before the crash.
+ </para>
+ <para>
+ Each WAL file can be released after a
+ <glossterm linkend="glossary-checkpoint">checkpoint</glossterm>
+ writes all the changes in it to the corresponding data files.
+ Releasing the file can be done either by deleting it, or by changing its
+ name so that it will be used in the future, which is called
+ <firstterm>recycling</firstterm>.
+ </para>
+
+ <para>
+ For more information, see
+ <xref linkend="wal-internals"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>WAL</glossterm>
+ <glosssee otherterm="glossary-wal" />
+ </glossentry>
+
+ <glossentry id="glossary-wal-record">
+ <glossterm>WAL Record</glossterm>
+ <glossdef>
+ <para>
+ A low-level description of an individual data change.
+ It contains sufficient information for the data change to be
+ re-executed (<firstterm>replayed</firstterm>) in case a system failure
+ causes the change to be lost.
+ WAL records use a non-printable binary format.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="wal-internals"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>WAL Segment</glossterm>
+ <glosssee otherterm="glossary-wal-file" />
+ </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 id="linkend-shared-memory">shared memory</glossterm> to
+ <glossterm id="linkend-wal-file">WAL files</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="runtime-config-wal"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-window-frame">
+ <glossterm>Window frame</glossterm>
+ <glossdef>
+ <para>
+ In a result set, a subset of neighboring rows that match some user
+ specified criteria form a window frame.
+ For example, in a query that returns employees across several departments,
+ the employees from each specific department can form one window frame.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-window-function">
+ <glossterm>Window Function</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-window-frame">window frame</glossterm>.
+ 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 window frame.
+ Also known as <firstterm>analytic functions</firstterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="tutorial-window"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-wal">
+ <glossterm>Write-Ahead Log</glossterm>
+ <glossdef>
+ <para>
+ The journal that keeps track of the changes in the
+ <glossterm>Instance</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>.
+ </para>
+ </glossdef>
+ </glossentry>
+ </glosslist>
+</appendix>
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index 1f7bd32878..ba3d626102 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -278,6 +278,7 @@
&docguide;
&limits;
&acronyms;
+ &glossary;
&color;
</part>
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-04-02 12:44 Jürgen Purtz <[email protected]>
parent: Alvaro Herrera <[email protected]>
1 sibling, 1 reply; 97+ messages in thread
From: Jürgen Purtz @ 2020-04-02 12:44 UTC (permalink / raw)
To: Alvaro Herrera <[email protected]>; +Cc: Corey Huinker <[email protected]>; Justin Pryzby <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
+1 and many thanks to Alvaros edits.
Kind regards
Jürgen Purtz
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-04-02 19:40 Corey Huinker <[email protected]>
parent: Jürgen Purtz <[email protected]>
0 siblings, 1 reply; 97+ messages in thread
From: Corey Huinker @ 2020-04-02 19:40 UTC (permalink / raw)
To: Jürgen Purtz <[email protected]>; +Cc: Alvaro Herrera <[email protected]>; Justin Pryzby <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
On Thu, Apr 2, 2020 at 8:44 AM Jürgen Purtz <[email protected]> wrote:
> +1 and many thanks to Alvaros edits.
>
>
I did some of the grunt work Alvaro alluded to in v6, and the results are
attached and they build, which means there are no invalid links.
Notes:
* no definition wordings were changed
* added a linkend to all remaining glossterms that do not immediately
follow a glossentry
* renamed id glossary-temporary-tables to glossary-temporary-table
* temporarily re-added an id for glossary-row as we have many references to
that. unsure if we should use the term Tuple in all those places or say Row
while linking to glossary-tuple, or something else
* temporarily re-added an id for glossary-segment, glossary-wal-segment,
glossary-analytic-function, as those were also referenced and will need
similar decisions made
* added a stub entry for glossary-unique-index, unsure if it should have a
definition on it's own, or we split it into unique and index.
* I noticed several cases where a glossterm is used twice in a definition,
but didn't de-term them
* I'm curious about how we should tag a term when using it in its own
definition. same as anywhere else?
Attachments:
[text/x-patch] 0001-glossary-v7.patch (61.7K, 3-0001-glossary-v7.patch)
download | inline diff:
From 4603ce04306e77f5508bb207b42e5dec1425e7c5 Mon Sep 17 00:00:00 2001
From: coreyhuinker <[email protected]>
Date: Thu, 2 Apr 2020 15:32:43 -0400
Subject: [PATCH] glossary v7
---
doc/src/sgml/filelist.sgml | 1 +
doc/src/sgml/glossary.sgml | 1589 ++++++++++++++++++++++++++++++++++++
doc/src/sgml/postgres.sgml | 1 +
3 files changed, 1591 insertions(+)
create mode 100644 doc/src/sgml/glossary.sgml
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 1043d0f7ab..cf21ef857e 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -170,6 +170,7 @@
<!ENTITY limits SYSTEM "limits.sgml">
<!ENTITY acronyms SYSTEM "acronyms.sgml">
+<!ENTITY glossary SYSTEM "glossary.sgml">
<!ENTITY color SYSTEM "color.sgml">
<!ENTITY features-supported SYSTEM "features-supported.sgml">
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
new file mode 100644
index 0000000000..edfcf9d725
--- /dev/null
+++ b/doc/src/sgml/glossary.sgml
@@ -0,0 +1,1589 @@
+<appendix id="glossary">
+ <title>Glossary</title>
+ <para>
+ This is a list of terms and their meaning in the context of
+ <productname>PostgreSQL</productname> and relational database
+ systems in general.
+ </para>
+
+ <glosslist>
+ <glossentry id="glossary-aggregate">
+ <glossterm>Aggregate Function</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm linkend="glossary-function">function</glossterm> that
+ combines (<firstterm>aggregates</firstterm>) multiple input values,
+ for example by counting, averaging or adding,
+ yielding a single output value.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="functions-aggregate"/>.
+ </para>
+ <glossseealso otherterm="glossary-window-function" />
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-analyze">
+ <glossterm>Analyze (operation)</glossterm>
+ <glossdef>
+ <para>
+ The process of collecting statistics from data in
+ <glossterm linkend="glossary-table">tables</glossterm>
+ and other <glossterm linkend="glossary-relation">relations</glossterm>
+ to help the <glossterm linkend="glossary-planner">query planner</glossterm>
+ to make decisions about how to execute
+ <glossterm linkend="glossary-query">queries</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-analytic-function">
+ <glossterm>Analytic Function</glossterm>
+ <glosssee otherterm="glossary-window-function" />
+ </glossentry>
+
+ <glossentry id="glossary-atomic">
+ <glossterm>Atomic</glossterm>
+ <glossdef>
+ <para>
+ In reference to a <glossterm linkend="glossary-datum">datum</glossterm>:
+ the fact that its value that cannot be broken down into smaller
+ components.
+ </para>
+ </glossdef>
+ <glossdef>
+ <para>
+ In reference to a
+ <glossterm linkend="glossary-transaction">database transaction</glossterm>:
+ see <glossterm linkend="glossary-atomicity">atomicity</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-atomicity">
+ <glossterm>Atomicity</glossterm>
+ <glossdef>
+ <para>
+ The property of a <glossterm linkend="glossary-transaction">transaction</glossterm>
+ that either all its operations complete as a single unit or none do.
+ This is one of the <acronym>ACID</acronym> properties.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-attribute">
+ <glossterm>Attribute</glossterm>
+ <glossdef>
+ <para>
+ An element with a certain name and data type found within a
+ <glossterm linkend="glossary-tuple">tuple</glossterm> or
+ <glossterm linkend="glossary-table">table</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-autovacuum">
+ <glossterm>Autovacuum</glossterm>
+ <glossdef>
+ <para>
+ Background processes that routinely perform
+ <glossterm linkend="glossary-vacuum">Vacuum</glossterm> and <glossterm linkend="glossary-analyze">Analyze</glossterm>
+ operations.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="routine-vacuuming"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-backend">
+ <glossterm>Backend (process)</glossterm>
+ <glossdef>
+ <para>
+ Processes of an <glossterm linkend="glossary-instance">Instance</glossterm> which act on behalf of
+ client <glossterm linkend="glossary-connection">Connection</glossterm>s and handle their requests.
+ </para>
+ <para>
+ (Don't confuse this term with the similar terms
+ <glossterm linkend="glossary-background-worker">Background Worker</glossterm> or
+ <glossterm linkend="glossary-background-writer">Background Writer</glossterm>).
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-background-worker">
+ <glossterm>Background Worker (process)</glossterm>
+ <glossdef>
+ <para>
+ Individual processes within an <glossterm linkend="glossary-instance">Instance</glossterm>, which
+ run system- or user-supplied code. A typical use case is a process
+ which handles parts of an <acronym>SQL</acronym> query to take
+ advantage of parallel execution on servers with multiple
+ <acronym>CPU</acronym>s.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="bgworker"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-background-writer">
+ <glossterm>Background Writer (process)</glossterm>
+ <glossdef>
+ <para>
+ A process that continuously writes dirty pages from
+ <glossterm linkend="glossary-shared-memory">Shared Memory</glossterm> to the file system.
+ It wakes up periodically, but
+ works only for a short period in order to distribute its expensive
+ <acronym>I/O</acronym> activity over time, instead of generating fewer
+ larger <acronym>I/O</acronym> peaks which could block other processes.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="runtime-config-resource"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-cast">
+ <glossterm>Cast</glossterm>
+ <glossdef>
+ <para>
+ A conversion of a <glossterm linkend="glossary-cast">Datum</glossterm> from its current data
+ type to another data type.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-catalog">
+ <glossterm>Catalog</glossterm>
+ <glossdef>
+ <para>
+ The <acronym>SQL</acronym> standard uses this term to
+ indicate what is called a <glossterm linkend="glossary-database">Database</glossterm> in
+ <productname>PostgreSQL</productname>'s terminology.
+ </para>
+ <para>
+ This should not be confused with the
+ <glossterm linkend="glossary-system-catalog">System Catalog</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="manage-ag-overview"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-check-constraint">
+ <glossterm>Check Constraint</glossterm>
+ <glossdef>
+ <para>
+ A type of <glossterm linkend="glossary-constraint">Constraint</glossterm> defined on a
+ <glossterm linkend="glossary-relation">Relation</glossterm> which restricts the values allowed in
+ one or more <glossterm linkend="glossary-attribute">Attribute</glossterm>s. The
+ <glossterm linkend="glossary-check-constraint">Check Constraint</glossterm> can make reference to any
+ attribute in the <glossterm linkend="glossary-relation">Relation</glossterm>, but cannot reference
+ other <glossterm linkend="glossary-row">Row</glossterm>s of the same
+ relation or other relations.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="ddl-constraints"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-checkpointer">
+ <glossterm>Checkpointer (process)</glossterm>
+ <glossdef>
+ <para>
+ A process that writes dirty pages to the file system and creates a special
+ checkpoint WAL 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 has been written.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-checkpoint">
+ <glossterm>Checkpoint</glossterm>
+ <glossdef>
+ <para>
+ A point in time when all older dirty pages of the
+ <glossterm linkend="glossary-shared-memory">Shared Memory</glossterm>, all older <glossterm linkend="glossary-wal-record">WAL Record</glossterm>s,
+ and a special <firstterm>Checkpoint record</firstterm>
+ have been written and flushed to disk.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-checkpoint"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Class</glossterm>
+ <glosssee otherterm="glossary-relation" />
+ </glossentry>
+
+ <glossentry id="glossary-cluster">
+ <glossterm>Cluster</glossterm>
+ <glossdef>
+ <para>
+ A group of <glossterm linkend="glossary-database">Database</glossterm>s plus their
+ <glossterm linkend="glossary-global-sql-object">Global SQL Object</glossterm>s. The
+ <glossterm linkend="glossary-cluster">Cluster</glossterm> is managed by exactly one
+ <glossterm linkend="glossary-instance">Instance</glossterm>. A newly created
+ <glossterm linkend="glossary-cluster">Cluster</glossterm> will have three
+ <glossterm linkend="glossary-database">Database</glossterm>s created automatically. They are
+ <literal>template0</literal>, <literal>template1</literal>, and
+ <literal>postgres</literal>. It is expected that an application will
+ create one or more additional <glossterm linkend="glossary-database">Database</glossterm>s aside
+ from these three.
+ </para>
+ <para>
+ Don't confuse the <productname>PostgreSQL</productname>-specific term
+ <glossterm linkend="glossary-cluster">Cluster</glossterm> with the SQL command
+ <literal>CLUSTER</literal>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-column">
+ <glossterm>Column</glossterm>
+ <glossdef>
+ <para>
+ An <glossterm linkend="glossary-attribute">Attribute</glossterm> found in a
+ <glossterm linkend="glossary-table">Table</glossterm> or <glossterm linkend="glossary-view">View</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-commit">
+ <glossterm>Commit</glossterm>
+ <glossdef>
+ <para>
+ The act of finalizing a <glossterm linkend="glossary-transaction">transaction</glossterm>
+ within the <glossterm linkend="glossary-database">Database</glossterm>, which makes it visible to other
+ transactions and assures its
+ <glossterm linkend="glossary-durability">durability</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-commit"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-concurrency">
+ <glossterm>Concurrency</glossterm>
+ <glossdef>
+ <para>
+ The concept that multiple independent operations happen within the
+ <glossterm linkend="glossary-database">Database</glossterm> at the same time.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-connection">
+ <glossterm>Connection</glossterm>
+ <glossdef>
+ <para>
+ An established line of communication between a client process
+ and a <glossterm linkend="glossary-backend">backend</glossterm>,
+ usually over a network.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="runtime-config-connection"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-consistency">
+ <glossterm>Consistency</glossterm>
+ <glossdef>
+ <para>
+ The property that the data in the <glossterm linkend="glossary-database">database</glossterm>
+ is always in compliance with its own rules such as <glossterm linkend="glossary-table">Table</glossterm>
+ structure, <glossterm linkend="glossary-constraint">Constraint</glossterm>s,
+ <glossterm linkend="glossary-unique">uniqueness</glossterm>, etc.
+ This is one of the <acronym>ACID</acronym> properties.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-constraint">
+ <glossterm>Constraint</glossterm>
+ <glossdef>
+ <para>
+ A restriction on the values of data allowed within a
+ <glossterm linkend="glossary-table">Table</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="ddl-constraints"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Data Area</glossterm>
+ <glosssee otherterm="glossary-data-directory" />
+ </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-cluster">Cluster</glossterm> with
+ the exception of <glossterm linkend="glossary-tablespace">Tablespace</glossterm>s. The environment
+ variable <literal>PGDATA</literal> often — but not always —
+ refers to the <glossterm linkend="glossary-data-directory">Data Directory</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="storage-file-layout"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-database">
+ <glossterm>Database</glossterm>
+ <glossdef>
+ <para>
+ A named collection of <glossterm linkend="glossary-sql-object">SQL Object</glossterm>s.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="manage-ag-overview"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Database Server</glossterm>
+ <glosssee otherterm="glossary-instance" />
+ </glossentry>
+
+ <glossentry id="glossary-datum">
+ <glossterm>Datum</glossterm>
+ <glossdef>
+ <para>
+ The internal representation of one value of a <acronym>SQL</acronym>
+ data type.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-delete">
+ <glossterm>Delete</glossterm>
+ <glossdef>
+ <para>
+ A <acronym>SQL</acronym> command which removes
+ <glossterm linkend="glossary-row">Row</glossterm>s from a given <glossterm linkend="glossary-table">Table</glossterm>
+ or <glossterm linkend="glossary-relation">Relation</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-delete"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-durability">
+ <glossterm>Durability</glossterm>
+ <glossdef>
+ <para>
+ The assurance that once a <glossterm linkend="glossary-transaction">transaction</glossterm>
+ has been <glossterm linkend="glossary-commit">Committed</glossterm>, the changes remain even after
+ a system failure or crash.
+ This is one of the <acronym>ACID</acronym> properties.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-file-segment">
+ <glossterm>File Segment</glossterm>
+ <glossdef>
+ <para>
+ A physical file which stores data for a given
+ <glossterm linkend="glossary-heap">Heap</glossterm> or <glossterm linkend="glossary-index">Index</glossterm> object.
+ <glossterm linkend="glossary-file-segment">File Segment</glossterm>s are limited in size by a
+ configuration value and if that size is exceeded, it will be split
+ into multiple physical files.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="storage-file-layout"/>.
+ </para>
+ <para>
+ (Don't confuse this term with the similar term
+ <glossterm linkend="glossary-wal-segment">WAL Segment</glossterm>).
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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 linkend="glossary-database">Database</glossterm> so that it appears as if were in local
+ <glossterm linkend="glossary-table">Table</glossterm>(s). With a Foreign Data Wrapper it is
+ possible to define a <glossterm linkend="glossary-foreign-server">Foreign Server</glossterm> and
+ <glossterm linkend="glossary-foreign-table">Foreign Table</glossterm>s.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createforeigndatawrapper"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-foreign-key">
+ <glossterm>Foreign Key</glossterm>
+ <glossdef>
+ <para>
+ A type of <glossterm linkend="glossary-constraint">Constraint</glossterm> defined on one or more
+ <glossterm linkend="glossary-column">Column</glossterm>s in a <glossterm linkend="glossary-table">Table</glossterm> which
+ requires the value(s) in those <glossterm linkend="glossary-column">Column</glossterm>s to
+ identify exactly one <glossterm linkend="glossary-row">Row</glossterm> in another (or the same)
+ <glossterm linkend="glossary-table">Table</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-foreign-server">
+ <glossterm>Foreign Server</glossterm>
+ <glossdef>
+ <para>
+ A named collection of <glossterm linkend="glossary-foreign-table">Foreign Table</glossterm>s which all
+ use the same <glossterm linkend="glossary-foreign-data-wrapper">Foreign Data Wrapper</glossterm> and have
+ other configuration values in common.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createserver"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-foreign-table">
+ <glossterm>Foreign Table</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm linkend="glossary-relation">Relation</glossterm> which appears to have
+ <glossterm linkend="glossary-row">Row</glossterm>s and <glossterm linkend="glossary-column">Column</glossterm>s similar
+ to a regular <glossterm linkend="glossary-table">Table</glossterm>, but will forward requests
+ for data through its <glossterm linkend="glossary-foreign-data-wrapper">Foreign Data Wrapper</glossterm>,
+ which will return <glossterm linkend="glossary-result-set">Result Set</glossterm>s structured
+ according to the definition of the <glossterm linkend="glossary-foreign-table">Foreign Table</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createforeigntable"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-function">
+ <glossterm>Function</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.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createfunction"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-global-sql-object">
+ <glossterm>Global SQL Object</glossterm>
+ <glossdef>
+ <para>
+ <glossterm linkend="glossary-sql-object">SQL Object</glossterm>s which do not belong to a specific
+ <glossterm linkend="glossary-schema">Schema</glossterm>.
+ </para>
+ <para>
+ Objects that exist at the <glossterm linkend="glossary-database">Database</glossterm> level
+ include Extensions such as
+ <glossterm linkend="glossary-foreign-data-wrapper">Foreign Data Wrapper</glossterm>s.
+ </para>
+ <para>
+ Objects that exist at the <glossterm linkend="glossary-cluster">Cluster</glossterm> level
+ include <glossterm linkend="glossary-role">Role</glossterm>s,
+ <glossterm linkend="glossary-tablespace">Tablespace</glossterm>s,
+ <glossterm linkend="glossary-replication">Replication</glossterm> origins, and subscriptions
+ for logical replication.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-grant">
+ <glossterm>Grant</glossterm>
+ <glossdef>
+ <para>
+ A <acronym>SQL</acronym> command that is used to allow
+ <glossterm linkend="glossary-user">User</glossterm>s or <glossterm linkend="glossary-role">Role</glossterm>s to access
+ specific objects within the <glossterm linkend="glossary-database">Database</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-grant"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-heap">
+ <glossterm>Heap</glossterm>
+ <glossdef>
+ <para>
+ Contains the values of <glossterm linkend="glossary-row">Row</glossterm> attributes
+ (i.e. the data). The <glossterm linkend="glossary-heap">Heap</glossterm> is realized within
+ <glossterm linkend="glossary-database">Database</glossterm> files.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Host</glossterm>
+ <glosssee otherterm="glossary-server" />
+ </glossentry>
+
+ <glossentry id="glossary-index">
+ <glossterm>Index</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>). Its internal
+ structure supports fast retrieval of and access to the original
+ data.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createindex"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-insert">
+ <glossterm>Insert</glossterm>
+ <glossdef>
+ <para>
+ A <acronym>SQL</acronym> command used to add new data into a
+ <glossterm linkend="glossary-table">Table</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-insert"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-instance">
+ <glossterm>Instance</glossterm>
+ <glossdef>
+ <para>
+ An <glossterm linkend="glossary-instance">Instance</glossterm> is a group of processes plus their
+ common <glossterm linkend="glossary-shared-memory">Shared Memory</glossterm> running on a single
+ <glossterm linkend="glossary-server">Server</glossterm>. The <glossterm linkend="glossary-instance">Instance</glossterm>
+ handles all key features of a <acronym>DBMS</acronym>: read and write
+ access to files and shared memory, assurance of
+ the <acronym>ACID</acronym> paradigm, <acronym>MVCC</acronym>,
+ <glossterm linkend="glossary-connection">Connection</glossterm>s to client programs, backup,
+ recovery, replication, privileges, etc.
+ </para>
+ <para>
+ An <glossterm linkend="glossary-instance">Instance</glossterm> manages exactly one
+ <glossterm linkend="glossary-cluster">Cluster</glossterm>.
+ </para>
+ <para>
+ Many <glossterm linkend="glossary-instance">Instance</glossterm>s can run on the same server as
+ long as their <acronym>TCP/IP</acronym> ports do not conflict.
+ Different instances on a server may use the
+ same or different versions of <productname>PostgreSQL</productname>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-isolation">
+ <glossterm>Isolation</glossterm>
+ <glossdef>
+ <para>
+ The property that the effects of a transaction are not visible to
+ <glossterm linkend="glossary-concurrency">concurrent transactions</glossterm>
+ before it commits.
+ This is one of the <acronym>ACID</acronym> properties.
+ </para>
+ <para>
+ For more information, see <xref linkend="transaction-iso" />.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-join">
+ <glossterm>Join</glossterm>
+ <glossdef>
+ <para>
+ A <acronym>SQL</acronym> keyword used in <command>SELECT</command> statements for
+ combining data from multiple <glossterm linkend="glossary-relation">Relation</glossterm>s.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-key">
+ <glossterm>Key</glossterm>
+ <glossdef>
+ <para>
+ A means of identifying a <glossterm linkend="glossary-row">Row</glossterm> within a
+ <glossterm linkend="glossary-table">Table</glossterm> or <glossterm linkend="glossary-relation">Relation</glossterm> by
+ values contained within one or more <glossterm linkend="glossary-attribute">Attribute</glossterm>s
+ in that <glossterm linkend="glossary-table">Table</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-lock">
+ <glossterm>Lock</glossterm>
+ <glossdef>
+ <para>
+ A mechanism that allows a process to limit or prevent simultaneous
+ access to a resource.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-log-file">
+ <glossterm>Log File</glossterm>
+ <glossdef>
+ <para>
+ <glossterm>Log File</glossterm>s contain human-readable text lines about
+ events. Examples include login failures, long-running queries, etc.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="logfile-maintenance"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-logger">
+ <glossterm>Logger (process)</glossterm>
+ <glossdef>
+ <para>
+ If activated, the
+ <glossterm linkend="glossary-logger">Logger</glossterm> process
+ writes information about database events into the current
+ <glossterm linkend="glossary-log-file">Log File</glossterm>. When reaching certain time- or
+ volume-dependent criteria, a new log file is created.
+ Also called <firstterm>syslogger</firstterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="runtime-config-logging"/>.
+ </para>
+ </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>
+ <para>
+ A <glossterm linkend="glossary-table">Table</glossterm> is considered
+ <glossterm linkend="glossary-logged">Logged</glossterm> if changes to it are sent to the
+ <glossterm linkend="glossary-wal">WAL Log</glossterm>. By default, all regular
+ <glossterm linkend="glossary-table">Table</glossterm>s are <glossterm linkend="glossary-logged">Logged</glossterm>. A
+ table can be specified as <glossterm linkend="glossary-unlogged">Unlogged</glossterm> either at
+ creation time or via the <command>ALTER TABLE</command> command.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Master (server)</glossterm>
+ <glosssee otherterm="glossary-primary-server" />
+ </glossentry>
+
+ <glossentry id="glossary-materialized">
+ <glossterm>Materialized</glossterm>
+ <glossdef>
+ <para>
+ The act of storing information rather than just the method of accessing
+ the information. This term is used in <glossterm linkend="glossary-materialized-view">Materialized
+ View</glossterm>s, meaning that the data derived from the
+ <glossterm linkend="glossary-view">View</glossterm> is actually stored on disk separately from
+ the sources of that data. When using the term
+ <glossterm linkend="glossary-materialized">Materialized</glossterm> to refer to
+ multi-step queries, it means that the data of a given step is stored
+ 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 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 <glossterm linkend="glossary-table">Table</glossterm> does. It cannot be modified via
+ <command>INSERT</command>, <command>UPDATE</command>, or
+ <command>DELETE</command> operations.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-creatematerializedview"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-null">
+ <glossterm>Null</glossterm>
+ <glossdef>
+ <para>
+ A concept of non-existence that is a central tenet of Relational
+ Database Theory. It represents the absence of value.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Optimizer</glossterm>
+ <glosssee otherterm="glossary-planner" />
+ </glossentry>
+
+ <glossentry id="glossary-partition">
+ <glossterm>Partition</glossterm>
+ <glossdef>
+ <para>
+ In reference to a <glossterm linkend="glossary-table">Table</glossterm>:
+ A <glossterm linkend="glossary-table">Table</glossterm> that can be queried directly,
+ or via a partitioned table, which is a collection of
+ sub-tables, each capable of holding one defined
+ subset of information that does not overlap with any other
+ table in the collection.
+ </para>
+ <para>
+ In reference to a <glossterm linkend="glossary-analytic-function">Analytic Function</glossterm>:
+ a partition is a definition that identifies which neighboring
+ <glossterm linkend="glossary-row">Row</glossterm>s can be considered by the
+ function.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-postmaster">
+ <glossterm>Postmaster (process)</glossterm>
+ <glossdef>
+ <para>
+ The very first process of an <glossterm linkend="glossary-instance">Instance</glossterm>. It
+ starts and manages the other auxiliary processes and creates
+ <glossterm linkend="glossary-backend">backend processes</glossterm>
+ on demand.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="server-start"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-primary-server">
+ <glossterm>Primary (server)</glossterm>
+ <glossdef>
+ <para>
+ When two or more <glossterm linkend="glossary-database">Database</glossterm>s 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>
+ <para>
+ A special case of a <glossterm linkend="glossary-unique-index">Unique Index</glossterm> defined on a
+ <glossterm linkend="glossary-table">Table</glossterm> or other <glossterm linkend="glossary-relation">Relation</glossterm>
+ that also guarantees that all of the <glossterm linkend="glossary-attribute">Attribute</glossterm>s
+ within the <glossterm linkend="glossary-primary-key">Primary Key</glossterm> do not have
+ <glossterm linkend="glossary-null">Null</glossterm> values. As the name implies, there can be
+ only one <glossterm linkend="glossary-primary-key">Primary Key</glossterm> per
+ table, though it is possible to have multiple
+ unique indexes that also have no null-capable attributes.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-procedure">
+ <glossterm>Procedure</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 may seem
+ similar to <glossterm linkend="glossary-function">Function</glossterm>s, 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
+ as <command>COMMIT</command> and <command>ROLLBACK</command>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createprocedure"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-query">
+ <glossterm>Query</glossterm>
+ <glossdef>
+ <para>
+ A request sent by a client to a <glossterm linkend="glossary-backend">backend</glossterm>,
+ usually to return results or to modify data on the database.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-planner">
+ <glossterm>Query Planner</glossterm>
+ <glossdef>
+ <para>
+ The part of <productname>PostgreSQL</productname> that is devoted to
+ determining (<firstterm>planning</firstterm>) the most efficient way to
+ execute <glossterm linkend="glossary-query">queries</glossterm>.
+ Also known as <firstterm>query optimizer</firstterm>,
+ <firstterm>optimizer</firstterm>, or simply <firstterm>planner</firstterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-record">
+ <glossterm>Record</glossterm>
+ <glosssee otherterm="glossary-tuple" />
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Recycling</glossterm>
+ <glosssee otherterm="glossary-wal-file" />
+ </glossentry>
+
+ <glossentry id="glossary-referential-integrity">
+ <glossterm>Referential Integrity</glossterm>
+ <glossdef>
+ <para>
+ A means of restricting data in one <glossterm linkend="glossary-relation">Relation</glossterm>
+ by a <glossterm linkend="glossary-foreign-key">Foreign Key</glossterm>
+ so that it must have matching data in another
+ <glossterm linkend="glossary-relation">Relation</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-relation">
+ <glossterm>Relation</glossterm>
+ <glossdef>
+ <para>
+ The generic term for all objects in a <glossterm linkend="glossary-database">Database</glossterm>
+ that have a name and a list of <glossterm linkend="glossary-attribute">Attribute</glossterm>s
+ defined in a specific order. <glossterm linkend="glossary-table">Table</glossterm>s,
+ <glossterm linkend="glossary-view">View</glossterm>s, <glossterm linkend="glossary-foreign-table">Foreign Table</glossterm>s,
+ <glossterm linkend="glossary-materialized-view">Materialized View</glossterm>s, and
+ <glossterm linkend="glossary-index">Index</glossterm>es are all relations.
+ </para>
+ <para>
+ <firstterm>Class</firstterm> is an archaic synonym for
+ <firstterm>relation</firstterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-replica">
+ <glossterm>Replica</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm linkend="glossary-database">Database</glossterm> that is paired with a
+ <glossterm linkend="glossary-primary-server">primary</glossterm>
+ database and is maintaining a copy of some or
+ all of the primary <glossterm linkend="glossary-database">Database</glossterm>'s data. The foremost
+ reasons for doing this are to allow for greater access to that data,
+ and to maintain availability of the data in the event that the
+ <glossterm linkend="glossary-primary-server">primary</glossterm> becomes unavailable.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-replication">
+ <glossterm>Replication</glossterm>
+ <glossdef>
+ <para>
+ The act of reproducing data on one <glossterm linkend="glossary-server">Server</glossterm> onto
+ another server called a <glossterm linkend="glossary-replica">Replica</glossterm>. This can take the
+ form of <firstterm>physical replication</firstterm>, where all file
+ changes from one server are copied verbatim,
+ or <firstterm>logical replication</firstterm> where a defined subset
+ of data changes are conveyed using a higher-level representation.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-result-set">
+ <glossterm>Result Set</glossterm>
+ <glossdef>
+ <para>
+ A data structure transmitted from a <glossterm linkend="glossary-backend">Backend Process</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. The data structure consists of zero or more
+ <glossterm linkend="glossary-row">Row</glossterm>s with the same ordered set of
+ <glossterm linkend="glossary-attribute">Attribute</glossterm>s.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-revoke">
+ <glossterm>Revoke</glossterm>
+ <glossdef>
+ <para>
+ A command to prevent access to a named set of
+ <glossterm linkend="glossary-database">Database</glossterm> objects for a named list of
+ <glossterm linkend="glossary-user">User</glossterm>s and <glossterm linkend="glossary-role">Role</glossterm>s.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-revoke"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-role">
+ <glossterm>Role</glossterm>
+ <glossdef>
+ <para>
+ A collection of access privileges to the
+ <glossterm linkend="glossary-database">Database</glossterm>. <glossterm linkend="glossary-role">Role</glossterm>s are
+ themselves a privilege that can be granted to other roles. This is
+ often done for convenience or to ensure completeness when multiple
+ <glossterm linkend="glossary-user">User</glossterm>s need the same privileges.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createrole"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-rollback">
+ <glossterm>Rollback</glossterm>
+ <glossdef>
+ <para>
+ A command to undo all of the operations performed since the beginning
+ of a <glossterm linkend="glossary-transaction">Transaction</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-rollback"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-row">
+ <glossterm>Row</glossterm>
+ <glosssee otherterm="glossary-tuple" />
+ </glossentry>
+
+ <glossentry id="glossary-savepoint">
+ <glossterm>Savepoint</glossterm>
+ <glossdef>
+ <para>
+ A special mark inside the sequence of steps in a
+ <glossterm linkend="glossary-transaction">Transaction</glossterm>. Data modifications after this
+ point in time may be reverted to the time of the savepoint.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-savepoint"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-schema">
+ <glossterm>Schema</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm linkend="glossary-schema">Schema</glossterm> is a namespace for
+ <glossterm linkend="glossary-sql-object">SQL object</glossterm>s, which all reside in the same
+ <glossterm linkend="glossary-database">database</glossterm>. Each
+ <glossterm linkend="glossary-sql-object">SQL object</glossterm> must reside in exactly one
+ <glossterm linkend="glossary-schema">Schema</glossterm>.
+ </para>
+ <para>
+ In general, the names of <glossterm linkend="glossary-sql-object">SQL Object</glossterm>s in the
+ schema are unique — even across different types of objects. The lone
+ exception is the case of <glossterm linkend="glossary-unique">Unique</glossterm>
+ <glossterm linkend="glossary-constraint">Constraint</glossterm>s, in which case there
+ <emphasis>must</emphasis> be a <glossterm linkend="glossary-unique-index">Unique Index</glossterm>
+ with the same name and <glossterm linkend="glossary-schema">Schema</glossterm> as the
+ <glossterm linkend="glossary-constraint">Constraint</glossterm>. There is no restriction on reusing
+ a name in multiple <glossterm linkend="glossary-schema">Schema</glossterm>s.
+ </para>
+ <para>
+ Many <glossterm linkend="glossary-sql-object">SQL Object</glossterm>s reside in the default
+ <glossterm linkend="glossary-schema">Schema</glossterm> <literal>public</literal>, but it is
+ expected that more schemas are created to hold application-specific
+ <glossterm linkend="glossary-sql-object">SQL Object</glossterm>s.
+ </para>
+ <para>
+ More generically, the term <glossterm linkend="glossary-schema">Schema</glossterm> is used to
+ mean all data descriptions (<glossterm linkend="glossary-table">Table</glossterm> definitions,
+ <glossterm linkend="glossary-constraint">Constraint</glossterm>s, comments) for a given
+ <glossterm linkend="glossary-database">Database</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="ddl-schemas"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-segment">
+ <glossterm linkend="glossary-segment">Segment</glossterm>
+ <glosssee otherterm="glossary-file-segment" />
+ </glossentry>
+
+ <glossentry id="glossary-select">
+ <glossterm>Select</glossterm>
+ <glossdef>
+ <para>
+ The <acronym>SQL</acronym> command used to query a <glossterm linkend="glossary-database">Database</glossterm>.
+ Normally, <command>SELECT</command>s are not expected to modify the
+ <glossterm linkend="glossary-database">Database</glossterm> in any way, but it is possible that
+ <glossterm linkend="glossary-function">Function</glossterm>s invoked within the query could have
+ side effects that do modify data.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-select"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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 linkend="glossary-database">Database</glossterm>
+ appears to be frozen for the duration of the
+ <glossterm linkend="glossary-transaction">Transaction</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-server">
+ <glossterm>Server</glossterm>
+ <glossdef>
+ <para>
+ A computer on which <productname>PostgreSQL</productname>
+ <glossterm linkend="glossary-instance">instances</glossterm> run.
+ The term <firstterm>server</firstterm> denotes real hardware, a
+ container, or a Virtual Machine.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-session">
+ <glossterm>Session</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm linkend="glossary-connection">Connection</glossterm> to the <glossterm linkend="glossary-database">Database</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-sequence">
+ <glossterm>Sequence</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm linkend="glossary-database">Database</glossterm> object which represents the
+ mathematical concept of a numerical integral sequence. It can be
+ thought of as a <glossterm linkend="glossary-table">Table</glossterm> with exactly one
+ <glossterm linkend="glossary-row">Row</glossterm> and one <glossterm linkend="glossary-column">Column</glossterm>. The
+ value stored is known as the current value. A
+ <glossterm linkend="glossary-sequence">Sequence</glossterm> has a defined direction (usually
+ increasing) and an interval step (usually 1). Whenever the
+ <literal>NEXTVAL</literal> pseudo-column of a
+ <glossterm linkend="glossary-sequence">Sequence</glossterm> is accessed, the current value is moved
+ in the defined direction by the defined interval step, that value
+ is returned to the invoking query, and the current value of the
+ sequence is updated to reflect the new value. The value can be updated
+ multiple times in a single query, the net effect being that each row
+ selected will have a different value. Values taken from a
+ <glossterm linkend="glossary-sequence">Sequence</glossterm> are never reverted, even in the case of
+ a <glossterm linkend="glossary-rollback">Rollback</glossterm>, which means that the
+ <glossterm linkend="glossary-sequence">Sequence</glossterm> will never generate the same number twice,
+ which makes it useful for generating
+ <glossterm linkend="glossary-primary-key">Primary Key</glossterm> values.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createsequence"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-shared-memory">
+ <glossterm>Shared Memory</glossterm>
+ <glossdef>
+ <para>
+ <acronym>RAM</acronym> which is used by the processes common to an
+ <glossterm linkend="glossary-instance">Instance</glossterm>. It mirrors parts of
+ <glossterm linkend="glossary-database">Database</glossterm> files, provides an area for
+ <glossterm linkend="glossary-wal-record">WAL Record</glossterm>s, and stores additional common
+ information. Note that <glossterm linkend="glossary-shared-memory">Shared Memory</glossterm> belongs to
+ the complete <glossterm linkend="glossary-instance">Instance</glossterm>, not to a single
+ <glossterm linkend="glossary-database">Database</glossterm>.
+ </para>
+ <para>
+ <glossterm linkend="glossary-shared-memory">Shared Memory</glossterm> is organized into pages. If a
+ page is modified, it is called a dirty page until it is written back
+ to the file system.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="runtime-config-resource-memory"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-sql-object">
+ <glossterm>SQL Object</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm linkend="glossary-table">Table</glossterm>, <glossterm linkend="glossary-view">View</glossterm>,
+ <glossterm linkend="glossary-materialized-view">Materialized View</glossterm>,
+ <glossterm linkend="glossary-index">Index</glossterm>, <glossterm linkend="glossary-constraint">Constraint</glossterm>,
+ <glossterm linkend="glossary-sequence">Sequence</glossterm>, <glossterm linkend="glossary-function">Function</glossterm>,
+ <glossterm linkend="glossary-procedure">Procedure</glossterm>, <glossterm linkend="glossary-trigger">Trigger</glossterm>,
+ data type, or operator. Every <glossterm linkend="glossary-sql-object">SQL Object</glossterm>
+ belongs to exactly one <glossterm linkend="glossary-schema">Schema</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="manage-ag-overview"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-stats-collector">
+ <glossterm>Stats Collector</glossterm>
+ <glossdef>
+ <para>
+ This process collects statistical information about the
+ <glossterm linkend="glossary-cluster">Cluster</glossterm>'s activities.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="monitoring-stats"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-system-catalog">
+ <glossterm>System Catalog</glossterm>
+ <glossdef>
+ <para>
+ A collection of <glossterm linkend="glossary-table">Table</glossterm>s and
+ <glossterm linkend="glossary-view">View</glossterm>s which describe the structure of all
+ <acronym>SQL</acronym> objects of the <glossterm linkend="glossary-database">Database</glossterm>
+ and the <glossterm linkend="glossary-global-sql-object">Global SQL Object</glossterm>s of the
+ <glossterm linkend="glossary-cluster">Cluster</glossterm>. The <glossterm linkend="glossary-system-catalog">System
+ Catalog</glossterm> resides in the schema
+ <literal>pg_catalog</literal>. Main parts are mirrored as
+ <glossterm linkend="glossary-view">View</glossterm>s in the <glossterm linkend="glossary-schema">Schema</glossterm>
+ <literal>information_schema</literal>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="ddl-schemas"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-table">
+ <glossterm>Table</glossterm>
+ <glossdef>
+ <para>
+ A collection of <glossterm linkend="glossary-tuple">Tuple</glossterm>s (also known as
+ <glossterm linkend="glossary-row">Row</glossterm>s or <glossterm linkend="glossary-record">Record</glossterm>s) having
+ a common data structure (the same number of
+ <glossterm linkend="glossary-attribute">Attribute</glossterm>s, in the same order, having the same
+ name and type per position). A <glossterm linkend="glossary-table">Table</glossterm> is the
+ most common form of <glossterm linkend="glossary-relation">Relation</glossterm> in
+ <productname>PostgreSQL</productname>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createtable"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-tablespace">
+ <glossterm>Tablespace</glossterm>
+ <glossdef>
+ <para>
+ A named location on the server filesystem. All <glossterm linkend="glossary-sql-object">SQL Object</glossterm>s
+ which require storage beyond their definition in the
+ <glossterm linkend="glossary-system-catalog">System Catalog</glossterm>
+ must belong to a single tablespace.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="manage-ag-tablespaces"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-temporary-table">
+ <glossterm>Temporary Table</glossterm>
+ <glossdef>
+ <para>
+ <glossterm linkend="glossary-table">Table</glossterm>s that exist either for the lifetime of a
+ <glossterm linkend="glossary-session">Session</glossterm> or a
+ <glossterm linkend="glossary-transaction">Transaction</glossterm>, as specified at the time of creation. The
+ data in them is not visible to other sessions,
+ and is not <glossterm linkend="glossary-logged">Logged</glossterm>.
+ <glossterm linkend="glossary-temporary-table">Temporary Table</glossterm>s are often used to store
+ intermediate data for a multi-step operation.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createtable"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-transaction">
+ <glossterm>Transaction</glossterm>
+ <glossdef>
+ <para>
+ A combination of commands that must act as a single
+ <glossterm linkend="glossary-atomic">Atomic</glossterm> command: they all succeed or all fail
+ as a single unit, and their effects are not visible to other
+ <glossterm linkend="glossary-session">Session</glossterm>s until
+ the <glossterm linkend="glossary-transaction">Transaction</glossterm> is complete.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="transaction-iso"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-trigger">
+ <glossterm>Trigger</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm linkend="glossary-function">Function</glossterm> which can be defined to execute
+ whenever a certain operation (<command>INSERT</command>,
+ <command>UPDATE</command>, <command>DELETE</command>,
+ <command>TRUNCATE</command>) is applied to a <glossterm linkend="glossary-relation">Relation</glossterm>.
+ A <glossterm linkend="glossary-trigger">Trigger</glossterm>
+ executes within the same <glossterm linkend="glossary-transaction">Transaction</glossterm> as the
+ statement which invoked it, and if the <glossterm linkend="glossary-function">Function</glossterm>
+ fails, then the invoking statement also fails.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createtrigger"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-tuple">
+ <glossterm>Tuple</glossterm>
+ <glossdef>
+ <para>
+ A collection of <glossterm linkend="glossary-attribute">Attribute</glossterm>s in a fixed order.
+ That order may be defined by the <glossterm linkend="glossary-table">Table</glossterm> where
+ the <glossterm linkend="glossary-tuple">Tuple</glossterm> is found, in which case the
+ <glossterm linkend="glossary-tuple">Tuple</glossterm> is often called a
+ <glossterm linkend="glossary-row">Row</glossterm> or <glossterm linkend="glossary-record">Record</glossterm>. It may
+ also be defined by the structure of a
+ <glossterm linkend="glossary-result-set">Result Set</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-unique">
+ <glossterm>Unique</glossterm>
+ <glossdef>
+ <para>
+ The condition of having no duplicate values in the same
+ <glossterm linkend="glossary-column">Column</glossterm> of a <glossterm linkend="glossary-relation">Relation</glossterm>.
+ Often used in the concept of
+ <glossterm linkend="glossary-unique-index">Unique Index</glossterm>es.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-unlogged">
+ <glossterm>Unlogged</glossterm>
+ <glossdef>
+ <para>
+ Changes to an unlogged <glossterm linkend="glossary-relation">Relation</glossterm> are not
+ reflected in the <glossterm linkend="glossary-wal">WAL Log</glossterm>. This disables
+ replication and crash recovery for these relations.
+ </para>
+ <para>
+ The primary use of unlogged tables is for storing
+ transient work data that must be shared across processes.
+ </para>
+ <para>
+ <glossterm linkend="glossary-temporary-table">Temporary Table</glossterm>s are always unlogged.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-update">
+ <glossterm>Update</glossterm>
+ <glossdef>
+ <para>
+ A <acronym>SQL</acronym> command used to modify <glossterm linkend="glossary-row">Row</glossterm>s
+ that may already exist in a specified <glossterm linkend="glossary-table">Table</glossterm>.
+ It cannot create or remove rows.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-update"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-user">
+ <glossterm>User</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm linkend="glossary-role">Role</glossterm> that has the <literal>LOGIN</literal>
+ privilege is said to be a <glossterm linkend="glossary-user">User</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-user-mapping">
+ <glossterm>User Mapping</glossterm>
+ <glossdef>
+ <para>
+ The translation of login credentials in the local
+ <glossterm linkend="glossary-database">Database</glossterm> to credentials in a remote data system
+ defined by a <glossterm linkend="glossary-foreign-data-wrapper">Foreign Data Wrapper</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createusermapping"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-vacuum">
+ <glossterm>Vacuum</glossterm>
+ <glossdef>
+ <para>
+ The process of removing outdated <acronym>MVCC</acronym>
+ <glossterm linkend="glossary-tuple">Tuple</glossterm>s from a <glossterm linkend="glossary-heap">Heap</glossterm> or
+ <glossterm linkend="glossary-index">Index</glossterm>. This can be initiated through the use of
+ the <command>VACUUM</command> command, but can also be handled automatically
+ via <glossterm linkend="glossary-autovacuum">Autovacuum</glossterm> processes.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-vacuum"/> .
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-view">
+ <glossterm>View</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm linkend="glossary-relation">Relation</glossterm> that is defined by a
+ <command>SELECT</command> statement, but has no storage of its own.
+ Any time a query references a <glossterm linkend="glossary-view">View</glossterm>, the
+ definition of the <glossterm linkend="glossary-view">View</glossterm> is substituted into the
+ query as if the user had typed that subquery instead of the name of
+ the <glossterm linkend="glossary-view">View</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createview"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-wal-archiver">
+ <glossterm>WAL Archiver (process)</glossterm>
+ <glossdef>
+ <para>
+ A process that saves copies of <glossterm linkend="glossary-wal-file">WAL File</glossterm>s
+ for the purposes of creating backups or keeping
+ <glossterm linkend="glossary-replica">Replica</glossterm>s current.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="continuous-archiving"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-wal-file">
+ <glossterm>WAL File</glossterm>
+ <glossdef>
+ <para>
+ Each of the numerically-numbered files that provide storage space for
+ <glossterm linkend="glossary-wal">WAL</glossterm>.
+ The files are all of the same predefined size
+ and are written in sequential order, interspersing changes
+ as they occur in multiple simultaneous sessions.
+ If the system crashes, the files are read in order, and each of the
+ changes are replayed to restore the system to the state as it was
+ before the crash.
+ </para>
+ <para>
+ Each WAL file can be released after a
+ <glossterm linkend="glossary-checkpoint">checkpoint</glossterm>
+ writes all the changes in it to the corresponding data files.
+ Releasing the file can be done either by deleting it, or by changing its
+ name so that it will be used in the future, which is called
+ <firstterm>recycling</firstterm>.
+ </para>
+
+ <para>
+ For more information, see
+ <xref linkend="wal-internals"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>WAL</glossterm>
+ <glosssee otherterm="glossary-wal" />
+ </glossentry>
+
+ <glossentry id="glossary-wal-record">
+ <glossterm>WAL Record</glossterm>
+ <glossdef>
+ <para>
+ A low-level description of an individual data change.
+ It contains sufficient information for the data change to be
+ re-executed (<firstterm>replayed</firstterm>) in case a system failure
+ causes the change to be lost.
+ WAL records use a non-printable binary format.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="wal-internals"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-wal-segment">
+ <glossterm>WAL Segment</glossterm>
+ <glosssee otherterm="glossary-wal-file" />
+ </glossentry>
+
+ <glossentry id="glossary-wal-writer">
+ <glossterm linkend="glossary-wal-writer">WAL Writer (process)</glossterm>
+ <glossdef>
+ <para>
+ A process that writes <glossterm linkend="glossary-wal-record">WAL records</glossterm>
+ from <glossterm id="linkend-shared-memory">shared memory</glossterm> to
+ <glossterm id="linkend-wal-file">WAL files</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="runtime-config-wal"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-window-frame">
+ <glossterm>Window frame</glossterm>
+ <glossdef>
+ <para>
+ In a result set, a subset of neighboring rows that match some user
+ specified criteria form a window frame.
+ For example, in a query that returns employees across several departments,
+ the employees from each specific department can form one window frame.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-window-function">
+ <glossterm>Window Function</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-window-frame">window frame</glossterm>.
+ 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 window frame.
+ Also known as <firstterm>analytic functions</firstterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="tutorial-window"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-wal">
+ <glossterm>Write-Ahead Log</glossterm>
+ <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. It comprises many individual
+ <glossterm linkend="glossary-wal-record">WAL records</glossterm> written
+ sequentially to <glossterm linkend="glossary-wal-file">WAL files</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-unique-index">
+ <glossterm>Unique Index</glossterm>
+ <glossdef>
+ <para>
+ TODO - we never defined this and we might just use the component glossterms "unique" and "index"
+ </para>
+ </glossdef>
+ </glossentry>
+ </glosslist>
+</appendix>
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index 1f7bd32878..ba3d626102 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -278,6 +278,7 @@
&docguide;
&limits;
&acronyms;
+ &glossary;
&color;
</part>
--
2.20.1
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-04-02 22:09 Alvaro Herrera <[email protected]>
parent: Corey Huinker <[email protected]>
0 siblings, 1 reply; 97+ messages in thread
From: Alvaro Herrera @ 2020-04-02 22:09 UTC (permalink / raw)
To: Corey Huinker <[email protected]>; +Cc: Jürgen Purtz <[email protected]>; Justin Pryzby <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
On 2020-Apr-02, Corey Huinker wrote:
> On Thu, Apr 2, 2020 at 8:44 AM Jürgen Purtz <[email protected]> wrote:
>
> > +1 and many thanks to Alvaros edits.
> >
> >
> I did some of the grunt work Alvaro alluded to in v6, and the results are
> attached and they build, which means there are no invalid links.
Thank you! I had been working on some other changes myself, and merged
most of your changes. I give you v8.
> * renamed id glossary-temporary-tables to glossary-temporary-table
Good.
> * temporarily re-added an id for glossary-row as we have many references to
> that. unsure if we should use the term Tuple in all those places or say Row
> while linking to glossary-tuple, or something else
I changed these to link to glossary-tuple; that entry already explains
these two other terms, so this seems acceptable.
> * temporarily re-added an id for glossary-segment, glossary-wal-segment,
> glossary-analytic-function, as those were also referenced and will need
> similar decisions made
Ditto.
> * added a stub entry for glossary-unique-index, unsure if it should have a
> definition on it's own, or we split it into unique and index.
I changed Unique Index into Unique Constraint, which is supposed to be
the overarching concept. Used that in the definition of primary key.
> * I noticed several cases where a glossterm is used twice in a definition,
> but didn't de-term them
Did that for most I found, but I expect that some remain.
> * I'm curious about how we should tag a term when using it in its own
> definition. same as anywhere else?
I think we should not tag those.
I fixed the definition of global object as mentioned previously. Also
added "client", made "connection" have less importance compared to
"session", and removed "window frame" (made "window function" refer to
"partition" instead). If you (or anybody) have suggestions for the
definition of "client" and "session", I'm all ears.
I'm quite liking the result of this now. Thanks for all your efforts.
--
Álvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Attachments:
[text/x-diff] 0001-glossary-v8.patch (62.7K, 2-0001-glossary-v8.patch)
download | inline diff:
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 1043d0f7ab..cf21ef857e 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -170,6 +170,7 @@
<!ENTITY limits SYSTEM "limits.sgml">
<!ENTITY acronyms SYSTEM "acronyms.sgml">
+<!ENTITY glossary SYSTEM "glossary.sgml">
<!ENTITY color SYSTEM "color.sgml">
<!ENTITY features-supported SYSTEM "features-supported.sgml">
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
new file mode 100644
index 0000000000..7d981a9223
--- /dev/null
+++ b/doc/src/sgml/glossary.sgml
@@ -0,0 +1,1692 @@
+<appendix id="glossary">
+ <title>Glossary</title>
+ <para>
+ This is a list of terms and their meaning in the context of
+ <productname>PostgreSQL</productname> and relational database
+ systems in general.
+ </para>
+
+ <glosslist>
+ <glossentry id="glossary-aggregate">
+ <glossterm>Aggregate Function</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm linkend="glossary-function">function</glossterm> that
+ combines (<firstterm>aggregates</firstterm>) multiple input values,
+ for example by counting, averaging or adding,
+ yielding a single output value.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="functions-aggregate"/>.
+ </para>
+ <glossseealso otherterm="glossary-window-function" />
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-analyze">
+ <glossterm>Analyze (operation)</glossterm>
+ <glossdef>
+ <para>
+ The process of collecting statistics from data in
+ <glossterm linkend="glossary-table">tables</glossterm>
+ and other <glossterm linkend="glossary-relation">relations</glossterm>
+ to help the <glossterm linkend="glossary-planner">query planner</glossterm>
+ to make decisions about how to execute
+ <glossterm linkend="glossary-query">queries</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Analytic Function</glossterm>
+ <glosssee otherterm="glossary-window-function" />
+ </glossentry>
+
+ <glossentry id="glossary-atomic">
+ <glossterm>Atomic</glossterm>
+ <glossdef>
+ <para>
+ In reference to a <glossterm linkend="glossary-datum">datum</glossterm>:
+ the fact that its value that cannot be broken down into smaller
+ components.
+ </para>
+ </glossdef>
+ <glossdef>
+ <para>
+ In reference to a
+ <glossterm linkend="glossary-transaction">database transaction</glossterm>:
+ see <glossterm linkend="glossary-atomicity">atomicity</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-atomicity">
+ <glossterm>Atomicity</glossterm>
+ <glossdef>
+ <para>
+ The property of a <glossterm linkend="glossary-transaction">transaction</glossterm>
+ that either all its operations complete as a single unit or none do.
+ In addition, if a system failure occurs during the execution of a
+ transaction, no partial results are visible after recovery.
+ This is one of the <acronym>ACID</acronym> properties.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-attribute">
+ <glossterm>Attribute</glossterm>
+ <glossdef>
+ <para>
+ An element with a certain name and data type found within a
+ <glossterm linkend="glossary-tuple">tuple</glossterm> or
+ <glossterm linkend="glossary-table">table</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-autovacuum">
+ <glossterm>Autovacuum (process)</glossterm>
+ <glossdef>
+ <para>
+ A set of background processes that routinely perform
+ <glossterm linkend="glossary-vacuum">vacuum</glossterm>
+ and <glossterm linkend="glossary-analyze">analyze</glossterm>
+ operations.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="autovacuum"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-backend">
+ <glossterm>Backend (process)</glossterm>
+ <glossdef>
+ <para>
+ Processes of an <glossterm linkend="glossary-instance">instance</glossterm>
+ which act on behalf of client <glossterm linkend="glossary-session">sessions</glossterm>
+ and handle their requests.
+ </para>
+ <para>
+ (Don't confuse this term with the similar terms
+ <glossterm linkend="glossary-background-worker">Background Worker</glossterm> or
+ <glossterm linkend="glossary-background-writer">Background Writer</glossterm>).
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-background-worker">
+ <glossterm>Background Worker (process)</glossterm>
+ <glossdef>
+ <para>
+ Individual processes within an <glossterm linkend="glossary-instance">instance</glossterm>,
+ which run system- or user-supplied code.
+ They provide infrastructure for several features in
+ <productname>PostgreSQL</productname>, such as
+ <glossterm linkend="glossary-replication">logical replication</glossterm>
+ and <glossterm linkend="glossary-parallel-query">parallel queries</glossterm>.
+ <glossterm linkend="glossary-extension">Extensions</glossterm> can add
+ custom background worker processes, as well.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="bgworker"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-background-writer">
+ <glossterm>Background Writer (process)</glossterm>
+ <glossdef>
+ <para>
+ A process that continuously writes dirty pages from
+ <glossterm linkend="glossary-shared-memory">Shared Memory</glossterm> to
+ the file system. It wakes up periodically, but works only for a short
+ period in order to distribute its expensive <acronym>I/O</acronym>
+ activity over time, instead of generating fewer larger
+ <acronym>I/O</acronym> peaks which could block other processes.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="runtime-config-resource"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-cast">
+ <glossterm>Cast</glossterm>
+ <glossdef>
+ <para>
+ A conversion of a <glossterm linkend="glossary-datum">Datum</glossterm>
+ from its current data type to another data type.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-catalog">
+ <glossterm>Catalog</glossterm>
+ <glossdef>
+ <para>
+ The <acronym>SQL</acronym> standard uses this term to
+ indicate what is called a
+ <glossterm linkend="glossary-database">Database</glossterm> in
+ <productname>PostgreSQL</productname>'s terminology.
+ </para>
+ <para>
+ This should not be confused with the
+ <glossterm linkend="glossary-system-catalog">System Catalog</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="manage-ag-overview"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-check-constraint">
+ <glossterm>Check Constraint</glossterm>
+ <glossdef>
+ <para>
+ A type of <glossterm linkend="glossary-constraint">constraint</glossterm>
+ defined on a <glossterm linkend="glossary-relation">relation</glossterm>
+ which restricts the values allowed in one or more
+ <glossterm linkend="glossary-attribute">attributes</glossterm>. The
+ check constraint can make reference to any attribute of the same row in
+ the relation, but cannot reference other rows of the same relation or
+ other relations.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="ddl-constraints"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-checkpointer">
+ <glossterm>Checkpointer (process)</glossterm>
+ <glossdef>
+ <para>
+ A process that writes dirty pages to the file system and creates a special
+ checkpoint WAL 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 has been written.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-checkpoint">
+ <glossterm>Checkpoint</glossterm>
+ <glossdef>
+ <para>
+ A point in the <glossterm linkend="glossary-wal">WAL</glossterm> sequence
+ at which it is guaranteed that the heap and index data files have been
+ updated with all information from
+ <glossterm linkend="glossary-shared-memory">Shared Memory</glossterm>
+ modified before that checkpoint;
+ a <firstterm>checkpoint record</firstterm> is written and flushed to WAL
+ to mark that point.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="wal-configuration"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Class (archaic)</glossterm>
+ <glosssee otherterm="glossary-relation" />
+ </glossentry>
+
+ <glossentry id="glossary-client">
+ <glossterm>Client (process)</glossterm>
+ <glossdef>
+ <para>
+ Any process, possibly remote, that establishes a
+ <glossterm linkend="glossary-session">session</glossterm>
+ by <glossterm linkend="glossary-connection">connecting</glossterm> to an
+ <glossterm linkend="glossary-instance">instance</glossterm>
+ to interact with a <glossterm linkend="glossary-database">database</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-cluster">
+ <glossterm>Cluster</glossterm>
+ <glossdef>
+ <para>
+ A group of <glossterm linkend="glossary-database">Databases</glossterm> plus their
+ <glossterm linkend="glossary-global-sql-object">Global SQL Objects</glossterm>. The
+ <firstterm>cluster</firstterm> is managed by exactly one
+ <glossterm linkend="glossary-instance">Instance</glossterm>. A newly created
+ Cluster will have three databases created automatically. They are
+ <literal>template0</literal>, <literal>template1</literal>, and
+ <literal>postgres</literal>. It is expected that an application will
+ create one or more additional database aside from these three.
+ </para>
+ <para>
+ Don't confuse the <productname>PostgreSQL</productname>-specific term
+ <glossterm linkend="glossary-cluster">Cluster</glossterm> with the SQL
+ command <command>CLUSTER</command>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-column">
+ <glossterm>Column</glossterm>
+ <glossdef>
+ <para>
+ An <glossterm linkend="glossary-attribute">Attribute</glossterm> found in
+ a <glossterm linkend="glossary-table">Table</glossterm> or
+ <glossterm linkend="glossary-view">View</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-commit">
+ <glossterm>Commit</glossterm>
+ <glossdef>
+ <para>
+ The act of finalizing a
+ <glossterm linkend="glossary-transaction">transaction</glossterm> within
+ the <glossterm linkend="glossary-database">Database</glossterm>, which
+ makes it visible to other transactions and assures its
+ <glossterm linkend="glossary-durability">durability</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-commit"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-concurrency">
+ <glossterm>Concurrency</glossterm>
+ <glossdef>
+ <para>
+ The concept that multiple independent operations happen within the
+ <glossterm linkend="glossary-database">Database</glossterm> at the same time.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-connection">
+ <glossterm>Connection</glossterm>
+ <glossdef>
+ <para>
+ An established line of communication between a client process and a
+ <glossterm linkend="glossary-backend">backend</glossterm> process,
+ usually over a network, supporting a
+ <glossterm linkend="glossary-session">session</glossterm>. This term is
+ sometimes used as a synonym for session.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="runtime-config-connection"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-consistency">
+ <glossterm>Consistency</glossterm>
+ <glossdef>
+ <para>
+ The property that the data in the
+ <glossterm linkend="glossary-database">database</glossterm>
+ is always in compliance with
+ <glossterm linkend="glossary-constraint">integrity constraints</glossterm>.
+ Transactions may be allowed to violate some of the constraints
+ transiently before it commits, but if such violations are not fixed
+ by the time it commits, such transaction is automatically
+ <glossterm linkend="glossary-rollback">rolled back</glossterm>.
+ This is one of the <acronym>ACID</acronym> properties.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-constraint">
+ <glossterm>Constraint</glossterm>
+ <glossdef>
+ <para>
+ A restriction on the values of data allowed within a
+ <glossterm linkend="glossary-table">Table</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="ddl-constraints"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Data Area</glossterm>
+ <glosssee otherterm="glossary-data-directory" />
+ </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-cluster">Cluster</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.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="storage-file-layout"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-database">
+ <glossterm>Database</glossterm>
+ <glossdef>
+ <para>
+ A named collection of
+ <glossterm linkend="glossary-sql-object">SQL Object</glossterm>s.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="manage-ag-overview"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Database Server</glossterm>
+ <glosssee otherterm="glossary-instance" />
+ </glossentry>
+
+ <glossentry id="glossary-datum">
+ <glossterm>Datum</glossterm>
+ <glossdef>
+ <para>
+ The internal representation of one value of a <acronym>SQL</acronym>
+ data type.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-delete">
+ <glossterm>Delete</glossterm>
+ <glossdef>
+ <para>
+ A <acronym>SQL</acronym> command which removes
+ <glossterm linkend="glossary-tuple">Row</glossterm>s from a given
+ <glossterm linkend="glossary-table">Table</glossterm>
+ or <glossterm linkend="glossary-relation">Relation</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-delete"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-durability">
+ <glossterm>Durability</glossterm>
+ <glossdef>
+ <para>
+ The assurance that once a
+ <glossterm linkend="glossary-transaction">transaction</glossterm> has
+ been <glossterm linkend="glossary-commit">Committed</glossterm>, the
+ changes remain even after a system failure or crash.
+ This is one of the <acronym>ACID</acronym> properties.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-extension">
+ <glossterm>Extension</glossterm>
+ <glossdef>
+ <para>
+ A software add-on package that can be installed on an
+ <glossterm linkend="glossary-instance">instance</glossterm> to
+ get extra features.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="extend-extensions" />.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-file-segment">
+ <glossterm>File Segment</glossterm>
+ <glossdef>
+ <para>
+ A physical file which stores data for a given
+ <glossterm linkend="glossary-heap">Heap</glossterm> or
+ <glossterm linkend="glossary-index">Index</glossterm> object.
+ <glossterm linkend="glossary-file-segment">File Segment</glossterm>s are
+ limited in size by a configuration value and if that size is exceeded, it
+ will be split into multiple physical files.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="storage-file-layout"/>.
+ </para>
+ <para>
+ (Don't confuse this term with the similar term
+ <glossterm linkend="glossary-wal-file">WAL Segment</glossterm>).
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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 linkend="glossary-database">Database</glossterm> so that it appears as if were in local
+ <glossterm linkend="glossary-table">Table</glossterm>(s). With a Foreign Data Wrapper it is
+ possible to define a <glossterm linkend="glossary-foreign-server">Foreign Server</glossterm> and
+ <glossterm linkend="glossary-foreign-table">Foreign Table</glossterm>s.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createforeigndatawrapper"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-foreign-key">
+ <glossterm>Foreign Key</glossterm>
+ <glossdef>
+ <para>
+ A type of <glossterm linkend="glossary-constraint">Constraint</glossterm>
+ defined on one or more <glossterm linkend="glossary-column">Column</glossterm>s
+ in a <glossterm linkend="glossary-table">Table</glossterm> which
+ requires the value(s) in those <glossterm linkend="glossary-column">Column</glossterm>s to
+ identify zero or one <glossterm linkend="glossary-tuple">Row</glossterm>
+ in another (or, infrequently, the same)
+ <glossterm linkend="glossary-table">Table</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-foreign-server">
+ <glossterm>Foreign Server</glossterm>
+ <glossdef>
+ <para>
+ A named collection of
+ <glossterm linkend="glossary-foreign-table">Foreign Table</glossterm>s which
+ all use the same
+ <glossterm linkend="glossary-foreign-data-wrapper">Foreign Data Wrapper</glossterm>
+ and have other configuration values in common.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createserver"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-foreign-table">
+ <glossterm>Foreign Table</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm linkend="glossary-relation">Relation</glossterm> which appears to have
+ <glossterm linkend="glossary-tuple">rows</glossterm> and
+ <glossterm linkend="glossary-column">columns</glossterm> similar to a
+ regular <glossterm linkend="glossary-table">Table</glossterm>, but will forward
+ requests for data through its
+ <glossterm linkend="glossary-foreign-data-wrapper">Foreign Data Wrapper</glossterm>,
+ which will return <glossterm linkend="glossary-result-set">Result Sets</glossterm>
+ structured according to the definition of the
+ <glossterm linkend="glossary-foreign-table">Foreign Table</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createforeigntable"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-function">
+ <glossterm>Function</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.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createfunction"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-global-sql-object">
+ <glossterm>Global SQL Object</glossterm>
+ <glossdef>
+ <para>
+ <glossterm linkend="glossary-sql-object">SQL Object</glossterm>s which do
+ not belong to a specific
+ <glossterm linkend="glossary-database">database</glossterm>.
+ </para>
+ <para>
+ These objects are
+ <glossterm linkend="glossary-role">roles</glossterm>,
+ <glossterm linkend="glossary-tablespace">tablespaces</glossterm>,
+ replication origins, and subscriptions for logical replication.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-grant">
+ <glossterm>Grant</glossterm>
+ <glossdef>
+ <para>
+ A <acronym>SQL</acronym> command that is used to allow
+ <glossterm linkend="glossary-user">User</glossterm>s or <glossterm linkend="glossary-role">Role</glossterm>s to access
+ specific objects within the <glossterm linkend="glossary-database">Database</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-grant"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-heap">
+ <glossterm>Heap</glossterm>
+ <glossdef>
+ <para>
+ Contains the values of <glossterm linkend="glossary-tuple">Row</glossterm>
+ attributes (i.e. the data). The <glossterm linkend="glossary-heap">Heap</glossterm>
+ is realized within <glossterm linkend="glossary-database">Database</glossterm> files.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Host</glossterm>
+ <glosssee otherterm="glossary-server" />
+ </glossentry>
+
+ <glossentry id="glossary-index">
+ <glossterm>Index</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>).
+ Its internal structure supports fast retrieval of and access to the original
+ data.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createindex"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-insert">
+ <glossterm>Insert</glossterm>
+ <glossdef>
+ <para>
+ A <acronym>SQL</acronym> command used to add new data into a
+ <glossterm linkend="glossary-table">Table</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-insert"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-instance">
+ <glossterm>Instance</glossterm>
+ <glossdef>
+ <para>
+ An <glossterm>Instance</glossterm> is a group of processes,
+ its supporting <glossterm linkend="glossary-data-directory">storage space</glossterm>,
+ plus their
+ common <glossterm linkend="glossary-shared-memory">Shared Memory</glossterm>,
+ running on a single <glossterm linkend="glossary-server">Server</glossterm>.
+ The <glossterm linkend="glossary-instance">Instance</glossterm>
+ handles all key features of a <acronym>DBMS</acronym>: read and write
+ access to files and shared memory, assurance of
+ the <acronym>ACID</acronym> paradigm, <acronym>MVCC</acronym>,
+ <glossterm linkend="glossary-connection">Connection</glossterm>s to client programs, backup,
+ recovery, replication, privileges, etc.
+ </para>
+ <para>
+ An <glossterm>Instance</glossterm> manages exactly one
+ <glossterm linkend="glossary-cluster">Cluster</glossterm>.
+ </para>
+ <para>
+ Many <glossterm>Instance</glossterm>s can run on the same server as
+ long as their <acronym>TCP/IP</acronym> ports do not conflict.
+ Different instances on a server may use the
+ same or different versions of <productname>PostgreSQL</productname>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-isolation">
+ <glossterm>Isolation</glossterm>
+ <glossdef>
+ <para>
+ The property that the effects of a transaction are not visible to
+ <glossterm linkend="glossary-concurrency">concurrent transactions</glossterm>
+ before it commits.
+ This is one of the <acronym>ACID</acronym> properties.
+ </para>
+ <para>
+ For more information, see <xref linkend="transaction-iso" />.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-join">
+ <glossterm>Join</glossterm>
+ <glossdef>
+ <para>
+ A <acronym>SQL</acronym> keyword used in <command>SELECT</command> statements for
+ combining data from multiple <glossterm linkend="glossary-relation">Relation</glossterm>s.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-key">
+ <glossterm>Key</glossterm>
+ <glossdef>
+ <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
+ values contained within one or more <glossterm linkend="glossary-attribute">Attribute</glossterm>s
+ in that <glossterm linkend="glossary-table">Table</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-lock">
+ <glossterm>Lock</glossterm>
+ <glossdef>
+ <para>
+ A mechanism that allows a process to limit or prevent simultaneous
+ access to a resource.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-log-file">
+ <glossterm>Log File</glossterm>
+ <glossdef>
+ <para>
+ <glossterm>Log File</glossterm>s contain human-readable text lines about
+ events. Examples include login failures, long-running queries, etc.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="logfile-maintenance"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-logger">
+ <glossterm>Logger (process)</glossterm>
+ <glossdef>
+ <para>
+ If activated, the
+ <glossterm linkend="glossary-logger">Logger</glossterm> process
+ writes information about database events into the current
+ <glossterm linkend="glossary-log-file">Log File</glossterm>. When reaching certain time- or
+ volume-dependent criteria, a new log file is created.
+ Also called <firstterm>syslogger</firstterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="runtime-config-logging"/>.
+ </para>
+ </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>
+ <para>
+ A <glossterm linkend="glossary-table">Table</glossterm> is considered
+ <glossterm linkend="glossary-logged">Logged</glossterm> if changes to it are sent to the
+ <glossterm linkend="glossary-wal">WAL</glossterm>. By default, all regular
+ <glossterm linkend="glossary-table">Table</glossterm>s are <glossterm linkend="glossary-logged">Logged</glossterm>. A
+ table can be specified as <glossterm linkend="glossary-unlogged">Unlogged</glossterm> either at
+ creation time or via the <command>ALTER TABLE</command> command.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Master (server)</glossterm>
+ <glosssee otherterm="glossary-primary-server" />
+ </glossentry>
+
+ <glossentry id="glossary-materialized">
+ <glossterm>Materialized</glossterm>
+ <glossdef>
+ <para>
+ The act of storing information rather than just the method of accessing
+ the information. This term is used in <glossterm linkend="glossary-materialized-view">Materialized
+ View</glossterm>s, meaning that the data derived from the
+ <glossterm linkend="glossary-view">View</glossterm> is actually stored on disk separately from
+ the sources of that data. When using the term
+ <glossterm linkend="glossary-materialized">Materialized</glossterm> to refer to
+ multi-step queries, it means that the data of a given step is stored
+ 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 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 <glossterm linkend="glossary-table">Table</glossterm> does. It cannot be modified via
+ <command>INSERT</command>, <command>UPDATE</command>, or
+ <command>DELETE</command> operations.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-creatematerializedview"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-mvcc">
+ <glossterm>Multi-version concurrency control (MVCC)</glossterm>
+ <glossdef>
+ <para>
+ A mechanism designed to allow several
+ <glossterm linkend="glossary-transaction">transactions</glossterm> to be
+ reading and writing the same rows without one process causing other
+ processes to stall.
+ In <productname>PostgreSQL</productname>, MVCC is implemented by
+ creating copies (<firstterm>versions</firstterm>) of
+ <glossterm linkend="glossary-tuple">tuples</glossterm> as they are
+ modified; after transactions that can see the old versions terminate,
+ those old versions need to be removed.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-null">
+ <glossterm>Null</glossterm>
+ <glossdef>
+ <para>
+ A concept of non-existence that is a central tenet of Relational
+ Database Theory. It represents the absence of value.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Optimizer</glossterm>
+ <glosssee otherterm="glossary-planner" />
+ </glossentry>
+
+ <glossentry id="glossary-parallel-query">
+ <glossterm>Parallel Query</glossterm>
+ <glossdef>
+ <para>
+ The ability to handle parts of executing a
+ <glossterm linkend="glossary-query">query</glossterm> to take advantage
+ of parallel processes on servers with multiple <acronym>CPU</acronym>s.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-partition">
+ <glossterm>Partition</glossterm>
+ <glossdef>
+ <para>
+ In reference to a <glossterm linkend="glossary-table">Table</glossterm>:
+ A <glossterm linkend="glossary-table">Table</glossterm> that can be queried directly,
+ or via a partitioned table, which is a collection of
+ sub-tables, each capable of holding one defined
+ subset of information that does not overlap with any other
+ table in the collection.
+ </para>
+ </glossdef>
+ <glossdef>
+ <para>
+ In reference to a <glossterm linkend="glossary-window-function">window function</glossterm>:
+ a partition is a definition that identifies which neighboring
+ <glossterm linkend="glossary-tuple">Row</glossterm>s can be considered by the
+ function.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-postmaster">
+ <glossterm>Postmaster (process)</glossterm>
+ <glossdef>
+ <para>
+ The very first process of an <glossterm linkend="glossary-instance">Instance</glossterm>. It
+ starts and manages the other auxiliary processes and creates
+ <glossterm linkend="glossary-backend">backend processes</glossterm>
+ on demand.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="server-start"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-primary-server">
+ <glossterm>Primary (server)</glossterm>
+ <glossdef>
+ <para>
+ When two or more <glossterm linkend="glossary-database">Database</glossterm>s 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>
+ <para>
+ A special case of a
+ <glossterm linkend="glossary-unique-constraint">unique constraint</glossterm>
+ defined on a
+ <glossterm linkend="glossary-table">Table</glossterm> or other
+ <glossterm linkend="glossary-relation">Relation</glossterm> that also
+ guarantees that all of the
+ <glossterm linkend="glossary-attribute">Attribute</glossterm>s
+ within the <glossterm linkend="glossary-primary-key">Primary Key</glossterm>
+ do not have <glossterm linkend="glossary-null">Null</glossterm> values.
+ As the name implies, there can be only one
+ primary key per table, though it is possible to have multiple unique
+ constraints that also have no null-capable attributes.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-procedure">
+ <glossterm>Procedure</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 may seem
+ 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
+ as <command>COMMIT</command> and <command>ROLLBACK</command>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createprocedure"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-query">
+ <glossterm>Query</glossterm>
+ <glossdef>
+ <para>
+ A request sent by a client to a <glossterm linkend="glossary-backend">backend</glossterm>,
+ usually to return results or to modify data on the database.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-planner">
+ <glossterm>Query Planner</glossterm>
+ <glossdef>
+ <para>
+ The part of <productname>PostgreSQL</productname> that is devoted to
+ determining (<firstterm>planning</firstterm>) the most efficient way to
+ execute <glossterm linkend="glossary-query">queries</glossterm>.
+ Also known as <firstterm>query optimizer</firstterm>,
+ <firstterm>optimizer</firstterm>, or simply <firstterm>planner</firstterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Record</glossterm>
+ <glosssee otherterm="glossary-tuple" />
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Recycling</glossterm>
+ <glosssee otherterm="glossary-wal-file" />
+ </glossentry>
+
+ <glossentry id="glossary-referential-integrity">
+ <glossterm>Referential Integrity</glossterm>
+ <glossdef>
+ <para>
+ A means of restricting data in one <glossterm linkend="glossary-relation">Relation</glossterm>
+ by a <glossterm linkend="glossary-foreign-key">Foreign Key</glossterm>
+ so that it must have matching data in another
+ <glossterm linkend="glossary-relation">Relation</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-relation">
+ <glossterm>Relation</glossterm>
+ <glossdef>
+ <para>
+ The generic term for all objects in a <glossterm linkend="glossary-database">Database</glossterm>
+ that have a name and a list of <glossterm linkend="glossary-attribute">Attribute</glossterm>s
+ defined in a specific order. <glossterm linkend="glossary-table">Table</glossterm>s,
+ <glossterm linkend="glossary-view">View</glossterm>s, <glossterm linkend="glossary-foreign-table">Foreign Table</glossterm>s,
+ <glossterm linkend="glossary-materialized-view">Materialized View</glossterm>s, and
+ <glossterm linkend="glossary-index">Index</glossterm>es are all relations.
+ </para>
+ <para>
+ <firstterm>Class</firstterm> is an archaic synonym for
+ <firstterm>relation</firstterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-replica">
+ <glossterm>Replica</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm linkend="glossary-database">Database</glossterm> that is paired with a
+ <glossterm linkend="glossary-primary-server">primary</glossterm>
+ database and is maintaining a copy of some or
+ all of the primary <glossterm linkend="glossary-database">Database</glossterm>'s data. The foremost
+ reasons for doing this are to allow for greater access to that data,
+ and to maintain availability of the data in the event that the
+ <glossterm linkend="glossary-primary-server">primary</glossterm> becomes unavailable.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-replication">
+ <glossterm>Replication</glossterm>
+ <glossdef>
+ <para>
+ The act of reproducing data on one <glossterm linkend="glossary-server">Server</glossterm> onto
+ another server called a <glossterm linkend="glossary-replica">Replica</glossterm>. This can take the
+ form of <firstterm>physical replication</firstterm>, where all file
+ changes from one server are copied verbatim,
+ or <firstterm>logical replication</firstterm> where a defined subset
+ of data changes are conveyed using a higher-level representation.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-result-set">
+ <glossterm>Result Set</glossterm>
+ <glossdef>
+ <para>
+ A data structure transmitted from a <glossterm linkend="glossary-backend">Backend Process</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. The data structure consists of zero or more
+ <glossterm linkend="glossary-tuple">Row</glossterm>s with the same ordered set of
+ <glossterm linkend="glossary-attribute">Attribute</glossterm>s.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-revoke">
+ <glossterm>Revoke</glossterm>
+ <glossdef>
+ <para>
+ A command to prevent access to a named set of
+ <glossterm linkend="glossary-database">Database</glossterm> objects for a named list of
+ <glossterm linkend="glossary-user">User</glossterm>s and <glossterm linkend="glossary-role">Role</glossterm>s.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-revoke"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-role">
+ <glossterm>Role</glossterm>
+ <glossdef>
+ <para>
+ A collection of access privileges to the
+ <glossterm linkend="glossary-database">Database</glossterm>. <glossterm linkend="glossary-role">Role</glossterm>s are
+ themselves a privilege that can be granted to other roles. This is
+ often done for convenience or to ensure completeness when multiple
+ <glossterm linkend="glossary-user">User</glossterm>s need the same privileges.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createrole"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-rollback">
+ <glossterm>Rollback</glossterm>
+ <glossdef>
+ <para>
+ A command to undo all of the operations performed since the beginning
+ of a <glossterm linkend="glossary-transaction">Transaction</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-rollback"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Row</glossterm>
+ <glosssee otherterm="glossary-tuple" />
+ </glossentry>
+
+ <glossentry id="glossary-savepoint">
+ <glossterm>Savepoint</glossterm>
+ <glossdef>
+ <para>
+ A special mark inside the sequence of steps in a
+ <glossterm linkend="glossary-transaction">Transaction</glossterm>. Data modifications after this
+ point in time may be reverted to the time of the savepoint.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-savepoint"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-schema">
+ <glossterm>Schema</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm linkend="glossary-schema">Schema</glossterm> is a namespace for
+ <glossterm linkend="glossary-sql-object">SQL object</glossterm>s, which all reside in the same
+ <glossterm linkend="glossary-database">database</glossterm>. Each
+ <glossterm linkend="glossary-sql-object">SQL object</glossterm> must reside in exactly one
+ <glossterm linkend="glossary-schema">Schema</glossterm>.
+ </para>
+ <para>
+ The names of <glossterm linkend="glossary-sql-object">SQL Objects</glossterm>
+ of the same type in the same schema are enforced unique. There is no
+ restriction on reusing a name in multiple schemas.
+ </para>
+ <para>
+ Many <glossterm linkend="glossary-sql-object">SQL Object</glossterm>s reside in the default
+ <glossterm linkend="glossary-schema">Schema</glossterm> <literal>public</literal>, but it is
+ expected that more schemas are created to hold application-specific
+ <glossterm linkend="glossary-sql-object">SQL Object</glossterm>s.
+ </para>
+ </glossdef>
+ <glossdef>
+ <para>
+ More generically, the term <firstterm>Schema</firstterm> is used to mean all data descriptions
+ (<glossterm linkend="glossary-table">Table</glossterm> definitions,
+ <glossterm linkend="glossary-constraint">Constraint</glossterm>s, comments, etc)
+ for a given <glossterm linkend="glossary-database">Database</glossterm> or
+ subset thereof.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="ddl-schemas"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Segment</glossterm>
+ <glosssee otherterm="glossary-file-segment" />
+ </glossentry>
+
+ <glossentry id="glossary-select">
+ <glossterm>Select</glossterm>
+ <glossdef>
+ <para>
+ The <acronym>SQL</acronym> command used to query a <glossterm linkend="glossary-database">Database</glossterm>.
+ Normally, <command>SELECT</command>s are not expected to modify the
+ <glossterm linkend="glossary-database">Database</glossterm> in any way, but it is possible that
+ <glossterm linkend="glossary-function">Function</glossterm>s invoked within the query could have
+ side effects that do modify data.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-select"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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 linkend="glossary-database">Database</glossterm>
+ appears to be frozen for the duration of the
+ <glossterm linkend="glossary-transaction">Transaction</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-server">
+ <glossterm>Server</glossterm>
+ <glossdef>
+ <para>
+ A computer on which <productname>PostgreSQL</productname>
+ <glossterm linkend="glossary-instance">instances</glossterm> run.
+ The term <firstterm>server</firstterm> denotes real hardware, a
+ container, or a Virtual Machine.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-session">
+ <glossterm>Session</glossterm>
+ <glossdef>
+ <para>
+ A state that allows a client and a backend to interact,
+ communicating over a <glossterm linkend="glossary-connection">connection</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-sequence">
+ <glossterm>Sequence</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm linkend="glossary-database">Database</glossterm> object which
+ represents the mathematical concept of a numerical integral sequence.
+ It can be thought of as a <glossterm linkend="glossary-table">Table</glossterm>
+ with exactly one <glossterm linkend="glossary-tuple">Row</glossterm> and
+ one <glossterm linkend="glossary-column">Column</glossterm>. The
+ value stored is known as the current value. A
+ <glossterm linkend="glossary-sequence">Sequence</glossterm> has a defined
+ direction (usually increasing) and an interval step (usually 1).
+ Whenever the <literal>NEXTVAL</literal> pseudo-column of a
+ <glossterm linkend="glossary-sequence">Sequence</glossterm> is accessed,
+ the current value is moved in the defined direction by the defined
+ interval step, that value is returned to the invoking query,
+ and the current value of the sequence is updated to reflect the new value.
+ The value can be updated multiple times in a single query,
+ the net effect being that each row selected will have a different value.
+ Values taken from a
+ <glossterm linkend="glossary-sequence">Sequence</glossterm> are never
+ reverted, even in the case of a
+ <glossterm linkend="glossary-rollback">Rollback</glossterm>, which means
+ that the <glossterm linkend="glossary-sequence">Sequence</glossterm>
+ will never generate the same number twice, which makes it useful for
+ generating
+ <glossterm linkend="glossary-primary-key">Primary Key</glossterm> values.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createsequence"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-shared-memory">
+ <glossterm>Shared Memory</glossterm>
+ <glossdef>
+ <para>
+ <acronym>RAM</acronym> which is used by the processes common to an
+ <glossterm linkend="glossary-instance">Instance</glossterm>. It mirrors parts of
+ <glossterm linkend="glossary-database">Database</glossterm> files, provides an area for
+ <glossterm linkend="glossary-wal-record">WAL Record</glossterm>s, and stores additional common
+ information. Note that <glossterm linkend="glossary-shared-memory">Shared Memory</glossterm> belongs to
+ the complete <glossterm linkend="glossary-instance">Instance</glossterm>, not to a single
+ <glossterm linkend="glossary-database">Database</glossterm>.
+ </para>
+ <para>
+ <glossterm linkend="glossary-shared-memory">Shared Memory</glossterm> is organized into pages. If a
+ page is modified, it is called a dirty page until it is written back
+ to the file system.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="runtime-config-resource-memory"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-sql-object">
+ <glossterm>SQL Object</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm linkend="glossary-table">table</glossterm>,
+ <glossterm linkend="glossary-view">view</glossterm>,
+ <glossterm linkend="glossary-materialized-view">materialized view</glossterm>,
+ <glossterm linkend="glossary-index">index</glossterm>,
+ <glossterm linkend="glossary-constraint">constraint</glossterm>,
+ <glossterm linkend="glossary-sequence">sequence</glossterm>,
+ <glossterm linkend="glossary-function">function</glossterm>,
+ <glossterm linkend="glossary-procedure">procedure</glossterm>,
+ <glossterm linkend="glossary-trigger">trigger</glossterm>,
+ data type, or operator. Every one of those SQL objects
+ belong to exactly one <glossterm linkend="glossary-schema">Schema</glossterm>.
+ </para>
+ <para>
+ There also exist SQL objects that do not belong to schemas; those include
+ <glossterm linkend="glossary-extension">extensions</glossterm>,
+ <glossterm linkend="glossary-cast">data type cases</glossterm>,
+ and
+ <glossterm linkend="glossary-foreign-data-wrapper">foreign data wrappers</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="manage-ag-overview"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-stats-collector">
+ <glossterm>Stats Collector</glossterm>
+ <glossdef>
+ <para>
+ This process collects statistical information about the
+ <glossterm linkend="glossary-cluster">Cluster</glossterm>'s activities.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="monitoring-stats"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-system-catalog">
+ <glossterm>System Catalog</glossterm>
+ <glossdef>
+ <para>
+ A collection of <glossterm linkend="glossary-table">Table</glossterm>s and
+ <glossterm linkend="glossary-view">View</glossterm>s which describe the structure of all
+ <acronym>SQL</acronym> objects of the <glossterm linkend="glossary-database">Database</glossterm>
+ and the <glossterm linkend="glossary-global-sql-object">Global SQL Object</glossterm>s of the
+ <glossterm linkend="glossary-cluster">Cluster</glossterm>. The <glossterm linkend="glossary-system-catalog">System
+ Catalog</glossterm> resides in the schema
+ <literal>pg_catalog</literal>. Main parts are mirrored as
+ <glossterm linkend="glossary-view">View</glossterm>s in the <glossterm linkend="glossary-schema">Schema</glossterm>
+ <literal>information_schema</literal>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="ddl-schemas"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-table">
+ <glossterm>Table</glossterm>
+ <glossdef>
+ <para>
+ A collection of <glossterm linkend="glossary-tuple">tuples</glossterm> having
+ a common data structure (the same number of
+ <glossterm linkend="glossary-attribute">attributes</glossterm>, in the same
+ order, having the same name and type per position).
+ A table is the most common form of
+ <glossterm linkend="glossary-relation">Relation</glossterm> in
+ <productname>PostgreSQL</productname>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createtable"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-tablespace">
+ <glossterm>Tablespace</glossterm>
+ <glossdef>
+ <para>
+ A named location on the server filesystem. All <glossterm linkend="glossary-sql-object">SQL Object</glossterm>s
+ which require storage beyond their definition in the
+ <glossterm linkend="glossary-system-catalog">System Catalog</glossterm>
+ must belong to a single tablespace.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="manage-ag-tablespaces"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-temporary-table">
+ <glossterm>Temporary Table</glossterm>
+ <glossdef>
+ <para>
+ <glossterm linkend="glossary-table">Table</glossterm>s that exist either
+ for the lifetime of a
+ <glossterm linkend="glossary-session">Session</glossterm> or a
+ <glossterm linkend="glossary-transaction">Transaction</glossterm>, as
+ specified at the time of creation. The data in them is not visible to
+ other sessions, and is not
+ <glossterm linkend="glossary-logged">Logged</glossterm>.
+ Temporary tables are often used to store intermediate data for a
+ multi-step operation.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createtable"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-transaction">
+ <glossterm>Transaction</glossterm>
+ <glossdef>
+ <para>
+ A combination of commands that must act as a single
+ <glossterm linkend="glossary-atomic">Atomic</glossterm> command: they all
+ succeed or all fail as a single unit, and their effects are not visible to
+ other <glossterm linkend="glossary-session">Session</glossterm>s until
+ the transaction is complete.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="transaction-iso"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-trigger">
+ <glossterm>Trigger</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm linkend="glossary-function">Function</glossterm> which can be defined to execute
+ whenever a certain operation (<command>INSERT</command>,
+ <command>UPDATE</command>, <command>DELETE</command>,
+ <command>TRUNCATE</command>) is applied to a <glossterm linkend="glossary-relation">Relation</glossterm>.
+ A <glossterm linkend="glossary-trigger">Trigger</glossterm>
+ executes within the same <glossterm linkend="glossary-transaction">Transaction</glossterm> as the
+ statement which invoked it, and if the <glossterm linkend="glossary-function">Function</glossterm>
+ fails, then the invoking statement also fails.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createtrigger"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-tuple">
+ <glossterm>Tuple</glossterm>
+ <glossdef>
+ <para>
+ A collection of <glossterm linkend="glossary-attribute">Attribute</glossterm>s in a fixed order.
+ That order may be defined by the <glossterm linkend="glossary-table">Table</glossterm> where
+ the <glossterm linkend="glossary-tuple">Tuple</glossterm> is found, in which case the
+ <glossterm linkend="glossary-tuple">Tuple</glossterm> is often called a
+ row or record.
+ It may also be defined by the structure of a
+ <glossterm linkend="glossary-result-set">Result Set</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-unique-constraint">
+ <glossterm>Unique Constraint</glossterm>
+ <glossdef>
+ <para>
+ A type of <glossterm linkend="glossary-constraint">constraint</glossterm>
+ defined on a <glossterm linkend="glossary-relation">relation</glossterm>
+ which restricts the values allowed in one or a combination of columns
+ so that each value or combination of values can only appear once in the
+ relation — that is, no other row in the relation contains values
+ that are equal to those.
+ </para>
+ <para>
+ Because <glossterm linkend="glossary-null">null values</glossterm> are
+ not considered equal to each other, multiple rows with null values are
+ allowed to exist without violating the unique constraint.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-unlogged">
+ <glossterm>Unlogged</glossterm>
+ <glossdef>
+ <para>
+ Changes to an unlogged <glossterm linkend="glossary-relation">Relation</glossterm>
+ are not reflected in the <glossterm linkend="glossary-wal">WAL</glossterm>.
+ This disables replication and crash recovery for these relations.
+ </para>
+ <para>
+ The primary use of unlogged tables is for storing
+ transient work data that must be shared across processes.
+ </para>
+ <para>
+ <glossterm linkend="glossary-temporary-table">Temporary Table</glossterm>s are always unlogged.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-update">
+ <glossterm>Update</glossterm>
+ <glossdef>
+ <para>
+ A <acronym>SQL</acronym> command used to modify
+ <glossterm linkend="glossary-tuple">rows</glossterm>
+ that may already exist in a specified <glossterm linkend="glossary-table">Table</glossterm>.
+ It cannot create or remove rows.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-update"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-user">
+ <glossterm>User</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm linkend="glossary-role">Role</glossterm> that has the <literal>LOGIN</literal>
+ privilege is said to be a <glossterm linkend="glossary-user">User</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-user-mapping">
+ <glossterm>User Mapping</glossterm>
+ <glossdef>
+ <para>
+ The translation of login credentials in the local
+ <glossterm linkend="glossary-database">Database</glossterm> to credentials
+ in a remote data system defined by a
+ <glossterm linkend="glossary-foreign-data-wrapper">Foreign Data Wrapper</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createusermapping"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-vacuum">
+ <glossterm>Vacuum</glossterm>
+ <glossdef>
+ <para>
+ The process of removing outdated <glossterm linkend="glossary-tuple">tuple
+ versions</glossterm> from tables, and other closely related
+ garbage-collection-like processing required by <productname>PostgreSQL</productname>'s
+ implementation of <glossterm linkend="glossary-mvcc">MVCC</glossterm>.
+ This can be initiated through the use of
+ the <command>VACUUM</command> command, but can also be handled automatically
+ via <glossterm linkend="glossary-autovacuum">Autovacuum</glossterm> processes.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="routine-vacuuming"/> .
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-view">
+ <glossterm>View</glossterm>
+ <glossdef>
+ <para>
+ A <glossterm linkend="glossary-relation">Relation</glossterm> that is defined by a
+ <command>SELECT</command> statement, but has no storage of its own.
+ Any time a query references a <glossterm linkend="glossary-view">View</glossterm>, the
+ definition of the <glossterm linkend="glossary-view">View</glossterm> is substituted into the
+ query as if the user had typed that subquery instead of the name of
+ the <glossterm linkend="glossary-view">View</glossterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="sql-createview"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-wal-archiver">
+ <glossterm>WAL Archiver (process)</glossterm>
+ <glossdef>
+ <para>
+ A process that saves copies of <glossterm linkend="glossary-wal-file">WAL File</glossterm>s
+ for the purposes of creating backups or keeping
+ <glossterm linkend="glossary-replica">Replica</glossterm>s current.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="continuous-archiving"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-wal-file">
+ <glossterm>WAL File</glossterm>
+ <glossdef>
+ <para>
+ Also known as <firstterm>WAL segment</firstterm> or
+ <firstterm>WAL segment file</firstterm>.
+ Each of the numerically-numbered files that provide storage space for
+ <glossterm linkend="glossary-wal">WAL</glossterm>.
+ The files are all of the same predefined size
+ and are written in sequential order, interspersing changes
+ as they occur in multiple simultaneous sessions.
+ If the system crashes, the files are read in order, and each of the
+ changes are replayed to restore the system to the state as it was
+ before the crash.
+ </para>
+ <para>
+ Each WAL file can be released after a
+ <glossterm linkend="glossary-checkpoint">checkpoint</glossterm>
+ writes all the changes in it to the corresponding data files.
+ Releasing the file can be done either by deleting it, or by changing its
+ name so that it will be used in the future, which is called
+ <firstterm>recycling</firstterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="wal-internals"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>WAL</glossterm>
+ <glosssee otherterm="glossary-wal" />
+ </glossentry>
+
+ <glossentry id="glossary-wal-record">
+ <glossterm>WAL Record</glossterm>
+ <glossdef>
+ <para>
+ A low-level description of an individual data change.
+ It contains sufficient information for the data change to be
+ re-executed (<firstterm>replayed</firstterm>) in case a system failure
+ causes the change to be lost.
+ WAL records use a non-printable binary format.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="wal-internals"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>WAL Segment</glossterm>
+ <glosssee otherterm="glossary-wal-file" />
+ </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 id="linkend-shared-memory">shared memory</glossterm> to
+ <glossterm id="linkend-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>
+ <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>.
+ 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.
+ Also known as <firstterm>analytic functions</firstterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="tutorial-window"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id="glossary-wal">
+ <glossterm>Write-Ahead Log</glossterm>
+ <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. It comprises many individual
+ <glossterm linkend="glossary-wal-record">WAL records</glossterm> written
+ sequentially to <glossterm linkend="glossary-wal-file">WAL files</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+ </glosslist>
+</appendix>
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index 1f7bd32878..ba3d626102 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -278,6 +278,7 @@
&docguide;
&limits;
&acronyms;
+ &glossary;
&color;
</part>
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-04-02 22:26 Justin Pryzby <[email protected]>
parent: Alvaro Herrera <[email protected]>
0 siblings, 1 reply; 97+ messages in thread
From: Justin Pryzby @ 2020-04-02 22:26 UTC (permalink / raw)
To: Alvaro Herrera <[email protected]>; +Cc: Corey Huinker <[email protected]>; Jürgen Purtz <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
On Thu, Apr 02, 2020 at 07:09:32PM -0300, Alvaro Herrera wrote:
> "partition" instead). If you (or anybody) have suggestions for the
> definition of "client" and "session", I'm all ears.
We already have Session:
A Connection to the Database.
I propose: Client:
A host (or a process on a host) which connects to a server to make
queries or other requests.
But note, "host" is still defined as "server", which I didn't like.
Maybe it should be:
A computer which may act as a >client< or a >server<.
--
Justin
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-04-03 16:45 Alvaro Herrera <[email protected]>
parent: Justin Pryzby <[email protected]>
0 siblings, 2 replies; 97+ messages in thread
From: Alvaro Herrera @ 2020-04-03 16:45 UTC (permalink / raw)
To: Justin Pryzby <[email protected]>; +Cc: Corey Huinker <[email protected]>; Jürgen Purtz <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
Pushed now. Many thanks to Corey who put the main thrust, and to Jürgen
and Roger for the great help, and to Justin for the extensive review and
Fabien for the initial discussion.
This is just a starting point. Let's keep improving it. And how that
we have it, we can start thinking of patching the main part of the docs
to make reference to it by using <glossterm> in key spots. Right now
the glossary links to itself, but it makes lots of sense to have other
places point to it.
On 2020-Apr-02, Justin Pryzby wrote:
> We already have Session:
> A Connection to the Database.
Yes, but I didn't like that much, so I rewrote it -- I was asking for
suggestions on how to improve it further. While I think we use those
terms (connection and session) interchangeably sometimes, they're not
exactly the same and the glossary should be more precise or at least
less vague about the distinction.
> I propose: Client:
> A host (or a process on a host) which connects to a server to make
> queries or other requests.
>
> But note, "host" is still defined as "server", which I didn't like.
>
> Maybe it should be:
> A computer which may act as a >client< or a >server<.
I changed all these terms, and a few others, added a couple more and
commented out some that I was not happy with, and pushed.
I think this still needs more work:
* We had "serializable", but none of the other isolation levels were
defined. If we think we should define them, let's define them all.
But also the definition we had for serializable was not correct;
it seemed more suited to define "repeatable read".
* I commented out the definition of "sequence", which seemed to go into
excessive detail. Let's have a more concise definition?
* We're missing exclusion constraints, and NOT NULL which is also a
weird type of constraint.
Patches for these omissions, and other contributions, welcome.
--
Álvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-04-03 17:34 Corey Huinker <[email protected]>
parent: Alvaro Herrera <[email protected]>
1 sibling, 1 reply; 97+ messages in thread
From: Corey Huinker @ 2020-04-03 17:34 UTC (permalink / raw)
To: Alvaro Herrera <[email protected]>; +Cc: Justin Pryzby <[email protected]>; Jürgen Purtz <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
>
> we have it, we can start thinking of patching the main part of the docs
> to make reference to it by using <glossterm> in key spots. Right now
> the glossary links to itself, but it makes lots of sense to have other
> places point to it.
>
I have some ideas about how to patch the main docs, but will leave those to
a separate thread.
> * I commented out the definition of "sequence", which seemed to go into
> excessive detail. Let's have a more concise definition?
>
That one's my fault.
>
> Patches for these omissions, and other contributions, welcome.
>
Thanks for all your work on this!
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-04-03 17:37 Roger Harkavy <[email protected]>
parent: Corey Huinker <[email protected]>
0 siblings, 0 replies; 97+ messages in thread
From: Roger Harkavy @ 2020-04-03 17:37 UTC (permalink / raw)
To: Corey Huinker <[email protected]>; +Cc: Alvaro Herrera <[email protected]>; Justin Pryzby <[email protected]>; Jürgen Purtz <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
On Fri, Apr 3, 2020 at 1:34 PM Corey Huinker <[email protected]>
wrote:
> Thanks for all your work on this!
>
And to add on to Corey's message of thanks, I also want to thank everyone
for their input and assistance on that. I am very grateful for the
opportunity to contribute to this project!
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-04-03 17:41 Erik Rijkers <[email protected]>
parent: Alvaro Herrera <[email protected]>
1 sibling, 2 replies; 97+ messages in thread
From: Erik Rijkers @ 2020-04-03 17:41 UTC (permalink / raw)
To: Alvaro Herrera <[email protected]>; +Cc: Justin Pryzby <[email protected]>; Corey Huinker <[email protected]>; Jürgen Purtz <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
On 2020-04-03 18:45, Alvaro Herrera wrote:
> Pushed now. Many thanks to Corey who put the main thrust, and to
> Jürgen
> and Roger for the great help, and to Justin for the extensive review
> and
> Fabien for the initial discussion.
A few improvements:
'its value that cannot' should be
'its value cannot'
'A newly created Cluster' should be
'A newly created cluster'
'term Cluster' should be
'term cluster'
'allowed within a Table.' should be
'allowed within a table.'
'of a SQL data type.' should be
'of an SQL data type.'
'A SQL command' should be
'An SQL command'
'i.e. the data' should be
'i.e., the data'
'that a a view is' should be
'that a view is'
'One of the tables that each contain part' should be
'One of multiple tables that each contain part'
'a partition is a user-defined criteria' should be
'a partition is a user-defined criterion'
'Roless are' should be
'Roles are'
'undo all of the operations' should be
'undo all operations'
'A special mark inside the sequence of steps' should be
'A special mark in the sequence of steps'
'are enforced unique' should be (?)
'are enforced to be unique'
'the term Schema is used' should be
'the term schema is used'
'belong to exactly one Schema.' should be
'belong to exactly one schema.'
'about the Cluster's activities' should be
'about the cluster's activities'
'the most common form of Relation' should be
'the most common form of relation'
'A Trigger executes' should be
'A trigger executes'
'and other closely related garbage-collection-like processing' should
be
'and other processing'
'each of the changes are replayed' should be
'each of the changes is replayed'
Should also be a lemmata in the glossary:
ACID
'archaic' should maybe be 'obsolete'. That seems to me to be an easier
word for non-native speakers.
Thanks,
Erik Rijkers
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-04-03 20:51 Alvaro Herrera <[email protected]>
parent: Erik Rijkers <[email protected]>
1 sibling, 3 replies; 97+ messages in thread
From: Alvaro Herrera @ 2020-04-03 20:51 UTC (permalink / raw)
To: Erik Rijkers <[email protected]>; +Cc: Justin Pryzby <[email protected]>; Corey Huinker <[email protected]>; Jürgen Purtz <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
On 2020-Apr-03, Erik Rijkers wrote:
> On 2020-04-03 18:45, Alvaro Herrera wrote:
> > Pushed now. Many thanks to Corey who put the main thrust, and to Jürgen
> > and Roger for the great help, and to Justin for the extensive review and
> > Fabien for the initial discussion.
>
> A few improvements:
Thanks! That gives me the attached patch.
> Should also be a lemmata in the glossary:
>
> ACID
Agreed. Wording suggestions welcome.
> 'archaic' should maybe be 'obsolete'. That seems to me to be an easier word
> for non-native speakers.
Bummer ;-)
--
Álvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Attachments:
[text/x-diff] glossfixes-1.patch (8.9K, 2-glossfixes-1.patch)
download | inline diff:
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
index 8c6cb6e942..b5155e1a85 100644
--- a/doc/src/sgml/glossary.sgml
+++ b/doc/src/sgml/glossary.sgml
@@ -48,7 +48,7 @@
<glossdef>
<para>
In reference to a <glossterm linkend="glossary-datum">datum</glossterm>:
- the fact that its value that cannot be broken down into smaller
+ the fact that its value cannot be broken down into smaller
components.
</para>
</glossdef>
@@ -270,14 +270,14 @@
<glossterm linkend="glossary-global-sql-object">global SQL objects</glossterm>. The
<firstterm>cluster</firstterm> is managed by exactly one
<glossterm linkend="glossary-instance">instance</glossterm>. A newly created
- Cluster will have three databases created automatically. They are
+ cluster will have three databases created automatically. They are
<literal>template0</literal>, <literal>template1</literal>, and
<literal>postgres</literal>. It is expected that an application will
create one or more additional database aside from these three.
</para>
<para>
(Don't confuse the <productname>PostgreSQL</productname>-specific term
- <glossterm linkend="glossary-cluster">Cluster</glossterm> with the SQL
+ <glossterm linkend="glossary-cluster">cluster</glossterm> with the SQL
command <command>CLUSTER</command>).
</para>
</glossdef>
@@ -363,7 +363,7 @@
<glossdef>
<para>
A restriction on the values of data allowed within a
- <glossterm linkend="glossary-table">Table</glossterm>.
+ <glossterm linkend="glossary-table">table</glossterm>.
</para>
<para>
For more information, see
@@ -424,7 +424,7 @@
<glossterm>Datum</glossterm>
<glossdef>
<para>
- The internal representation of one value of a <acronym>SQL</acronym>
+ The internal representation of one value of an <acronym>SQL</acronym>
data type.
</para>
</glossdef>
@@ -617,7 +617,7 @@
<glossdef>
<para>
Contains the values of <glossterm linkend="glossary-tuple">row</glossterm>
- attributes (i.e. the data) for a
+ attributes (i.e., the data) for a
<glossterm linkend="glossary-relation">relation</glossterm>.
The heap is realized within
<glossterm linkend="glossary-file-segment">segment files</glossterm>.
@@ -835,7 +835,7 @@
<glossdef>
<para>
A <glossterm linkend="glossary-relation">relation</glossterm> that is
- defined in the same way that a a <glossterm linkend="glossary-view">view</glossterm>
+ defined in the same way that a <glossterm linkend="glossary-view">view</glossterm>
is, 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
@@ -900,7 +900,7 @@
<para>
In reference to a
<glossterm linkend="glossary-partitioned-table">partitioned table</glossterm>:
- One of the tables that each contain part of the data of the partitioned table,
+ One of multiple tables that each contain part of the data of the partitioned table,
which is said to be the <firstterm>parent</firstterm>.
The partition is itself a table, so it can also be queried directly;
at the same time, a partition can sometimes be a partitioned table,
@@ -910,7 +910,7 @@
<glossdef>
<para>
In reference to a <glossterm linkend="glossary-window-function">window function</glossterm>:
- a partition is a user-defined criteria that identifies which neighboring
+ a partition is a user-defined criterion that identifies which neighboring
<glossterm linkend="glossary-tuple">rows</glossterm> can be considered by the
function.
</para>
@@ -1103,7 +1103,7 @@
<para>
A data structure transmitted from a
<glossterm linkend="glossary-backend">backend process</glossterm> to
- client program upon the completion of a <acronym>SQL</acronym>
+ client program 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>
@@ -1134,8 +1134,8 @@
<glossdef>
<para>
A collection of access privileges to the
- <glossterm linkend="glossary-database">instance</glossterm>.
- Roless are themselves a privilege that can be granted to other roles.
+ <glossterm linkend="glossary-instance">instance</glossterm>.
+ Roles are themselves a privilege that can be granted to other roles.
This is often done for convenience or to ensure completeness
when multiple <glossterm linkend="glossary-user">users</glossterm> need
the same privileges.
@@ -1151,7 +1151,7 @@
<glossterm>Rollback</glossterm>
<glossdef>
<para>
- A command to undo all of the operations performed since the beginning
+ A command to undo all operations performed since the beginning
of a <glossterm linkend="glossary-transaction">transaction</glossterm>.
</para>
<para>
@@ -1170,7 +1170,7 @@
<glossterm>Savepoint</glossterm>
<glossdef>
<para>
- A special mark inside the sequence of steps in a
+ A special mark in the sequence of steps in a
<glossterm linkend="glossary-transaction">transaction</glossterm>.
Data modifications after this point in time may be reverted
to the time of the savepoint.
@@ -1192,7 +1192,8 @@
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 unique.
+ 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>
@@ -1205,7 +1206,7 @@
</glossdef>
<glossdef>
<para>
- More generically, the term <firstterm>Schema</firstterm> is used to mean
+ More generically, the term <firstterm>schema</firstterm> is used to mean
all data descriptions (<glossterm linkend="glossary-table">table</glossterm> definitions,
<glossterm linkend="glossary-constraint">constraints</glossterm>, comments, etc)
for a given <glossterm linkend="glossary-database">database</glossterm> or
@@ -1356,7 +1357,7 @@
<glossterm linkend="glossary-procedure">procedure</glossterm>,
<glossterm linkend="glossary-trigger">trigger</glossterm>,
data type, or operator. Every one of those SQL objects
- belong to exactly one <glossterm linkend="glossary-schema">Schema</glossterm>.
+ belong to exactly one <glossterm linkend="glossary-schema">schema</glossterm>.
</para>
<para>
There also exist SQL objects that do not belong to schemas; those include
@@ -1386,7 +1387,7 @@
<glossdef>
<para>
This process collects statistical information about the
- <glossterm linkend="glossary-cluster">Cluster</glossterm>'s activities.
+ <glossterm linkend="glossary-cluster">cluster</glossterm>'s activities.
</para>
<para>
For more information, see
@@ -1431,7 +1432,7 @@
<glossterm linkend="glossary-attribute">attributes</glossterm>, in the same
order, having the same name and type per position).
A table is the most common form of
- <glossterm linkend="glossary-relation">Relation</glossterm> in
+ <glossterm linkend="glossary-relation">relation</glossterm> in
<productname>PostgreSQL</productname>.
</para>
<para>
@@ -1508,7 +1509,7 @@
<command>UPDATE</command>, <command>DELETE</command>,
<command>TRUNCATE</command>) is applied to a
<glossterm linkend="glossary-relation">relation</glossterm>.
- A Trigger executes within the same
+ A trigger executes within the same
<glossterm linkend="glossary-transaction">transaction</glossterm> as the
statement which invoked it, and if the function fails, then the invoking
statement also fails.
@@ -1620,8 +1621,8 @@
<glossdef>
<para>
The process of removing outdated <glossterm linkend="glossary-tuple">tuple
- versions</glossterm> from tables, and other closely related
- garbage-collection-like processing required by <productname>PostgreSQL</productname>'s
+ versions</glossterm> from tables, and other
+ processing required by <productname>PostgreSQL</productname>'s
implementation of <glossterm linkend="glossary-mvcc">MVCC</glossterm>.
This can be initiated through the use of
the <command>VACUUM</command> command, but can also be handled automatically
@@ -1678,7 +1679,7 @@
and are written in sequential order, interspersing changes
as they occur in multiple simultaneous sessions.
If the system crashes, the files are read in order, and each of the
- changes are replayed to restore the system to the state as it was
+ changes is replayed to restore the system to the state as it was
before the crash.
</para>
<para>
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-04-03 21:01 Justin Pryzby <[email protected]>
parent: Alvaro Herrera <[email protected]>
2 siblings, 2 replies; 97+ messages in thread
From: Justin Pryzby @ 2020-04-03 21:01 UTC (permalink / raw)
To: Alvaro Herrera <[email protected]>; +Cc: Erik Rijkers <[email protected]>; Corey Huinker <[email protected]>; Jürgen Purtz <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
On Fri, Apr 03, 2020 at 05:51:43PM -0300, Alvaro Herrera wrote:
> - The internal representation of one value of a <acronym>SQL</acronym>
> + The internal representation of one value of an <acronym>SQL</acronym>
I'm not sure about this one. The new glossary says "a SQL" seven times, and
doesn't say "an sql" at all.
"An SQL" does appear to be more common in the rest of the docs, but if you
change one, I think you'd change them all.
BTW it's now visible at:
https://www.postgresql.org/docs/devel/glossary.html
--
Justin
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-04-03 21:05 Erik Rijkers <[email protected]>
parent: Alvaro Herrera <[email protected]>
2 siblings, 0 replies; 97+ messages in thread
From: Erik Rijkers @ 2020-04-03 21:05 UTC (permalink / raw)
To: Alvaro Herrera <[email protected]>; +Cc: Justin Pryzby <[email protected]>; Corey Huinker <[email protected]>; Jürgen Purtz <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
On 2020-04-03 22:51, Alvaro Herrera wrote:
> On 2020-Apr-03, Erik Rijkers wrote:
>
>> On 2020-04-03 18:45, Alvaro Herrera wrote:
>> > Pushed now. Many thanks to Corey who put the main thrust, and to Jürgen
>> > and Roger for the great help, and to Justin for the extensive review and
>> > Fabien for the initial discussion.
>>
>> A few improvements:
>
> Thanks! That gives me the attached patch.
>
>> Should also be a lemmata in the glossary:
>>
>> ACID
>
> Agreed. Wording suggestions welcome.
How about:
"
ACID
Atomicity, consistency, isolation, and durability. ACID is a set of
properties of database transactions intended to guarantee validity even
in the event of power failures, etc.
ACID is concerned with how the database recovers from such failures that
might occur while processing a transaction.
"
>> 'archaic' should maybe be 'obsolete'. That seems to me to be an easier
>> word
>> for non-native speakers.
>
> Bummer ;-)
OK - we'll figure it out :)
> --
> Álvaro Herrera https://www.2ndQuadrant.com/
> PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-04-04 04:04 Laurenz Albe <[email protected]>
parent: Justin Pryzby <[email protected]>
1 sibling, 1 reply; 97+ messages in thread
From: Laurenz Albe @ 2020-04-04 04:04 UTC (permalink / raw)
To: Justin Pryzby <[email protected]>; Alvaro Herrera <[email protected]>; +Cc: Erik Rijkers <[email protected]>; Corey Huinker <[email protected]>; Jürgen Purtz <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
On Fri, 2020-04-03 at 16:01 -0500, Justin Pryzby wrote:
> BTW it's now visible at:
> https://www.postgresql.org/docs/devel/glossary.html
Great!
Some comments:
- SQL object: There are more kinds of objects, like roles or full text dictionaries.
Perhaps better:
Anything that is created with a CREATE statement, for example ...
Most objects belong to a database schema, except ...
Or do we consider a replication slot to be an object?
- The glossary has "Primary (server)", but not "Standby (server)".
That should be a synonym for "Replica".
- Server: is that really our definition?
I thought that "server" is what the glossary defines as "instance", and
the thing called "server" in the glossary should really be called "host".
Maybe I am too Unix-centered.
Many people I know use "instance" synonymous to "cluster".
- Role: I understand the motivation behind the definition (except that the word "instance"
is ill chosen), but a role is more than a collection of privileges.
How can a collection of privileges have a password or own an object?
Perhaps, instead of the first sentence:
A database object used for authentication, authorization and ownership.
Both database users and user groups are "roles" in PostgreSQL.
In the second sentence, "roles" is mis-spelled as "roless".
- Null
I think it should say "It represents the absence of *a definite* value."
Usually it is better to think of NULL as "unknown".
- Function
I don't know if "transformation of data" describes it well.
Quite a lot of functions in PostgreSQL have side effects.
How about:
Procedural code stored in the database that can be used in SQL statements.
Yours,
Laurenz Albe
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-04-04 06:55 Fabien COELHO <[email protected]>
parent: Justin Pryzby <[email protected]>
1 sibling, 1 reply; 97+ messages in thread
From: Fabien COELHO @ 2020-04-04 06:55 UTC (permalink / raw)
To: Justin Pryzby <[email protected]>; +Cc: Alvaro Herrera <[email protected]>; Erik Rijkers <[email protected]>; Corey Huinker <[email protected]>; =?ISO-8859-15?Q?J=FCrgen_Purtz?= <[email protected]>; Roger Harkavy <[email protected]>; [email protected], Michael Paquier <[email protected]>
> BTW it's now visible at:
> https://www.postgresql.org/docs/devel/glossary.html
Awesome! Linking beetween defs and to relevant sections is great.
BTW, I'm in favor of "an SQL" because I pronounce it "ess-kew-el", but I
guess that people who say "sequel" would prefer "a SQL". Failing that, I'm
fine with some heterogeneity, life is diverse!
ISTM that occurrences of these words elsewhere in the documentation should
link to the glossary definitions?
As the definitions are short and to the point, maybe the HTML display
could (also) "hover" the definitions when the mouse passes over the word,
using the "title" attribute?
"ACID" does not appear as an entry, nor in the acronyms sections. Also no
DCL, although DML & DDL are in acronyms.
Entries could link to relevant wikipedia pages, like the acronyms section
does?
--
Fabien.
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-04-04 12:30 Jürgen Purtz <[email protected]>
parent: Laurenz Albe <[email protected]>
0 siblings, 0 replies; 97+ messages in thread
From: Jürgen Purtz @ 2020-04-04 12:30 UTC (permalink / raw)
To: Laurenz Albe <[email protected]>; Justin Pryzby <[email protected]>; Alvaro Herrera <[email protected]>; +Cc: Erik Rijkers <[email protected]>; Corey Huinker <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
> - Server: is that really our definition?
> I thought that "server" is what the glossary defines as "instance", and
> the thing called "server" in the glossary should really be called "host".
>
> Maybe I am too Unix-centered.
>
> Many people I know use "instance" synonymous to "cluster".
Currently our documentation uses 'server', 'database server', 'host',
'instance', ... in an indifferent way. Similar problem with
database/cluster. Now we have the chance to come to a conclusion about
preferred terms an their exact meaning. Definitions in the glossary
shall be the guideline, the documentation itself can adopt these terms
over time.
Here is my point of view. We have distinguishable things:
(1) (virtual) hardware
(2) an abstract structure of several object types, which models a
management system for data
(3) a group of closely related processes. They implement the internal
'business logic' or 'work flow' of (2).
(4) abstract data, which fits into (2)
(5) a physical representation of (4). Mainly and long lasting on disc,
but - partly - mirrored in RAM.
(6) client processes, which connect to (3)
IMO for (1) the two terms 'server' and 'host' both have their
justification, depending on the context. There are historical terms
('server-side', 'foreign server', 'client/server architecture', 'host'
or 'host name' for IP-specification, 'host variable') which cannot be
changed. Therefor we shall accept both with identical definition and use
them as synonyms. Independent from this, there are many paragraphs in
the documentation, where they are used in a misleading sense ('server
crash', '... started the server', 'database server'). They should be
changed over time.
For me, (3) is an 'instance' and (5) is a 'cluster'. There is a 1:1
relation between the two, because one 'instance' controls exactly one
'cluster'. But the 'instance' consists of processes and memory whereas
the 'cluster' of databases which resides (mainly) on disc.
Concerning (6) we are not interested in any hardware-question. We are
only interested in the processes, which connect to backend processes. We
should only define the term "Client process".
Kind regards, Jürgen
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-04-04 16:52 Corey Huinker <[email protected]>
parent: Fabien COELHO <[email protected]>
0 siblings, 1 reply; 97+ messages in thread
From: Corey Huinker @ 2020-04-04 16:52 UTC (permalink / raw)
To: Fabien COELHO <[email protected]>; +Cc: Justin Pryzby <[email protected]>; Alvaro Herrera <[email protected]>; Erik Rijkers <[email protected]>; Jürgen Purtz <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Michael Paquier <[email protected]>
On Sat, Apr 4, 2020 at 2:55 AM Fabien COELHO <[email protected]> wrote:
>
> > BTW it's now visible at:
> > https://www.postgresql.org/docs/devel/glossary.html
Nice. I went looking for it yesterday and the docs hadn't rebuilt yet.
> ISTM that occurrences of these words elsewhere in the documentation should
> link to the glossary definitions?
>
Yes, that's a big project. I was considering writing a script to compile
all the terms as search terms, paired with their glossary ids, and then
invoke git grep to identify all pages that have term FOO but don't have
glossary-foo. We would then go about gloss-linking those pages as
appropriate, but only a few pages at a time to keep scope sane. Also, I'm
unclear about the circumstances under which we should _not_ tag a term. I
remember hearing that we should only tag it on the first usage, but is that
per section or per page?
> As the definitions are short and to the point, maybe the HTML display
> could (also) "hover" the definitions when the mouse passes over the word,
> using the "title" attribute?
>
I like that idea, if it doesn't conflict with accessibility standards
(maybe that's just titles on images, not sure).
I suspect we would want to just carry over the first sentence or so with a
... to avoid cluttering the screen with my overblown definition of a
sequence.
I suggest we pursue this idea in another thread, as we'd probably want to
do it for acronyms as well.
>
> "ACID" does not appear as an entry, nor in the acronyms sections. Also no
> DCL, although DML & DDL are in acronyms.
>
It needs to be in the acronyms page, and in light of all the docbook
wizardry that I've learned from Alvaro, those should probably get their own
acronym-foo ids as well. The cutoff date for 13 fast approaches, so it
might be for 14+ unless doc-only patches are treated differently.
> Entries could link to relevant wikipedia pages, like the acronyms section
> does?
>
They could. I opted not to do that because each external link invites
debate about how authoritative that link is, which is easier to do with
acronyms. Now that the glossary is a reality, it's easier to have those
discussions.
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-04-05 07:38 Fabien COELHO <[email protected]>
parent: Corey Huinker <[email protected]>
0 siblings, 1 reply; 97+ messages in thread
From: Fabien COELHO @ 2020-04-05 07:38 UTC (permalink / raw)
To: Corey Huinker <[email protected]>; +Cc: Justin Pryzby <[email protected]>; Alvaro Herrera <[email protected]>; Erik Rijkers <[email protected]>; =?ISO-8859-15?Q?J=FCrgen_Purtz?= <[email protected]>; Roger Harkavy <[email protected]>; [email protected], Michael Paquier <[email protected]>
Hi Corey,
>> ISTM that occurrences of these words elsewhere in the documentation should
>> link to the glossary definitions?
>
> Yes, that's a big project. I was considering writing a script to compile
> all the terms as search terms, paired with their glossary ids, and then
> invoke git grep to identify all pages that have term FOO but don't have
> glossary-foo. We would then go about gloss-linking those pages as
> appropriate, but only a few pages at a time to keep scope sane.
Id go for scripting the thing.
Should the glossary be backpatched, to possibly ease doc patchpatches?
> Also, I'm unclear about the circumstances under which we should _not_
> tag a term.
At least when then are explained locally.
> I remember hearing that we should only tag it on the first usage, but is
> that per section or per page?
Page?
>> As the definitions are short and to the point, maybe the HTML display
>> could (also) "hover" the definitions when the mouse passes over the word,
>> using the "title" attribute?
>
> I like that idea, if it doesn't conflict with accessibility standards
> (maybe that's just titles on images, not sure).
The following worked fine:
<html><head><title>Title Tag Test</title></head>
<body>The <a href="acid.html" title="ACID stands for Atomic, Consistent, Isolated & Durable">ACID</a>
property is great.
</body></html>
So basically the def can be put on the glossary link, however retrieving
the definition should be automatic.
> I suspect we would want to just carry over the first sentence or so with a
> ... to avoid cluttering the screen with my overblown definition of a
> sequence.
Dunno. The definitions are quite short, maybe the can fit whole.
> I suggest we pursue this idea in another thread, as we'd probably want to
> do it for acronyms as well.
Or not. I'd test committer temperature before investing time because it
would mean that backpatching the doc would be a little harder.
>> Entries could link to relevant wikipedia pages, like the acronyms section
>> does?
>
> They could. I opted not to do that because each external link invites
> debate about how authoritative that link is, which is easier to do with
> acronyms. Now that the glossary is a reality, it's easier to have those
> discussions.
Ok.
--
Fabien.
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-04-05 08:41 Jürgen Purtz <[email protected]>
parent: Alvaro Herrera <[email protected]>
2 siblings, 1 reply; 97+ messages in thread
From: Jürgen Purtz @ 2020-04-05 08:41 UTC (permalink / raw)
To: Alvaro Herrera <[email protected]>; +Cc: Erik Rijkers <[email protected]>; Justin Pryzby <[email protected]>; Corey Huinker <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
a) Some rearrangements of the sequence of terms to meet alphabetical order.
b) <glossterm id="linkend-xxx"> --> <glossterm linkend="glossary-xxx">
in two cases. Or should it be a <firstterm>?
Kind regards, Jürgen
Attachments:
[text/x-patch] glossfixes-2.patch (3.5K, 2-glossfixes-2.patch)
download | inline diff:
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
index 8c6cb6e942..25762b7c3a 100644
--- a/doc/src/sgml/glossary.sgml
+++ b/doc/src/sgml/glossary.sgml
@@ -208,15 +208,6 @@
</glossdef>
</glossentry>
- <glossentry id="glossary-checkpointer">
- <glossterm>Checkpointer (process)</glossterm>
- <glossdef>
- <para>
- A specialized process responsible for executing checkpoints.
- </para>
- </glossdef>
- </glossentry>
-
<glossentry id="glossary-checkpoint">
<glossterm>Checkpoint</glossterm>
<glossdef>
@@ -244,6 +235,15 @@
</glossdef>
</glossentry>
+ <glossentry id="glossary-checkpointer">
+ <glossterm>Checkpointer (process)</glossterm>
+ <glossdef>
+ <para>
+ A specialized process responsible for executing checkpoints.
+ </para>
+ </glossdef>
+ </glossentry>
+
<glossentry>
<glossterm>Class (archaic)</glossterm>
<glosssee otherterm="glossary-relation" />
@@ -761,25 +761,6 @@
</glossdef>
</glossentry>
- <glossentry id="glossary-logger">
- <glossterm>Logger (process)</glossterm>
- <glossdef>
- <para>
- If activated, the
- <glossterm linkend="glossary-logger">Logger</glossterm> process
- writes information about database events into the current
- <glossterm linkend="glossary-log-file">log file</glossterm>.
- When reaching certain time- or
- volume-dependent criteria, a new log file is created.
- Also called <firstterm>syslogger</firstterm>.
- </para>
- <para>
- For more information, see
- <xref linkend="runtime-config-logging"/>.
- </para>
- </glossdef>
- </glossentry>
-
<glossentry id="glossary-log-record">
<glossterm>Log Record</glossterm>
<glossdef>
@@ -803,6 +784,25 @@
</glossdef>
</glossentry>
+ <glossentry id="glossary-logger">
+ <glossterm>Logger (process)</glossterm>
+ <glossdef>
+ <para>
+ If activated, the
+ <glossterm linkend="glossary-logger">Logger</glossterm> process
+ writes information about database events into the current
+ <glossterm linkend="glossary-log-file">log file</glossterm>.
+ When reaching certain time- or
+ volume-dependent criteria, a new log file is created.
+ Also called <firstterm>syslogger</firstterm>.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="runtime-config-logging"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
<glossentry>
<glossterm>Master (server)</glossterm>
<glosssee otherterm="glossary-primary-server" />
@@ -1651,6 +1651,11 @@
</glossdef>
</glossentry>
+ <glossentry>
+ <glossterm>WAL</glossterm>
+ <glosssee otherterm="glossary-wal" />
+ </glossentry>
+
<glossentry id="glossary-wal-archiver">
<glossterm>WAL Archiver (process)</glossterm>
<glossdef>
@@ -1696,11 +1701,6 @@
</glossdef>
</glossentry>
- <glossentry>
- <glossterm>WAL</glossterm>
- <glosssee otherterm="glossary-wal" />
- </glossentry>
-
<glossentry id="glossary-wal-record">
<glossterm>WAL Record</glossterm>
<glossdef>
@@ -1728,8 +1728,8 @@
<glossdef>
<para>
A process that writes <glossterm linkend="glossary-wal-record">WAL records</glossterm>
- from <glossterm id="linkend-shared-memory">shared memory</glossterm> to
- <glossterm id="linkend-wal-file">WAL files</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
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-04-05 19:00 Alvaro Herrera <[email protected]>
parent: Jürgen Purtz <[email protected]>
0 siblings, 1 reply; 97+ messages in thread
From: Alvaro Herrera @ 2020-04-05 19:00 UTC (permalink / raw)
To: Jürgen Purtz <[email protected]>; +Cc: Erik Rijkers <[email protected]>; Justin Pryzby <[email protected]>; Corey Huinker <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
On 2020-Apr-05, Jürgen Purtz wrote:
> a) Some rearrangements of the sequence of terms to meet alphabetical order.
Thanks, will get this pushed.
> b) <glossterm id="linkend-xxx"> --> <glossterm linkend="glossary-xxx"> in
> two cases. Or should it be a <firstterm>?
Ah, yeah, those should be linkend.
--
Álvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-04-05 22:07 Alvaro Herrera <[email protected]>
parent: Fabien COELHO <[email protected]>
0 siblings, 0 replies; 97+ messages in thread
From: Alvaro Herrera @ 2020-04-05 22:07 UTC (permalink / raw)
To: Fabien COELHO <[email protected]>; +Cc: Corey Huinker <[email protected]>; Justin Pryzby <[email protected]>; Erik Rijkers <[email protected]>; Jürgen Purtz <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Michael Paquier <[email protected]>
On 2020-Apr-05, Fabien COELHO wrote:
> > > As the definitions are short and to the point, maybe the HTML display
> > > could (also) "hover" the definitions when the mouse passes over the word,
> > > using the "title" attribute?
> >
> > I like that idea, if it doesn't conflict with accessibility standards
> > (maybe that's just titles on images, not sure).
>
> The following worked fine:
>
> <html><head><title>Title Tag Test</title></head>
> <body>The <a href="acid.html" title="ACID stands for Atomic, Consistent, Isolated & Durable">ACID</a>
> property is great.
> </body></html>
I don't see myself patching the stylesheet as would be needed to do
this.
> > I suggest we pursue this idea in another thread, as we'd probably want to
> > do it for acronyms as well.
>
> Or not. I'd test committer temperature before investing time because it
> would mean that backpatching the doc would be a little harder.
TBH I can't get very excited about this idea. Maybe other documentation
champions would be happier about doing that.
--
Álvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-04-11 12:10 Jürgen Purtz <[email protected]>
parent: Alvaro Herrera <[email protected]>
0 siblings, 1 reply; 97+ messages in thread
From: Jürgen Purtz @ 2020-04-11 12:10 UTC (permalink / raw)
To: Alvaro Herrera <[email protected]>; +Cc: Erik Rijkers <[email protected]>; Justin Pryzby <[email protected]>; Corey Huinker <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
> On 2020-Apr-05, Jürgen Purtz wrote:
>
>> a) Some rearrangements of the sequence of terms to meet alphabetical order.
> Thanks, will get this pushed.
>
>> b) <glossterm id="linkend-xxx"> --> <glossterm linkend="glossary-xxx"> in
>> two cases. Or should it be a <firstterm>?
> Ah, yeah, those should be linkend.
>
Term 'relation': A sequence is internally a table with one row - right?
Shall we extend the list of concrete relations by 'sequence'? Or is this
not necessary because 'table' is already there?
Kind regards, Jürgen
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-04-11 19:47 Corey Huinker <[email protected]>
parent: Jürgen Purtz <[email protected]>
0 siblings, 1 reply; 97+ messages in thread
From: Corey Huinker @ 2020-04-11 19:47 UTC (permalink / raw)
To: Jürgen Purtz <[email protected]>; +Cc: Alvaro Herrera <[email protected]>; Erik Rijkers <[email protected]>; Justin Pryzby <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
>
>
> Term 'relation': A sequence is internally a table with one row - right?
> Shall we extend the list of concrete relations by 'sequence'? Or is this
> not necessary because 'table' is already there?
>
I wrote one for sequence, it was a bit math-y for Alvaro's taste, so we're
going to try again.
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-04-12 07:36 Jürgen Purtz <[email protected]>
parent: Corey Huinker <[email protected]>
0 siblings, 0 replies; 97+ messages in thread
From: Jürgen Purtz @ 2020-04-12 07:36 UTC (permalink / raw)
To: Corey Huinker <[email protected]>; +Cc: Alvaro Herrera <[email protected]>; Erik Rijkers <[email protected]>; Justin Pryzby <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Fabien COELHO <[email protected]>; Michael Paquier <[email protected]>
On 11.04.20 21:47, Corey Huinker wrote:
>
>
> Term 'relation': A sequence is internally a table with one row -
> right?
> Shall we extend the list of concrete relations by 'sequence'? Or
> is this
> not necessary because 'table' is already there?
>
>
> I wrote one for sequence, it was a bit math-y for Alvaro's taste, so
> we're going to try again.
>
This seems to be a misunderstanding. My question was whether we shall
extend the definition of Relation to: "... Tables, views, foreign
tables, materialized views, indexes, and *sequences* are all relations."
Kind regards, Jürgen
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-04-29 19:15 Peter Eisentraut <[email protected]>
parent: Corey Huinker <[email protected]>
2 siblings, 1 reply; 97+ messages in thread
From: Peter Eisentraut @ 2020-04-29 19:15 UTC (permalink / raw)
To: Corey Huinker <[email protected]>; [email protected]
Why are all the glossary terms capitalized? Seems kind of strange.
--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-04-29 19:55 Corey Huinker <[email protected]>
parent: Peter Eisentraut <[email protected]>
0 siblings, 1 reply; 97+ messages in thread
From: Corey Huinker @ 2020-04-29 19:55 UTC (permalink / raw)
To: Peter Eisentraut <[email protected]>; +Cc: [email protected]
On Wed, Apr 29, 2020 at 3:15 PM Peter Eisentraut <
[email protected]> wrote:
> Why are all the glossary terms capitalized? Seems kind of strange.
>
>
They weren't intended to be, and they don't appear to be in the page I'm
looking at. Are you referring to the anchor like in
https://www.postgresql.org/docs/devel/glossary.html#GLOSSARY-RELATION ? If
so, that all-capping is part of the rendering, as the ids were all named in
all-lower-case.
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-05-15 00:00 Alvaro Herrera <[email protected]>
parent: Erik Rijkers <[email protected]>
1 sibling, 2 replies; 97+ messages in thread
From: Alvaro Herrera @ 2020-05-15 00:00 UTC (permalink / raw)
To: Erik Rijkers <[email protected]>; Laurenz Albe <[email protected]>; Fabien COELHO <[email protected]>; Jürgen Purtz <[email protected]>; Peter Eisentraut <[email protected]>; Corey Huinker <[email protected]>; +Cc: Justin Pryzby <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Michael Paquier <[email protected]>
Thanks everybody. I have compiled together all the suggestions and the
result is in the attached patch. Some of it is of my own devising.
* I changed "instance", and made "cluster" be mostly a synonym of that.
* I removed "global SQL object" and made "SQL object" explain it.
* Added definitions for ACID, sequence, bloat, fork, FSM, VM, data page,
transaction ID, epoch.
* Changed "a SQL" to "an sql" everywhere.
* Sorted alphabetically.
* Removed caps in term names.
I think I should get this pushed, and if there are further suggestions,
they're welcome.
Dim Fontaine and others suggested a number of terms that could be
included; see https://twitter.com/alvherre/status/1246192786287865856
--
Álvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Attachments:
[text/x-diff] glossfixes-2.patch (39.4K, 2-glossfixes-2.patch)
download | inline diff:
diff --git a/doc/src/sgml/acronyms.sgml b/doc/src/sgml/acronyms.sgml
index f638665dc9..b05c065546 100644
--- a/doc/src/sgml/acronyms.sgml
+++ b/doc/src/sgml/acronyms.sgml
@@ -766,7 +766,7 @@
<term><acronym>XID</acronym></term>
<listitem>
<para>
- <link linkend="datatype-oid">Transaction Identifier</link>
+ <glossterm linkend="glossary-xid">Transaction identifier</glossterm>
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
index 8c6cb6e942..d4255215aa 100644
--- a/doc/src/sgml/glossary.sgml
+++ b/doc/src/sgml/glossary.sgml
@@ -7,8 +7,22 @@
</para>
<glosslist>
+ <glossentry id="glossary-acid">
+ <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.
+ </para>
+ </glossdef>
+ </glossentry>
+
<glossentry id="glossary-aggregate">
- <glossterm>Aggregate Function</glossterm>
+ <glossterm>Aggregate function</glossterm>
<glossdef>
<para>
A <glossterm linkend="glossary-function">function</glossterm> that
@@ -35,11 +49,15 @@
to make decisions about how to execute
<glossterm linkend="glossary-query">queries</glossterm>.
</para>
+ <para>
+ (Don't confuse this term with the <literal>ANALYZE</literal> option
+ to the <xref linkend="sql-explain"/> command.)
+ </para>
</glossdef>
</glossentry>
<glossentry>
- <glossterm>Analytic Function</glossterm>
+ <glossterm>Analytic function</glossterm>
<glosssee otherterm="glossary-window-function" />
</glossentry>
@@ -106,8 +124,8 @@
<glossdef>
<para>
Process of an <glossterm linkend="glossary-instance">instance</glossterm>
- which act on behalf of <glossterm linkend="glossary-session">client sessions</glossterm>
- and handle their requests.
+ which acts on behalf of a <glossterm linkend="glossary-session">client session</glossterm>
+ and handles its requests.
</para>
<para>
(Don't confuse this term with the similar terms
@@ -118,7 +136,7 @@
</glossentry>
<glossentry id="glossary-background-worker">
- <glossterm>Background Worker (process)</glossterm>
+ <glossterm>Background worker (process)</glossterm>
<glossdef>
<para>
Process within an <glossterm linkend="glossary-instance">instance</glossterm>,
@@ -138,10 +156,11 @@
</glossentry>
<glossentry id="glossary-background-writer">
- <glossterm>Background Writer (process)</glossterm>
+ <glossterm>Background writer (process)</glossterm>
<glossdef>
<para>
- A process that continuously writes dirty pages from
+ A process that continuously writes dirty
+ <glossterm linkend="glossary-data-page">data pages</glossterm> from
<glossterm linkend="glossary-shared-memory">shared memory</glossterm> to
the file system. It wakes up periodically, but works only for a short
period in order to distribute its expensive <acronym>I/O</acronym>
@@ -155,6 +174,16 @@
</glossdef>
</glossentry>
+ <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.
+ </para>
+ </glossdef>
+ </glossentry>
+
<glossentry id="glossary-cast">
<glossterm>Cast</glossterm>
<glossdef>
@@ -190,7 +219,7 @@
</glossentry>
<glossentry id="glossary-check-constraint">
- <glossterm>Check Constraint</glossterm>
+ <glossterm>Check constraint</glossterm>
<glossdef>
<para>
A type of <glossterm linkend="glossary-constraint">constraint</glossterm>
@@ -208,15 +237,6 @@
</glossdef>
</glossentry>
- <glossentry id="glossary-checkpointer">
- <glossterm>Checkpointer (process)</glossterm>
- <glossdef>
- <para>
- A specialized process responsible for executing checkpoints.
- </para>
- </glossdef>
- </glossentry>
-
<glossentry id="glossary-checkpoint">
<glossterm>Checkpoint</glossterm>
<glossdef>
@@ -244,6 +264,15 @@
</glossdef>
</glossentry>
+ <glossentry id="glossary-checkpointer">
+ <glossterm>Checkpointer (process)</glossterm>
+ <glossdef>
+ <para>
+ A specialized process responsible for executing checkpoints.
+ </para>
+ </glossdef>
+ </glossentry>
+
<glossentry>
<glossterm>Class (archaic)</glossterm>
<glosssee otherterm="glossary-relation" />
@@ -262,27 +291,6 @@
</glossdef>
</glossentry>
- <glossentry id="glossary-cluster">
- <glossterm>Cluster</glossterm>
- <glossdef>
- <para>
- A group of <glossterm linkend="glossary-database">databases</glossterm> plus their
- <glossterm linkend="glossary-global-sql-object">global SQL objects</glossterm>. The
- <firstterm>cluster</firstterm> is managed by exactly one
- <glossterm linkend="glossary-instance">instance</glossterm>. A newly created
- Cluster will have three databases created automatically. They are
- <literal>template0</literal>, <literal>template1</literal>, and
- <literal>postgres</literal>. It is expected that an application will
- create one or more additional database aside from these three.
- </para>
- <para>
- (Don't confuse the <productname>PostgreSQL</productname>-specific term
- <glossterm linkend="glossary-cluster">Cluster</glossterm> with the SQL
- command <command>CLUSTER</command>).
- </para>
- </glossdef>
- </glossentry>
-
<glossentry id="glossary-column">
<glossterm>Column</glossterm>
<glossdef>
@@ -363,7 +371,10 @@
<glossdef>
<para>
A restriction on the values of data allowed within a
- <glossterm linkend="glossary-table">Table</glossterm>.
+ <glossterm linkend="glossary-table">table</glossterm>,
+ or in attributes of a
+ <!-- XXX Should have term "domain". Need term "type" for that. -->
+ <firstterm>domain</firstterm>.
</para>
<para>
For more information, see
@@ -373,18 +384,18 @@
</glossentry>
<glossentry>
- <glossterm>Data Area</glossterm>
+ <glossterm>Data area</glossterm>
<glosssee otherterm="glossary-data-directory" />
</glossentry>
<glossentry id="glossary-data-directory">
- <glossterm>Data Directory</glossterm>
+ <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-cluster">cluster</glossterm> with the
+ <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
@@ -416,15 +427,31 @@
</glossentry>
<glossentry>
- <glossterm>Database Server</glossterm>
+ <glossterm>Database server</glossterm>
<glosssee otherterm="glossary-instance" />
</glossentry>
+ <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
+ to disk. New pages, which initially exist in memory only, are also
+ dirty until written.
+ </para>
+ </glossdef>
+ </glossentry>
+
<glossentry id="glossary-datum">
<glossterm>Datum</glossterm>
<glossdef>
<para>
- The internal representation of one value of a <acronym>SQL</acronym>
+ The internal representation of one value of an <acronym>SQL</acronym>
data type.
</para>
</glossdef>
@@ -434,7 +461,7 @@
<glossterm>Delete</glossterm>
<glossdef>
<para>
- A <acronym>SQL</acronym> command which removes
+ An <acronym>SQL</acronym> command which removes
<glossterm linkend="glossary-tuple">rows</glossterm> from a given
<glossterm linkend="glossary-table">table</glossterm>
or <glossterm linkend="glossary-relation">relation</glossterm>.
@@ -459,6 +486,11 @@
</glossdef>
</glossentry>
+ <glossentry>
+ <glossterm>Epoch</glossterm>
+ <glosssee otherterm="glossary-xid" />
+ </glossentry>
+
<glossentry id="glossary-extension">
<glossterm>Extension</glossterm>
<glossdef>
@@ -475,12 +507,13 @@
</glossentry>
<glossentry id="glossary-file-segment">
- <glossterm>File Segment</glossterm>
+ <glossterm>File segment</glossterm>
<glossdef>
<para>
A physical file which stores data for a given
<glossterm linkend="glossary-relation">relation</glossterm>.
- File segments are limited in size by a configuration value,
+ File segments are limited in size by a configuration value
+ (typically 1 gigabyte),
so if a relation exceeds that size, it is split into multiple segments.
</para>
<para>
@@ -495,14 +528,14 @@
</glossentry>
<glossentry id="glossary-foreign-data-wrapper">
- <glossterm>Foreign Data Wrapper</glossterm>
+ <glossterm>Foreign data wrapper</glossterm>
<glossdef>
<para>
A means of representing data that is not contained in the local
<glossterm linkend="glossary-database">database</glossterm> so that it appears as if were in local
- <glossterm linkend="glossary-table">table(s)</glossterm>. With a Foreign Data Wrapper it is
+ <glossterm linkend="glossary-table">table(s)</glossterm>. With a foreign data wrapper it is
possible to define a <glossterm linkend="glossary-foreign-server">foreign server</glossterm> and
- <glossterm linkend="glossary-foreign-table">foreign table</glossterm>s.
+ <glossterm linkend="glossary-foreign-table">foreign tables</glossterm>.
</para>
<para>
For more information, see
@@ -512,7 +545,7 @@
</glossentry>
<glossentry id="glossary-foreign-key">
- <glossterm>Foreign Key</glossterm>
+ <glossterm>Foreign key</glossterm>
<glossdef>
<para>
A type of <glossterm linkend="glossary-constraint">constraint</glossterm>
@@ -527,7 +560,7 @@
</glossentry>
<glossentry id="glossary-foreign-server">
- <glossterm>Foreign Server</glossterm>
+ <glossterm>Foreign server</glossterm>
<glossdef>
<para>
A named collection of
@@ -544,7 +577,7 @@
</glossentry>
<glossentry id="glossary-foreign-table">
- <glossterm>Foreign Table</glossterm>
+ <glossterm>Foreign table</glossterm>
<glossdef>
<para>
A <glossterm linkend="glossary-relation">relation</glossterm> which appears to have
@@ -564,6 +597,35 @@
</glossdef>
</glossentry>
+ <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
+ forks: the <glossterm linkend="glossary-fsm">free space map</glossterm>
+ <glossterm linkend="glossary-vm">visibility map</glossterm>.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <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. The free space map entry for each space stores the
+ 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.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="storage-fsm"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
<glossentry id="glossary-function">
<glossterm>Function</glossterm>
<glossdef>
@@ -579,28 +641,11 @@
</glossdef>
</glossentry>
- <glossentry id="glossary-global-sql-object">
- <glossterm>Global SQL Object</glossterm>
- <glossdef>
- <para>
- <glossterm linkend="glossary-sql-object">SQL objects</glossterm> which do
- not belong to a specific
- <glossterm linkend="glossary-database">database</glossterm>.
- </para>
- <para>
- These objects are
- <glossterm linkend="glossary-role">roles</glossterm>,
- <glossterm linkend="glossary-tablespace">tablespaces</glossterm>,
- replication origins, and subscriptions for logical replication.
- </para>
- </glossdef>
- </glossentry>
-
<glossentry id="glossary-grant">
<glossterm>Grant</glossterm>
<glossdef>
<para>
- A <acronym>SQL</acronym> command that is used to allow
+ An <acronym>SQL</acronym> command that is used to allow
<glossterm linkend="glossary-user">users</glossterm> or
<glossterm linkend="glossary-role">role</glossterm> to access
specific objects within the <glossterm linkend="glossary-database">database</glossterm>.
@@ -620,7 +665,8 @@
attributes (i.e. the data) for a
<glossterm linkend="glossary-relation">relation</glossterm>.
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>.
</para>
</glossdef>
</glossentry>
@@ -629,10 +675,11 @@
<glossterm>Host</glossterm>
<glossdef>
<para>
- A computer that communicates with other hosts over a network.
- This term can be used to refer to either a
- <glossterm linkend="glossary-client">client</glossterm>
- or a <glossterm linkend="glossary-server">server</glossterm>.
+ A computer that communicates with other computers over a network.
+ This is sometimes used as a synonym for
+ <glossterm linkend="glossary-server">server</glossterm>.
+ It is also used to refer to a computer where
+ <glossterm linkend="glossary-client">client processes</glossterm> run.
</para>
</glossdef>
</glossentry>
@@ -659,7 +706,7 @@
<glossterm>Insert</glossterm>
<glossdef>
<para>
- A <acronym>SQL</acronym> command used to add new data into a
+ An <acronym>SQL</acronym> command used to add new data into a
<glossterm linkend="glossary-table">table</glossterm>.
</para>
<para>
@@ -673,27 +720,28 @@
<glossterm>Instance</glossterm>
<glossdef>
<para>
- An <glossterm>instance</glossterm> is a group of processes,
- its supporting <glossterm linkend="glossary-data-directory">storage space</glossterm>,
- plus their
- common <glossterm linkend="glossary-shared-memory">shared memory</glossterm>,
- running on a single <glossterm linkend="glossary-server">server</glossterm>.
- The <glossterm linkend="glossary-instance">instance</glossterm>
- handles all key features of a <acronym>DBMS</acronym>: read and write
- access to files and shared memory, assurance of
- the <acronym>ACID</acronym> paradigm, <acronym>MVCC</acronym>,
- <glossterm linkend="glossary-connection">connections</glossterm> to client programs, backup,
- recovery, replication, privileges, etc.
+ 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
+ <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
+ <glossterm linkend="glossary-server">server</glossterm>
+ as long as their <acronym>TCP</acronym> ports do not conflict.
</para>
<para>
- An <glossterm>instance</glossterm> manages exactly one
- <glossterm linkend="glossary-cluster">cluster</glossterm>.
+ 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,
+ backup, recovery, replication, privileges, etc.
</para>
<para>
- Many <glossterm>instances</glossterm> can run on the same server as
- long as their <acronym>TCP/IP</acronym> ports do not conflict.
- Different instances on a server may use the
- same or different versions of <productname>PostgreSQL</productname>.
+ 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>
@@ -717,7 +765,7 @@
<glossterm>Join</glossterm>
<glossdef>
<para>
- A <acronym>SQL</acronym> keyword used in <command>SELECT</command> statements for
+ An <acronym>SQL</acronym> keyword used in <command>SELECT</command> statements for
combining data from multiple <glossterm linkend="glossary-relation">relations</glossterm>.
</para>
</glossdef>
@@ -748,7 +796,7 @@
</glossentry>
<glossentry id="glossary-log-file">
- <glossterm>Log File</glossterm>
+ <glossterm>Log file</glossterm>
<glossdef>
<para>
Log files contain human-readable text lines about events.
@@ -761,6 +809,29 @@
</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>
+ <para>
+ A <glossterm linkend="glossary-table">table</glossterm> is considered
+ <glossterm linkend="glossary-logged">logged</glossterm> if changes to it are sent to the
+ <glossterm linkend="glossary-wal">WAL</glossterm>. By default, all regular
+ tables are logged. A table can be specified as
+ <glossterm linkend="glossary-unlogged">unlogged</glossterm> either at
+ creation time or via the <command>ALTER TABLE</command> command.
+ </para>
+ </glossdef>
+ </glossentry>
+
<glossentry id="glossary-logger">
<glossterm>Logger (process)</glossterm>
<glossdef>
@@ -780,29 +851,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>
- <para>
- A <glossterm linkend="glossary-table">table</glossterm> is considered
- <glossterm linkend="glossary-logged">logged</glossterm> if changes to it are sent to the
- <glossterm linkend="glossary-wal">WAL</glossterm>. By default, all regular
- tables are logged. A table can be specified as
- <glossterm linkend="glossary-unlogged">unlogged</glossterm> either at
- creation time or via the <command>ALTER TABLE</command> command.
- </para>
- </glossdef>
- </glossentry>
-
<glossentry>
<glossterm>Master (server)</glossterm>
<glosssee otherterm="glossary-primary-server" />
@@ -831,7 +879,7 @@
</glossentry>
<glossentry id="glossary-materialized-view">
- <glossterm>Materialized View</glossterm>
+ <glossterm>Materialized view</glossterm>
<glossdef>
<para>
A <glossterm linkend="glossary-relation">relation</glossterm> that is
@@ -869,8 +917,8 @@
<glossterm>Null</glossterm>
<glossdef>
<para>
- A concept of non-existence that is a central tenet of Relational
- Database Theory. It represents the absence of value.
+ A concept of non-existence that is a central tenet of relational
+ database theory. It represents the absence of a definite value.
</para>
</glossdef>
</glossentry>
@@ -881,7 +929,7 @@
</glossentry>
<glossentry id="glossary-parallel-query">
- <glossterm>Parallel Query</glossterm>
+ <glossterm>Parallel query</glossterm>
<glossdef>
<para>
The ability to handle parts of executing a
@@ -918,7 +966,7 @@
</glossentry>
<glossentry id="glossary-partitioned-table">
- <glossterm>Partitioned Table</glossterm>
+ <glossterm>Partitioned table</glossterm>
<glossdef>
<para>
A <glossterm linkend="glossary-relation">relation</glossterm> that is
@@ -960,7 +1008,7 @@
</glossentry>
<glossentry id="glossary-primary-key">
- <glossterm>Primary Key</glossterm>
+ <glossterm>Primary key</glossterm>
<glossdef>
<para>
A special case of a
@@ -1011,7 +1059,7 @@
</glossentry>
<glossentry id="glossary-planner">
- <glossterm>Query Planner</glossterm>
+ <glossterm>Query planner</glossterm>
<glossdef>
<para>
The part of <productname>PostgreSQL</productname> that is devoted to
@@ -1034,7 +1082,7 @@
</glossentry>
<glossentry id="glossary-referential-integrity">
- <glossterm>Referential Integrity</glossterm>
+ <glossterm>Referential integrity</glossterm>
<glossdef>
<para>
A means of restricting data in one <glossterm linkend="glossary-relation">relation</glossterm>
@@ -1055,6 +1103,7 @@
<glossterm linkend="glossary-attribute">attributes</glossterm>
defined in a specific order.
<glossterm linkend="glossary-table">Tables</glossterm>,
+ <glossterm linkend="glossary-sequence">sequences</glossterm>,
<glossterm linkend="glossary-view">views</glossterm>,
<glossterm linkend="glossary-foreign-table">foreign tables</glossterm>,
<glossterm linkend="glossary-materialized-view">materialized views</glossterm>, and
@@ -1068,7 +1117,7 @@
</glossentry>
<glossentry id="glossary-replica">
- <glossterm>Replica</glossterm>
+ <glossterm>Replica (server)</glossterm>
<glossdef>
<para>
A <glossterm linkend="glossary-database">database</glossterm> that is paired
@@ -1098,12 +1147,13 @@
</glossentry>
<glossentry id="glossary-result-set">
- <glossterm>Result Set</glossterm>
+ <glossterm>Result set</glossterm>
<glossdef>
<para>
A data structure transmitted from a
<glossterm linkend="glossary-backend">backend process</glossterm> to
- client program upon the completion of a <acronym>SQL</acronym>
+ 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>
@@ -1135,7 +1185,7 @@
<para>
A collection of access privileges to the
<glossterm linkend="glossary-database">instance</glossterm>.
- Roless are themselves a privilege that can be granted to other roles.
+ Roles are themselves a privilege that can be granted to other roles.
This is often done for convenience or to ensure completeness
when multiple <glossterm linkend="glossary-user">users</glossterm> need
the same privileges.
@@ -1170,7 +1220,7 @@
<glossterm>Savepoint</glossterm>
<glossdef>
<para>
- A special mark inside the sequence of steps in a
+ A special mark in the sequence of steps in a
<glossterm linkend="glossary-transaction">transaction</glossterm>.
Data modifications after this point in time may be reverted
to the time of the savepoint.
@@ -1186,13 +1236,15 @@
<glossterm>Schema</glossterm>
<glossdef>
<para>
- A schema is a namespace for <glossterm linkend="glossary-sql-object">SQL objects</glossterm>,
+ A schema is a namespace for
+ <glossterm linkend="glossary-sql-object">SQL objects</glossterm>,
which all reside in the same
<glossterm linkend="glossary-database">database</glossterm>. 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 unique.
+ 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>
@@ -1205,7 +1257,7 @@
</glossdef>
<glossdef>
<para>
- More generically, the term <firstterm>Schema</firstterm> is used to mean
+ More generically, the term <firstterm>schema</firstterm> is used to mean
all data descriptions (<glossterm linkend="glossary-table">table</glossterm> definitions,
<glossterm linkend="glossary-constraint">constraints</glossterm>, comments, etc)
for a given <glossterm linkend="glossary-database">database</glossterm> or
@@ -1264,7 +1316,10 @@
A computer on which <productname>PostgreSQL</productname>
<glossterm linkend="glossary-instance">instances</glossterm> run.
The term <firstterm>server</firstterm> denotes real hardware, a
- container, or a Virtual Machine.
+ container, or a <firstterm>virtual machine</firstterm>.
+ </para>
+ <para>
+ This term is sometimes used to refer to an instance or to a host.
</para>
</glossdef>
</glossentry>
@@ -1279,45 +1334,21 @@
</glossdef>
</glossentry>
-<!-- XXX we should have a much more concise definition
<glossentry id="glossary-sequence">
<glossterm>Sequence</glossterm>
<glossdef>
<para>
- A <glossterm linkend="glossary-database">Database</glossterm> object which
- represents the mathematical concept of a numerical integral sequence.
- It can be thought of as a <glossterm linkend="glossary-table">Table</glossterm>
- with exactly one <glossterm linkend="glossary-tuple">Row</glossterm> and
- one <glossterm linkend="glossary-column">Column</glossterm>. The
- value stored is known as the current value. A
- <glossterm linkend="glossary-sequence">Sequence</glossterm> has a defined
- direction (usually increasing) and an interval step (usually 1).
- Whenever the <literal>NEXTVAL</literal> pseudo-column of a
- <glossterm linkend="glossary-sequence">Sequence</glossterm> is accessed,
- the current value is moved in the defined direction by the defined
- interval step, that value is returned to the invoking query,
- and the current value of the sequence is updated to reflect the new value.
- The value can be updated multiple times in a single query,
- the net effect being that each row selected will have a different value.
- Values taken from a
- <glossterm linkend="glossary-sequence">Sequence</glossterm> are never
- reverted, even in the case of a
- <glossterm linkend="glossary-rollback">Rollback</glossterm>, which means
- that the <glossterm linkend="glossary-sequence">Sequence</glossterm>
- will never generate the same number twice, which makes it useful for
- generating
- <glossterm linkend="glossary-primary-key">Primary Key</glossterm> values.
- </para>
- <para>
- For more information, see
- <xref linkend="sql-createsequence"/>.
+ 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>
+ <glossterm>Shared memory</glossterm>
<glossdef>
<para>
<acronym>RAM</acronym> which is used by the processes common to an
@@ -1342,28 +1373,32 @@
</glossdef>
</glossentry>
+ <glossentry>
+ <glossterm>Standby (server)</glossterm>
+ <glosssee otherterm="glossary-replica" />
+ </glossentry>
+
<glossentry id="glossary-sql-object">
<glossterm>SQL Object</glossterm>
<glossdef>
<para>
- A <glossterm linkend="glossary-table">table</glossterm>,
- <glossterm linkend="glossary-view">view</glossterm>,
- <glossterm linkend="glossary-materialized-view">materialized view</glossterm>,
- <glossterm linkend="glossary-index">index</glossterm>,
- <glossterm linkend="glossary-constraint">constraint</glossterm>,
-<!-- XXX define sequence <glossterm linkend="glossary-sequence"> --> sequence,
- <glossterm linkend="glossary-function">function</glossterm>,
- <glossterm linkend="glossary-procedure">procedure</glossterm>,
- <glossterm linkend="glossary-trigger">trigger</glossterm>,
- data type, or operator. Every one of those SQL objects
- belong to exactly one <glossterm linkend="glossary-schema">Schema</glossterm>.
- </para>
- <para>
- There also exist SQL objects that do not belong to schemas; those include
- <glossterm linkend="glossary-extension">extensions</glossterm>,
- <glossterm linkend="glossary-cast">data type cases</glossterm>,
- and
- <glossterm linkend="glossary-foreign-data-wrapper">foreign data wrappers</glossterm>.
+ 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.
+ 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>
<para>
For more information, see
@@ -1373,7 +1408,7 @@
</glossentry>
<glossentry id="glossary-sql-standard">
- <glossterm>SQL Standard</glossterm>
+ <glossterm>SQL standard</glossterm>
<glossdef>
<para>
A series of documents that define the <acronym>SQL</acronym> language.
@@ -1382,11 +1417,11 @@
</glossentry>
<glossentry id="glossary-stats-collector">
- <glossterm>Stats Collector</glossterm>
+ <glossterm>Stats collector</glossterm>
<glossdef>
<para>
This process collects statistical information about the
- <glossterm linkend="glossary-cluster">Cluster</glossterm>'s activities.
+ <glossterm linkend="glossary-instance">instance</glossterm>'s activities.
</para>
<para>
For more information, see
@@ -1396,22 +1431,21 @@
</glossentry>
<glossentry id="glossary-system-catalog">
- <glossterm>System Catalog</glossterm>
+ <glossterm>System catalog</glossterm>
<glossdef>
<para>
A collection of <glossterm linkend="glossary-table">tables</glossterm>
which describe the structure of all
<glossterm linkend="glossary-sql-object">SQL objects</glossterm>
- of each <glossterm linkend="glossary-database">database</glossterm>
- and the <glossterm linkend="glossary-global-sql-object">global SQL objects</glossterm>
- of the <glossterm linkend="glossary-cluster">cluster</glossterm>.
+ of the instance.
The system catalog resides in the schema <literal>pg_catalog</literal>.
These tables contain data in internal representation and are
not typically considered useful for user examination;
a number of user-friendlier <glossterm linkend="glossary-view">views</glossterm>
also in schema <literal>pg_catalog</literal> offer more convenient access to
some of that information, while additional tables and views
- exist in schema <literal>information_schema</literal> that expose some
+ exist in schema <literal>information_schema</literal>
+ (see <xref linkend="information-schema" />) that expose some
of the same and additional information as mandated by the
<glossterm linkend="glossary-sql-standard">SQL standard</glossterm>.
</para>
@@ -1431,7 +1465,7 @@
<glossterm linkend="glossary-attribute">attributes</glossterm>, in the same
order, having the same name and type per position).
A table is the most common form of
- <glossterm linkend="glossary-relation">Relation</glossterm> in
+ <glossterm linkend="glossary-relation">relation</glossterm> in
<productname>PostgreSQL</productname>.
</para>
<para>
@@ -1461,7 +1495,7 @@
</glossentry>
<glossentry id="glossary-temporary-table">
- <glossterm>Temporary Table</glossterm>
+ <glossterm>Temporary table</glossterm>
<glossdef>
<para>
<glossterm linkend="glossary-table">Tables</glossterm> that exist either
@@ -1499,6 +1533,30 @@
</glossdef>
</glossentry>
+ <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>.
+ When stored on disk, xids are only 32-bits wide, so only
+ approximately four billion write transactions IDs can be generated;
+ to permit the system to run for longer than that would allow,
+ <firstterm>epochs</firstterm> are used, also 32 bits wide.
+ When the counter reaches the maximum xid value, it starts over at
+ <literal>3</literal> (values under that are reserved) and the
+ <firstterm>epoch</firstterm> value is incremented by one.
+ In some contexts, both the epoch and xid values are
+ considered together as a single 64-bit value.
+ </para>
+ <para>
+ For more information, see
+ <xref linkend="datatype-oid"/>.
+ </para>
+ </glossdef>
+ </glossentry>
+
<glossentry id="glossary-trigger">
<glossterm>Trigger</glossterm>
<glossdef>
@@ -1508,7 +1566,7 @@
<command>UPDATE</command>, <command>DELETE</command>,
<command>TRUNCATE</command>) is applied to a
<glossterm linkend="glossary-relation">relation</glossterm>.
- A Trigger executes within the same
+ A trigger executes within the same
<glossterm linkend="glossary-transaction">transaction</glossterm> as the
statement which invoked it, and if the function fails, then the invoking
statement also fails.
@@ -1535,7 +1593,7 @@
</glossentry>
<glossentry id="glossary-unique-constraint">
- <glossterm>Unique Constraint</glossterm>
+ <glossterm>Unique constraint</glossterm>
<glossdef>
<para>
A type of <glossterm linkend="glossary-constraint">constraint</glossterm>
@@ -1577,7 +1635,7 @@
<glossterm>Update</glossterm>
<glossdef>
<para>
- A <acronym>SQL</acronym> command used to modify
+ An <acronym>SQL</acronym> command used to modify
<glossterm linkend="glossary-tuple">rows</glossterm>
that may already exist in a specified <glossterm linkend="glossary-table">table</glossterm>.
It cannot create or remove rows.
@@ -1621,7 +1679,7 @@
<para>
The process of removing outdated <glossterm linkend="glossary-tuple">tuple
versions</glossterm> from tables, and other closely related
- garbage-collection-like processing required by <productname>PostgreSQL</productname>'s
+ processing required by <productname>PostgreSQL</productname>'s
implementation of <glossterm linkend="glossary-mvcc">MVCC</glossterm>.
This can be initiated through the use of
the <command>VACUUM</command> command, but can also be handled automatically
@@ -1651,8 +1709,28 @@
</glossdef>
</glossentry>
+ <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
+ each page stores two bits: the first one
+ (<literal>all-visible</literal>) indicates that all tuples
+ in the page are visible to all transactions. The second one
+ (<literal>all-frozen</literal>) indicate that all tuples
+ in the page are marked frozen.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>WAL</glossterm>
+ <glosssee otherterm="glossary-wal" />
+ </glossentry>
+
<glossentry id="glossary-wal-archiver">
- <glossterm>WAL Archiver (process)</glossterm>
+ <glossterm>WAL archiver (process)</glossterm>
<glossdef>
<para>
A process that saves copies of <glossterm linkend="glossary-wal-file">WAL files</glossterm>
@@ -1667,7 +1745,7 @@
</glossentry>
<glossentry id="glossary-wal-file">
- <glossterm>WAL File</glossterm>
+ <glossterm>WAL file</glossterm>
<glossdef>
<para>
Also known as <firstterm>WAL segment</firstterm> or
@@ -1678,7 +1756,7 @@
and are written in sequential order, interspersing changes
as they occur in multiple simultaneous sessions.
If the system crashes, the files are read in order, and each of the
- changes are replayed to restore the system to the state as it was
+ changes is replayed to restore the system to the state as it was
before the crash.
</para>
<para>
@@ -1696,13 +1774,8 @@
</glossdef>
</glossentry>
- <glossentry>
- <glossterm>WAL</glossterm>
- <glosssee otherterm="glossary-wal" />
- </glossentry>
-
<glossentry id="glossary-wal-record">
- <glossterm>WAL Record</glossterm>
+ <glossterm>WAL record</glossterm>
<glossdef>
<para>
A low-level description of an individual data change.
@@ -1719,17 +1792,17 @@
</glossentry>
<glossentry>
- <glossterm>WAL Segment</glossterm>
+ <glossterm>WAL segment</glossterm>
<glosssee otherterm="glossary-wal-file" />
</glossentry>
<glossentry id="glossary-wal-writer">
- <glossterm>WAL Writer (process)</glossterm>
+ <glossterm>WAL writer (process)</glossterm>
<glossdef>
<para>
A process that writes <glossterm linkend="glossary-wal-record">WAL records</glossterm>
- from <glossterm id="linkend-shared-memory">shared memory</glossterm> to
- <glossterm id="linkend-wal-file">WAL files</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
@@ -1739,7 +1812,7 @@
</glossentry>
<glossentry id="glossary-window-function">
- <glossterm>Window Function</glossterm>
+ <glossterm>Window function</glossterm>
<glossdef>
<para>
A type of <glossterm linkend="glossary-function">function</glossterm> whose
@@ -1759,7 +1832,7 @@
</glossentry>
<glossentry id="glossary-wal">
- <glossterm>Write-Ahead Log</glossterm>
+ <glossterm>Write-ahead log</glossterm>
<glossdef>
<para>
The journal that keeps track of the changes in the
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-05-15 01:03 Justin Pryzby <[email protected]>
parent: Alvaro Herrera <[email protected]>
1 sibling, 1 reply; 97+ messages in thread
From: Justin Pryzby @ 2020-05-15 01:03 UTC (permalink / raw)
To: Alvaro Herrera <[email protected]>; +Cc: Erik Rijkers <[email protected]>; Laurenz Albe <[email protected]>; Fabien COELHO <[email protected]>; Jürgen Purtz <[email protected]>; Peter Eisentraut <[email protected]>; Corey Huinker <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Michael Paquier <[email protected]>
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
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-05-15 17:26 Alvaro Herrera <[email protected]>
parent: Justin Pryzby <[email protected]>
0 siblings, 1 reply; 97+ messages in thread
From: Alvaro Herrera @ 2020-05-15 17:26 UTC (permalink / raw)
To: Justin Pryzby <[email protected]>; +Cc: Erik Rijkers <[email protected]>; Laurenz Albe <[email protected]>; Fabien COELHO <[email protected]>; Jürgen Purtz <[email protected]>; Peter Eisentraut <[email protected]>; Corey Huinker <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Michael Paquier <[email protected]>
Applied all these suggestions, and made a few additional very small
edits, and pushed -- better to ship what we have now in beta1, but
further edits are still possible.
Other possible terms to define, including those from the tweet I linked
to and a couple more:
archive
availability
backup
composite type
common table expression
data type
domain
dump
export
fault tolerance
GUC
high availability
hot standby
LSN
restore
secondary server (?)
snapshot
transactions per second
Anybody want to try their hand at a tentative definition?
--
Álvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-05-16 21:45 Erik Rijkers <[email protected]>
parent: Alvaro Herrera <[email protected]>
0 siblings, 1 reply; 97+ messages in thread
From: Erik Rijkers @ 2020-05-16 21:45 UTC (permalink / raw)
To: Alvaro Herrera <[email protected]>; +Cc: Justin Pryzby <[email protected]>; Laurenz Albe <[email protected]>; Fabien COELHO <[email protected]>; Jürgen Purtz <[email protected]>; Peter Eisentraut <[email protected]>; Corey Huinker <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Michael Paquier <[email protected]>
On 2020-05-15 19:26, Alvaro Herrera wrote:
> Applied all these suggestions, and made a few additional very small
> edits, and pushed -- better to ship what we have now in beta1, but
> further edits are still possible.
I've gone through the glossary as committed and found some more small
things; patch attached.
Thanks,
Erik Rijkers
> Other possible terms to define, including those from the tweet I linked
> to and a couple more:
>
> archive
> availability
> backup
> composite type
> common table expression
> data type
> domain
> dump
> export
> fault tolerance
> GUC
> high availability
> hot standby
> LSN
> restore
> secondary server (?)
> snapshot
> transactions per second
>
> Anybody want to try their hand at a tentative definition?
>
> --
> Álvaro Herrera https://www.2ndQuadrant.com/
> PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Attachments:
[text/x-diff] glossary-20200516.sgml.diff (4.2K, 2-glossary-20200516.sgml.diff)
download | inline diff:
--- doc/src/sgml/glossary.sgml.orig 2020-05-16 23:30:01.132290237 +0200
+++ doc/src/sgml/glossary.sgml 2020-05-16 23:38:35.643371310 +0200
@@ -67,7 +67,7 @@
<glossdef>
<para>
In reference to a <glossterm linkend="glossary-datum">datum</glossterm>:
- the fact that its value that cannot be broken down into smaller
+ the fact that its value cannot be broken down into smaller
components.
</para>
</glossdef>
@@ -360,7 +360,7 @@
<glossterm linkend="glossary-constraint">integrity constraints</glossterm>.
Transactions may be allowed to violate some of the constraints
transiently before it commits, but if such violations are not resolved
- by the time it commits, such transaction is automatically
+ by the time it commits, such a transaction is automatically
<glossterm linkend="glossary-rollback">rolled back</glossterm>.
This is one of the <acronym>ACID</acronym> properties.
</para>
@@ -649,8 +649,8 @@
<glossterm>Grant</glossterm>
<glossdef>
<para>
- An <acronym>SQL</acronym> command that is used to allow
- <glossterm linkend="glossary-user">users</glossterm> or
+ An <acronym>SQL</acronym> command that is used to allow a
+ <glossterm linkend="glossary-user">user</glossterm> or
<glossterm linkend="glossary-role">role</glossterm> to access
specific objects within the <glossterm linkend="glossary-database">database</glossterm>.
</para>
@@ -887,7 +887,7 @@
<glossdef>
<para>
A <glossterm linkend="glossary-relation">relation</glossterm> that is
- defined in the same way that a a <glossterm linkend="glossary-view">view</glossterm>
+ defined in the same way that a <glossterm linkend="glossary-view">view</glossterm>
is, 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
@@ -962,7 +962,7 @@
<glossdef>
<para>
In reference to a <glossterm linkend="glossary-window-function">window function</glossterm>:
- a partition is a user-defined criteria that identifies which neighboring
+ a partition is a user-defined criterion that identifies which neighboring
<glossterm linkend="glossary-tuple">rows</glossterm> can be considered by the
function.
</para>
@@ -1446,8 +1446,8 @@
The system catalog resides in the schema <literal>pg_catalog</literal>.
These tables contain data in internal representation and are
not typically considered useful for user examination;
- a number of user-friendlier <glossterm linkend="glossary-view">views</glossterm>
- also in schema <literal>pg_catalog</literal> offer more convenient access to
+ a number of user-friendlier <glossterm linkend="glossary-view">views</glossterm>,
+ also in schema <literal>pg_catalog</literal>, offer more convenient access to
some of that information, while additional tables and views
exist in schema <literal>information_schema</literal>
(see <xref linkend="information-schema" />) that expose some
@@ -1739,7 +1739,7 @@
each page stores two bits: the first one
(<literal>all-visible</literal>) indicates that all tuples
in the page are visible to all transactions. The second one
- (<literal>all-frozen</literal>) indicate that all tuples
+ (<literal>all-frozen</literal>) indicates that all tuples
in the page are marked frozen.
</para>
</glossdef>
@@ -1755,7 +1755,7 @@
<glossdef>
<para>
A process that saves copies of <glossterm linkend="glossary-wal-file">WAL files</glossterm>
- for the purposes of creating backups or keeping
+ for the purpose of creating backups or keeping
<glossterm linkend="glossary-replica">replicas</glossterm> current.
</para>
<para>
@@ -1777,7 +1777,7 @@
and are written in sequential order, interspersing changes
as they occur in multiple simultaneous sessions.
If the system crashes, the files are read in order, and each of the
- changes is replayed to restore the system to the state as it was
+ changes is replayed to restore the system to the state it was in
before the crash.
</para>
<para>
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-05-17 02:22 Alvaro Herrera <[email protected]>
parent: Erik Rijkers <[email protected]>
0 siblings, 0 replies; 97+ messages in thread
From: Alvaro Herrera @ 2020-05-17 02:22 UTC (permalink / raw)
To: Erik Rijkers <[email protected]>; +Cc: Justin Pryzby <[email protected]>; Laurenz Albe <[email protected]>; Fabien COELHO <[email protected]>; Jürgen Purtz <[email protected]>; Peter Eisentraut <[email protected]>; Corey Huinker <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Michael Paquier <[email protected]>
On 2020-May-16, Erik Rijkers wrote:
> On 2020-05-15 19:26, Alvaro Herrera wrote:
> > Applied all these suggestions, and made a few additional very small
> > edits, and pushed -- better to ship what we have now in beta1, but
> > further edits are still possible.
>
> I've gone through the glossary as committed and found some more small
> things; patch attached.
All pushed! Many thanks,
--
Álvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-05-17 06:15 Jürgen Purtz <[email protected]>
parent: Alvaro Herrera <[email protected]>
1 sibling, 1 reply; 97+ messages in thread
From: Jürgen Purtz @ 2020-05-17 06:15 UTC (permalink / raw)
To: Alvaro Herrera <[email protected]>; Erik Rijkers <[email protected]>; Laurenz Albe <[email protected]>; Fabien COELHO <[email protected]>; Peter Eisentraut <[email protected]>; Corey Huinker <[email protected]>; +Cc: Justin Pryzby <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Michael Paquier <[email protected]>
On 15.05.20 02:00, Alvaro Herrera wrote:
> Thanks everybody. I have compiled together all the suggestions and the
> result is in the attached patch. Some of it is of my own devising.
>
> * I changed "instance", and made "cluster" be mostly a synonym of that.
In my understanding, "instance" and "cluster" should be different
things, not only synonyms. "instance" can be the term for permanently
fluctuating objects (processes and RAM) and "cluster" can denote the
more static objects (directories and files). What do you think? If you
agree, I would create a patch.
> * I removed "global SQL object" and made "SQL object" explain it.
+1., but see the (huge) different spellings in patch.
bloat: changed 'current row' to 'relevant row' because not only the
youngest one is relevant (non-bloat).
data type casts: Are you sure that they are global? In pg_cast
'relisshared' is 'false'.
--
Jürgen Purtz
Attachments:
[text/x-patch] 0002-glossfixes-purtz.patch (2.5K, 2-0002-glossfixes-purtz.patch)
download | inline diff:
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
index 8bb1ea5d87..75f0dc9a8c 100644
--- a/doc/src/sgml/glossary.sgml
+++ b/doc/src/sgml/glossary.sgml
@@ -179,7 +179,7 @@
<glossterm>Bloat</glossterm>
<glossdef>
<para>
- Space in data pages which does not contain current row versions,
+ Space in data pages which does not contain relevant row versions,
such as unused (free) space or outdated row versions.
</para>
</glossdef>
@@ -1388,23 +1388,27 @@
<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>.
+ command. Most objects are specific to one schema within
+ one database, and are commonly
+ known as <firstterm>local SQL objects</firstterm>.
+ </para>
+ <para>
+ Some of the SQL objects do not belong to a single schema but
+ are known in all schemas of a database. Examples are
+ <glossterm linkend="glossary-extension">extensions</glossterm> like
+ <glossterm linkend="glossary-foreign-data-wrapper">foreign data wrappers</glossterm>, and
+ <glossterm linkend="glossary-cast">data type casts</glossterm>.
+ </para>
+ <para>
+ Some others even belong to the complete cluster and are
+ known in all databases and all its schemas.
<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>.
+ all <firstterm>database names</firstterm> exist
+ entirely outside of any specific database.
+ They are called <firstterm>global SQL objects</firstterm>.
</para>
- <para>
- Most local objects belong to a specific
- <glossterm linkend="glossary-schema">schema</glossterm> in their containing database.
- 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>
<para>
For more information, see
<xref linkend="manage-ag-overview"/>.
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-05-17 06:51 Alvaro Herrera <[email protected]>
parent: Jürgen Purtz <[email protected]>
0 siblings, 3 replies; 97+ messages in thread
From: Alvaro Herrera @ 2020-05-17 06:51 UTC (permalink / raw)
To: Jürgen Purtz <[email protected]>; +Cc: Erik Rijkers <[email protected]>; Laurenz Albe <[email protected]>; Fabien COELHO <[email protected]>; Peter Eisentraut <[email protected]>; Corey Huinker <[email protected]>; Justin Pryzby <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Michael Paquier <[email protected]>
On 2020-May-17, Jürgen Purtz wrote:
> On 15.05.20 02:00, Alvaro Herrera wrote:
> > Thanks everybody. I have compiled together all the suggestions and the
> > result is in the attached patch. Some of it is of my own devising.
> >
> > * I changed "instance", and made "cluster" be mostly a synonym of that.
> In my understanding, "instance" and "cluster" should be different things,
> not only synonyms. "instance" can be the term for permanently fluctuating
> objects (processes and RAM) and "cluster" can denote the more static objects
> (directories and files). What do you think? If you agree, I would create a
> patch.
I don't think that's the general understanding of those terms. For all
I know, they *are* synonyms, and there's no specific term for "the
fluctuating objects" as you call them. The instance is either running
(in which case there are processes and RAM) or it isn't.
> > * I removed "global SQL object" and made "SQL object" explain it.
> +1., but see the (huge) different spellings in patch.
This seems a misunderstanding of what "local" means. Any object that
exists in a database is local, regardless of whether it exists in a
schema or not. "Extensions" is one type of object that does not belong
in a schema. "Foreign data wrapper" is another type of object that does
not belong in a schema. Same with data type casts. They are *not*
global objects.
> bloat: changed 'current row' to 'relevant row' because not only the youngest
> one is relevant (non-bloat).
Hm. TBH I'm not sure of this term at all. I think we sometimes use the
term "bloat" to talk about the dead rows only, ignoring the free space.
> data type casts: Are you sure that they are global? In pg_cast 'relisshared'
> is 'false'.
I'm not saying they're global. I'm saying they're outside schemas.
Maybe this definition needs more rewording, if this bit is unclear.
--
Álvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-05-17 08:09 Jürgen Purtz <[email protected]>
parent: Alvaro Herrera <[email protected]>
2 siblings, 0 replies; 97+ messages in thread
From: Jürgen Purtz @ 2020-05-17 08:09 UTC (permalink / raw)
To: Alvaro Herrera <[email protected]>; +Cc: Erik Rijkers <[email protected]>; Laurenz Albe <[email protected]>; Fabien COELHO <[email protected]>; Peter Eisentraut <[email protected]>; Corey Huinker <[email protected]>; Justin Pryzby <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Michael Paquier <[email protected]>
On 17.05.20 08:51, Alvaro Herrera wrote:
> Any object that
> exists in a database is local, regardless of whether it exists in a
> schema or not.
This implies that the term "local" is unnecessary, just call them "SQL
object".
> "Extensions" is one type of object that does not belong
> in a schema. "Foreign data wrapper" is another type of object that does
> not belong in a schema. ... They are*not*
> global objects.
postgres_fdw is a module among many others. It's only an example for
"extensions" and has no different nature. Yes, they are not global SQL
objects because they don't belong to the cluster.
In summary we have 3 types of objects: belonging to a schema, to a
database, or to the cluster (global). Maybe, we can avoid the use of the
different names 'local SQL object' and 'global SQL object' at all and
just call them 'SQL object'. 'global SQL object' is used only once. We
could rephrase "A set of databases and accompanying global SQL objects
... " to "A set of databases and accompanying SQL objects, which exists
at the cluster level, ... "
> TBH I'm not sure of this term at all. I think we sometimes use the
> term "bloat" to talk about the dead rows only, ignoring the free space.
That's a good example for the necessity of the glossary. Currently we
don't have a common understanding about all of our used terms. The
glossary shall fix that and give a mandatory definition - after a
clearing discussion.
--
Jürgen Purtz
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-05-17 08:44 Jürgen Purtz <[email protected]>
parent: Alvaro Herrera <[email protected]>
2 siblings, 0 replies; 97+ messages in thread
From: Jürgen Purtz @ 2020-05-17 08:44 UTC (permalink / raw)
To: Alvaro Herrera <[email protected]>; +Cc: Erik Rijkers <[email protected]>; Laurenz Albe <[email protected]>; Fabien COELHO <[email protected]>; Peter Eisentraut <[email protected]>; Corey Huinker <[email protected]>; Justin Pryzby <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Michael Paquier <[email protected]>
On 17.05.20 08:51, Alvaro Herrera wrote:
>> On 15.05.20 02:00, Alvaro Herrera wrote:
>>> Thanks everybody. I have compiled together all the suggestions and the
>>> result is in the attached patch. Some of it is of my own devising.
>>>
>>> * I changed "instance", and made "cluster" be mostly a synonym of that.
>> In my understanding, "instance" and "cluster" should be different things,
>> not only synonyms. "instance" can be the term for permanently fluctuating
>> objects (processes and RAM) and "cluster" can denote the more static objects
>> (directories and files). What do you think? If you agree, I would create a
>> patch.
> I don't think that's the general understanding of those terms. For all
> I know, they*are* synonyms, and there's no specific term for "the
> fluctuating objects" as you call them. The instance is either running
> (in which case there are processes and RAM) or it isn't.
>
We have the basic tools "initdb — create a new PostgreSQL database
cluster" which affects nothing but files, and we have "pg_ctl —
initialize, start, stop, or control a PostgreSQL server" which -
directly - affects nothing but processes and RAM. (Here the term
"server" collides with new definitions in the glossary. But that's
another story.)
--
Jürgen Purtz
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-05-17 09:08 Erik Rijkers <[email protected]>
parent: Alvaro Herrera <[email protected]>
2 siblings, 1 reply; 97+ messages in thread
From: Erik Rijkers @ 2020-05-17 09:08 UTC (permalink / raw)
To: Alvaro Herrera <[email protected]>; +Cc: Jürgen Purtz <[email protected]>; Laurenz Albe <[email protected]>; Fabien COELHO <[email protected]>; Peter Eisentraut <[email protected]>; Corey Huinker <[email protected]>; Justin Pryzby <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Michael Paquier <[email protected]>
On 2020-05-17 08:51, Alvaro Herrera wrote:
> On 2020-May-17, Jürgen Purtz wrote:
>
>> On 15.05.20 02:00, Alvaro Herrera wrote:
>> > Thanks everybody. I have compiled together all the suggestions and the
>> >
>> > * I changed "instance", and made "cluster" be mostly a synonym of that.
>> In my understanding, "instance" and "cluster" should be different
>> things,
>
> I don't think that's the general understanding of those terms. For all
> I know, they *are* synonyms, and there's no specific term for "the
> fluctuating objects" as you call them. The instance is either running
> (in which case there are processes and RAM) or it isn't.
For what it's worth, I've also always understood 'instance' as 'a
running database'. I admit it might be a left-over from my oracle
years:
https://docs.oracle.com/cd/E11882_01/server.112/e40540/startup.htm#CNCPT601
There, 'instance' clearly refers to a running database. When that
database is stopped, it ceases to be an instance. I've always
understood this to be the same for the PostgreSQL 'instance'. Once
stopped, it is no longer an instance, but it is, of course, still a
cluster.
I know, we don't have to do the same as Oracle, but clearly it's going
to be an ongoing source of misunderstanding if we define such a
high-level term differently.
Erik Rijkers
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-05-17 15:28 Alvaro Herrera <[email protected]>
parent: Erik Rijkers <[email protected]>
0 siblings, 2 replies; 97+ messages in thread
From: Alvaro Herrera @ 2020-05-17 15:28 UTC (permalink / raw)
To: Erik Rijkers <[email protected]>; +Cc: Jürgen Purtz <[email protected]>; Laurenz Albe <[email protected]>; Fabien COELHO <[email protected]>; Peter Eisentraut <[email protected]>; Corey Huinker <[email protected]>; Justin Pryzby <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Michael Paquier <[email protected]>
On 2020-May-17, Erik Rijkers wrote:
> On 2020-05-17 08:51, Alvaro Herrera wrote:
> > I don't think that's the general understanding of those terms. For all
> > I know, they *are* synonyms, and there's no specific term for "the
> > fluctuating objects" as you call them. The instance is either running
> > (in which case there are processes and RAM) or it isn't.
>
> For what it's worth, I've also always understood 'instance' as 'a running
> database'. I admit it might be a left-over from my oracle years:
>
> https://docs.oracle.com/cd/E11882_01/server.112/e40540/startup.htm#CNCPT601
>
> There, 'instance' clearly refers to a running database. When that database
> is stopped, it ceases to be an instance.
I've never understood it that way, but I'm open to having my opinion on
it changed. So let's discuss it and maybe gather opinions from others.
I think the terms under discussion are just
* cluster
* instance
* server
We don't have "host" (I just made it a synonym for server), but perhaps
we can add that too, if it's useful. It would be good to be consistent
with historical Postgres usage, such as the initdb usage of "cluster"
etc.
Perhaps we should not only define what our use of each term is, but also
explain how each term is used outside PostgreSQL and highlight the
differences. (This would be particularly useful for "cluster" ISTM.)
It seems difficult to get this sorted out before beta1, but there's
still time before the glossary is released.
--
Álvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-05-18 16:08 Jürgen Purtz <[email protected]>
parent: Alvaro Herrera <[email protected]>
1 sibling, 1 reply; 97+ messages in thread
From: Jürgen Purtz @ 2020-05-18 16:08 UTC (permalink / raw)
To: [email protected]; Pg Docs <[email protected]>; +Cc: Erik Rijkers <[email protected]>; Fabien COELHO <[email protected]>; Corey Huinker <[email protected]>; Justin Pryzby <[email protected]>; Roger Harkavy <[email protected]>
On 17.05.20 17:28, Alvaro Herrera wrote:
> On 2020-May-17, Erik Rijkers wrote:
>
>> On 2020-05-17 08:51, Alvaro Herrera wrote:
>>> I don't think that's the general understanding of those terms. For all
>>> I know, they*are* synonyms, and there's no specific term for "the
>>> fluctuating objects" as you call them. The instance is either running
>>> (in which case there are processes and RAM) or it isn't.
>> For what it's worth, I've also always understood 'instance' as 'a running
>> database'. I admit it might be a left-over from my oracle years:
>>
>> https://docs.oracle.com/cd/E11882_01/server.112/e40540/startup.htm#CNCPT601
>>
>> There, 'instance' clearly refers to a running database. When that database
>> is stopped, it ceases to be an instance.
> I've never understood it that way, but I'm open to having my opinion on
> it changed. So let's discuss it and maybe gather opinions from others.
>
> I think the terms under discussion are just
>
> * cluster
> * instance
> * server
>
> We don't have "host" (I just made it a synonym for server), but perhaps
> we can add that too, if it's useful. It would be good to be consistent
> with historical Postgres usage, such as the initdb usage of "cluster"
> etc.
>
> Perhaps we should not only define what our use of each term is, but also
> explain how each term is used outside PostgreSQL and highlight the
> differences. (This would be particularly useful for "cluster" ISTM.)
In fact, we have reached a point where we don't have a common
understanding of a group of terms. I'm sure that we will meet some more
situations like this in the future. Such discussions, subsequent
decisions, and implementations in the docs are necessary to gain a solid
foundation - primarily for newcomers (what is my first motivation) as
well as for more complex discussions among experts. Obviously, each of
us will include his previous understanding of terms. But we also should
be open to sometimes revise old terms.
Here are my two cents.
cluster/instance: PG (mainly) consists of a group of processes that
commonly act on shared buffers. The processes are very closely related
to each other and with the buffers. They exist altogether or not at all.
They use a common initialization file and are incarnated by one command.
Everything exists solely in RAM and therefor has a fluctuating nature.
In summary: they build a unit and this unit needs to have a name of
itself. In some pages we used to use the term *instance* - sometimes in
extended forms: *database instance*, *PG instance*, *standby instance*,
*standby server instance*, *server instance*, or *remote instance*. For
me, the term *instance* makes sense, the extensions *standby instance*
and *remote instance* in their context too.
The next essential component is the data itself. It is organized as a
group of databases plus some common management information (global,
pg_wal, pg_xact, pg_tblspc, ...). The complete data must be treated as a
whole because the management information concerns all databases. Its
nature is different from the processes and shared buffers. Of course,
its content changes, but it has a steady nature. It even survives a
'power down'. There is one command to instantiate a new incarnation of
the directory structure and all files. In summary, it's something of its
own and should have its own name. 'database' is not possible because it
consists of databases and other things. My favorite is *cluster*;
*database cluster* is also possible.
server/host: We need a term to describe the underlying hardware
respectively the virtual machine or container, where PG is running. I
suggest to use both *server* and *host*. In computer science, both have
their eligibility and are widely used. Everybody understands
*client/server architecture* or *host* in TCP/IP configuration. We
cannot change such matter of course. I suggest to use both depending on
the context, but with the same meaning: "real hardware, a container, or
a virtual machine".
--
Jürgen Purtz
(PS: I added the docs mailing list)
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-05-19 06:17 Laurenz Albe <[email protected]>
parent: Jürgen Purtz <[email protected]>
0 siblings, 3 replies; 97+ messages in thread
From: Laurenz Albe @ 2020-05-19 06:17 UTC (permalink / raw)
To: Jürgen Purtz <[email protected]>; [email protected]; Pg Docs <[email protected]>; +Cc: Erik Rijkers <[email protected]>; Fabien COELHO <[email protected]>; Corey Huinker <[email protected]>; Justin Pryzby <[email protected]>; Roger Harkavy <[email protected]>
On Mon, 2020-05-18 at 18:08 +0200, Jürgen Purtz wrote:
> cluster/instance: PG (mainly) consists of a group of processes that commonly
> act on shared buffers. The processes are very closely related to each other
> and with the buffers. They exist altogether or not at all. They use a common
> initialization file and are incarnated by one command. Everything exists
> solely in RAM and therefor has a fluctuating nature. In summary: they build
> a unit and this unit needs to have a name of itself. In some pages we used
> to use the term *instance* - sometimes in extended forms: *database instance*,
> *PG instance*, *standby instance*, *standby server instance*, *server instance*,
> or *remote instance*. For me, the term *instance* makes sense, the extensions
> *standby instance* and *remote instance* in their context too.
FWIW, I feel somewhat like Alvaro on that point; I use those terms synonymously,
perhaps distinguishing between a "started cluster" and a "stopped cluster".
After all, "cluster" refers to "a cluster of databases", which are there, regardless
if you start the server or not.
The term "cluster" is unfortunate, because to most people it suggests a group of
machines, so the term "instance" is better, but that ship has sailed long ago.
The static part of a cluster to me is the "data directory".
> server/host: We need a term to describe the underlying hardware respectively
> the virtual machine or container, where PG is running. I suggest to use both
> *server* and *host*. In computer science, both have their eligibility and are
> widely used. Everybody understands *client/server architecture* or *host* in
> TCP/IP configuration. We cannot change such matter of course. I suggest to
> use both depending on the context, but with the same meaning: "real hardware,
> a container, or a virtual machine".
On this I have a strong opinion because of my Unix mindset.
"machine" and "host" are synonyms, and it doesn't matter to the database if they
are virtualized or not. You can always disambiguate by adding "virtual" or "physical".
A "server" is a piece of software that responds to client requests, never a machine.
In my book, this is purely Windows jargon. The term "client-server architecture"
that you quote emphasized that.
Perhaps "machine" would be the preferable term, because "host" is more prone to
misunderstandings (except in a networking context).
Yours,
Laurenz Albe
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-05-19 06:44 Andrew Grillet <[email protected]>
parent: Laurenz Albe <[email protected]>
2 siblings, 0 replies; 97+ messages in thread
From: Andrew Grillet @ 2020-05-19 06:44 UTC (permalink / raw)
To: Laurenz Albe <[email protected]>; +Cc: Jürgen Purtz <[email protected]>; [email protected]; Pg Docs <[email protected]>; Erik Rijkers <[email protected]>; Fabien COELHO <[email protected]>; Corey Huinker <[email protected]>; Justin Pryzby <[email protected]>; Roger Harkavy <[email protected]>
I think there needs to be a careful analysis of the language and a formal
effort to stabilise it for the future.
In the context of, say, an Oracle T series, which is partitioned into
multiple domains (virtual machines) in it, each
of these has multiple CPUs, and can run an instance of the OS which hosts
multiple virtual instances
of the same or different OSes. Som domains might do this while others do
not!
A host could be a domain, one of many virtual machines, or it could be one
of many hosts on that VM
but even these hosts could be virtual machines that each runs several
virtual servers!
Of course, PostgreSQL can run on any tier of this regime, but the
documentation at least needs to be consistent
about language.
A "machine" should probably refer to hardware, although I would accept that
a domain might count as "virtual
hardware" while a host should probably refer to a single instance of OS.
Of course it is possible for a single instance of OS to run multiple
instances of PostgreSQL, and people do this. (I have
in the past).
Slightly more confusingly, it would appear possible for a single instance
of an OS to have multiple IP addresses
and if there are multiple instances of PostgreSQL, they may serve different
IP Addresses uniquely, or
share them. I think this case suggests that a host probably best describes
an OS instance. I might be wrong.
The word "server" might be an instance of any of the above, or a waiter
with a bowl of soup. It is best
reserved for situations where clarity is not required.
If you are new to all this, I am sure it is very confusing, and
inconsistent language is not going to help.
Andrew
AFAICT
On Tue, 19 May 2020 at 07:17, Laurenz Albe <[email protected]> wrote:
> On Mon, 2020-05-18 at 18:08 +0200, Jürgen Purtz wrote:
> > cluster/instance: PG (mainly) consists of a group of processes that
> commonly
> > act on shared buffers. The processes are very closely related to each
> other
> > and with the buffers. They exist altogether or not at all. They use a
> common
> > initialization file and are incarnated by one command. Everything exists
> > solely in RAM and therefor has a fluctuating nature. In summary: they
> build
> > a unit and this unit needs to have a name of itself. In some pages we
> used
> > to use the term *instance* - sometimes in extended forms: *database
> instance*,
> > *PG instance*, *standby instance*, *standby server instance*, *server
> instance*,
> > or *remote instance*. For me, the term *instance* makes sense, the
> extensions
> > *standby instance* and *remote instance* in their context too.
>
> FWIW, I feel somewhat like Alvaro on that point; I use those terms
> synonymously,
> perhaps distinguishing between a "started cluster" and a "stopped cluster".
> After all, "cluster" refers to "a cluster of databases", which are there,
> regardless
> if you start the server or not.
>
> The term "cluster" is unfortunate, because to most people it suggests a
> group of
> machines, so the term "instance" is better, but that ship has sailed long
> ago.
>
> The static part of a cluster to me is the "data directory".
>
> > server/host: We need a term to describe the underlying hardware
> respectively
> > the virtual machine or container, where PG is running. I suggest to use
> both
> > *server* and *host*. In computer science, both have their eligibility
> and are
> > widely used. Everybody understands *client/server architecture* or
> *host* in
> > TCP/IP configuration. We cannot change such matter of course. I suggest
> to
> > use both depending on the context, but with the same meaning: "real
> hardware,
> > a container, or a virtual machine".
>
> On this I have a strong opinion because of my Unix mindset.
> "machine" and "host" are synonyms, and it doesn't matter to the database
> if they
> are virtualized or not. You can always disambiguate by adding "virtual"
> or "physical".
>
> A "server" is a piece of software that responds to client requests, never
> a machine.
> In my book, this is purely Windows jargon. The term "client-server
> architecture"
> that you quote emphasized that.
>
> Perhaps "machine" would be the preferable term, because "host" is more
> prone to
> misunderstandings (except in a networking context).
>
> Yours,
> Laurenz Albe
>
>
>
>
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-05-19 11:25 Peter Eisentraut <[email protected]>
parent: Laurenz Albe <[email protected]>
2 siblings, 0 replies; 97+ messages in thread
From: Peter Eisentraut @ 2020-05-19 11:25 UTC (permalink / raw)
To: Laurenz Albe <[email protected]>; Jürgen Purtz <[email protected]>; [email protected]; Pg Docs <[email protected]>; +Cc: Erik Rijkers <[email protected]>; Fabien COELHO <[email protected]>; Corey Huinker <[email protected]>; Justin Pryzby <[email protected]>; Roger Harkavy <[email protected]>
On 2020-05-19 08:17, Laurenz Albe wrote:
> The term "cluster" is unfortunate, because to most people it suggests a group of
> machines, so the term "instance" is better, but that ship has sailed long ago.
I don't see what would stop us from renaming some things, with some care.
--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-05-20 11:17 Jürgen Purtz <[email protected]>
parent: Laurenz Albe <[email protected]>
2 siblings, 1 reply; 97+ messages in thread
From: Jürgen Purtz @ 2020-05-20 11:17 UTC (permalink / raw)
To: Laurenz Albe <[email protected]>; [email protected]; Pg Docs <[email protected]>; +Cc: Erik Rijkers <[email protected]>; Fabien COELHO <[email protected]>; Corey Huinker <[email protected]>; Justin Pryzby <[email protected]>; Roger Harkavy <[email protected]>
On 19.05.20 08:17, Laurenz Albe wrote:
> On Mon, 2020-05-18 at 18:08 +0200, Jürgen Purtz wrote:
>> cluster/instance: PG (mainly) consists of a group of processes that commonly
>> act on shared buffers. The processes are very closely related to each other
>> and with the buffers. They exist altogether or not at all. They use a common
>> initialization file and are incarnated by one command. Everything exists
>> solely in RAM and therefor has a fluctuating nature. In summary: they build
>> a unit and this unit needs to have a name of itself. In some pages we used
>> to use the term *instance* - sometimes in extended forms: *database instance*,
>> *PG instance*, *standby instance*, *standby server instance*, *server instance*,
>> or *remote instance*. For me, the term *instance* makes sense, the extensions
>> *standby instance* and *remote instance* in their context too.
> FWIW, I feel somewhat like Alvaro on that point; I use those terms synonymously,
> perhaps distinguishing between a "started cluster" and a "stopped cluster".
> After all, "cluster" refers to "a cluster of databases", which are there, regardless
> if you start the server or not.
>
> The term "cluster" is unfortunate, because to most people it suggests a group of
> machines, so the term "instance" is better, but that ship has sailed long ago.
>
> The static part of a cluster to me is the "data directory".
cluster/instance: The different nature (static/dynamic) of what I call
"cluster" and "instance" as well as the existence of the two commands
"initdb — create a new PostgreSQL database cluster" and "pg_ctl —
initialize, start, stop, or control a PostgreSQL server" confirms me in
my opinion that we need two different terms for them. Those two terms
shall not be synonym to each other, they label distinct things. If
people prefer "data directory" instead of "cluster", this is ok for me.
There are situations where we need a single term for both of them.
"Instance and its data directory" or "Instance and its cluster" are too
wordy. In many cases we use "database server" or "server" in this sense.
Imo "Server" is too short and ambiguous. "database server", the plural
form "databases server", or the new term "cluster server", which is more
accurate, would be ok for me. (Similar to "server", the term "cluster"
is also used in many different contexts - but only outside of the PG
world; within our context "cluster" is not ambiguous.)
>> server/host: We need a term to describe the underlying hardware respectively
>> the virtual machine or container, where PG is running. I suggest to use both
>> *server* and *host*. In computer science, both have their eligibility and are
>> widely used. Everybody understands *client/server architecture* or *host* in
>> TCP/IP configuration. We cannot change such matter of course. I suggest to
>> use both depending on the context, but with the same meaning: "real hardware,
>> a container, or a virtual machine".
> On this I have a strong opinion because of my Unix mindset.
> "machine" and "host" are synonyms, and it doesn't matter to the database if they
> are virtualized or not. You can always disambiguate by adding "virtual" or "physical".
>
> A "server" is a piece of software that responds to client requests, never a machine.
> In my book, this is purely Windows jargon. The term "client-server architecture"
> that you quote emphasized that.
>
> Perhaps "machine" would be the preferable term, because "host" is more prone to
> misunderstandings (except in a networking context).
>
server/host: I agree that we are not interested in the question whether
there is real hardware or any virtualization container. We are even not
interested in the operating system. Our primary concern is the existence
of a port of the Internet Protocol. But is the term "server" appropriate
to name an IP-port? Additionally, "server" is used for other meanings:
a) the previously mentioned "database server" b) a (virtual) machine:
"server-side", "... the file ... loaded by the server ..." c) binaries
"... the server must be built with SSL support ..." d) whenever it seems
to be appropriate: "standby server", "... the server parses query ...",
"server configuration", "server process".
Because of its ambiguous usage, the definition of "server" must clarify
the allowed meanings. What's about:
--
server: Depending on the context, the term *server* denotes:
* An IP-port which is offered by any OS. ?????
* A - possibly virtualized - machine
* An abbreviation for the slightly longer term "database(s)/cluster
server" ??? this will support the readability, but not the clarity ???
* More ?
--
The term "host" is used mainly for IP configuration "host name", "host
address" and in the context of compiling "host language", "host
variable". These are clear situations and can be defined easily.
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-05-20 11:38 Laurenz Albe <[email protected]>
parent: Jürgen Purtz <[email protected]>
0 siblings, 0 replies; 97+ messages in thread
From: Laurenz Albe @ 2020-05-20 11:38 UTC (permalink / raw)
To: Jürgen Purtz <[email protected]>; [email protected]; Pg Docs <[email protected]>; +Cc: Erik Rijkers <[email protected]>; Fabien COELHO <[email protected]>; Corey Huinker <[email protected]>; Justin Pryzby <[email protected]>; Roger Harkavy <[email protected]>
On Wed, 2020-05-20 at 13:17 +0200, Jürgen Purtz wrote:
> > FWIW, I feel somewhat like Alvaro on that point; I use those terms synonymously,
> > perhaps distinguishing between a "started cluster" and a "stopped cluster".
> > After all, "cluster" refers to "a cluster of databases", which are there, regardless
> > if you start the server or not.
> >
> > The term "cluster" is unfortunate, because to most people it suggests a group of
> > machines, so the term "instance" is better, but that ship has sailed long ago.
> >
> > The static part of a cluster to me is the "data directory".
>
> cluster/instance: The different nature (static/dynamic) of what I
> call "cluster" and "instance" as well as the existence of the two
> commands "initdb — create a new PostgreSQL database cluster" and
> "pg_ctl — initialize, start, stop, or control a PostgreSQL server"
> confirms me in my opinion that we need two different terms for
> them.
I think that the "pg_ctl" example does not apply:
It does not talk about starting the cluster, but about starting the server process,
that is "server" in the way I understand it.
> There are situations where we need a single term for both of
> them. "Instance and its data directory" or "Instance and its
> cluster" are too wordy. In many cases we use "database server" or
> "server" in this sense. Imo "Server" is too short and ambiguous.
> "database server", the plural form "databases server", or the new
> term "cluster server", which is more accurate, would be ok for me.
> (Similar to "server", the term "cluster" is also used in many
> different contexts - but only outside of the PG world; within our
> context "cluster" is not ambiguous.)
That does not feel right to me.
"cluster server", ouch. "databases server", ouch as well.
I never felt the term "cluster" was unclear in these contexts.
Sometimes it means "data directory", sometimes it is used for "server process",
but I think few people would think one cound connect to a data directory
or create a process in a directory (initdb).
I think clarity is a Good Thing, but it can be overdone.
> > > server/host: We need a term to describe the underlying hardware respectively
> > > the virtual machine or container, where PG is running. I suggest to use both
> > > *server* and *host*. In computer science, both have their eligibility and are
> > > widely used. Everybody understands *client/server architecture* or *host* in
> > > TCP/IP configuration. We cannot change such matter of course. I suggest to
> > > use both depending on the context, but with the same meaning: "real hardware,
> > > a container, or a virtual machine".
> >
> > On this I have a strong opinion because of my Unix mindset.
> > "machine" and "host" are synonyms, and it doesn't matter to the database if they
> > are virtualized or not. You can always disambiguate by adding "virtual" or "physical".
> >
> > A "server" is a piece of software that responds to client requests, never a machine.
> > In my book, this is purely Windows jargon. The term "client-server architecture"
> > that you quote emphasized that.
> >
> > Perhaps "machine" would be the preferable term, because "host" is more prone to
> > misunderstandings (except in a networking context).
>
> server/host: I agree that we are not interested in the question
> whether there is real hardware or any virtualization container. We
> are even not interested in the operating system. Our primary
> concern is the existence of a port of the Internet Protocol. But
> is the term "server" appropriate to name an IP-port? Additionally,
> "server" is used for other meanings: a) the previously mentioned
> "database server" b) a (virtual) machine: "server-side", "... the
> file ... loaded by the server ..." c) binaries "... the server
> must be built with SSL support ..." d) whenever it seems to be
> appropriate: "standby server", "... the server parses query ...",
> "server configuration", "server process".
You are most thorough :^)
> Because of its ambiguous usage, the definition of "server" must
> clarify the allowed meanings. What's about:
>
> server: Depending on the context, the term *server* denotes:
>
> An IP-port which is offered by any OS. ?????
A port is a server? No way.
> A - possibly virtualized - machine
It might be good to disambiguate that, but I don't think that the PostgreSQL
documentation should use the word "server" to mean "machine".
> An abbreviation for the slightly longer term
> "database(s)/cluster server" ??? this will support the
> readability, but not the clarity ???
"Server" is short for "database server" and is a set of processes that listen
for and handle incoming database client requests.
I think that covers all the meanings you quoted from the documentation,
except c), where it is used as shorthand for "server executable".
Yours,
Laurenz Albe
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-05-26 12:01 Peter Eisentraut <[email protected]>
parent: Corey Huinker <[email protected]>
0 siblings, 0 replies; 97+ messages in thread
From: Peter Eisentraut @ 2020-05-26 12:01 UTC (permalink / raw)
To: Corey Huinker <[email protected]>; +Cc: [email protected]
On 2020-04-29 21:55, Corey Huinker wrote:
> On Wed, Apr 29, 2020 at 3:15 PM Peter Eisentraut
> <[email protected]
> <mailto:[email protected]>> wrote:
>
> Why are all the glossary terms capitalized? Seems kind of strange.
>
>
> They weren't intended to be, and they don't appear to be in the page I'm
> looking at. Are you referring to the anchor like in
> https://www.postgresql.org/docs/devel/glossary.html#GLOSSARY-RELATION ?
> If so, that all-capping is part of the rendering, as the ids were all
> named in all-lower-case.
Sorry, I meant why is the first letter of each term capitalized. That
seems unusual.
--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-06-09 11:25 Jürgen Purtz <[email protected]>
parent: Alvaro Herrera <[email protected]>
1 sibling, 1 reply; 97+ messages in thread
From: Jürgen Purtz @ 2020-06-09 11:25 UTC (permalink / raw)
To: Alvaro Herrera <[email protected]>; +Cc: Erik Rijkers <[email protected]>; Laurenz Albe <[email protected]>; Fabien COELHO <[email protected]>; Peter Eisentraut <[email protected]>; Corey Huinker <[email protected]>; Justin Pryzby <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Michael Paquier <[email protected]>; Pg Docs <[email protected]>
On 17.05.20 17:28, Alvaro Herrera wrote:
> I think the terms under discussion are just
>
> * cluster
> * instance
> * server
Despite the short period of its existence the glossary achieved some
importance, see:
https://www.postgresql.org/message-id/b8e12875ebec9e6d3107df5fa1129e1e%40postgrespro.ru
. We have to be careful with publications. It's not acceptable that we
change definitions from release to release. Therefore IMO we should mark
or even ignore such terms for which we cannot reach consensus.
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."
- "Database" (No change to existing definition): "A named collection of
SQL objects."
- "Database Cluster", "Cluster" (New definition and rearrangements of
some sentences): "A collection of related databases, and their common
static and dynamic meta-data.
This term is sometimes used to refer to an instance.
(Don't confuse the term CLUSTER with the SQL command CLUSTER.)"
- "Data Directory" (Replaced 'instance' by 'cluster'): "The base
directory on the filesystem of a server that contains all data files and
subdirectories associated with a cluster (with the exception of
tablespaces). The environment variable PGDATA is commonly used to refer
to the data directory.
A cluster's storage space comprises the data directory plus any
additional tablespaces.
For more information, see Section 68.1."
- "Database Server", "Instance" (Major changes): "A group of backend and
auxiliary processes that communicate using a common shared memory area.
One postmaster process manages the instance; one instance manages
exactly one cluster with all its databases. Many instances can run on
the same server as long as their TCP ports do not conflict.
The instance handles all key features of a DBMS: read and write access
to files and shared memory, assurance of the ACID properties,
connections to client processes, privilege verification, crash recovery,
replication, etc."
- "Server" (No change to existing definition): "A computer on which
PostgreSQL instances run. The term server denotes real hardware, a
container, or a virtual machine.
This term is sometimes used to refer to an instance or to a host."
- "Host" (No change to existing definition): "A computer that
communicates with other computers over a network. This is sometimes used
as a synonym for server. It is also used to refer to a computer where
client processes run."
--
Jürgen Purtz
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-06-17 00:09 Alvaro Herrera <[email protected]>
parent: Jürgen Purtz <[email protected]>
0 siblings, 2 replies; 97+ messages in thread
From: Alvaro Herrera @ 2020-06-17 00:09 UTC (permalink / raw)
To: Jürgen Purtz <[email protected]>; +Cc: Erik Rijkers <[email protected]>; Laurenz Albe <[email protected]>; Fabien COELHO <[email protected]>; Peter Eisentraut <[email protected]>; Corey Huinker <[email protected]>; Justin Pryzby <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Michael Paquier <[email protected]>; Pg Docs <[email protected]>
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.
--
Álvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Attachments:
[text/x-diff] glossary.patch (7.9K, 2-glossary.patch)
download | inline diff:
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
index 25b03f3b37..e29b55e5ac 100644
--- a/doc/src/sgml/glossary.sgml
+++ b/doc/src/sgml/glossary.sgml
@@ -395,15 +395,15 @@
<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>).
+ 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>).
The environment variable <literal>PGDATA</literal> is commonly used to
- refer to the
- <glossterm linkend="glossary-data-directory">data directory</glossterm>.
+ refer to the data directory.
</para>
<para>
- An <glossterm linkend="glossary-instance">instance</glossterm>'s storage
+ A <glossterm linkend="glossary-instance">cluster</glossterm>'s storage
space comprises the data directory plus any additional tablespaces.
</para>
<para>
@@ -418,7 +418,7 @@
<glossdef>
<para>
A named collection of
- <glossterm linkend="glossary-sql-object">SQL objects</glossterm>.
+ <glossterm linkend="glossary-sql-object">local SQL objects</glossterm>.
</para>
<para>
For more information, see
@@ -427,6 +427,22 @@
</glossdef>
</glossentry>
+ <glossentry id="glossary-db-cluster">
+ <glossterm>Database cluster</glossterm>
+ <glossdef>
+ <para>
+ A collection of databases and global SQL objects,
+ and their common static and dynamic meta-data.
+ Sometimes referred to as a
+ <firstterm>cluster</firstterm>.
+ </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>
+ </glossentry>
+
<glossentry>
<glossterm>Database server</glossterm>
<glosssee otherterm="glossary-instance" />
@@ -634,7 +650,7 @@
<glossterm>Function</glossterm>
<glossdef>
<para>
- Any defined transformation of data. Many functions are already defined
+ A defined transformation of data. Many functions are already defined
within <productname>PostgreSQL</productname> itself, but user-defined
ones can also be added.
</para>
@@ -724,14 +740,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 +753,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>
@@ -1245,12 +1255,17 @@
<glossterm linkend="glossary-sql-object">SQL objects</glossterm>,
which all reside in the same
<glossterm linkend="glossary-database">database</glossterm>.
- Each SQL object must reside in exactly one schema.
+ Each SQL object must reside in exactly one schema
+ (though certain types of SQL objects exist outside schemas).
</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.
+ For local objects that exist outside schemas, their names are enforced
+ unique across the whole database. For global objects, their names
+ are enforced unique across the whole
+ <glossterm linkend="glossary-db-cluster">database cluster</glossterm>.
</para>
<para>
All system-defined SQL objects reside in schema <literal>pg_catalog</literal>,
@@ -1384,27 +1399,34 @@
</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">all types of relations</glossterm>,
+ <glossterm linkend="glossary-function">all types of functions</glossterm>,
+ data types, etc.
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>
+ </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>.
+ </para>
<para>
For more information, see
<xref linkend="manage-ag-overview"/>.
@@ -1489,7 +1511,7 @@
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
+ Initially, a database cluster contains a single usable tablespace which is
used as the default one for all SQL objects, called <literal>pg_default</literal>.
</para>
<para>
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-06-17 00:33 Justin Pryzby <[email protected]>
parent: Alvaro Herrera <[email protected]>
1 sibling, 1 reply; 97+ messages in thread
From: Justin Pryzby @ 2020-06-17 00:33 UTC (permalink / raw)
To: Alvaro Herrera <[email protected]>; +Cc: Jürgen Purtz <[email protected]>; Erik Rijkers <[email protected]>; Laurenz Albe <[email protected]>; Fabien COELHO <[email protected]>; Peter Eisentraut <[email protected]>; Corey Huinker <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Michael Paquier <[email protected]>; Pg Docs <[email protected]>
On Tue, Jun 16, 2020 at 08:09:26PM -0400, Alvaro Herrera wrote:
> diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
> index 25b03f3b37..e29b55e5ac 100644
> --- a/doc/src/sgml/glossary.sgml
> +++ b/doc/src/sgml/glossary.sgml
> @@ -395,15 +395,15 @@
> <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>).
> + 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) WAL
> + <glossentry id="glossary-db-cluster">
> + <glossterm>Database cluster</glossterm>
> + <glossdef>
> + <para>
> + A collection of databases and global SQL objects,
> + and their common static and dynamic meta-data.
metadata
> @@ -1245,12 +1255,17 @@
> <glossterm linkend="glossary-sql-object">SQL objects</glossterm>,
> which all reside in the same
> <glossterm linkend="glossary-database">database</glossterm>.
> - Each SQL object must reside in exactly one schema.
> + Each SQL object must reside in exactly one schema
> + (though certain types of SQL objects exist outside schemas).
(except for global objects which ..)
> <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.
> + For local objects that exist outside schemas, their names are enforced
> + unique across the whole database. For global objects, their names
I would say "unique within the database"
> + are enforced unique across the whole
> + <glossterm linkend="glossary-db-cluster">database cluster</glossterm>.
and "unique within the whole db cluster"
> 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">all types of relations</glossterm>,
> + <glossterm linkend="glossary-function">all types of functions</glossterm>,
Maybe say: >Relations< (all types), and >Functions< (all types)
> used as the default one for all SQL objects, called <literal>pg_default</literal>.
"the default" (remove "one")
--
Justin
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-06-17 12:52 Jürgen Purtz <[email protected]>
parent: Alvaro Herrera <[email protected]>
1 sibling, 0 replies; 97+ messages in thread
From: Jürgen Purtz @ 2020-06-17 12:52 UTC (permalink / raw)
To: Alvaro Herrera <[email protected]>; +Cc: Erik Rijkers <[email protected]>; Laurenz Albe <[email protected]>; Fabien COELHO <[email protected]>; Peter Eisentraut <[email protected]>; Corey Huinker <[email protected]>; Justin Pryzby <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Michael Paquier <[email protected]>; Pg Docs <[email protected]>
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
Attachments:
[text/x-patch] 0004-glossary.patch (1.9K, 3-0004-glossary.patch)
download | inline diff:
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 @@
</glossdef>
</glossentry>
+ <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 become clean when written
+ to disk. New pages, which initially exist in memory only, are also
+ dirty until written.
+ </para>
+ </glossdef>
+ </glossentry>
+
<glossentry id="glossary-database">
<glossterm>Database</glossterm>
<glossdef>
@@ -441,6 +457,7 @@
<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>
<glossentry>
@@ -448,22 +465,6 @@
<glosssee otherterm="glossary-instance" />
</glossentry>
- <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 become clean when written
- to disk. New pages, which initially exist in memory only, are also
- dirty until written.
- </para>
- </glossdef>
- </glossentry>
-
<glossentry id="glossary-datum">
<glossterm>Datum</glossterm>
<glossdef>
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-06-18 23:51 Alvaro Herrera <[email protected]>
parent: Justin Pryzby <[email protected]>
0 siblings, 1 reply; 97+ messages in thread
From: Alvaro Herrera @ 2020-06-18 23:51 UTC (permalink / raw)
To: Justin Pryzby <[email protected]>; Jürgen Purtz <[email protected]>; +Cc: Erik Rijkers <[email protected]>; Laurenz Albe <[email protected]>; Fabien COELHO <[email protected]>; Peter Eisentraut <[email protected]>; Corey Huinker <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Michael Paquier <[email protected]>; Pg Docs <[email protected]>
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, 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>.
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-06-19 15:45 Erik Rijkers <[email protected]>
parent: Alvaro Herrera <[email protected]>
0 siblings, 1 reply; 97+ messages in thread
From: Erik Rijkers @ 2020-06-19 15:45 UTC (permalink / raw)
To: Alvaro Herrera <[email protected]>; +Cc: Justin Pryzby <[email protected]>; Jürgen Purtz <[email protected]>; Laurenz Albe <[email protected]>; Fabien COELHO <[email protected]>; Peter Eisentraut <[email protected]>; Corey Huinker <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Michael Paquier <[email protected]>; Pg Docs <[email protected]>
On 2020-06-19 01:51, Alvaro Herrera wrote:
> On 2020-Jun-16, Justin Pryzby wrote:
>> On Tue, Jun 16, 2020 at 08:09:26PM -0400, Alvaro Herrera wrote:
I noticed one typo:
'aggregates functions' should be
'aggregate functions'
And one thing that I am not sure of (but strikes me as a bit odd):
there are several cases of
'are enforced unique'. Should that not be
'are enforced to be unique' ?
Anther small mistake (2x):
'The name of such objects of the same type are' should be
'The names of such objects of the same type are'
(this phrase occurs 2x wrong, 1x correct)
thanks,
Erik Rijkers
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-06-19 17:10 Alvaro Herrera <[email protected]>
parent: Erik Rijkers <[email protected]>
0 siblings, 1 reply; 97+ messages in thread
From: Alvaro Herrera @ 2020-06-19 17:10 UTC (permalink / raw)
To: Erik Rijkers <[email protected]>; +Cc: Justin Pryzby <[email protected]>; Jürgen Purtz <[email protected]>; Laurenz Albe <[email protected]>; Fabien COELHO <[email protected]>; Peter Eisentraut <[email protected]>; Corey Huinker <[email protected]>; Roger Harkavy <[email protected]>; [email protected]; Michael Paquier <[email protected]>; Pg Docs <[email protected]>
Thanks for these fixes! I included all of these.
On 2020-Jun-19, Erik Rijkers wrote:
> And one thing that I am not sure of (but strikes me as a bit odd):
> there are several cases of
> 'are enforced unique'. Should that not be
> 'are enforced to be unique' ?
I included this change too; I am not too sure of it myself. If some
English language neatnik wants to argue one way or the other, be my
guest.
--
Álvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-07-21 11:47 Jürgen Purtz <[email protected]>
parent: Alvaro Herrera <[email protected]>
0 siblings, 1 reply; 97+ messages in thread
From: Jürgen Purtz @ 2020-07-21 11:47 UTC (permalink / raw)
To: [email protected]
On 19.06.20 19:10, Alvaro Herrera wrote:
> Thanks for these fixes! I included all of these.
>
> On 2020-Jun-19, Erik Rijkers wrote:
>
>> And one thing that I am not sure of (but strikes me as a bit odd):
>> there are several cases of
>> 'are enforced unique'. Should that not be
>> 'are enforced to be unique' ?
> I included this change too; I am not too sure of it myself. If some
> English language neatnik wants to argue one way or the other, be my
> guest.
>
- Added '(process)' to the two terms 'Autovacuum' and 'Stats Collector'
- Removed link to himself in 'Logger (process)'
- new term: Base Backup
--
Jürgen Purtz
Attachments:
[text/x-patch] 0005-glossary.patch (1.7K, 2-0005-glossary.patch)
download | inline diff:
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
index 76525c6302..58e5071642 100644
--- a/doc/src/sgml/glossary.sgml
+++ b/doc/src/sgml/glossary.sgml
@@ -108,7 +108,7 @@
</glossentry>
<glossentry id="glossary-autovacuum">
- <glossterm>Autovacuum</glossterm>
+ <glossterm>Autovacuum (process)</glossterm>
<glossdef>
<para>
A set of background processes that routinely perform
@@ -178,6 +178,19 @@
</glossdef>
</glossentry>
+ <glossentry id="glossary-basebackup">
+ <glossterm>Base Backup</glossterm>
+ <glossdef>
+ <para>
+ A binary copy of all
+ <glossterm linkend="glossary-db-cluster">database cluster</glossterm>
+ files. It is generated by the tool <xref linkend="app-pgbasebackup"/>.
+ In combination with WAL files it can be used as the starting point
+ for recovery, log shipping, or streaming replication.
+ </para>
+ </glossdef>
+ </glossentry>
+
<glossentry id="glossary-bloat">
<glossterm>Bloat</glossterm>
<glossdef>
@@ -855,8 +868,7 @@
<glossterm>Logger (process)</glossterm>
<glossdef>
<para>
- If activated, the
- <glossterm linkend="glossary-logger">Logger</glossterm> process
+ If activated, the process
writes information about database events into the current
<glossterm linkend="glossary-log-file">log file</glossterm>.
When reaching certain time- or
@@ -1486,7 +1498,7 @@
</glossentry>
<glossentry id="glossary-stats-collector">
- <glossterm>Stats collector</glossterm>
+ <glossterm>Stats collector (process)</glossterm>
<glossdef>
<para>
This process collects statistical information about the
^ permalink raw reply [nested|flat] 97+ messages in thread
* Re: Add A Glossary
@ 2020-07-21 17:13 Alvaro Herrera <[email protected]>
parent: Jürgen Purtz <[email protected]>
0 siblings, 0 replies; 97+ messages in thread
From: Alvaro Herrera @ 2020-07-21 17:13 UTC (permalink / raw)
To: Jürgen Purtz <[email protected]>; +Cc: [email protected]
On 2020-Jul-21, Jürgen Purtz wrote:
> - Added '(process)' to the two terms 'Autovacuum' and 'Stats Collector'
>
> - Removed link to himself in 'Logger (process)'
>
> - new term: Base Backup
Pushed. I was not courageous enough to include "base backup" in 13, so
that one's in master only, but the other ones are in both branches.
--
Álvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 97+ messages in thread
end of thread, other threads:[~2020-07-21 17:13 UTC | newest]
Thread overview: 97+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2019-10-13 20:52 Add A Glossary Corey Huinker <[email protected]>
2019-11-09 08:19 ` Fabien COELHO <[email protected]>
2019-11-25 07:55 ` Michael Paquier <[email protected]>
2020-02-12 04:22 ` Corey Huinker <[email protected]>
2020-03-10 15:37 ` Corey Huinker <[email protected]>
2020-03-11 13:40 ` Roger Harkavy <[email protected]>
2020-03-11 16:50 ` Jürgen Purtz <[email protected]>
2020-03-11 16:56 ` Corey Huinker <[email protected]>
2020-03-11 17:23 ` Corey Huinker <[email protected]>
2020-03-11 17:36 ` Corey Huinker <[email protected]>
2020-03-13 04:18 ` Jürgen Purtz <[email protected]>
2020-03-19 02:34 ` Corey Huinker <[email protected]>
2020-03-20 00:11 ` Alvaro Herrera <[email protected]>
2020-03-20 01:41 ` Corey Huinker <[email protected]>
2020-03-20 15:48 ` Corey Huinker <[email protected]>
2020-03-20 17:51 ` Alvaro Herrera <[email protected]>
2020-03-20 18:08 ` Roger Harkavy <[email protected]>
2020-03-20 18:16 ` Corey Huinker <[email protected]>
2020-03-20 22:32 ` Jürgen Purtz <[email protected]>
2020-03-21 03:45 ` Corey Huinker <[email protected]>
2020-03-20 19:58 ` Justin Pryzby <[email protected]>
2020-03-20 22:32 ` Jürgen Purtz <[email protected]>
2020-03-20 23:03 ` Justin Pryzby <[email protected]>
2020-03-21 14:08 ` Jürgen Purtz <[email protected]>
2020-03-21 15:15 ` Justin Pryzby <[email protected]>
2020-03-27 20:12 ` Justin Pryzby <[email protected]>
2020-03-29 09:29 ` Jürgen Purtz <[email protected]>
2020-03-30 17:10 ` Corey Huinker <[email protected]>
2020-03-31 14:13 ` Jürgen Purtz <[email protected]>
2020-03-31 17:58 ` Justin Pryzby <[email protected]>
2020-04-01 07:34 ` Jürgen Purtz <[email protected]>
2020-04-02 00:09 ` Alvaro Herrera <[email protected]>
2020-04-02 03:34 ` Corey Huinker <[email protected]>
2020-04-02 12:44 ` Jürgen Purtz <[email protected]>
2020-04-02 19:40 ` Corey Huinker <[email protected]>
2020-04-02 22:09 ` Alvaro Herrera <[email protected]>
2020-04-02 22:26 ` Justin Pryzby <[email protected]>
2020-04-03 16:45 ` Alvaro Herrera <[email protected]>
2020-04-03 17:34 ` Corey Huinker <[email protected]>
2020-04-03 17:37 ` Roger Harkavy <[email protected]>
2020-04-03 17:41 ` Erik Rijkers <[email protected]>
2020-04-03 20:51 ` Alvaro Herrera <[email protected]>
2020-04-03 21:01 ` Justin Pryzby <[email protected]>
2020-04-04 04:04 ` Laurenz Albe <[email protected]>
2020-04-04 12:30 ` Jürgen Purtz <[email protected]>
2020-04-04 06:55 ` Fabien COELHO <[email protected]>
2020-04-04 16:52 ` Corey Huinker <[email protected]>
2020-04-05 07:38 ` Fabien COELHO <[email protected]>
2020-04-05 22:07 ` Alvaro Herrera <[email protected]>
2020-04-03 21:05 ` Erik Rijkers <[email protected]>
2020-04-05 08:41 ` Jürgen Purtz <[email protected]>
2020-04-05 19:00 ` Alvaro Herrera <[email protected]>
2020-04-11 12:10 ` Jürgen Purtz <[email protected]>
2020-04-11 19:47 ` Corey Huinker <[email protected]>
2020-04-12 07:36 ` Jürgen Purtz <[email protected]>
2020-05-15 00:00 ` Alvaro Herrera <[email protected]>
2020-05-15 01:03 ` Justin Pryzby <[email protected]>
2020-05-15 17:26 ` Alvaro Herrera <[email protected]>
2020-05-16 21:45 ` Erik Rijkers <[email protected]>
2020-05-17 02:22 ` Alvaro Herrera <[email protected]>
2020-05-17 06:15 ` Jürgen Purtz <[email protected]>
2020-05-17 06:51 ` Alvaro Herrera <[email protected]>
2020-05-17 08:09 ` Jürgen Purtz <[email protected]>
2020-05-17 08:44 ` Jürgen Purtz <[email protected]>
2020-05-17 09:08 ` Erik Rijkers <[email protected]>
2020-05-17 15:28 ` Alvaro Herrera <[email protected]>
2020-05-18 16:08 ` Jürgen Purtz <[email protected]>
2020-05-19 06:17 ` Laurenz Albe <[email protected]>
2020-05-19 06:44 ` Andrew Grillet <[email protected]>
2020-05-19 11:25 ` Peter Eisentraut <[email protected]>
2020-05-20 11:17 ` Jürgen Purtz <[email protected]>
2020-05-20 11:38 ` Laurenz Albe <[email protected]>
2020-06-09 11:25 ` Jürgen Purtz <[email protected]>
2020-06-17 00:09 ` Alvaro Herrera <[email protected]>
2020-06-17 00:33 ` Justin Pryzby <[email protected]>
2020-06-18 23:51 ` Alvaro Herrera <[email protected]>
2020-06-19 15:45 ` Erik Rijkers <[email protected]>
2020-06-19 17:10 ` Alvaro Herrera <[email protected]>
2020-07-21 11:47 ` Jürgen Purtz <[email protected]>
2020-07-21 17:13 ` Alvaro Herrera <[email protected]>
2020-06-17 12:52 ` Jürgen Purtz <[email protected]>
2020-03-31 18:07 ` Justin Pryzby <[email protected]>
2020-04-01 07:34 ` Jürgen Purtz <[email protected]>
2020-03-24 18:46 ` Robert Haas <[email protected]>
2020-03-24 19:27 ` Corey Huinker <[email protected]>
2020-03-24 19:40 ` Jürgen Purtz <[email protected]>
2020-03-24 19:58 ` Robert Haas <[email protected]>
2020-03-24 18:26 ` Peter Eisentraut <[email protected]>
2020-03-31 18:09 ` Justin Pryzby <[email protected]>
2020-03-31 19:26 ` Corey Huinker <[email protected]>
2020-04-02 01:09 ` Justin Pryzby <[email protected]>
2020-04-02 01:41 ` Alvaro Herrera <[email protected]>
2020-04-02 03:44 ` Corey Huinker <[email protected]>
2020-04-02 08:43 ` Alvaro Herrera <[email protected]>
2020-04-29 19:15 ` Peter Eisentraut <[email protected]>
2020-04-29 19:55 ` Corey Huinker <[email protected]>
2020-05-26 12:01 ` Peter Eisentraut <[email protected]>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox