Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jZe6R-0005tM-TP for pgsql-hackers@arkaria.postgresql.org; Fri, 15 May 2020 17:26:32 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.92) (envelope-from ) id 1jZe6Q-0000VM-Pf for pgsql-hackers@arkaria.postgresql.org; Fri, 15 May 2020 17:26:30 +0000 Received: from makus.postgresql.org ([2001:4800:3e1:1::229]) by malur.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jZe6Q-0000VF-03 for pgsql-hackers@lists.postgresql.org; Fri, 15 May 2020 17:26:30 +0000 Received: from mail-qt1-x843.google.com ([2607:f8b0:4864:20::843]) by makus.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.92) (envelope-from ) id 1jZe6J-0007Eo-VY for pgsql-hackers@postgresql.org; Fri, 15 May 2020 17:26:29 +0000 Received: by mail-qt1-x843.google.com with SMTP id v4so2621443qte.3 for ; Fri, 15 May 2020 10:26:23 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=2ndquadrant-com.20150623.gappssmtp.com; s=20150623; h=date:from:to:cc:subject:message-id:mime-version:content-disposition :content-transfer-encoding:in-reply-to:user-agent; bh=VRB0zo0PjzRw7ZKDoIQ0ke5rfqBWtpvCAqEja+2GB+k=; b=dZ8MXBC6pz9CF2PO9VQElE1/RsLGHpgYOSONDS/tXsn2+xOpxEaA0PgSRvtMfGPo3X 1klH5NcjUt/xhSZGY4hnzucua6XwcopEHAzC6dAIUtyeNcG/tP380SMmxPWLi4pYTczL jFLfHNbj2m+LiZMeQHVtYuWWFyHn5fGB1JntzKovydneqnfNv56bmAoY+Iwwb5T7LkyQ O3L1/Bv5+VWuinEazzvINskOJF8l1zgXr3mFdsj4HvX5UNTpjgPd2UwNE8aKbqsMoPKl GK/TiWekKdw006WA6AYyF5XzULM6Hjdi/BsSB7YfMD4434gRBqzsTkBNLVoPrHLIhr0d vFKA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:cc:subject:message-id:mime-version :content-disposition:content-transfer-encoding:in-reply-to :user-agent; bh=VRB0zo0PjzRw7ZKDoIQ0ke5rfqBWtpvCAqEja+2GB+k=; b=ktgPkvYy2HPiKKzx/oYyYhUl7JQ9bCv7J/GqJ6qnPnosBOPRhiz4++vjrbueTCej3L hDAb2SJAxJO/L6vAJeh5oSMerB6Va22tBDIbP4Ojox/lUPAATuneAMSQujy3V16GY4Dw /uI9XLOYImO4L5Zka/4r+tVQFSGsT287x3cSfEPa0Kvjlip3dWhTpnGeubAxa1x1Qvet kizGdee77l30YqJWwL77sWuP/jo53R5+gLMmUgRIQgmKHwvMQT64U9CyrEMRm6nGawMt SdikX+ldsh6RXnZWbS8MceEDM6RCeyHezOm3+rzPYvtR8JEfk5N066ZfJfySf/ulK6Ag gncw== X-Gm-Message-State: AOAM530/RtfWTFUNfasnG4SYI0d9pdD4I6jnoCl2NCidmexjo/56vGVJ uTe4G2KWzTXfT2TtSZg5KmcWag== X-Google-Smtp-Source: ABdhPJxA99RICsu08LlUF596m8TIg168Q/EYweyNJoHyp9RVFWjUbrzqw1brnDUkSdMB5Ysew/yTNg== X-Received: by 2002:aed:2462:: with SMTP id s31mr4906598qtc.188.1589563582994; Fri, 15 May 2020 10:26:22 -0700 (PDT) Received: from nimloth.alvh.no-ip.org ([190.95.18.252]) by smtp.gmail.com with ESMTPSA id p81sm2057640qke.67.2020.05.15.10.26.21 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 15 May 2020 10:26:21 -0700 (PDT) Received: by nimloth.alvh.no-ip.org (Postfix, from userid 1000) id 77A803006AA; Fri, 15 May 2020 13:26:19 -0400 (-04) Date: Fri, 15 May 2020 13:26:19 -0400 From: Alvaro Herrera To: Justin Pryzby Cc: Erik Rijkers , Laurenz Albe , Fabien COELHO , =?iso-8859-1?Q?J=FCrgen?= Purtz , Peter Eisentraut , Corey Huinker , Roger Harkavy , pgsql-hackers@postgresql.org, Michael Paquier Subject: Re: Add A Glossary Message-ID: <20200515172619.GA31053@alvherre.pgsql> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="HlL+5n6rz5pIUxbD" Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: <20200515010304.GN18456@telsasoft.com> User-Agent: Mutt/1.10.1 (2018-07-13) List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Precedence: bulk --HlL+5n6rz5pIUxbD Content-Type: text/plain; charset=iso-8859-1 Content-Disposition: inline Content-Transfer-Encoding: 8bit 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 --HlL+5n6rz5pIUxbD Content-Type: text/x-diff; charset=iso-8859-1 Content-Disposition: attachment; filename="v3-0001-Review-of-the-glossary.patch" Content-Transfer-Encoding: 8bit From 6cdbfd1d9f2d6c7fa815aab853a51f86b3650e11 Mon Sep 17 00:00:00 2001 From: Alvaro Herrera Date: Fri, 15 May 2020 13:04:11 -0400 Subject: [PATCH v3] Review of the glossary MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add some more terms, clarify some definitions, remove redundant terms, move a couple of terms to keep alphabetical order. Co-authored-by: Jürgen Purtz Co-authored-by: Erik Rijkers Co-authored-by: Laurenz Albe Discussion: https://postgr.es/m/7b9b469e804777ac9df4d37716db935e@xs4all.nl --- doc/src/sgml/acronyms.sgml | 2 +- doc/src/sgml/glossary.sgml | 536 ++++++++++++++++++++++--------------- 2 files changed, 316 insertions(+), 222 deletions(-) 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 @@ XID - Transaction Identifier + Transaction identifier diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml index 8c6cb6e942..a1e8a595c8 100644 --- a/doc/src/sgml/glossary.sgml +++ b/doc/src/sgml/glossary.sgml @@ -7,8 +7,23 @@ + + ACID + + + Atomicity, + Consistency, + Isolation, and + Durability. + This set of properties of database transactions is intended to + guarantee validity in concurrent operation and even in event of + errors, power failures, etc. + + + + - Aggregate Function + Aggregate function A function that @@ -35,11 +50,15 @@ to make decisions about how to execute queries. + + (Don't confuse this term with the ANALYZE option + to the command.) + - Analytic Function + Analytic function @@ -106,8 +125,8 @@ Process of an instance - which act on behalf of client sessions - and handle their requests. + which acts on behalf of a client session + and handles its requests. (Don't confuse this term with the similar terms @@ -118,7 +137,7 @@ - Background Worker (process) + Background worker (process) Process within an instance, @@ -138,10 +157,11 @@ - Background Writer (process) + Background writer (process) - A process that continuously writes dirty pages from + A process that writes dirty + data pages from shared memory to the file system. It wakes up periodically, but works only for a short period in order to distribute its expensive I/O @@ -155,6 +175,16 @@ + + Bloat + + + Space in data pages which does not contain current row versions, + such as unused (free) space or outdated row versions. + + + + Cast @@ -190,7 +220,7 @@ - Check Constraint + Check constraint A type of constraint @@ -208,15 +238,6 @@ - - Checkpointer (process) - - - A specialized process responsible for executing checkpoints. - - - - Checkpoint @@ -244,6 +265,15 @@ + + Checkpointer (process) + + + A specialized process responsible for executing checkpoints. + + + + Class (archaic) @@ -262,27 +292,6 @@ - - Cluster - - - A group of databases plus their - global SQL objects. The - cluster is managed by exactly one - instance. A newly created - Cluster will have three databases created automatically. They are - template0, template1, and - postgres. It is expected that an application will - create one or more additional database aside from these three. - - - (Don't confuse the PostgreSQL-specific term - Cluster with the SQL - command CLUSTER). - - - - Column @@ -363,7 +372,10 @@ A restriction on the values of data allowed within a - Table. + table, + or in attributes of a + + domain. For more information, see @@ -373,19 +385,19 @@ - Data Area + Data area - Data Directory + Data directory 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. + data files and subdirectories associated with an + instance (with the + exception of tablespaces). The environment variable PGDATA is commonly used to refer to the data directory. @@ -416,15 +428,31 @@ - Database Server + Database server + + Data page + + + 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 shared buffers + where they can be modified, becoming + dirty. They become clean when written + to disk. New pages, which initially exist in memory only, are also + dirty until written. + + + + Datum - The internal representation of one value of a SQL + The internal representation of one value of an SQL data type. @@ -434,7 +462,7 @@ Delete - A SQL command which removes + An SQL command which removes rows from a given table or relation. @@ -459,6 +487,11 @@ + + Epoch + + + Extension @@ -475,12 +508,13 @@ - File Segment + File segment A physical file which stores data for a given relation. - 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. @@ -495,14 +529,14 @@ - Foreign Data Wrapper + Foreign data wrapper A means of representing data that is not contained in the local database so that it appears as if were in local - table(s). With a Foreign Data Wrapper it is + table(s). With a foreign data wrapper it is possible to define a foreign server and - foreign tables. + foreign tables. For more information, see @@ -512,7 +546,7 @@ - Foreign Key + Foreign key A type of constraint @@ -527,7 +561,7 @@ - Foreign Server + Foreign server A named collection of @@ -544,7 +578,7 @@ - Foreign Table + Foreign table A relation which appears to have @@ -564,6 +598,38 @@ + + Fork + + + Each of the separate segmented file sets in which a relation is stored. + The main fork is where the actual data resides. + There also exist two secondary forks for metadata: + the free space map + and the visibility map. + Unlogged relations + also have an init fork. + + + + + + Free space map (fork) + + + A storage structure that keeps metadata about each data page of a table's + main fork. The free space map entry for each page stores the + amount of free space that's available for future tuples, and is structured + to be efficiently searched for available space for a new tuple of a given + size. + + + For more information, see + . + + + + Function @@ -579,28 +645,11 @@ - - Global SQL Object - - - SQL objects which do - not belong to a specific - database. - - - These objects are - roles, - tablespaces, - replication origins, and subscriptions for logical replication. - - - - Grant - A SQL command that is used to allow + An SQL command that is used to allow users or role to access specific objects within the database. @@ -619,8 +668,9 @@ Contains the values of row attributes (i.e. the data) for a relation. - The heap is realized within - segment files. + The heap is realized within one of more + file segments + in the relation's main fork. @@ -629,10 +679,11 @@ Host - A computer that communicates with other hosts over a network. - This term can be used to refer to either a - client - or a server. + 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. @@ -659,7 +710,7 @@ Insert - A SQL command used to add new data into a + An SQL command used to add new data into a table. @@ -673,27 +724,28 @@ Instance - An instance is a group of processes, - its supporting storage space, - plus their - common shared memory, - running on a single server. - The instance - handles all key features of a DBMS: read and write - access to files and shared memory, assurance of - the ACID paradigm, MVCC, - connections to client programs, backup, - recovery, replication, privileges, etc. + A set of databases and accompanying global SQL objects that are stored in + the same data directory + in a single server. + If running, one + postmaster process + manages a group of backend and auxiliary processes that communicate + using a common shared memory + area. Many instances can run on the same + server + as long as their TCP ports do not conflict. - An instance manages exactly one - cluster. + 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. - Many instances can run on the same server as - long as their TCP/IP ports do not conflict. - Different instances on a server may use the - same or different versions of PostgreSQL. + In PostgreSQL, the term + cluster is also sometimes used to refer to an instance. + (Don't confuse this term with the SQL command CLUSTER.) @@ -717,7 +769,7 @@ Join - A SQL keyword used in SELECT statements for + An SQL keyword used in SELECT statements for combining data from multiple relations. @@ -748,7 +800,7 @@ - Log File + Log file Log files contain human-readable text lines about events. @@ -761,6 +813,29 @@ + + Log record + + + Archaic term for a WAL record. + + + + + + Logged + + + A table is considered + logged if changes to it are sent to the + WAL. By default, all regular + tables are logged. A table can be specified as + unlogged either at + creation time or via the ALTER TABLE command. + + + + Logger (process) @@ -780,29 +855,6 @@ - - Log Record - - - Archaic term for a WAL record. - - - - - - Logged - - - A table is considered - logged if changes to it are sent to the - WAL. By default, all regular - tables are logged. A table can be specified as - unlogged either at - creation time or via the ALTER TABLE command. - - - - Master (server) @@ -831,7 +883,7 @@ - Materialized View + Materialized view A relation that is @@ -869,8 +921,8 @@ Null - 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. @@ -881,7 +933,7 @@ - Parallel Query + Parallel query The ability to handle parts of executing a @@ -918,7 +970,7 @@ - Partitioned Table + Partitioned table A relation that is @@ -960,7 +1012,7 @@ - Primary Key + Primary key A special case of a @@ -1011,7 +1063,7 @@ - Query Planner + Query planner The part of PostgreSQL that is devoted to @@ -1034,7 +1086,7 @@ - Referential Integrity + Referential integrity A means of restricting data in one relation @@ -1055,9 +1107,11 @@ attributes defined in a specific order. Tables, + sequences, views, foreign tables, - materialized views, and + materialized views, + composite types, and indexes are all relations. @@ -1068,7 +1122,7 @@ - Replica + Replica (server) A database that is paired @@ -1098,12 +1152,13 @@ - Result Set + Result set A data structure transmitted from a backend process to - client program upon the completion of a SQL + a client upon the + completion of an SQL command, usually a SELECT but it can be an INSERT, UPDATE, or DELETE command if the RETURNING @@ -1135,7 +1190,7 @@ A collection of access privileges to the instance. - 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 users need the same privileges. @@ -1170,7 +1225,7 @@ Savepoint - A special mark inside the sequence of steps in a + A special mark in the sequence of steps in a transaction. Data modifications after this point in time may be reverted to the time of the savepoint. @@ -1186,13 +1241,15 @@ Schema - A schema is a namespace for SQL objects, + A schema is a namespace for + SQL objects, which all reside in the same - database. Each - SQL object must reside in exactly one schema. + database. + Each SQL object must reside in exactly one schema. - 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. @@ -1205,7 +1262,7 @@ - More generically, the term Schema is used to mean + More generically, the term schema is used to mean all data descriptions (table definitions, constraints, comments, etc) for a given database or @@ -1264,7 +1321,10 @@ A computer on which PostgreSQL instances run. The term server denotes real hardware, a - container, or a Virtual Machine. + container, or a virtual machine. + + + This term is sometimes used to refer to an instance or to a host. @@ -1279,45 +1339,21 @@ - - Shared Memory + Shared memory RAM which is used by the processes common to an @@ -1342,28 +1378,32 @@ + + Standby (server) + + + SQL Object - A table, - view, - materialized view, - index, - constraint, - sequence, - function, - procedure, - trigger, - data type, or operator. Every one of those SQL objects - belong to exactly one Schema. - - - There also exist SQL objects that do not belong to schemas; those include - extensions, - data type cases, - and - foreign data wrappers. + Any object that can be created with a CREATE + command. Most objects are specific to one database, and are commonly + known as local objects. + Roles, + tablespaces, + 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 global objects. + + + Most local objects belong to a specific + schema in their containing database. + There also exist local objects that do not belong to schemas; some examples are + extensions, + data type casts, and + foreign data wrappers. For more information, see @@ -1373,7 +1413,7 @@ - SQL Standard + SQL standard A series of documents that define the SQL language. @@ -1382,11 +1422,11 @@ - Stats Collector + Stats collector This process collects statistical information about the - Cluster's activities. + instance's activities. For more information, see @@ -1396,22 +1436,21 @@ - System Catalog + System catalog A collection of tables which describe the structure of all SQL objects - of each database - and the global SQL objects - of the cluster. + of the instance. The system catalog resides in the schema pg_catalog. These tables contain data in internal representation and are not typically considered useful for user examination; a number of user-friendlier views also in schema pg_catalog offer more convenient access to some of that information, while additional tables and views - exist in schema information_schema that expose some + exist in schema information_schema + (see ) that expose some of the same and additional information as mandated by the SQL standard. @@ -1431,7 +1470,7 @@ attributes, in the same order, having the same name and type per position). A table is the most common form of - Relation in + relation in PostgreSQL. @@ -1461,7 +1500,7 @@ - Temporary Table + Temporary table Tables that exist either @@ -1481,6 +1520,21 @@ + + TOAST + + + A mechanism by which large attributes of table rows are split and + stored in a secondary table, called the TOAST table. + Each relation with large attributes has its own TOAST table. + + + For more information, see + . + + + + Transaction @@ -1499,6 +1553,30 @@ + + Transaction ID + + + The numerical, unique, sequentially-assigned identifier that each + transaction receives when it first causes a database modification. + Frequently abbreviated as xid. + When stored on disk, xids are only 32-bits wide, so only + approximately four billion write transaction IDs can be generated; + to permit the system to run for longer than that, + epochs are used, also 32 bits wide. + When the counter reaches the maximum xid value, it starts over at + 3 (values under that are reserved) and the + epoch value is incremented by one. + In some contexts, the epoch and xid values are + considered together as a single 64-bit value. + + + For more information, see + . + + + + Trigger @@ -1508,7 +1586,7 @@ UPDATE, DELETE, TRUNCATE) is applied to a relation. - A Trigger executes within the same + A trigger executes within the same transaction as the statement which invoked it, and if the function fails, then the invoking statement also fails. @@ -1535,7 +1613,7 @@ - Unique Constraint + Unique constraint A type of constraint @@ -1577,7 +1655,7 @@ Update - A SQL command used to modify + An SQL command used to modify rows that may already exist in a specified table. It cannot create or remove rows. @@ -1619,9 +1697,10 @@ Vacuum - The process of removing outdated tuple - versions from tables, and other closely related - garbage-collection-like processing required by PostgreSQL's + The process of removing outdated + tuple versions + from tables or materialized views, and other closely related + processing required by PostgreSQL's implementation of MVCC. This can be initiated through the use of the VACUUM command, but can also be handled automatically @@ -1651,8 +1730,28 @@ + + Visibility map (fork) + + + A storage structure that keeps metadata about each data page + of a table's main fork. The visibility map entry for + each page stores two bits: the first one + (all-visible) indicates that all tuples + in the page are visible to all transactions. The second one + (all-frozen) indicate that all tuples + in the page are marked frozen. + + + + + + WAL + + + - WAL Archiver (process) + WAL archiver (process) A process that saves copies of WAL files @@ -1667,7 +1766,7 @@ - WAL File + WAL file Also known as WAL segment or @@ -1678,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 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. @@ -1696,13 +1795,8 @@ - - WAL - - - - WAL Record + WAL record A low-level description of an individual data change. @@ -1719,17 +1813,17 @@ - WAL Segment + WAL segment - WAL Writer (process) + WAL writer (process) A process that writes WAL records - from shared memory to - WAL files. + from shared memory to + WAL files. For more information, see @@ -1739,7 +1833,7 @@ - Window Function + Window function A type of function whose @@ -1759,7 +1853,7 @@ - Write-Ahead Log + Write-ahead log The journal that keeps track of the changes in the -- 2.20.1 --HlL+5n6rz5pIUxbD--