Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.92) (envelope-from ) id 1jC4ZJ-0000t1-0h for pgsql-hackers@arkaria.postgresql.org; Wed, 11 Mar 2020 16:50:53 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.89) (envelope-from ) id 1jC4ZG-0003WG-Uv for pgsql-hackers@arkaria.postgresql.org; Wed, 11 Mar 2020 16:50:50 +0000 Received: from makus.postgresql.org ([2001:4800:3e1:1::229]) by malur.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1jC4ZG-0003VV-Dt for pgsql-hackers@lists.postgresql.org; Wed, 11 Mar 2020 16:50:50 +0000 Received: from mout.kundenserver.de ([212.227.126.187]) by makus.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.92) (envelope-from ) id 1jC4ZC-0004Mn-Oy for pgsql-hackers@postgresql.org; Wed, 11 Mar 2020 16:50:49 +0000 Received: from [10.0.7.107] ([80.242.212.26]) by mrelayeu.kundenserver.de (mreue012 [212.227.15.129]) with ESMTPSA (Nemesis) id 1N4eOd-1jMTux3BJv-011mq2; Wed, 11 Mar 2020 17:50:33 +0100 Subject: Re: Add A Glossary To: Corey Huinker Cc: Roger Harkavy , pgsql-hackers@postgresql.org, Fabien COELHO , Michael Paquier References: <20191125075507.GH99720@paquier.xyz> From: =?UTF-8?Q?J=c3=bcrgen_Purtz?= Message-ID: <763ae38f-599b-cfb9-0447-337649dfb017@purtz.de> Date: Wed, 11 Mar 2020 22:50:28 +0600 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.4.1 MIME-Version: 1.0 In-Reply-To: Content-Type: multipart/mixed; boundary="------------A3DD6A01CEB241512B8EC20A" Content-Language: en-US X-Provags-ID: V03:K1:yB2q0Lh1YN2s0ErqLeS3mked9HH1NrO4J2ImGnVkQc7Bg8v8fR6 DCgOd1JK1BQiQ0AB5hfGQhp79V6SLNHPryfQLILW6Ffa9pPwaFgklbpAo8ecLxto264Ku2G GZjqle5grxW93Q3GNcXEPIyXuAvA/P6S8eQYrMFyKyPr//API8B0+Ue8LwuFVZvNbHn3E3F x0UULVnZAtPQ5FXEX1DXA== X-Spam-Flag: NO X-UI-Out-Filterresults: notjunk:1;V03:K0:2rkaaHnQCqU=:Aw0EtWAS+AqhNlx8kqLz5y el+czKFxTwTO6GNwoKjIgQzuKpYGQKpLR9ooMMM4XN5XBUNeommzUtpGujLqpuMZhERXQPY1H Hhb04s9jixE8wYWpOCIVYOYWAUBjQJSQUP2fpYkt/nGr4H1yxxnaGSpl6gTR9pFcCxeVHd7Py cVm2Wxs9jM3muc6zDrxULDBjCnLmNAXBQUT8Lijkm5DrC/c9GfwY7FJlDeohjVFxoYvzF5yec 03f04M8asbvVRqvh8Vas7ffx39Ac0j/tIIPARzdbWp9/IAQ/78xg0eCYitNGjmhPxA3iqrNbA FkHY/+ugWob3VxnpfuGUJJTy+jbClJdlEDzpWQ5zXXAvHuEFteJmasant3vyhg1KWdwmc/HJU OgYWffwmSNOkxEBYAguzNNRNWF21QnSRf6wb8d+63LAH56h+A25NAbMzrtSeiq11T0aS6qoC3 ZnOqYO9PXq5I6nMBzKoA0R7yjcMi4IH9VLUT1FPvN1UG9XFAmfHJimGhWjUJLI+wDCj0eewMB LIDcbZyetRdQSraz7juQmkaeKWlfoYpT7TUmlViU8N2Mj/v7nvJH/u4lIFj5w4S2jxtj0Hanr 16GdIrKJBUmbwUkfCSyDLdBwPDFehOQNmAW3H7vHCnygyB8IvzEmF4H4Z/a8Y+T4BXmFpMelz RoAjrA7mbIUw9D118bDYK65eRkm1+kowfYJjYBYaebz+9Zvapq6UV/I+ZS+zF1rxteyNtyiB9 zkGDHmWAHbzLeuHmH1Xq89feQ2I5zmGwNLBxPgUCX2KwzQ+R0dFuBCsHTKaJGOPhp9KLG3ozQ IMPQCdSlHg8PlvsZ4n6vJDWPHitt3gVnapCIBGJSop21GUe0OQBPSJtSe7E6JXsUYcMTX4G List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Precedence: bulk This is a multi-part message in MIME format. --------------A3DD6A01CEB241512B8EC20A Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit 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 --------------A3DD6A01CEB241512B8EC20A Content-Type: text/x-patch; charset=UTF-8; name="0002-add-glossary-page.patch" Content-Transfer-Encoding: quoted-printable Content-Disposition: attachment; filename="0002-add-glossary-page.patch" 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 @@ Glossary - This is a list of terms and their in the context of Postg= reSQL and Databases in general. + This is a list of terms and their meaning in the context of PostgreSQL and Databases in gener= al. @@ -44,7 +44,7 @@ Atomic - In reference to the value of an Attribute o= r Datum: cannot be broken up into smaller componen= ts. + In reference to the value of an Attribute o= r Datum: cannot be broken down into smaller compon= ents. 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 Transacti= on, and that transaction is said to be= Atomic. @@ -56,7 +56,7 @@ Attribute - A typed data element found within a Tuple o= r Relation or Table. + An element with a certain name and data type found within a Tuple or Table. @@ -164,12 +164,30 @@ any Attribute in the Relation, but =20 + + Checkpoint + + + A + Checkpoint + is a point in time when all older dirty + pages of the Shared Memory, + all older WAL records, and a + special Checkpoint record + have been written and flushed to disk. + + + + Cluster A group of Databases plus their = Global SQL Objects. The Cluster is man= aged by exactly one Instance. A newly created Cluster will have three Databases created automatically. They are template0, template1, and postgres. It is expected tha= t an application will create one or more additional Databases<= /glossterm> aside from these three. + + Don't confuse the PostgreSQL specific t= erm Cluster with the SQL command Cluster<= /literal>. + =20 @@ -198,7 +216,7 @@ any Attribute in the Relation, but Concurrency - The concept that multiple independent operations can be happening = within the Database at the same time. + The concept that multiple independent operations happen within the= Database at the same time. @@ -216,7 +234,7 @@ any Attribute in the Relation, but Constraint - A method of restricting the values of data allowed within a Table. + A concept of restricting the values of data allowed within a Table. For more information, see Constr= aints. @@ -238,7 +256,7 @@ any Attribute in the Relation, but The base directory on the filesystem of a Server that contains all data -files and subdirectories associated with a Cluster. The name for this directory in configuration files is PGD= ATA. + files and subdirectories associated with a Cluster with the exception of tablespaces. The environment variable PGDATA often - but not always - referes to the D= ata Directory. For more information, see Da= tabase Physical Storage: Database File Layout. @@ -250,7 +268,7 @@ files and subdirectories associated with a Cluster. The n Database - A named collection of SQL Objects. =20 + A named collection of SQL Objects. For more information, see Man= aging Databases: Overview. @@ -292,14 +310,13 @@ files and subdirectories associated with a Cluster. The n File Segment - If a Database object grows in size past a = designated limit, it may be -split into multiple physical files. These files are called Fi= le Segments. + If a heap or index file grows in size over 1 GB, it will be split= into multiple physical files. These files are called File Seg= ments. - (Don't confuse this term with the similar term WAL Segm= ent). + For more information, see Da= tabase Physical Storage: Database File Layout. - For more information, see Da= tabase Physical Storage: Database File Layout. + (Don't confuse this term with the similar term WAL Segm= ent). @@ -353,7 +370,7 @@ split into multiple physical files. These files are c= alled File Segme Function - Any pre-defined tranformation of data. Many Functions are already defined within PostgreSQL itself, but can also be user-defined. + Any pre-defined transformation of data. Many Functions<= /glossterm> are already defined within PostgreSQL itself, but can also be user-defined. For more information, see SQL= Commands: CREATE FUNCTION. @@ -365,7 +382,7 @@ split into multiple physical files. These files are c= alled File Segme Global SQL Object - Not all objects belong to a certain Schema,= or to their Database, or even to the complete Cluster. These are referred to as Global S= QL Objects. Collations and Extensions such as Fore= ign Data Wrappers reside at the Database level; Database names, Roles, Tablespaces, Replication origins, and subscriptions for logical Replication at the Cluster level. + Not all SQL Objects belong to a certain Schema. Some belong to the complete Databa= se, or even to the complete Cluster. T= hese are referred to as Global SQL Objects. Collat= ions and Extensions such as Foreign Data Wrappers = reside at the Database level; Database<= /glossterm> names, Roles, Tablespaces, Replication origins, and subscriptions= for logical Replication at the Cluster= level. @@ -391,7 +408,7 @@ split into multiple physical files. These files are c= alled File Segme =20 - + Host @@ -404,7 +421,7 @@ split into multiple physical files. These files are c= alled File Segme Index - A Relation that contains data derived from = a Table (or Relation such a= s a Materialized View) that stores the data in a w= ay that makes specific values easier to retrieve. + A Relation that contains data derived from = a Table (or Relation such a= s a Materialized View). It's internal structure su= pports very fast retrieval of and access to the original data. For more information, see SQL Co= mmands: CREATE INDEX. @@ -466,7 +483,33 @@ split into multiple physical files. These files are = called File Segme =20 - + + Log File + + + LOG files + contain readable text lines about serious + and non-serious events, e.g.: use of + wrong password, long-running queries, ... . + + + + + + Log Writer + + + If activated and parameterized, the + Log Writer + process writes information about database events into the + current Log file. When reaching + certain time- or volume-dependent criterias, he creates + a new Log file. + + + + + Log Record @@ -528,10 +571,10 @@ data in the same way that a Table does. it cannot be modi Partition - A Table that can be queried independently b= y its own name, but can also be queried via another Table, a partitioend Table, which is a collectio= n of sub-Tables, each capable of holding one defin= ed subset of information that does not overlap with any other = Table in the set of Tables. + a) A Table that can be queried independentl= y by its own name, but can also be queried via another Table, a partitionend Table, which is a colle= ction of sub-Tables, each capable of holding one d= efined subset of information that does not overlap with any other Table in the set of Tables. - A defined boundary used in an Analytic Function to identify which neighboring Rows= can be considered by the Function for= this particular Row. + b) A defined boundary used in an Analytic <= glossterm>Function to identify which neighboring R= ows can be considered by the Function = for this particular Row. @@ -573,7 +616,7 @@ data in the same way that a Table does. it cannot be modi Record - A data structure that consists of one or more Attribute= s in a defined order. + See Tupple. A single Row of a Table or other Relation. @@ -603,7 +646,7 @@ data in the same way that a Table does. it cannot be modi Replica - 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 fo= r doing this are to allow for greater access to that data, and to maintai= n availability of the data in the even that the Master becomes unavailable. + 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 fo= r doing this are to allow for greater access to that data, and to maintai= n availability of the data in the event that the Master becomes unavailable. @@ -621,7 +664,7 @@ data in the same way that a Table does. it cannot be modi Result Set - A data structure tranmitted from a Server t= o client program upon the completion of a SQL command,= usually a SELECT but it can be an INSERT, UPDATE, or DELETE command i= f the RETURNING clause is specified. The data structur= e consists of zero or more Rows with the same orde= red set of Attributes. + A data structure transmitted from a Server = to client program upon the completion of a SQL command= , usually a SELECT but it can be an INSERT, UPDATE, or DELETE command = if the RETURNING clause is specified. The data structu= re consists of zero or more Rows with the same ord= ered set of Attributes. @@ -666,7 +709,7 @@ data in the same way that a Table does. it cannot be modi Row - A Tuple or Record fo= und within a Relation or a Result Set. This term is often used interchangably with Record= and Tuple. + See Tupple. @@ -687,7 +730,22 @@ data in the same way that a Table does. it cannot be modi Schema - A means of organizing a collection of objects residing in the same= Database to facilitate clarity or security. Schemas are most often used in the same way that a name= space is used in programming languages. All objects belong to exactly one= Schema, most commonly "public", the default Schema. + A schema is a + namespace for SQL objects, which + all reside in the same database. + Each SQL object must reside in + exactly one Schema. + + + The names of SQL objects in the + schema are unique - even across different types of objects. + Same object names can only be used in different schemas. + + + Many SQL objects reside in the default + Schema public, but it + is expected that more schemas are created to hold application + specific SQL objects. More generically, the term Schema is used t= o mean all data descriptions (Table definitions, <= glossterm>Constraints, comments) for a given Datab= ase. @@ -717,7 +775,7 @@ data in the same way that a Table does. it cannot be modi Serializable - Database Sessions in= a transaction defined as SERIALIZABLE are unable to s= ee changes made to the Database by other sessions.= In effect, the entire Database appears to be froz= en in time for the duration of the Transaction. + Transactions defined as SERIALIZABLE are unable= to see changes made within other transactions. In effect, for the initia= lizing session the entire Database appears to be f= rozen duration such a Transaction. (??? Isn't it t= he other way round: changes done by serializable transactions are not see= n by other transactions ???) @@ -747,7 +805,7 @@ data in the same way that a Table does. it cannot be modi Sequence - An Database object which represents the ma= thematical concept of a generic numerical sequence. It can be thought of = as a Table with exactly one Row and one Column. The value stores is know as t= he current value. A Sequence has a defined directi= on (almost always increasing) and an interval step (usually 1). Whenever= the NEXTVAL pseudo-column of a Sequence 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 n= ew 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. Valu= es taken from a Sequence are never reverted even i= n the case of a Rollback, which means that the Sequence will never emit the same number twice, and t= hus is the normal way of generating values to be put in a Prim= ary Key. + An Database object which represents the ma= thematical concept of a numerical integral sequence. It can be thought of= as a Table with exactly one Row and one Column. The value stored is known as= the current value. A Sequence has a defined direc= tion (almost always increasing) and an interval step (usually 1). Whenev= er the NEXTVAL pseudo-column of a Sequence<= /glossterm> is accessed, the curent value is moved in the defined directi= on by the defined interval step, and that value is returned to the invoki= ng 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, th= e net effect being that each row selected will have a different value. Va= lues taken from a Sequence are never reverted even= in the case of a Rollback, which means that the <= glossterm>Sequence will never emit the same number twice, and= thus is the normal way of generating values to be put in a Pr= imary Key. For more information, see SQL= Commands: CREATE SEQUENCE. @@ -810,7 +868,7 @@ data in the same way that a Table does. it cannot be modi Table - A collection of Tuples (also known as Rows or Records) having a common= data structure (the same number of Attributess, i= n the same order, having the same name and type). A Table is the most common form of Relation in PostgreSQL. + A collection of Tuples (also known as Rows or Records) having a common= data structure (the same number of Attributess, i= n the same order, having the same name and type per position). A Table is the most common form of Relation in PostgreSQL. For more information, see SQL Co= mmands: CREATE TABLE. @@ -834,7 +892,7 @@ data in the same way that a Table does. it cannot be modi Transaction - A combination of one or more commands that must act as a single Atomic command: they all succeed or fail together, a= nd their effects are not visible to other sessions until the T= ransaction is complete. + A combination of one or more commands that must act as a single Atomic command: they all succeed or fail together, a= nd their effects are not visible to other sessions until the T= ransaction is complete. (??? non repeatable read, phantom rea= d, serialization ananomaly are possible ???) @@ -873,8 +931,8 @@ data in the same way that a Table does. it cannot be modi Unlogged - A Relation that is unlogged will not have c= hanges reflected in the WAL Log, -which would enable those changes to be duplicated on a Replic= a, and also enables the change to survive a Databa= se crash. + Changes to an unlogged Relation are not ref= lected in the WAL Log. + This disables replication and crash recovery for such R= elations. @@ -953,7 +1011,7 @@ cannot create Rows nor can it= remove RowsWAL Record - A WAL Record contains either new or changed= Heap or Index data or othe= r binary information about a COMMIT, ROLLBACK= , SAVEPOINT, or Checkpointer operation. + A WAL Record contains either new or changed= Heap or Index data or info= rmation about a COMMIT, ROLLBACK, <= command>SAVEPOINT, or Checkpointer opera= tion. WAL records use a non-printabe binary format. For more information, see Reliabi= lity and the Write-Ahead Log: WAL Internals. --------------A3DD6A01CEB241512B8EC20A--