public inbox for [email protected]
help / color / mirror / Atom feedFrom: Jürgen Purtz <[email protected]>
To: David G. Johnston <[email protected]>
Cc: Erik Rijkers <[email protected]>
Cc: PostgreSQL Hackers <[email protected]>
Cc: Justin Pryzby <[email protected]>
Subject: Re: Additional Chapter for Tutorial
Date: Sun, 15 Nov 2020 19:45:35 +0100
Message-ID: <[email protected]> (raw)
In-Reply-To: <CAKFQuwaEp3HRgB=C3CfqLWsHqH3p_kmow+n+ERuaCRR=ozt0nw@mail.gmail.com>
References: <[email protected]>
<[email protected]>
<[email protected]>
<[email protected]>
<CAKFQuwZ_USvnhZ5wQLFtpr8v+iMiwvZOiVZhviQwPYGDVR7w+g@mail.gmail.com>
<[email protected]>
<CAKFQuwbqiZ4Er_e21oXt8J_JDyNucLMcW7murkMr0v=pTy10RA@mail.gmail.com>
<CAKFQuwbtReW3dBO0HmZCb8rF4z-w+oFt24nPko8pbAk4Y2VWEw@mail.gmail.com>
<[email protected]>
<[email protected]>
<[email protected]>
<[email protected]>
<[email protected]>
<[email protected]>
<[email protected]>
<[email protected]>
<[email protected]>
<CAKFQuwaEp3HRgB=C3CfqLWsHqH3p_kmow+n+ERuaCRR=ozt0nw@mail.gmail.com>
On 10.11.20 00:14, David G. Johnston wrote:
> Reviewed the first three sections.
>
> template0 - I would remove the schema portions of this and simply note
> this as being a pristine recovery database in the diagram.
ok
>
> I would drop the word "more" and just say "system schemas". I would
> drop pg_toast from the list of system schema and focus on the three
> user-facing ones.
ok
>
> Instead of "my_schema" (optional) I would do "my_schema" (example)
The terms 'optional' and 'default' are used at various places with their
literal meaning. We shall not change them.
>
> Server Graphic
> #3 Global SQL Objects: Objects which are shared among all databases
> within a cluster.
> #6 Client applications are prohibited from connecting to template0
ok
> #1 If by you we mean "the client" saying that you work "in the cluster
> data" doesn't really help. I would emphasize the point that the
> client sees an endpoint the Postmaster publishes as a port or socket
> file and that plus the database name defines the endpoint the client
> connects to (meld with #5)
ok, with some changes.
>
> In lieu of some of the existing detail provided about structure I
> would add information about configuration and search_path at this level.
Search path appended. But IMO configuration questions are out of scope
of this sub-chapter.
>
> I like the object type enumeration - I would suggest grouping them by
> type in a manner consistent with the documentation and making each one
> a link to its "primary" section - the SQL Command reference if all
> else fails.
ok. But don't how to group them in a better way.
>
> The "i" in internal in 51.3 (the image) needs capitalization).
ok
>
> You correctly add both Extension and Collation as database-level
> objects but they are not mentioned anywhere else. They do belong here
> and need to be tied in properly in the text.
Have some courage to the gap, it's an introductory chapter.
>
> The whole thing needs a good pass focused on capitalization. Both for
> typos and to decide when various primary concepts like Instance should
> be capitalized and when not.
'Instance' and 'Cluster' are now uppercase because of their importance,
everything else lowercase for better reading.
>
> 51.4 - When you look at the diagram seeing /pg/data/base looks really
> cool, but when reading the prose where both the "pg" and the "base"
> are omitted and all you get are repeated references to "data", the
> directory name choice becomes an issue IMO. I suggest (and changed
> the attached) to name the actual root directory "pgdata". You should
> change the /pg/ directory name to something like ".../tutorial_project/".
The graphic shall reflect the default behavior of PG. Without the
parameter -D, initdb creates the new cluster in the directory where
PGDATA points to. This is in many cases |/var/lib/pgsql/data|. Therefore
'data' and its subdirectory 'base' are not my invention but reflects the
default situation.
(Diving a little deeper into this issue I noticed that there is a
parameter 'cluster_name' in the config file. But it does not change the
name of the cluster's root directory, it only changes the names of the
running processes. Choosing 'instance_name' instead of 'cluster_name' as
the parameter's name would be a better choice imo - but that is not what
we are speaking about in the context of the new chapter).
I changed the very first directory in the graphic to visualize the
standard behavior; I reverted your recommendation to use 'pgdata'
instead of 'data' in the text part.
> Since you aren't following alphabetical order anyway I would place
> pg_tblspc after globals since tablespaces are globals and thus
> proximity links them here - and pointing out that pg_tblspc holds the
> data makes stating that global doesn't contain tablespace data
> unnecessary.
ok
>
> Maybe point out somewhere the the "base/databaseOID" directory
> represents the default tablespace for each database, which isn't
> "global", only the non-default tablespaces are considered globals (or
> just get rid of the mentioned on "non-default tablespace" for now).
ok
more:
1) some changes concerning the nature of connections (52.2: logical
perspective). IMO accessing multiple databases within one connection is
not a question of configuring, you have to take more actions. But I'm
not sure we should mention this at all.
2) you propose to cancel or trim down the paragraphs behind figure 51.2.
(cluster, database, schema). I believe that a textual description of
this hierarchy is essential for the understanding of the system. Because
it isn't described explicitly at a different place, it should remain.
--- snipp -------- from other e-mail ----
> MVCC Section
>
> The first paragraph and example in the MVCC section is a good example
> but seems misplaced - its relationship to MVCC generally is tenuous,
> rather I would expect a discussion of the serializable isolation mode
> to follow.
>
> I'm not sure how much detail this section wants to get into given the
> coverage of concurrency elsewhere in the documentation. "Not much"
> would be my baseline.
The paragraph focus on the fact that new row versions are generated
instead of locking something. Explaining serialization isolation modes
is imo very complicate and out of the scope of this subchapter. If we
want to give an overview - in addition to the exiting documentation - it
should be a separate subchapter.
>
> I would suggest spelling out what "OLTP" stands for and ideally
> pointing the user to the glossary for the term.
ok, but not added to glossary. The given explanation "... with a massive
number of concurrent write actions" should be sufficient.
>
> Tending more toward a style gripe but the amount of leader phrases and
> redundancy are at a level that I am noticing them when I read this but
> do not have the same impression having read large portions of
> documentation. In particular:
Because I'm not a native English speaker, orthographic and style hits
are always welcome.
>
> "When we speak about transaction IDs, you need to know that xids are
> like sequences."
>
> "But keep in mind that xids are independent of any time measurement —
> in milliseconds or otherwise. If you dive deeper into PostgreSQL, you
> will recognize parameters with names such as 'xxx_age'. Despite their
> names, these '_age' parameters do not specify a period of time but
> represent a certain number of transactions, e.g., 100 million."
>
> Could just be: xids are sequences and age computations involving them
> measure a transaction count as opposed to a time interval.
ok
>
> Then I would consider adding a bit more detail/context here.
>
> xids are 32bit sequences, with a reserved value to handle
> wrap-around. There are 4 billion values in the sequence but
> wrap-around handling must occur every 2 billion transactions. Age
> computations involving xids measure a transaction count as opposed to
> a time interval.
>
> I would move the mentioning of "vacuum" to the main paragraph about
> delete and not solely as a "keep in mind" note.
The mentioning here at the food of the page is a crossover to the next
subchapter.
>
> The part before the diagram seems like it should be much shorter,
> concise, and provide links to the excellent documentation. The part
> after the image, and the image itself, are good material, though
> possibly should be in a main administration chapter instead of an
> internals chapter.
vacuum: The problem - and one reason for the existence of this
subchapter - is that vacuum's documentation is scattered across may pages:
19.4: parameters to configure the server, especially five parameters
'vacuum_cost_xxx'.
19.10: parameters to configure autovacuum.
19.11: parameters to configure client connections, especially five
parameters 'vacuum_xxx' concerning their freeze-behavior.
24.1: explains the general necessity of (auto)vacuum and their strategies.
The page about the SQL command VACUUM explains the different options
(FULL, FREEZE, ..) and their meaning.
Because of the structure of our documentation as well as the complexity
of the issue that's ok. The existing documentation describes every
parameter very well, but I'm missing a page where the 'big picture' of
vacuum is explained (not necessarily here). It shall show the
relationship between the huge number of parameters and an explanation
*why* they exists. As far as we don't have such a page within the vacuum
documentation the proposed subchapter fills the gap. (The provided
graphics can be included multiple times without generating redundancies
- here and at arbitrary other places.)
>
> The first bullet of "keep in mind" is both wordy and wrong - in
> particular "as xids grow old row versions get out of scope over time"
> doesn't make sense (or rather it only does in the context of
> wrap-around, not normal visibility). Having the only mention of bloat
> be here is also not ideal, it too should be weaved into the main
> narrative. The "keep in mind" section here should be a recap of
> already covered material in a succinct form, nothing should be new to
> someone who just read the entire section.
ok.
>
> I don't think that usage of exclamation marks (!) is warranted here,
> though emphasis on the key phrase wouldn't hurt.
ok
>
> Vacuum Section
>
> avoid -> prevent (continued growth)
ok
>
> Autovacuum is enabled by default. The whole note needs commas.
ok
>
> I'd try to get rid of "at arbitrary point in time"
ok
>
> "Instance." we've already described where instances are previously
> ("on the server")
ok
>
> The other sections - these seem misplaced for the tutorial, update the
> main documentation if this information is wholly missing or lacking.
> The MVCC chapter can incorporate overview information as it is a
> strict consequence of that implementation.
>
> Statistics belong elsewhere - the tutorial should not use poor command
> implementation choices as a guide for user education.
>
> In short, this whole section should not exist and its content moved to
> more appropriate areas (mainly MVCC). Vacuum is a tool that one must
> use but the narrative should be about the system generally.
>
>
concerning vacuum section: see my comments above
concerning 'the other sections' (transactions, reliability, backup
(plus: someone should add 'replication', I'm not familiar with this
issue)): The intention of the chapter is to give a *summary* about PG's
essential architecture and about central implementation aspects. This
implies that the chapters does not present any new information. They
shall only show (or repeat) essential things in their context and
explain *why* they are used. In this sense the three chapters may be
reasonable. Concerning this, I like to hear some comments from other people.
Attachments:
0013-architecture.patch: complete patch vs. master
0013-architecture.sgml.diff: changes in file architecture.sgml since 0012
0013-images.diff: changes in files *-raw.svg since 0012
--
J. Purtz
Attachments:
[text/x-patch] 0013-architecture.patch (228.0K, 3-0013-architecture.patch)
download | inline diff:
diff --git a/doc/src/sgml/advanced.sgml b/doc/src/sgml/advanced.sgml
index 2d4ab85d45..5c3245c0ec 100644
--- a/doc/src/sgml/advanced.sgml
+++ b/doc/src/sgml/advanced.sgml
@@ -1,7 +1,7 @@
<!-- doc/src/sgml/advanced.sgml -->
<chapter id="tutorial-advanced">
- <title>Advanced Features</title>
+ <title>Advanced SQL Features</title>
<sect1 id="tutorial-advanced-intro">
<title>Introduction</title>
diff --git a/doc/src/sgml/arch-dev.sgml b/doc/src/sgml/arch-dev.sgml
index 7883c3cd82..9db0ae2c78 100644
--- a/doc/src/sgml/arch-dev.sgml
+++ b/doc/src/sgml/arch-dev.sgml
@@ -1,7 +1,7 @@
<!-- doc/src/sgml/arch-dev.sgml -->
<chapter id="overview">
- <title>Overview of PostgreSQL Internals</title>
+ <title>Overview of Query Handling</title>
<note>
<title>Author</title>
diff --git a/doc/src/sgml/architecture.sgml b/doc/src/sgml/architecture.sgml
new file mode 100644
index 0000000000..4bbd6abb8a
--- /dev/null
+++ b/doc/src/sgml/architecture.sgml
@@ -0,0 +1,1524 @@
+<!-- doc/src/sgml/architecture.sgml -->
+
+ <chapter id="tutorial-architecture">
+ <title>Overview of Architecture and Implementation</title>
+
+ <para>
+ Every DBMS implements basic strategies to ensure a fast
+ and robust system. This chapter provides an overview of the
+ basic techniques <productname>PostgreSQL</productname> uses to
+ achieve this aim. It does not offer anything which exceeds
+ the information content of other pages. Instead, it tries to
+ explain <emphasis>why</emphasis> certain implementation
+ decisions have been taken.
+ </para>
+
+ <sect1 id="tutorial-ram-proc-file">
+ <title>Collaboration of Processes, RAM, and Files</title>
+ <para>
+ In a client/server architecture clients do not have direct access
+ to database files and the data stored in them. Instead, they send
+ requests to the server and receive the requested data in the response.
+ In the case of <productname>PostgreSQL</productname>, the server
+ launches a single process for each client connection, referred to as a
+ <glossterm linkend="glossary-backend">Backend</glossterm> process.
+ Such a Backend process handles the client's requests by acting on the
+ <glossterm linkend="glossary-shared-memory">Shared Memory</glossterm>.
+ This leads to other activities (file access, WAL, vacuum, ...) of the
+ <glossterm linkend="glossary-instance">Instance</glossterm>. The
+ Instance is a group of server-side processes acting on a common
+ Shared Memory. PostgreSQL does not use threading.
+ </para>
+
+ <para>
+ All aspects of an Instance are launched and managed using a single primary
+ process termed the
+ <glossterm linkend="glossary-postmaster">Postmaster</glossterm>.
+ It loads configuration files, allocates Shared Memory, and
+ starts the other collaborating processes of the Instance:
+ <glossterm linkend="glossary-background-writer">Background Writer</glossterm>,
+ <glossterm linkend="glossary-checkpointer">Checkpointer</glossterm>,
+ <glossterm linkend="glossary-wal-writer">WAL Writer</glossterm>,
+ <glossterm linkend="glossary-wal-archiver">WAL Archiver</glossterm>,
+ <glossterm linkend="glossary-autovacuum">Autovacuum</glossterm>,
+ <glossterm linkend="glossary-stats-collector">Statistics Collector</glossterm>,
+ <glossterm linkend="glossary-logger">Logger</glossterm>, and more.
+ Later, the Postmaster listens on its configured system port and in response
+ to client connection attempts launches
+ <glossterm linkend="glossary-backend">Backend</glossterm> processes
+ to which it delegates authentication, communication, and the handling of their requests.
+ <xref linkend="tutorial-ram-proc-file-figure"/> visualizes the processes
+ of an Instance and the main aspects of their collaboration.
+ </para>
+
+ <figure id="tutorial-ram-proc-file-figure">
+ <title>Architecture</title>
+ <mediaobject>
+ <imageobject role="html">
+ <!-- distinction html/pdf is necessary to keep font-size of SVG text
+ in correlation with font-size of surrounding HTML -->
+ <imagedata fileref="images/ram-proc-file-raw.svg" format="SVG" />
+ </imageobject>
+ <imageobject role="fo">
+ <!-- For PDF attribute 'width=100%' is necessary to keep complete SVG visible
+ on the page, which has a fixed width. Font sizes will be adopted. -->
+ <imagedata fileref="images/ram-proc-file-raw.svg" format="SVG" width="100%" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>
+ Client requests like <command>SELECT</command> or
+ <command>UPDATE</command> usually lead to the
+ necessity to read or write data. This is carried out
+ by the client's backend process. Reads involve a page-level
+ cache, located in Shared Memory (for details see:
+ <xref linkend="sysvipc"/>) for the benefit of all processes
+ in the Instance. Writes also use this cache, in addition
+ to a journal, called the write-ahead-log or WAL.
+ </para>
+
+ <para>
+ Shared Memory is limited in size and it can become necessary
+ to evict pages. As long as the content of such pages hasn't
+ changed, this is not a problem. But writes directly modify
+ the pages in Shared Memory. Modified pages are called dirty
+ pages (or dirty buffers) and before they can be evicted they
+ must be written to disk. This happens regularly by the
+ Checkpointer and the Background Writer processes to ensure
+ that the disk version of the pages are up-to-date.
+ The synchronization from RAM to disk consists of two steps.
+ </para>
+
+ <para>
+ First, whenever the content of a page changes, a
+ <glossterm linkend="glossary-wal-record">WAL record</glossterm>
+ is created from the delta-information (difference between the
+ old and the new content) and stored in another area of
+ Shared Memory. The concurrently running WAL Writer process
+ reads them and appends them to the end of the current
+ <glossterm linkend="glossary-wal-record">WAL file</glossterm>.
+ Such sequential writes are faster than writes to random
+ positions of heap and index files. All WAL records created
+ from one dirty page must be transferred to disk before the
+ dirty page itself can be transferred to disk in the second step.
+ </para>
+
+ <para>
+ Second, the Instance transfers dirty buffers from Shared Memory to
+ files. This is the primary task of the
+ Background Writer process. Because I/O activities can block
+ other processes, it starts periodically and
+ acts only for a short period. Doing so, its extensive (and
+ expensive) I/O activities are spread over time, avoiding
+ debilitating I/O peaks. The Checkpointer process
+ also transfers dirty buffers to file.
+ </para>
+
+ <para>
+ The Checkpointer process creates
+ <glossterm linkend="glossary-checkpoint">Checkpoints</glossterm>.
+ A Checkpoint is a point in time when all older dirty buffers,
+ all older WAL records, and finally a special Checkpoint record
+ are written and flushed to disk.
+ Older WAL files are no longer required to recover the system from a crash.
+ </para>
+
+ <para>
+ While the Checkpointer ensures that the database system can,
+ after a crash, restart itself in a valid state, the administrator needs
+ to handle the case where the heap or other files become
+ corrupted (and possibly the locally written WAL, though that is
+ less common). Options and details are covered
+ in the backup and restore section (<xref linkend="backup"/>).
+ For our purposes here, just note that the WAL Archiver process
+ can be enabled and configured to run a script on completed WAL
+ files — usually to copy them to a remote location. Note
+ that when a Checkpoint record is written to the WAL the current
+ file is immediately completed.
+ </para>
+
+ <para>
+ The Statistics Collector collects counters about access to
+ SQL objects like tables, rows, indexes, pages, and more. It
+ stores the obtained information in system tables.
+ </para>
+
+ <para>
+ The Logger writes text lines about serious and less serious
+ events that may happen during database access, e.g., wrong
+ password, no permission, long-running queries, etc.
+ </para>
+
+ </sect1>
+
+ <sect1 id="tutorial-cluster-db-schema">
+ <title>The logical Perspective: Cluster, Database, Schema</title>
+
+ <para>
+ A <glossterm linkend="glossary-server">Server</glossterm> contains one or more
+ <glossterm linkend="glossary-db-cluster">Database Clusters</glossterm>
+ (<glossterm linkend="glossary-db-cluster">Clusters</glossterm>
+ for short). By default each newly initialized Cluster contains three
+ <glossterm linkend="glossary-database">databases</glossterm>
+ (one interactive and two templates, see <xref linkend="app-initdb"/>).
+ Each database can contain many user-writable
+ <glossterm linkend="glossary-schema">schemas</glossterm>
+ (public, by name and permissiveness, by default), the system
+ generated user-facing schemas <literal>pg_catalog</literal>,
+ <literal>pg_temp</literal>, and <literal>information_schema</literal>,
+ and some more system schemas.
+ <glossterm linkend="glossary-table">Tables</glossterm>,
+ <glossterm linkend="glossary-view">views</glossterm>, and a lot
+ of other objects uniquely reside in a single schema.
+ <xref linkend="tutorial-cluster-db-schema-figure"/> visualizes
+ this hierarchy.
+ </para>
+
+ <para>
+ <!-- is the para helpful at this position? -->
+ Client connections act at the database level and can access
+ its schemas simultaneously. Special techniques like
+ <link linkend="sql-createforeigndatawrapper">foreing data wrapper</link>
+ or <link linkend="dblink">dblink</link> are required
+ to access multiple databases, even within the same Cluster,
+ from a single client connection.
+ </para>
+
+ <figure id="tutorial-cluster-db-schema-figure">
+ <title>Cluster, Database, Schema</title>
+ <mediaobject>
+ <imageobject role="html">
+ <!-- distinction html/pdf is necessary to keep font-size of SVG text
+ in correlation with font-size of surrounding HTML -->
+ <imagedata fileref="images/cluster-db-schema-raw.svg" format="SVG" />
+ </imageobject>
+ <imageobject role="fo">
+ <!-- For PDF attribute 'width=100%' is necessary to keep complete SVG visible
+ on the page, which has a fixed width. Font sizes will be adopted. -->
+ <imagedata fileref="images/cluster-db-schema-raw.svg" format="SVG" width="100%" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>
+ A Cluster is the outer container for a
+ collection of databases. Clusters are created by the command
+ <xref linkend="app-initdb"/>.
+ </para>
+
+ <para>
+ <literal>template0</literal> is the very first
+ database of any Cluster. It
+ is created during the initialization phase of the Cluster.
+ In a second step, database <literal>template1</literal> is generated
+ as a copy of <literal>template0</literal>, and finally database
+ <literal>postgres</literal> is generated as a copy of
+ <literal>template1</literal>. Any
+ <glossterm linkend="app-createdb">new databases</glossterm>
+ of the Cluster that a user might need,
+ such as <literal>my_db</literal>, will be copied from the
+ <literal>template1</literal> database. Due to the unique
+ role of <literal>template0</literal> as the pristine original
+ of all other databases, no client is allowed to connect to it.
+ </para>
+
+ <para>
+ <glossterm linkend="glossary-sql-object">SQL Objects</glossterm>
+ are contained in a schema.
+ Schemas are namespaces for SQL objects and ensure
+ (with one exception) that the SQL object names are used only once within
+ their scope across all types of SQL objects. E.g., it is not possible
+ to have a table <literal>employee</literal> and a view
+ <literal>employee</literal> within the same schema. But it is
+ possible to have two tables <literal>employee</literal> in two
+ different schemas. In this case, the two tables
+ are separate objects and independent of each
+ other. The only exception to this cross-type uniqueness is that
+ <glossterm linkend="glossary-unique-constraint">unique constraints
+ </glossterm> and the according unique index
+ (<xref linkend="indexes-unique"/>) use the same name.
+ </para>
+
+ <para>
+ Some schemas are predefined. <literal>public</literal>
+ acts as the default schema and contains all SQL objects
+ which are created within <literal>public</literal> or
+ without using an explicit schema name. <literal>public</literal>
+ should not contain user-defined SQL objects. Instead, it is
+ recommended to create a separate schema that holds individual
+ objects like application-specific tables or views. To access
+ objects in such a schema they can be fully qualified, e.g.
+ <literal>my_schema.my_table</literal>, or by changing the
+ <link linkend="ddl-schemas-path">schema search path</link>.
+ </para>
+
+ <para>
+ <literal>pg_catalog</literal> is a schema for all tables and views of the
+ <glossterm linkend="glossary-system-catalog">System Catalog</glossterm>.
+ <literal>information_schema</literal> is a similar schema. It
+ contains several tables and views of the System Catalog in a
+ way that conforms to the SQL standard.
+ </para>
+
+ <para>
+ There are many different SQL object types:
+ <glossterm linkend="glossary-database">database</glossterm>,
+ <glossterm linkend="glossary-schema">schema</glossterm>,
+ <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>,
+ <glossterm linkend="glossary-role">role</glossterm>,
+ <glossterm linkend="datatype">data type</glossterm>,
+ <glossterm linkend="functions">operator</glossterm>,
+ <glossterm linkend="glossary-tablespace">tablespace</glossterm>,
+ <glossterm linkend="glossary-extension">extension</glossterm>,
+ <glossterm linkend="glossary-foreign-data-wrapper">foreign data wrapper</glossterm>,
+ and more. A few of them, the
+ <firstterm>Global SQL Objects</firstterm>, are outside of the
+ strict hierarchy: All <firstterm>database names</firstterm>,
+ all <firstterm>tablespace names</firstterm>, and all
+ <firstterm>role names</firstterm> are automatically
+ available throughout the Cluster, not just the database in which
+ the SQL command was executed.
+ <xref linkend="tutorial-internal-objects-hierarchy-figure"/>
+ shows the relation between the object types.
+ </para>
+
+ <figure id="tutorial-internal-objects-hierarchy-figure">
+ <title>Hierarchy of Internal Objects</title>
+ <mediaobject>
+ <imageobject role="html">
+ <!-- distinction html/pdf is necessary to keep font-size of SVG text
+ in correlation with font-size of surrounding HTML -->
+ <imagedata fileref="images/internal-objects-hierarchy-raw.svg" format="SVG" />
+ </imageobject>
+ <imageobject role="fo">
+ <!-- For PDF attribute 'width=100%' is necessary to keep complete SVG visible
+ on the page, which has a fixed width. Font sizes will be adopted. -->
+ <imagedata fileref="images/internal-objects-hierarchy-raw.svg" format="SVG" width="100%" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ </sect1>
+
+ <sect1 id="tutorial-directories">
+ <title>The Physical Perspective: Directories and Files</title>
+
+ <para>
+ <productname>PostgreSQL</productname> organizes long-lasting (persistent)
+ data as well as volatile state information about transactions
+ or replication actions in the file system. Every
+ <xref linkend="glossary-db-cluster"/> has its root directory
+ somewhere in the file system. In many cases, the environment
+ variable <literal>PGDATA</literal> points to this directory.
+ The example shown in
+ <xref linkend="tutorial-directories-figure"/> uses
+ <literal>data</literal> as the name of the cluster's root directory.
+ </para>
+
+ <figure id="tutorial-directories-figure">
+ <title>Directory Structure</title>
+ <mediaobject>
+ <imageobject role="html">
+ <!-- distinction html/pdf is necessary to keep font-size of SVG text
+ in correlation with font-size of surrounding HTML -->
+ <imagedata fileref="images/directories-raw.svg" format="SVG" />
+ </imageobject>
+ <imageobject role="fo">
+ <!-- For PDF attribute 'width=100%' is necessary to keep complete SVG visible
+ on the page, which has a fixed width. Font sizes will be adopted. -->
+ <imagedata fileref="images/directories-raw.svg" format="SVG" width="100%" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>
+ The cluster's root directory contains many subdirectories and
+ some files, all of which are necessary to store long-lasting
+ as well as temporary data. The root's name can be selected
+ as desired, but the names of its subdirectories and files
+ are more or less fix and detertermined by
+ <productname>PostgreSQL</productname>. The following
+ paragraphs describe the most important subdirectories
+ and files.
+ </para>
+
+ <para>
+ <literal>base</literal> contains one
+ subdirectory per database. The names of those
+ subdirectories consist of numbers. These are the internal
+ Object Identifiers (OID), which are numbers to identify
+ their definition in the
+ <glossterm linkend="glossary-system-catalog">System Catalog</glossterm>.
+ </para>
+
+ <para>
+ Within the database-specific subdirectories of <literal>base</literal>
+ there are many files: one or more for every table
+ and every index. Those files are accompanied by files for the
+ <link linkend="storage-fsm">Free Space Maps</link>
+ (suffixed <literal>_fsm</literal>) and
+ <link linkend="storage-vm">Visibility Maps</link>
+ (suffixed <literal>_vm</literal>), which contain optimization information.
+ </para>
+
+ <para>
+ Another subdirectory is <literal>global</literal>. It
+ contains files with information about
+ <glossterm linkend="glossary-sql-object">Global SQL Objects</glossterm>.
+ </para>
+
+ <para>
+ In <literal>pg_tblspc</literal>, there are symbolic links
+ that point to directories that are outside of the root
+ directory tree, e.g. at a different disc. Files for tables
+ and indexes of non-default tablespaces reside there. As
+ previously mentioned, those defined within the default
+ tablespace reside in the database-specific subdirectories.
+ </para>
+
+ <para>
+ The subdirectory <literal>pg_wal</literal> contains the
+ <glossterm linkend="glossary-wal-file">WAL files</glossterm>.
+ They arise and grow in parallel with data changes in the
+ Cluster and remain as long as
+ they are required for recovery, archiving, or replication.
+ </para>
+
+ <para>
+ The subdirectory <literal>pg_xact</literal> contains
+ information about the status of each transaction:
+ <literal>in_progress</literal>, <literal>committed</literal>,
+ <literal>aborted</literal>, or <literal>sub_committed</literal>.
+ </para>
+
+ <para>
+ In the root directory
+ there are also some files. In many cases, the configuration
+ files of the Cluster are stored here. If the
+ Instance is up and running, the file
+ <literal>postmaster.pid</literal> exists here
+ (by default)
+ and contains the process ID (pid) of the
+ Postmaster which started the Instance.
+ </para>
+
+ <para>
+ For more details about the physical implementation
+ of database objects, see <xref linkend="storage"/>.
+ </para>
+
+ </sect1>
+
+ <sect1 id="tutorial-mvcc">
+ <title>MVCC — Multiversion Concurrency Control</title>
+
+ <para>
+ In most cases, <productname>PostgreSQL</productname> databases
+ support many clients at the same time which makes it necessary to
+ protect concurrently running requests from unwanted overwriting
+ of other's data as well as from reading inconsistent data. Imagine an
+ online shop offering the last copy of an article. Two clients have the
+ article displayed at their user interface. After a while, but at the same time,
+ both users decide to put it to their shopping cart or even to buy it.
+ Both have seen the article, but only one can be allowed to get it.
+ The database must bring the two requests in a row, permit the access
+ to one of them, block the other, and inform the blocked client
+ that the data was changed by a different process.
+ </para>
+
+ <para>
+ <productname>PostgreSQL</productname> implements a
+ sophisticated technique which avoids locking:
+ <firstterm>Multiversion Concurrency Control</firstterm> (MVCC).
+ The advantage of MVCC over technologies that use row locks
+ becomes evident in multiuser Online Transaction Processing (OLTP)
+ environments with a massive number of concurrent write
+ actions. There, MVCC generally performs better than solutions
+ using locks. In a <productname>PostgreSQL</productname>
+ database, reading never blocks writing and writing never
+ blocks reading, even in the strictest level of transaction
+ isolation.
+ </para>
+
+ <para>
+ Instead of locking rows, the <firstterm>MVCC</firstterm> technique creates
+ a new version of the row when a data-change takes place. To
+ distinguish between these two versions, and to track the timeline
+ of the row, each of the versions contains, in addition to their user-defined
+ columns, two special system columns, which are not visible
+ for the usual <command>SELECT * FROM ...</command> command.
+ The column <literal>xmin</literal> contains the transaction ID (xid)
+ of the transaction which created this version of the row.
+ <literal>xmax</literal> contains the xid of the transaction which has
+ deleted this version, or zero if the version is not
+ deleted. You can read both with the command
+ <command>SELECT xmin, xmax, * FROM ... </command>.
+ </para>
+
+ <para>
+ Xids are sequences (with a reserved value to handle wrap-around
+ in pre-9.4 <productname>PostgreSQL</productname> versions).
+ Age computations involving them measure a transaction
+ count as opposed to a time interval (in milliseconds or otherwise).
+ If you dive deeper into <productname>PostgreSQL</productname>,
+ you will recognize parameters with names such as 'xxx_age'.
+ Despite their names, these '_age' parameters do not specify
+ a period of time but represent a certain number of transactions,
+ e.g., 100 million.
+ </para>
+
+ <para>
+ The description in this chapter simplifies by omitting details.
+ When many transactions are running simultaneously, things can
+ get complicated. Sometimes transactions are aborted via
+ <command>ROLLBACK</command> immediately or after a lot of other activities, sometimes
+ a single row is involved in more than one transaction, sometimes
+ a client crashes, sometimes the sequence of xids restarts
+ from zero, ... . Therefore, every version of a row contains more
+ system columns and flags, not only <literal>xmin</literal>
+ and <literal>xmax</literal>.
+ </para>
+
+ <para>
+ So, what's going on in detail when write access takes place?
+ <xref linkend="tutorial-mvcc-figure"/> shows details concerning
+ <literal>xmin</literal>, <literal>xmax</literal>, and user data.
+ </para>
+
+ <figure id="tutorial-mvcc-figure">
+ <title>Multiversion Concurrency Control</title>
+ <mediaobject>
+ <imageobject role="html">
+ <!-- distinction html/pdf is necessary to keep font-size of SVG text
+ in correlation with font-size of surrounding HTML -->
+ <imagedata fileref="images/mvcc-raw.svg" format="SVG" />
+ </imageobject>
+ <imageobject role="fo">
+ <imagedata fileref="images/mvcc-raw.svg" format="SVG" width="100%" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>
+ An <command>INSERT</command> command creates the first
+ version of a row. Besides its user data <literal>'x'</literal>,
+ this version contains the ID of the creating transaction
+ <literal>123</literal> in <literal>xmin</literal> and
+ <literal>0</literal> in <literal>xmax</literal>.
+ <literal>xmin</literal> indicates that the version
+ exists since transaction <literal>123</literal> and
+ <literal>xmax</literal> that it is currently not deleted.
+ </para>
+
+ <para>
+ Somewhat later, transaction <literal>135</literal>
+ executes an <command>UPDATE</command> of this row by
+ changing the user data from <literal>'x'</literal> to
+ <literal>'y'</literal>. According to the MVCC principles,
+ the data in the old version of the row is not changed.
+ The value <literal>'x'</literal> remains as it was before.
+ Only <literal>xmax</literal> changes to <literal>135</literal>.
+ Now, this version is treated as valid exclusively for
+ transactions with xids from <literal>123</literal> to
+ <literal>134</literal>. In addition to the non-occurring
+ data change in the old version, the <command>UPDATE</command>
+ creates a new version of the row with its xid in
+ <literal>xmin</literal>, <literal>0</literal> in
+ <literal>xmax</literal>, and <literal>'y'</literal> in the
+ user data (plus all other user data from the old version).
+ This new row version is visible to all future transactions.
+ (Internally, an <command>UPDATE</command> command acts
+ as a <command>DELETE</command> command followed by
+ an <command>INSERT</command> command.)
+ </para>
+
+ <para>
+ All subsequent <command>UPDATE</command> commands behave
+ in the same way as the first one: they put their xid in
+ <literal>xmax</literal> of the current version, create
+ a new version with their xid in <literal>xmin</literal> and
+ <literal>0</literal> in <literal>xmax</literal>.
+ </para>
+
+ <para>
+ Finally, a row may be deleted by a <command>DELETE</command>
+ command. Even in this case, all versions of the row remain as
+ before; nothing is thrown away. Only <literal>xmax</literal>
+ of the last version is set to the xid of the <command>DELETE</command>
+ transaction, which indicates that (if committed) it is only visible to
+ transactions with xids older than that (from
+ <literal>142</literal> to <literal>820</literal> in this
+ example).
+ </para>
+
+ <para>
+ In summary, the MVCC technology creates more and more versions
+ of the same row in the table's heap file and leaves them there,
+ even after a <command>DELETE</command> command. Only the youngest
+ version is relevant for all future transactions. But the
+ system must also preserve some of the older ones for
+ awhile, because they could still be needed by
+ transactions which started before the deleting transaction commits.
+ Over time, also the older ones get out of scope
+ for ALL transactions and therefore become unnecessary.
+ Nevertheless, they do exist physically on the disk and occupy
+ space. They are called <firstterm>dead rows</firstterm> and are part
+ of the <glossterm linkend="glossary-bloat">bloat</glossterm>.
+ </para>
+
+ <para>
+ Keep in mind:
+ </para>
+ <itemizedlist>
+
+ <listitem>
+ <simpara>
+ <literal>xmin</literal> and <literal>xmax</literal>
+ indicate the range in which
+ <firstterm>row versions</firstterm> are valid (visible) for transactions.
+ This range doesn't imply any direct temporal meaning;
+ the sequence of xids reflects only the sequence of
+ transaction begin events.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ Internally, an <command>UPDATE</command> command acts in the
+ same way as a <command>DELETE</command> command followed by
+ an <command>INSERT</command> command.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ Nothing is removed — with the consequence that the database
+ occupies more and more disk space. It is obvious that
+ this behavior has to be corrected in some way. The next
+ chapter explains how <firstterm>vacuum</firstterm> and
+ <firstterm>autovacuum</firstterm> fulfill this task.
+ </simpara>
+ </listitem>
+
+ </itemizedlist>
+
+ </sect1>
+
+ <sect1 id="tutorial-vacuum">
+ <title>Vacuum</title>
+
+ <para>
+ As we have seen in the previous chapter, the database
+ tends to occupy more and more disk space, caused by
+ <glossterm linkend="glossary-bloat">bloat</glossterm>.
+ This chapter explains how the SQL command
+ <command>VACUUM</command> and the automatically running
+ <firstterm>Autovacuum</firstterm> processes clean up
+ and prevent continued growth.
+ </para>
+
+ <note>
+ <para>
+ Autovacuum runs automatically, by
+ default. Its default parameters as well as those for
+ <command>VACUUM</command> are appropriate for most standard
+ situations. Therefore a novice database manager can
+ skip the rest of this chapter which explains
+ a lot of details.
+ </para>
+ </note>
+
+ <para>
+ Client processes can issue the SQL command <command>VACUUM</command>
+ at any time. DBAs do this when they recognize
+ special situations, or they start it in batch jobs which run
+ periodically. Additionally, there is a constantly running
+ Autovacuum daemon which is part of the
+ <link linkend="glossary-instance">Instance</link>. It continuously
+ monitors the state of all databases based on values that are collected by the
+ <link linkend="glossary-stats-collector">Statistics Collector</link>
+ and starts Autovacuum processes whenever it detects
+ certain situations. Thus, it's a dynamic behavior of
+ <productname>PostgreSQL</productname> with the intention to tidy
+ up whenever it is appropriate.
+ </para>
+
+ <para>
+ <command>VACUUM</command>, as well as Autovacuum, don't just eliminate
+ bloat. They perform additional tasks for minimizing future
+ I/O activities of themselves as well as of other processes.
+ This extra work can be done in a very efficient way since in most
+ cases the expensive physical access to pages has taken place anyway
+ to eliminate bloat. The additional operations are:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <simpara>
+ <firstterm>Freeze</firstterm>: Mark certain row versions
+ as frozen. This means that they
+ are always treated as valid (visible) independent from
+ the <firstterm>wraparound problem</firstterm> (see below).
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <firstterm>Visibility Map</firstterm> and
+ <firstterm>Free Space Map</firstterm>: Log information about
+ the state of the handled pages in two additional files, the
+ Visibility Map and the Free Space Map.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <emphasis>Statistics</emphasis>: Collect statistics about the
+ number of rows per table, the distribution of values, and so on,
+ as the basis for decisions of the query planner.
+ </simpara>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ The eagerness — or 'aggressiveness' — of the
+ operations for <emphasis>eliminating bloat</emphasis> and
+ <emphasis>freeze</emphasis> is controlled by configuration
+ parameters, runtime flags, and in extreme situations by
+ the processes themselves. Because vacuum operations typically are I/O
+ intensive, which can hinder other activities, Autovacuum
+ avoids performing many vacuum operations in bulk. Instead,
+ it carries out many small actions with delay points in between.
+ The SQL command <command>VACUUM</command> runs immediately
+ and without any time delay.
+ </para>
+
+ <bridgehead renderas="sect2">Eliminate Bloat</bridgehead>
+
+ <para>
+ To determine which of the row versions are no longer needed, the
+ elimination operation must evaluate <literal>xmax</literal>
+ against several criteria which must all apply:
+ </para>
+ <itemizedlist>
+
+ <listitem>
+ <simpara>
+ <literal>xmax</literal> must be different from zero because a
+ value of zero indicates that the row version is still valid.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <literal>xmax</literal> must contain an xid which is older
+ than the oldest xid of all currently running transactions
+ <literal>(min(pg_stat_activity.backend_xmin))</literal>.
+ This criterion guarantees that no existing or upcoming transaction
+ will have read or write access to this row version.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ The transaction of <literal>xmax</literal> must be committed. If it was rollback-ed,
+ this row version is treated as valid.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ If there is the situation that the row version is part of
+ multiple transactions, special care and some more actions
+ must be taken, see: <xref linkend="vacuum-for-multixact-wraparound"/>.
+ </simpara>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ After the vacuum operation detects an unused row version, it
+ marks its space as free for future use of writing actions. Only
+ in rare situations (or in the case of <command>VACUUM FULL</command>),
+ is this space released to the operating system. In most cases,
+ it remains occupied by <productname>PostgreSQL</productname>
+ and will be used by future <command>INSERT</command> or
+ <command>UPDATE</command> commands to this table.
+ </para>
+
+ <para>
+ Which actions start the elimination of bloat?
+
+ <itemizedlist>
+
+ <listitem>
+ <simpara>
+ When a client issues the SQL command <command>VACUUM</command>
+ in its default format, i.e., without any option. To boost performance,
+ in this and the next case <command>VACUUM</command> does not
+ read and act on all pages of the heap file.
+ The Visibility Map, which is very compact and therefore fast to read,
+ contains information about which pages have no deleted row versions, and
+ can be skipped by <command>VACUUM</command>.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ When a client issues the SQL command <command>VACUUM</command>
+ with the option <command>FREEZE</command>. (In this case,
+ it undertakes many more actions, see
+ <link linkend="tutorial-freeze">Freeze Row Versions</link>.)
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ When a client issues the SQL command <command>VACUUM</command>
+ with the option <command>FULL</command>.
+ In this mode, an exclusive lock is taken, and
+ the whole table is copied to a different file, skipping all outdated row
+ versions. All bloat is thereby eliminated, which
+ may lead to a significant reduction of used disk space.
+ The old file is deleted.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ When an Autovacuum process acts. For optimization
+ purposes, it considers the Visibility Map in the same way as
+ <command>VACUUM</command>. Additionally, it ignores tables with few modifications;
+ see <xref linkend="guc-autovacuum-vacuum-threshold"/>,
+ which defaults to 50 rows and
+ <xref linkend="guc-autovacuum-vacuum-scale-factor"/>,
+ which defaults to 20%.
+ </simpara>
+ </listitem>
+
+ </itemizedlist>
+ </para>
+
+ <para>
+ This logic only applies to row versions of the heap. Index entries
+ don't use <literal>xmin/xmax</literal>. Nevertheless, such index
+ entries, which would lead to outdated row versions, are cleaned up
+ accordingly.
+ </para>
+
+ <para>
+ The above descriptions omit the fact that xids on a real computer
+ have a limited size, and after
+ a certain number of transactions they are forced to restart
+ from the beginning, which is called <firstterm>wraparound</firstterm>.
+ Therefore the terms 'old transaction' / 'young transaction' does
+ not always correlate with low / high values of xids. Near to
+ wraparound point, there are cases where <literal>xmin</literal> has
+ a higher value than <literal>xmax</literal>, although their meaning
+ is said to be older than <literal>xmax</literal>.
+ </para>
+
+ <figure id="tutorial-wraparound-figure">
+ <title>Cyclic usage of XIDs</title>
+ <mediaobject>
+ <imageobject role="html">
+ <!-- distinction html/pdf is necessary to keep font-size of SVG text
+ in correlation with font-size of surrounding HTML -->
+ <imagedata fileref="images/wraparound-raw.svg" format="SVG" />
+ </imageobject>
+ <imageobject role="fo">
+ <!-- For PDF attribute 'width=100%' is necessary to keep complete SVG visible
+ on the page, which has a fixed width. Font sizes will be adopted. -->
+ <imagedata fileref="images/wraparound-raw.svg" format="SVG" width="100%" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <bridgehead renderas="sect2" id="tutorial-freeze">Freeze Row Versions</bridgehead>
+
+ <para>
+ The use of a limited range of IDs for transactions leads
+ to the necessity to restart the sequence sooner or later.
+ This not only has the rare consequence, previously
+ described, that sometimes <literal>xmin</literal> is
+ higher than <literal>xmax</literal>. A far
+ more critical problem is that whenever the system has
+ to evaluate a WHERE condition, it must decide which row
+ version is valid (visible) from the perspective of the
+ transaction of the query. If a wraparound couldn't happen,
+ this decision would be relatively easy: the xid
+ must be between <literal>xmin</literal> and <literal>xmax</literal>,
+ and the corresponding transactions of <literal>xmin</literal>
+ and <literal>xmax</literal> must be committed. However,
+ <productname>PostgreSQL</productname> has to consider the
+ possibility of wraparound.
+ Therefore the decision becomes more complex. The general
+ idea of the solution is to use the 'between
+ <literal>xmin</literal> and <literal>xmax</literal>'
+ comparison only during the youngest period of the row
+ versions lifetime and afterward replace it with a
+ 'valid forever' flag in its header.
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <simpara>
+ As a first step, <productname>PostgreSQL</productname>
+ divides the complete range of
+ possible xids into two halves with the two split-points
+ 'txid_current' and 'txid_current + 2^31'. The half behind
+ 'txid_current' is considered to represent xids of the
+ 'past' and the half ahead of 'txid_current' those of the
+ 'future'. Those of the 'past' are valid (visible) and those
+ of the 'future' not.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ With each newly created transaction the two split-points
+ move forward. If 'txid_current + 2^31' reached a
+ row version with <literal>xmin</literal> equal to that value, it would
+ immediately jump from 'past' to 'future' and would be
+ no longer visible!
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ If not handled in some way, data inserted many transactions ago
+ would become invisibile. The vacuum operation <firstterm>freeze</firstterm>
+ avoids this long before the split-point is reached by setting
+ a flag in the header of the row version which avoids
+ future comparison of its <literal>xmin/xmax</literal> and indicates
+ that the version is valid not only in the 'past'-half
+ but also in the 'future'-half, as well as in all coming
+ <glossterm linkend="glossary-xid">epochs</glossterm>.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ Which row versions can be frozen by the vacuum operation?
+ Again, several criteria must be checked, and all must be met.
+
+ <itemizedlist>
+
+ <listitem>
+ <simpara>
+ <literal>xmax</literal> must be zero because only
+ non-deleted rows can be visible 'forever'.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <literal>xmin</literal> must be older than all currently
+ existing transactions. This guarantees that no existing
+ transaction can modify or delete the version.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ The transactions of <literal>xmin</literal> and
+ <literal>xmax</literal> must be committed.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ At what point in time does the freeze operation take place?
+
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ When a client issues the SQL command <command>VACUUM</command>
+ with its <command>FREEZE</command> option. In this case, all
+ pages are processed that are marked in the Visibility Map
+ as potentially having unfrozen rows.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ When a client issues the SQL command <command>VACUUM</command> without
+ any options but there are xids older than
+ <xref linkend="guc-vacuum-freeze-table-age"/>
+ (default: 150 million) minus
+ <xref linkend="guc-vacuum-freeze-min-age"/>
+ (default: 50 million).
+ As before, all pages are processed that are
+ marked in the Visibility Map to potentially having unfrozen
+ rows.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ When an Autovacuum process runs. Such a process acts in one
+ of two modes:
+ </simpara>
+
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ In the <emphasis>normal mode</emphasis>, it skips
+ pages with row versions that are younger than
+ <xref linkend="guc-vacuum-freeze-min-age"/>
+ (default: 50 million) and works only on pages where
+ all xids are older. The skipping of young xids prevents
+ work on such pages, which are likely to be changed
+ by one of the future SQL commands.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ The process switches
+ to an <emphasis>aggressive mode</emphasis> if it recognizes
+ that for the processed table the oldest xid exceeds
+ <xref linkend="guc-autovacuum-freeze-max-age"/>
+ (default: 200 million). The value of the oldest unfrozen
+ xid is stored per table in <literal>pg_class.relfrozenxid</literal>.
+ In this <emphasis>aggressive mode</emphasis> Autovacuum
+ processes all such pages of the selected table that are marked
+ in the Visibility Map to potentially have bloat or unfrozen rows.
+ </simpara>
+ </listitem>
+
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ In the first two cases and with Autovacuum in
+ <emphasis>aggressive mode</emphasis>, the system knows
+ to which value the oldest unfrozen xid has moved forward and
+ logs the value in <literal>pg_class.relfrozenxid</literal>.
+ The distance between this value and the 'txid_current' split
+ point becomes smaller, and the distance to 'txid_current + 2^31'
+ becomes larger than before.
+ </para>
+
+ <figure id="tutorial-freeze-figure">
+ <title>Freeze</title>
+ <mediaobject>
+ <imageobject role="html">
+ <!-- distinction html/pdf is necessary to keep font-size of SVG text
+ in correlation with font-size of surrounding HTML -->
+ <imagedata fileref="images/freeze-raw.svg" format="SVG" />
+ </imageobject>
+ <imageobject role="fo">
+ <!-- For PDF attribute 'width=100%' is necessary to keep complete SVG visible
+ on the page, which has a fixed width. Font sizes will be adopted. -->
+ <imagedata fileref="images/freeze-raw.svg" format="SVG" width="100%" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <bridgehead renderas="sect2">Protection against Wraparound Failure</bridgehead>
+
+ <para>
+ The Autovacuum processes are initiated by the constantly running
+ Autovacuum daemon. If the daemon detects that for a table
+ <literal>autovacuum_freeze_max_age</literal> is exceeded, it
+ starts an Autovacuum process in <emphasis>aggressive mode</emphasis>
+ (see above) — even if Autovacuum is disabled.
+ </para>
+
+ <bridgehead renderas="sect2">Visibility Map and Free Space Map</bridgehead>
+
+ <para>
+ The <link linkend="glossary-vm">Visibility Map</link>
+ (VM) contains two flags — stored as
+ two bits — for each page of the heap file. The
+ first bit indicates that the associated page does
+ not contain any bloat. The second bit indicates
+ that the page contains only frozen row versions.
+ </para>
+
+ <para>
+ Please consider two details. First, in most cases a page
+ contains many rows or row versions.
+ However, the flags are associated with the page,
+ not with an individual row version. The flags are set
+ only under the condition that they are valid for ALL
+ row versions of the page. Second, since there
+ are only two bits per page, the VM is considerably
+ smaller than the heap.
+ </para>
+
+ <para>
+ The setting of the flags is silently done by <command>VACUUM</command>
+ and Autovacuum during their bloat and freeze operations.
+ This is done to speed up future vacuum actions,
+ regular access to heap pages, and some access to
+ the index. Every data-modifying operation on any row
+ version of the page clears the flags.
+ </para>
+
+ <para>
+ The <link linkend="glossary-fsm">Free Space Map</link>
+ (FSM) tracks the amount of free space per page. It is
+ organized as a highly condensed b-tree of (rounded) sizes.
+ Whenever <command>VACUUM</command> or Autovacuum changes
+ the free space on any processed page, they log the new
+ values in the FSM in the same way as all other writing
+ processes.
+ </para>
+
+ <bridgehead renderas="sect2">Statistics</bridgehead>
+
+ <para>
+ Statistical information helps the <link
+ linkend="planner-stats">Query Planner</link> to make optimal
+ decisions for the generation of execution plans. This
+ information can be gathered with the SQL commands
+ <command>ANALYZE</command> or <command>VACUUM ANALYZE</command>.
+ But Autovacuum processes also gather
+ such information. Depending on the percentage of changed rows
+ <xref linkend="guc-autovacuum-analyze-scale-factor"/>,
+ and minimum number of changed rows <xref linkend="guc-autovacuum-analyze-threshold"/>,
+ the Autovacuum daemon starts Autovacuum processes to collect
+ statistics per table. The automatic analysis
+ allows <productname>PostgreSQL</productname> to
+ adapt query execution to changing circumstances.
+ </para>
+
+ <para>
+ For more details about vacuum operations, especially for its
+ numerous parameters, see <xref linkend="routine-vacuuming"/>.
+ </para>
+
+ </sect1>
+
+ <sect1 id="tutorial-transactions-mvcc">
+ <title>Transactions</title>
+ <para>
+ <link linkend="tutorial-transactions">Transactions</link>
+ are a fundamental concept of relational database systems.
+ Their essential point is that they bundle multiple
+ read- or write-operations into a single all-or-nothing
+ operation. Furthermore, they separate and protect concurrent
+ actions of different connections from each other. Thereby
+ they implement the ACID paradigm.
+ </para>
+
+ <para>
+ In <productname>PostgreSQL</productname> there are two ways
+ to establish a transaction. The explicit way uses the keywords
+ <link linkend="sql-begin">BEGIN</link> and
+ <link linkend="sql-commit">COMMIT</link> (respectively
+ <link linkend="sql-rollback">ROLLBACK</link>) before
+ and after a sequence of SQL statements. The keywords mark
+ the transaction's start- and end-point. On the other hand, you
+ can omit the keywords. This is the implicit way, where
+ every single SQL command automatically establishes a new
+ transaction.
+
+ <programlisting>
+BEGIN; -- establish a new transaction
+UPDATE accounts SET balance = balance - 100.00 WHERE name = 'Alice';
+UPDATE accounts SET balance = balance + 100.00 WHERE name = 'Bob';
+COMMIT; -- finish the transaction
+
+-- this UPDATE runs as the only command of a separate transaction ...
+UPDATE accounts SET balance = balance - 100.00 WHERE name = 'Alice';
+
+-- ... and this one runs in another transaction
+UPDATE accounts SET balance = balance + 100.00 WHERE name = 'Bob';
+ </programlisting>
+ </para>
+
+ <para>
+ As mentioned, the primary property of a transaction is its
+ atomicity: either all or none of its operations succeed,
+ regardless of the fact that it may consist of a lot of
+ different write-operations, and each such operation may
+ affect many rows. As soon as one of the
+ operations fails, all previous operations fail also, which
+ means that all modified rows retain their values as of the
+ beginning of the transaction.
+ </para>
+
+ <para>
+ The atomicity also affects the visibility of changes. No
+ connection running simultaneously with a data modifying
+ transaction will ever see any change before the
+ transaction successfully executes a <command>COMMIT</command>
+ — even in the lowest
+ <link linkend="transaction-iso">isolation level</link>
+ of transactions. <productname>PostgreSQL</productname>
+ never shows uncommitted changes to other connections.
+ </para>
+
+ <para>
+ The situation regarding visibility is somewhat different
+ from the point of view of the modifying transaction.
+ A <command>SELECT</command> command issued inside a
+ transaction shows all changes done so far by this
+ transaction.
+ </para>
+
+ <bridgehead renderas="sect2">How does it work?</bridgehead>
+
+ <para>
+ Every <command>INSERT</command>, <command>UPDATE</command>,
+ and <command>DELETE</command> command creates new row
+ versions — according to the MVCC rules. This
+ creates the risk that other transactions may see the
+ new row versions, and after a while and some more
+ activities of the modifying transaction they may see the
+ next row versions. Results would be a kind of 'moving
+ target' which would be contrary to the all-or-nothing
+ principle.
+ </para>
+
+ <para>
+ <productname>PostgreSQL</productname> overcomes this
+ problem by showing only such row versions to other
+ transactions whose originating transaction has
+ successfully committed. It skips all row versions of
+ uncommitted transactions. And
+ <productname>PostgreSQL</productname> solves one more
+ problem. Even the single <command>COMMIT</command>
+ command needs a short time interval for its execution.
+ Therefore its critical 'dead-or-survival' phase
+ runs in a privileged mode that cannot be
+ interrupted by other processes.
+ </para>
+
+ <bridgehead renderas="sect2">What are the benefits?</bridgehead>
+
+ <para>
+ Transactions relieve applications from many standard
+ actions that would otherwise need to be implemented for nearly every use case.
+ </para>
+
+ <para>
+ Business logic often contains strong, but for a computer,
+ relative abstract requirements. The above example shows
+ the transfers of some money from one account to another.
+ It is obvious
+ that the decrease of the one account and the increase of the
+ other must be indivisible. Nevertheless, there is no particular
+ need for an application to do something to ensure the
+ <glossterm linkend="glossary-atomicity">atomicity</glossterm>
+ of this behavior. It's enough to surround them with
+ <command>BEGIN</command> and <command>COMMIT</command>.
+ </para>
+
+ <para>
+ Applications often demand the feature of 'undoing'
+ previously taken actions under some application-specific
+ conditions. In such cases, the application simply issues a
+ <command>ROLLBACK</command> command instead of a
+ <command>COMMIT</command>. The <command>ROLLBACK</command>
+ cancels the transaction, and all changes made so far remain
+ invisible forever; it is as if they had never happened. There
+ is no need for the application to log its activities and
+ undo every step of the transaction separately.
+ </para>
+
+ <para>
+ Transactions ensure that the
+ database always remains
+ <glossterm linkend="glossary-consistency">consistent</glossterm>.
+ Declarative rules like
+ <link linkend="ddl-constraints-primary-keys">primary</link>- or
+ <link linkend="ddl-constraints-fk">foreign keys</link>,
+ <link linkend="ddl-constraints-check-constraints">checks</link>,
+ other constraints, or
+ <link linkend="trigger-definition">triggers</link>
+ are part of the all-or-nothing nature of transactions.
+ </para>
+
+ <para>
+ There is the additional feature
+ '<link linkend="transaction-iso">isolation level</link>',
+ which separates transactions from each other in certain ways.
+ It automatically prevents applications from some strange
+ situations.
+ </para>
+
+ <para>
+ Lastly, it is worth noticing that changes done by a
+ committed transaction will survive all failures in the application or
+ the Database Cluster. The next chapter explains the
+ <glossterm linkend="glossary-durability">durability</glossterm>
+ guarantees.
+ </para>
+ </sect1>
+
+ <sect1 id="tutorial-reliability">
+ <title>Reliability</title>
+
+ <para>
+ Nothing is perfect and failures inevitably happen.
+ However, the most common types of failure are
+ well known and <productname>PostgreSQL</productname>
+ implements strategies to overcome them.
+ Such strategies use parts of the previously presented
+ techniques MVCC and transaction-rollback, plus additional
+ features.
+ </para>
+
+ <bridgehead renderas="sect2">Failures at the client side</bridgehead>
+ <para>
+ A <glossterm linkend="glossary-client">client</glossterm>
+ can fail in different ways. Its hardware can get damaged,
+ the power supply can fail, the network connection to the
+ server can break, or the client application may run into
+ a severe software error like a null pointer exception.
+ Because <productname>PostgreSQL</productname> uses a
+ client/server architecture, no direct problem for the
+ database will occur. In all of these cases, the
+ <glossterm linkend="glossary-backend">Backend process</glossterm>,
+ which is the client's counterpart at the server side,
+ may recognize that the network connection is no longer
+ working, or it may run into a timeout after a while. It
+ terminates, and there is no harm to the database. As
+ usual, uncommitted data changes initiated by this client
+ are not visible to any other client.
+ </para>
+
+ <bridgehead renderas="sect2">Failures at the server-side</bridgehead>
+
+ <bridgehead renderas="sect3">Instance failure</bridgehead>
+ <para>
+ The Instance may suddenly fail because of <emphasis>power off</emphasis>
+ or other problems. This will affect all running processes, the RAM,
+ and possibly the consistency of disk files.
+ </para>
+
+ <para>
+ After a restart, <productname>PostgreSQL</productname>
+ automatically recognizes that the last shutdown of the
+ Instance did not happen as expected: files might not be
+ closed properly and the <literal>postmaster.pid</literal>
+ file unexpectedly exists. <productname>PostgreSQL</productname>
+ tries to clean up the situation. This is possible because
+ all changes in the database are stored twice. First,
+ the WAL files contain them as a chronology of
+ <glossterm linkend="glossary-wal-record">WAL records</glossterm>,
+ which include the new data values and information about commit
+ actions. The WAL records are written first. Only then is
+ the data itself written to the heap and index files.
+ In contrast to the WAL records, this part may or may
+ not have been transferred entirely from Shared Memory
+ to the files.
+ </para>
+
+ <para>
+ The automatic recovery searches within the WAL files for
+ the latest
+ <glossterm linkend="glossary-checkpoint">checkpoint</glossterm>.
+ This checkpoint signals that the database files are in
+ a consistent state, especially that all WAL records up to
+ this point were successfully stored in heap and index files. Starting
+ here, the recovery process copies any remaining WAL records
+ to heap and index. The result is that the heap files contain all
+ changes recorded to the WAL and reach a consistent state. Changes of committed
+ transactions are visible; those of uncommitted transactions
+ are also in the files, but - as usual - they are never seen
+ by any of the following transactions because uncommitted
+ changes are never shown. These recovery actions run
+ automatically; it is not necessary that a
+ database administrator configure or start anything by
+ himself.
+ </para>
+
+ <bridgehead renderas="sect3">Disk crash</bridgehead>
+ <para>
+ If a disk crashes, the course of action described previously
+ cannot work: it is likely that the WAL files and/or the
+ data and index files are no longer available. The
+ database administrator must take special actions to
+ prepare for such a situation.
+ </para>
+
+ <para>
+ They obviously need a backup. How to take such a backup
+ and use it as a starting point for a recovery of the
+ Cluster is explained in more detail in the next
+ <link linkend="tutorial-backup">chapter</link>.
+ </para>
+
+ <bridgehead renderas="sect3">Disk full</bridgehead>
+ <para>
+ It is conceivable that over time the disk gets full,
+ and there is no room for additional data. In this case,
+ <productname>PostgreSQL</productname> stops accepting
+ data-modifying commands or even terminates completely.
+ Committed data is neither lost nor corrupted.
+ </para>
+
+ <para>
+ To recover from such a situation, the administrator should
+ remove unused files from this disk. But they should never
+ delete files from the
+ <glossterm linkend="glossary-data-directory">data directory</glossterm>.
+ Nearly all of them are necessary for the consistency
+ of the database.
+ </para>
+
+ <bridgehead renderas="sect2">High availability</bridgehead>
+ <para>
+ Database servers can work together to allow a second
+ server to quickly take over the workload if the
+ primary server fails for whatever reason
+ (<link linkend="high-availability">high availability</link>),
+ or to allow several computers to serve the same data
+ for the purpose of load balancing.
+ </para>
+
+ </sect1>
+
+ <sect1 id="tutorial-backup">
+ <title>Backup</title>
+
+ <para>
+ Taking backups is a basic task of database maintenance.
+ <productname>PostgreSQL</productname> supports
+ three different strategies; each has its own
+ strengths and weaknesses.
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ File system level backup
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ Logical backup via <command>pg_dump</command>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ Continuous archiving based on <command>pg_basebackup</command>
+ and WAL files
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <bridgehead renderas="sect2">File system level backup</bridgehead>
+ <para>
+ You can use any appropriate OS tool to create a
+ <link linkend="backup-file">copy</link>
+ of the Cluster's directory structure and files. In
+ case of severe problems such a copy can serve as
+ the source of recovery. But in order to get a
+ <emphasis>USABLE</emphasis> backup by this method,
+ the database server <emphasis>MUST</emphasis> be
+ shut down during the complete runtime of the copy
+ command!
+ </para>
+
+ <para>
+ The obvious disadvantage of this method is that there
+ is a downtime.
+ The other two strategies run during regular operating
+ times.
+ </para>
+
+ <bridgehead renderas="sect2">Logical backup via pg_dump</bridgehead>
+ <para>
+ The tool <command>pg_dump</command> is able to take a
+ <link linkend="backup-dump">copy</link>
+ of the complete Cluster or certain parts of it. It stores
+ the copy in the form of SQL commands like <command>CREATE</command>
+ and <command>COPY</command>. It runs in
+ parallel with other processes, in its own transaction.
+ </para>
+
+ <para>
+ The output of <command>pg_dump</command> may be used as
+ input of <command>psql</command> to restore the data
+ (or to copy it to another database).
+ </para>
+
+ <para>
+ The main advantage over the other two methods is that it
+ can pick parts of the Cluster, e.g., a single table or one
+ database. The other two methods work only at the level of
+ the complete Cluster.
+ </para>
+
+ <bridgehead renderas="sect2">Continuous archiving based on pg_basebackup and WAL files</bridgehead>
+ <para>
+ <link linkend="continuous-archiving">This method</link>
+ is the most sophisticated and most complex one. It
+ consists of two phases.
+ </para>
+
+ <para>
+ First, you need to create a so-called
+ <firstterm>basebackup</firstterm> with the tool
+ <command>pg_basebackup</command>. The result is a
+ directory structure plus files which contain a
+ consistent copy of the original Cluster.
+ <command>pg_basebackup</command> runs in
+ parallel with other processes in its own transaction.
+ </para>
+
+ <para>
+ The second step is recommended but not necessary. All
+ changes to the data are stored in WAL files. If you
+ continuously save such WAL files, you have the history
+ of the Cluster. This history can be applied to a
+ basebackup in order to recreate
+ any state of the Cluster between the time of
+ <command>pg_basebackup</command>'s start time and
+ any later point in time. This technique
+ is called 'Point-in-Time Recovery (PITR)'.
+ </para>
+
+ <para>
+ If configured, the
+ <glossterm linkend="glossary-wal-archiver">Archiver process</glossterm>
+ will automatically copy every single WAL file to a save location.
+ <link linkend="backup-archiving-wal">Its configuration</link>
+ consists mainly of a string that contains a copy command
+ in the operating system's syntax. In order to protect your
+ data against a disk crash, the destination location
+ of a basebackup as well as of the
+ <firstterm>archived WAL files</firstterm> should be on a
+ disk which is different from the data disk.
+ </para>
+
+ <para>
+ If it becomes necessary to restore the Cluster, you have to
+ copy the basebackup and the archived WAL files to
+ their original directories. The configuration of this
+ <link linkend="backup-pitr-recovery">recovery procedure</link>
+ contains a string with the reversed copy command: from
+ archive location to database location.
+ </para>
+
+ </sect1>
+
+<!-- ToDo: replication, index-types, extension mechanism, ...
+ <sect1 id="tutorial-replication">
+ <title>Replication</title>
+
+ <para>
+...
+ </para>
+
+ </sect1>
+-->
+
+ </chapter>
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 38e8aa0bbf..7490d3c9c2 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -80,6 +80,7 @@
%allfiles;
<!-- developer's guide -->
+<!ENTITY architecture SYSTEM "architecture.sgml">
<!ENTITY arch-dev SYSTEM "arch-dev.sgml">
<!ENTITY bki SYSTEM "bki.sgml">
<!ENTITY catalogs SYSTEM "catalogs.sgml">
diff --git a/doc/src/sgml/images/cluster-db-schema-ink-svgo.svg b/doc/src/sgml/images/cluster-db-schema-ink-svgo.svg
new file mode 100644
index 0000000000..487eec47e1
--- /dev/null
+++ b/doc/src/sgml/images/cluster-db-schema-ink-svgo.svg
@@ -0,0 +1,184 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="900" height="685" viewBox="0 0 900 685">
+ <title>
+ Server (Hardware, Container, or VM)
+ </title>
+ <style>
+ .text_normal,.text_small{font-style:normal;font-weight:400;font-family:"Open Sans",sans-serif;fill:#000}.text_small{font-size:12px}.text_normal{font-size:14px}
+ </style>
+ <defs>
+ <symbol id="rectangle_special_0">
+ <rect width="225" height="155" rx="10" stroke="blue" fill="none"/>
+ </symbol>
+ <symbol id="rectangle_special_1">
+ <rect width="225" height="155" rx="10" stroke="blue" fill="none"/>
+ <rect x="15" y="40" width="195" height="50" rx="10" stroke="blue" fill="none" stroke-dasharray="4 2"/>
+ <text class="text_normal" x="20" y="60">
+ schema 'public'
+ </text>
+ <text class="text_small" x="25" y="80">
+ tables, views, ...
+ </text>
+ <rect x="15" y="105" width="195" height="30" rx="10" stroke="blue" fill="none" stroke-dasharray="4 2"/>
+ <text class="text_small" x="20" y="125">
+ System schemas
+ </text>
+ </symbol>
+ <symbol id="rectangle_special_2">
+ <rect width="245" height="225" rx="10" stroke="blue" fill="none"/>
+ <rect x="15" y="40" width="205" height="50" rx="10" stroke="blue" fill="none" stroke-dasharray="4 2"/>
+ <text class="text_normal" x="20" y="60">
+ schema 'public'
+ </text>
+ <text class="text_small" x="25" y="80">
+ tables, views, ...
+ </text>
+ <rect x="15" y="105" width="205" height="30" rx="10" stroke="blue" fill="none" stroke-dasharray="4 2"/>
+ <text class="text_small" x="20" y="125">
+ System schemas
+ </text>
+ <rect x="15" y="150" width="205" height="50" rx="10" stroke="blue" fill="none" stroke-dasharray="4 2"/>
+ <text class="text_normal" x="20" y="170">
+ 'my_schema' (optional)
+ </text>
+ <text class="text_small" x="25" y="185">
+ tables, views, ...
+ </text>
+ </symbol>
+ <symbol id="note_0" stroke="black" fill="lightyellow">
+ <title>
+ UML Note
+ </title>
+ <path d="M190 10v70H0V0h180v10h10L180 0"/>
+ </symbol>
+ <symbol id="note_1" stroke="black" fill="lightyellow">
+ <title>
+ UML Note
+ </title>
+ <path d="M450 10v240H0V0h440v10h10L440 0"/>
+ </symbol>
+ <marker id="arrowhead_end" markerWidth="10" markerHeight="10" refX="6" refY="3" orient="auto">
+ <path d="M0 0l6 3-6 3" stroke="black" fill="none"/>
+ </marker>
+ </defs>
+ <rect x="1" y="1" rx="5" width="99%" height="99%" stroke="black" fill="none"/>
+ <text x="270" y="40" font-weight="400" font-size="24" font-family=""Open Sans",sans-serif">
+ Server (Hardware, Container, or VM)
+ </text>
+ <path stroke="blue" stroke-width="2" fill="none" d="M20 110h790v555H20z"/>
+ <text class="text_normal" x="180" y="25" transform="translate(20 110)">
+ cluster 'data' (default, managed by one instance)
+ </text>
+ <path d="M50 110V80h790v555h-30" stroke="blue" stroke-width="2" fill="none"/>
+ <text class="text_normal" x="190" y="-10" transform="translate(45 110)">
+ cluster 'cluster_2' (optional, managed by a different instance)
+ </text>
+ <g transform="translate(40 155)">
+ <use xlink:href="#rectangle_special_0"/>
+ <text class="text_normal" x="10" y="25">
+ database 'template0'
+ </text>
+ <use xlink:href="#note_0" x="20" y="40"/>
+ <text class="text_small" x="30" y="60">
+ 'template0' is a pristine
+ </text>
+ <text class="text_small" x="30" y="75">
+ and unchangeable template.
+ </text>
+ <text class="text_small" x="30" y="90">
+ It is used to generate
+ </text>
+ <text class="text_small" x="30" y="105">
+ database 'template1'.
+ </text>
+ </g>
+ <g transform="translate(290 155)">
+ <use xlink:href="#rectangle_special_1"/>
+ <text class="text_normal" x="10" y="25">
+ database 'template1'
+ </text>
+ </g>
+ <g transform="translate(540 155)">
+ <use xlink:href="#rectangle_special_2"/>
+ <text class="text_normal" x="10" y="25">
+ database 'postgres'
+ </text>
+ </g>
+ <g transform="translate(40 350)">
+ <use xlink:href="#rectangle_special_2"/>
+ <text class="text_normal" x="10" y="25">
+ database 'my_db' (optional)
+ </text>
+ </g>
+ <g transform="translate(320 330)">
+ <rect width="180" height="45" rx="10" stroke="blue" fill="none" stroke-dasharray="10 4 4 4"/>
+ <text class="text_normal" x="15" y="27">
+ Global SQL objects
+ </text>
+ <path d="M80 0v-30" stroke="black" fill="none" marker-end="url(#arrowhead_end)"/>
+ <path d="M180 40h50" stroke="black" fill="none" marker-end="url(#arrowhead_end)"/>
+ <path d="M0 40l-45 20" stroke="black" fill="none" marker-end="url(#arrowhead_end)"/>
+ </g>
+ <g transform="translate(335 405)">
+ <use xlink:href="#note_1"/>
+ <text class="text_small" x="10" y="20">
+ 1)
+ </text>
+ <text class="text_small" x="30" y="20">
+ By default, clients connect via port '5432' to Cluster 'data',
+ </text>
+ <text class="text_small" x="30" y="35">
+ database 'postgres', schema 'public'. Of course, they can
+ </text>
+ <text class="text_small" x="30" y="50">
+ specify other connection properties.
+ </text>
+ <text class="text_small" x="10" y="70">
+ 2)
+ </text>
+ <text class="text_small" x="30" y="70">
+ System schemas: pg_catalog, information_schema,
+ </text>
+ <text class="text_small" x="30" y="85">
+ pg_temp, ...
+ </text>
+ <text class="text_small" x="10" y="105">
+ 3)
+ </text>
+ <text class="text_small" x="30" y="105">
+ Global SQL objects: Objects which are shared among all
+ </text>
+ <text class="text_small" x="30" y="120">
+ databases within a Cluster.
+ </text>
+ <text class="text_small" x="10" y="140">
+ 4)
+ </text>
+ <text class="text_small" x="30" y="140">
+ The command 'initdb' creates a new cluster with the three
+ </text>
+ <text class="text_small" x="30" y="155">
+ databases 'template0', 'template1', and 'postgres'. The command
+ </text>
+ <text class="text_small" x="30" y="170">
+ 'createdb' creates a new database.
+ </text>
+ <text class="text_small" x="10" y="190">
+ 5)
+ </text>
+ <text class="text_small" x="30" y="190">
+ If multiple clusters are active on one server at the same time,
+ </text>
+ <text class="text_small" x="30" y="205">
+ each one is managed by an individual instance. Each such instance
+ </text>
+ <text class="text_small" x="30" y="220">
+ uses a different port.
+ </text>
+ <text class="text_small" x="10" y="240">
+ 6)
+ </text>
+ <text class="text_small" x="30" y="240">
+ Client application are prohibited from connecting to 'template0'.
+ </text>
+ </g>
+</svg>
diff --git a/doc/src/sgml/images/cluster-db-schema-ink.svg b/doc/src/sgml/images/cluster-db-schema-ink.svg
new file mode 100644
index 0000000000..05623a4092
--- /dev/null
+++ b/doc/src/sgml/images/cluster-db-schema-ink.svg
@@ -0,0 +1,528 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ version="1.1"
+ width="900px"
+ height="685px"
+ viewBox="0 0 900 685"
+ id="svg165"
+ sodipodi:docname="cluster-db-schema-ink.svg"
+ inkscape:version="0.92.5 (2060ec1f9f, 2020-04-08)">
+ <metadata
+ id="metadata169">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title>Server (Hardware, Container, or VM)</dc:title>
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <sodipodi:namedview
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1"
+ objecttolerance="10"
+ gridtolerance="10"
+ guidetolerance="10"
+ inkscape:pageopacity="0"
+ inkscape:pageshadow="2"
+ inkscape:window-width="780"
+ inkscape:window-height="480"
+ id="namedview167"
+ showgrid="false"
+ inkscape:zoom="0.34452555"
+ inkscape:cx="450"
+ inkscape:cy="342.5"
+ inkscape:window-x="66"
+ inkscape:window-y="27"
+ inkscape:window-maximized="0"
+ inkscape:current-layer="svg165" />
+ <title
+ id="title2">Server (Hardware, Container, or VM)</title>
+ <!-- common text classes -->
+ <style
+ type="text/css"
+ id="style4">
+ .text_small {font-style:normal;
+ font-weight:normal;
+ font-size:12px;
+ font-family:"Open Sans", sans-serif;
+ fill:black;
+ }
+ .text_normal {font-style:normal;
+ font-weight:normal;
+ font-size:14px;
+ font-family:"Open Sans", sans-serif;
+ fill:black;
+ }
+ .text_big {font-style:normal;
+ font-weight:normal;
+ font-size:24px;
+ font-family:"Open Sans", sans-serif;
+ fill:black;
+ }
+ </style>
+ <defs
+ id="defs57">
+ <!-- a rectangle with rounded corners and inner definitions for schemas -->
+ <symbol
+ id="rectangle_special_0">
+ <!-- the database -->
+ <rect
+ width="225"
+ height="155"
+ rx="10"
+ stroke="blue"
+ fill="none"
+ id="rect6" />
+ </symbol>
+ <!-- a rectangle with rounded corners and inner definitions for schemas -->
+ <symbol
+ id="rectangle_special_1">
+ <!-- the database -->
+ <rect
+ width="225"
+ height="155"
+ rx="10"
+ stroke="blue"
+ fill="none"
+ id="rect9" />
+ <!-- schemas -->
+ <rect
+ x="15"
+ y="40"
+ width="195"
+ height="50"
+ rx="10"
+ stroke="blue"
+ fill="none"
+ stroke-dasharray="4 2"
+ id="rect11" />
+ <text
+ class="text_normal"
+ x="20"
+ y="60"
+ id="text13">schema 'public'</text>
+ <text
+ class="text_small"
+ x="25"
+ y="80"
+ id="text15">tables, views, ...</text>
+ <rect
+ x="15"
+ y="105"
+ width="195"
+ height="30"
+ rx="10"
+ stroke="blue"
+ fill="none"
+ stroke-dasharray="4 2"
+ id="rect17" />
+ <text
+ class="text_small"
+ x="20"
+ y="125"
+ id="text19">System schemas</text>
+ </symbol>
+ <!-- same as before, but one more schema -->
+ <symbol
+ id="rectangle_special_2">
+ <!-- the database -->
+ <rect
+ width="245"
+ height="225"
+ rx="10"
+ stroke="blue"
+ fill="none"
+ id="rect22" />
+ <!-- schemas -->
+ <rect
+ x="15"
+ y="40"
+ width="205"
+ height="50"
+ rx="10"
+ stroke="blue"
+ fill="none"
+ stroke-dasharray="4 2"
+ id="rect24" />
+ <text
+ class="text_normal"
+ x="20"
+ y="60"
+ id="text26">schema 'public'</text>
+ <text
+ class="text_small"
+ x="25"
+ y="80"
+ id="text28">tables, views, ...</text>
+ <rect
+ x="15"
+ y="105"
+ width="205"
+ height="30"
+ rx="10"
+ stroke="blue"
+ fill="none"
+ stroke-dasharray="4 2"
+ id="rect30" />
+ <text
+ class="text_small"
+ x="20"
+ y="125"
+ id="text32">System schemas</text>
+ <rect
+ x="15"
+ y="150"
+ width="205"
+ height="50"
+ rx="10"
+ stroke="blue"
+ fill="none"
+ stroke-dasharray="4 2"
+ id="rect34" />
+ <text
+ class="text_normal"
+ x="20"
+ y="170"
+ id="text36">'my_schema' (optional)</text>
+ <text
+ class="text_small"
+ x="25"
+ y="185"
+ id="text38">tables, views, ...</text>
+ </symbol>
+ <symbol
+ id="note_0"
+ stroke="black"
+ fill="lightyellow">
+ <title
+ id="title41">UML Note</title>
+ <path
+ d="M 190,10 v 70 h -190 v -80 h 180 v 10 h 10 l -10,-10"
+ id="path43" />
+ </symbol>
+ <symbol
+ id="note_1"
+ stroke="black"
+ fill="lightyellow">
+ <title
+ id="title46">UML Note</title>
+ <path
+ d="M 450,10 v 240 h -450 v -250 h 440 v 10 h 10 l -10,-10"
+ id="path48" />
+ </symbol>
+ <!-- marker start/end -->
+ <marker
+ id="arrowhead_start"
+ markerWidth="10"
+ markerHeight="10"
+ refX="0"
+ refY="3"
+ orient="auto">
+ <path
+ d="M 6,0 l -6,3 l 6,3"
+ stroke="black"
+ fill="none"
+ id="path51" />
+ </marker>
+ <marker
+ id="arrowhead_end"
+ markerWidth="10"
+ markerHeight="10"
+ refX="6"
+ refY="3"
+ orient="auto">
+ <path
+ d="M 0,0 l 6,3 l -6,3"
+ stroke="black"
+ fill="none"
+ id="path54" />
+ </marker>
+ </defs>
+ <!-- start of rendering area -->
+ <!-- enclosing rectangle -->
+ <rect
+ x="1"
+ y="1"
+ rx="5"
+ width="99%"
+ height="99%"
+ stroke="black"
+ fill="none"
+ id="rect59" />
+ <text
+ class="text_big"
+ x="270"
+ y="40"
+ id="text61">Server (Hardware, Container, or VM)</text>
+ <!-- two clusters -->
+ <g
+ transform="translate(20 110)"
+ id="g67">
+ <rect
+ x="0"
+ y="0"
+ width="790"
+ height="555"
+ stroke="blue"
+ stroke-width="2px"
+ fill="none"
+ id="rect63" />
+ <text
+ class="text_normal"
+ x="180"
+ y="25"
+ id="text65">cluster 'data' (default, managed by one instance)</text>
+ </g>
+ <g
+ transform="translate(45 110)"
+ id="g73">
+ <path
+ d="M 5,0 v -30 h 790 v 555 h -30"
+ stroke="blue"
+ stroke-width="2px"
+ fill="none"
+ id="path69" />
+ <text
+ class="text_normal"
+ x="190"
+ y="-10"
+ id="text71">cluster 'cluster_2' (optional, managed by a different instance)</text>
+ </g>
+ <!-- database template 0 -->
+ <g
+ transform="translate(40 155)"
+ id="g89">
+ <use
+ xlink:href="#rectangle_special_0"
+ id="use75" />
+ <text
+ class="text_normal"
+ x="10"
+ y="25"
+ id="text77">database 'template0'</text>
+ <use
+ xlink:href="#note_0"
+ x="20"
+ y="40"
+ id="use79" />
+ <text
+ class="text_small"
+ x="30"
+ y="60"
+ id="text81">'template0' is a pristine</text>
+ <text
+ class="text_small"
+ x="30"
+ y="75"
+ id="text83">and unchangeable template.</text>
+ <text
+ class="text_small"
+ x="30"
+ y="90"
+ id="text85">It is used to generate</text>
+ <text
+ class="text_small"
+ x="30"
+ y="105"
+ id="text87">database 'template1'.</text>
+ </g>
+ <!-- database template 1 -->
+ <g
+ transform="translate(290 155)"
+ id="g95">
+ <use
+ xlink:href="#rectangle_special_1"
+ id="use91" />
+ <text
+ class="text_normal"
+ x="10"
+ y="25"
+ id="text93">database 'template1'</text>
+ </g>
+ <!-- database postgres -->
+ <g
+ transform="translate(540 155)"
+ id="g101">
+ <use
+ xlink:href="#rectangle_special_2"
+ id="use97" />
+ <text
+ class="text_normal"
+ x="10"
+ y="25"
+ id="text99">database 'postgres'</text>
+ </g>
+ <!-- database my_db -->
+ <g
+ transform="translate(40 350)"
+ id="g107">
+ <use
+ xlink:href="#rectangle_special_2"
+ id="use103" />
+ <text
+ class="text_normal"
+ x="10"
+ y="25"
+ id="text105">database 'my_db' (optional)</text>
+ </g>
+ <!-- global objects -->
+ <g
+ transform="translate(320 330)"
+ id="g119">
+ <rect
+ x="0"
+ y="0"
+ width="180"
+ height="45"
+ rx="10"
+ stroke="blue"
+ fill="none"
+ stroke-dasharray="10 4 4 4"
+ id="rect109" />
+ <text
+ class="text_normal"
+ x="15"
+ y="27"
+ id="text111">Global SQL objects</text>
+ <path
+ d="M 80,0 v-30"
+ stroke="black"
+ fill="none"
+ marker-end="url(#arrowhead_end)"
+ id="path113" />
+ <path
+ d="M 180,40 h50"
+ stroke="black"
+ fill="none"
+ marker-end="url(#arrowhead_end)"
+ id="path115" />
+ <path
+ d="M 0,40 l-45,20"
+ stroke="black"
+ fill="none"
+ marker-end="url(#arrowhead_end)"
+ id="path117" />
+ </g>
+ <!-- Some comments -->
+ <g
+ transform="translate(335 405)"
+ id="g163">
+ <use
+ xlink:href="#note_1"
+ x="0"
+ y="0"
+ id="use121" />
+ <text
+ class="text_small"
+ x="10"
+ y="20"
+ id="text123">1)</text>
+ <text
+ class="text_small"
+ x="30"
+ y="20"
+ id="text125">By default, clients connect via port '5432' to Cluster 'data',</text>
+ <text
+ class="text_small"
+ x="30"
+ y="35"
+ id="text127">database 'postgres', schema 'public'. Of course, they can</text>
+ <text
+ class="text_small"
+ x="30"
+ y="50"
+ id="text129">specify other connection properties.</text>
+ <text
+ class="text_small"
+ x="10"
+ y="70"
+ id="text131">2)</text>
+ <text
+ class="text_small"
+ x="30"
+ y="70"
+ id="text133">System schemas: pg_catalog, information_schema,</text>
+ <text
+ class="text_small"
+ x="30"
+ y="85"
+ id="text135">pg_temp, ...</text>
+ <text
+ class="text_small"
+ x="10"
+ y="105"
+ id="text137">3)</text>
+ <text
+ class="text_small"
+ x="30"
+ y="105"
+ id="text139">Global SQL objects: Objects which are shared among all</text>
+ <text
+ class="text_small"
+ x="30"
+ y="120"
+ id="text141">databases within a Cluster.</text>
+ <text
+ class="text_small"
+ x="10"
+ y="140"
+ id="text143">4)</text>
+ <text
+ class="text_small"
+ x="30"
+ y="140"
+ id="text145">The command 'initdb' creates a new cluster with the three</text>
+ <text
+ class="text_small"
+ x="30"
+ y="155"
+ id="text147">databases 'template0', 'template1', and 'postgres'. The command</text>
+ <text
+ class="text_small"
+ x="30"
+ y="170"
+ id="text149">'createdb' creates a new database.</text>
+ <text
+ class="text_small"
+ x="10"
+ y="190"
+ id="text151">5)</text>
+ <text
+ class="text_small"
+ x="30"
+ y="190"
+ id="text153">If multiple clusters are active on one server at the same time,</text>
+ <text
+ class="text_small"
+ x="30"
+ y="205"
+ id="text155">each one is managed by an individual instance. Each such instance</text>
+ <text
+ class="text_small"
+ x="30"
+ y="220"
+ id="text157">uses a different port.</text>
+ <text
+ class="text_small"
+ x="10"
+ y="240"
+ id="text159">6)</text>
+ <text
+ class="text_small"
+ x="30"
+ y="240"
+ id="text161">Client application are prohibited from connecting to 'template0'.</text>
+ </g>
+</svg>
diff --git a/doc/src/sgml/images/cluster-db-schema-raw.svg b/doc/src/sgml/images/cluster-db-schema-raw.svg
new file mode 100644
index 0000000000..8534b18ec2
--- /dev/null
+++ b/doc/src/sgml/images/cluster-db-schema-raw.svg
@@ -0,0 +1,191 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg xmlns="http://www.w3.org/2000/svg"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ version="1.1"
+ width="900px" height="685px"
+ viewBox="0 0 900 685" >
+
+ <title>Server (Hardware, Container, or VM)</title>
+
+ <!-- common text classes -->
+ <style type="text/css">
+ .text_small {font-style:normal;
+ font-weight:normal;
+ font-size:12px;
+ font-family:"Open Sans", sans-serif;
+ fill:black;
+ }
+ .text_normal {font-style:normal;
+ font-weight:normal;
+ font-size:14px;
+ font-family:"Open Sans", sans-serif;
+ fill:black;
+ }
+ .text_big {font-style:normal;
+ font-weight:normal;
+ font-size:24px;
+ font-family:"Open Sans", sans-serif;
+ fill:black;
+ }
+ </style>
+
+ <defs>
+ <!-- a rectangle with rounded corners and inner definitions for schemas -->
+ <symbol id="rectangle_special_0">
+
+ <!-- the database -->
+ <rect width="225" height="155" rx="10" stroke="blue" fill="none"/>
+
+ </symbol>
+
+ <!-- a rectangle with rounded corners and inner definitions for schemas -->
+ <symbol id="rectangle_special_1">
+
+ <!-- the database -->
+ <rect width="225" height="155" rx="10" stroke="blue" fill="none"/>
+
+ <!-- schemas -->
+ <rect x="15" y="40" width="195" height="50" rx="10" stroke="blue" fill="none" stroke-dasharray="4 2" />
+ <text class="text_normal" x="20" y="60">schema 'public'</text>
+ <text class="text_small" x="25" y="80">tables, views, ...</text>
+
+ <rect x="15" y="105" width="195" height="30" rx="10" stroke="blue" fill="none" stroke-dasharray="4 2" />
+ <text class="text_small" x="20" y="125">System schemas</text>
+ </symbol>
+
+ <!-- same as before, but one more schema -->
+ <symbol id="rectangle_special_2">
+ <!-- the database -->
+ <rect width="245" height="225" rx="10" stroke="blue" fill="none"/>
+
+ <!-- schemas -->
+ <rect x="15" y="40" width="205" height="50" rx="10" stroke="blue" fill="none" stroke-dasharray="4 2" />
+ <text class="text_normal" x="20" y="60">schema 'public'</text>
+ <text class="text_small" x="25" y="80">tables, views, ...</text>
+
+ <rect x="15" y="105" width="205" height="30" rx="10" stroke="blue" fill="none" stroke-dasharray="4 2" />
+ <text class="text_small" x="20" y="125">System schemas</text>
+
+ <rect x="15" y="150" width="205" height="50" rx="10" stroke="blue" fill="none" stroke-dasharray="4 2" />
+ <text class="text_normal" x="20" y="170">'my_schema' (optional)</text>
+ <text class="text_small" x="25" y="185">tables, views, ...</text>
+ </symbol>
+
+ <symbol id="note_0" stroke="black" fill="lightyellow">
+ <title>UML Note</title>
+ <path d="M 190,10 v 70 h -190 v -80 h 180 v 10 h 10 l -10,-10" />
+ </symbol>
+
+ <symbol id="note_1" stroke="black" fill="lightyellow">
+ <title>UML Note</title>
+ <path d="M 450,10 v 240 h -450 v -250 h 440 v 10 h 10 l -10,-10" />
+ </symbol>
+
+ <!-- marker start/end -->
+ <marker id="arrowhead_start"
+ markerWidth="10"
+ markerHeight="10"
+ refX="0"
+ refY="3"
+ orient="auto">
+ <path d="M 6,0 l -6,3 l 6,3" stroke="black" fill="none" />
+ </marker>
+ <marker id="arrowhead_end"
+ markerWidth="10"
+ markerHeight="10"
+ refX="6"
+ refY="3"
+ orient="auto">
+ <path d="M 0,0 l 6,3 l -6,3" stroke="black" fill="none" />
+ </marker>
+
+ </defs>
+
+
+ <!-- start of rendering area -->
+ <!-- enclosing rectangle -->
+ <rect x="1" y="1" rx="5" width="99%" height="99%" stroke="black" fill="none" />
+ <text class="text_big" x="270" y="40">Server (Hardware, Container, or VM)</text>
+
+ <!-- two clusters -->
+ <g transform="translate(20 110)">
+ <rect x="0" y="0" width="790" height="555" stroke="blue" stroke-width="2px" fill="none" />
+ <text class="text_normal" x="180" y="25">cluster 'data' (default, managed by one instance)</text>
+ </g>
+ <g transform="translate(45 110)">
+ <path d="M 5,0 v -30 h 790 v 555 h -30" stroke="blue" stroke-width="2px" fill="none" />
+ <text class="text_normal" x="190" y="-10">cluster 'cluster_2' (optional, managed by a different instance)</text>
+ </g>
+
+
+ <!-- database template 0 -->
+ <g transform="translate(40 155)">
+ <use xlink:href="#rectangle_special_0" />
+ <text class="text_normal" x="10" y="25">database 'template0'</text>
+ <use xlink:href="#note_0" x="20" y="40" />
+ <text class="text_small" x="30" y="60">'template0' is a pristine</text>
+ <text class="text_small" x="30" y="75">and unchangeable template.</text>
+ <text class="text_small" x="30" y="90">It is used to generate</text>
+ <text class="text_small" x="30" y="105">database 'template1'.</text>
+ </g>
+
+ <!-- database template 1 -->
+ <g transform="translate(290 155)">
+ <use xlink:href="#rectangle_special_1" />
+ <text class="text_normal" x="10" y="25">database 'template1'</text>
+ </g>
+
+ <!-- database postgres -->
+ <g transform="translate(540 155)">
+ <use xlink:href="#rectangle_special_2" />
+ <text class="text_normal" x="10" y="25">database 'postgres'</text>
+ </g>
+
+ <!-- database my_db -->
+ <g transform="translate(40 350)">
+ <use xlink:href="#rectangle_special_2" />
+ <text class="text_normal" x="10" y="25">database 'my_db' (optional)</text>
+ </g>
+
+ <!-- global objects -->
+ <g transform="translate(320 330)">
+ <rect x="0" y="0" width="180" height="45" rx="10" stroke="blue" fill="none" stroke-dasharray="10 4 4 4" />
+ <text class="text_normal" x="15" y="27">Global SQL objects</text>
+ <path d="M 80,0 v-30" stroke="black" fill="none" marker-end="url(#arrowhead_end)" />
+ <path d="M 180,40 h50" stroke="black" fill="none" marker-end="url(#arrowhead_end)" />
+ <path d="M 0,40 l-45,20" stroke="black" fill="none" marker-end="url(#arrowhead_end)" />
+ </g>
+
+ <!-- Some comments -->
+ <g transform="translate(335 405)">
+ <use xlink:href="#note_1" x="0" y="0" />
+
+ <text class="text_small" x="10" y="20">1)</text>
+ <text class="text_small" x="30" y="20">By default, clients connect via port '5432' to Cluster 'data',</text>
+ <text class="text_small" x="30" y="35">database 'postgres', schema 'public'. Of course, they can</text>
+ <text class="text_small" x="30" y="50">specify other connection properties.</text>
+
+ <text class="text_small" x="10" y="70">2)</text>
+ <text class="text_small" x="30" y="70">System schemas: pg_catalog, information_schema,</text>
+ <text class="text_small" x="30" y="85">pg_temp, ...</text>
+
+ <text class="text_small" x="10" y="105">3)</text>
+ <text class="text_small" x="30" y="105">Global SQL objects: Objects which are shared among all</text>
+ <text class="text_small" x="30" y="120">databases within a Cluster.</text>
+
+ <text class="text_small" x="10" y="140">4)</text>
+ <text class="text_small" x="30" y="140">The command 'initdb' creates a new cluster with the three</text>
+ <text class="text_small" x="30" y="155">databases 'template0', 'template1', and 'postgres'. The command</text>
+ <text class="text_small" x="30" y="170">'createdb' creates a new database.</text>
+
+ <text class="text_small" x="10" y="190">5)</text>
+ <text class="text_small" x="30" y="190">If multiple clusters are active on one server at the same time,</text>
+ <text class="text_small" x="30" y="205">each one is managed by an individual instance. Each such instance</text>
+ <text class="text_small" x="30" y="220">uses a different port.</text>
+
+ <text class="text_small" x="10" y="240">6)</text>
+ <text class="text_small" x="30" y="240">Client application are prohibited from connecting to 'template0'.</text>
+
+ </g>
+
+</svg>
diff --git a/doc/src/sgml/images/directories-ink-svgo.svg b/doc/src/sgml/images/directories-ink-svgo.svg
new file mode 100644
index 0000000000..a59198c66f
--- /dev/null
+++ b/doc/src/sgml/images/directories-ink-svgo.svg
@@ -0,0 +1,164 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="900" height="640" viewBox="0 0 900 640">
+ <title>
+ Directory structure of a cluster
+ </title>
+ <style>
+ .text_italic,.text_normal{font-weight:400;font-size:14px;font-family:"Open Sans",sans-serif}.text_normal{font-style:normal;fill:#000}.text_italic{font-style:italic;fill:silver}
+ </style>
+ <defs>
+ <symbol id="directory" stroke="blue" stroke-width=".3" fill="aqua">
+ <title>
+ Directory
+ </title>
+ <path d="M0 10h110v20H0z"/>
+ <path d="M0 10V8l3-3h35l3 3v2"/>
+ </symbol>
+ <symbol id="file" stroke="black" fill="none">
+ <title>
+ File
+ </title>
+ <path stroke="blue" d="M0 0h40v50H0z"/>
+ <path d="M5 10h20" stroke-dasharray="4 2"/>
+ <path d="M5 17h15" stroke-dasharray="6 2"/>
+ <path d="M5 24h25" stroke-dasharray="4 2"/>
+ <path d="M5 31h20" stroke-dasharray="5 2"/>
+ </symbol>
+ </defs>
+ <rect x="1" y="1" rx="5" width="99%" height="99%" stroke="black" fill="none"/>
+ <text x="200" y="50" font-weight="400" font-size="24" font-family=""Open Sans",sans-serif">
+ Directory Structure
+ </text>
+ <g transform="translate(20 100)">
+ <use xlink:href="#directory"/>
+ <text x="10" y="26" class="text_italic">
+ /var/lib/pgsql/
+ </text>
+ <text x="300" y="26" class="text_normal">
+ An arbitrary directory
+ </text>
+ </g>
+ <g transform="translate(70 130)">
+ <use xlink:href="#directory"/>
+ <text x="10" y="26" class="text_italic">
+ data/
+ </text>
+ <text x="250" y="26" class="text_normal">
+ Cluster's root directory (with an arbitrary name; see: PGDATA)
+ </text>
+ </g>
+ <g transform="translate(120 160)">
+ <use xlink:href="#directory"/>
+ <text x="10" y="26" class="text_normal">
+ base/
+ </text>
+ <text x="200" y="26" class="text_normal">
+ Subdirectory containing per-database subdirectories
+ </text>
+ </g>
+ <g transform="translate(170 190)">
+ <use xlink:href="#directory"/>
+ <text x="10" y="26" class="text_normal">
+ 1/
+ </text>
+ <text x="150" y="26" class="text_normal">
+ Subdirectory for data in default-tablespace of first database 'template0'
+ </text>
+ </g>
+ <g transform="translate(170 220)">
+ <use xlink:href="#directory"/>
+ <text x="10" y="26" class="text_normal">
+ 12992/
+ </text>
+ <text x="150" y="26" class="text_normal">
+ Subdirectory for data in default-tablespace of second database 'template1'
+ </text>
+ </g>
+ <g transform="translate(170 250)">
+ <use xlink:href="#directory"/>
+ <text x="10" y="26" class="text_normal">
+ 12999/
+ </text>
+ <text x="150" y="26" class="text_normal">
+ Subdirectory for data in default-tablespace of third database 'postgres'
+ </text>
+ </g>
+ <g transform="translate(170 280)">
+ <use xlink:href="#directory"/>
+ <text x="10" y="26" class="text_normal">
+ nnnnn/
+ </text>
+ <text x="150" y="26" class="text_normal">
+ Optional: one subdirectory for each new database, e.g. '23456' for 'my_db'
+ </text>
+ </g>
+ <g transform="translate(120 310)">
+ <use xlink:href="#directory"/>
+ <text x="10" y="26" class="text_normal">
+ global/
+ </text>
+ <text x="200" y="26" class="text_normal">
+ Subdirectory for information about Global SQL Objects
+ </text>
+ </g>
+ <g transform="translate(120 340)">
+ <use xlink:href="#directory"/>
+ <text x="10" y="26" class="text_normal">
+ pg_tblspc/
+ </text>
+ <text x="200" y="26" class="text_normal">
+ Subdirectory for symbolic links to non-default tablespaces
+ </text>
+ </g>
+ <g transform="translate(120 370)">
+ <use xlink:href="#directory"/>
+ <text x="10" y="26" class="text_normal">
+ pg_wal/
+ </text>
+ <text x="200" y="26" class="text_normal">
+ Subdirectory for Write Ahead Log files ('pg_xlog' before version 10)
+ </text>
+ </g>
+ <g transform="translate(120 400)">
+ <use xlink:href="#directory"/>
+ <text x="10" y="26" class="text_normal">
+ pg_xact/
+ </text>
+ <text x="200" y="26" class="text_normal">
+ Subdirectory for transaction commit status ('pg_clog' before version 10)
+ </text>
+ </g>
+ <g transform="translate(120 430)">
+ <use xlink:href="#directory"/>
+ <text x="10" y="26" class="text_normal">
+ pg_... /
+ </text>
+ <text x="200" y="26" class="text_normal">
+ Some more subdirectories
+ </text>
+ </g>
+ <g transform="translate(120 465)">
+ <use xlink:href="#file"/>
+ <use xlink:href="#file" x="50"/>
+ <text x="200" y="26" class="text_normal">
+ 'postmaster.pid' and other files with cluster-wide relevance
+ </text>
+ </g>
+ <g transform="translate(20 540)">
+ <use xlink:href="#directory"/>
+ <text x="10" y="26" class="text_italic">
+ ...
+ </text>
+ <text x="300" y="26" class="text_normal">
+ Same or another arbitrary directory
+ </text>
+ </g>
+ <g transform="translate(70 570)">
+ <use xlink:href="#directory"/>
+ <text x="10" y="26" class="text_italic">
+ cluster_2/
+ </text>
+ <text x="250" y="26" class="text_normal">
+ Root of another cluster
+ </text>
+ </g>
+</svg>
diff --git a/doc/src/sgml/images/directories-ink.svg b/doc/src/sgml/images/directories-ink.svg
new file mode 100644
index 0000000000..615a6d214a
--- /dev/null
+++ b/doc/src/sgml/images/directories-ink.svg
@@ -0,0 +1,403 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ version="1.1"
+ width="900px"
+ height="640px"
+ viewBox="0 0 900 640"
+ id="svg329"
+ sodipodi:docname="directories-ink.svg"
+ inkscape:version="0.92.5 (2060ec1f9f, 2020-04-08)">
+ <metadata
+ id="metadata333">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title>Directory structure of a cluster</dc:title>
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <sodipodi:namedview
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1"
+ objecttolerance="10"
+ gridtolerance="10"
+ guidetolerance="10"
+ inkscape:pageopacity="0"
+ inkscape:pageshadow="2"
+ inkscape:window-width="1106"
+ inkscape:window-height="813"
+ id="namedview331"
+ showgrid="false"
+ inkscape:zoom="0.36875"
+ inkscape:cx="450"
+ inkscape:cy="311.86441"
+ inkscape:window-x="66"
+ inkscape:window-y="27"
+ inkscape:window-maximized="0"
+ inkscape:current-layer="svg329" />
+ <title
+ id="title179">Directory structure of a cluster</title>
+ <style
+ type="text/css"
+ id="style181">
+ .text_normal {font-style:normal;
+ font-weight:normal;
+ font-size:14px;
+ font-family:"Open Sans", sans-serif;
+ fill:black;
+ }
+ .text_italic {font-style:italic;
+ font-weight:normal;
+ font-size:14px;
+ font-family:"Open Sans", sans-serif;
+ fill:silver;
+ }
+ .text_big {font-style:normal;
+ font-weight:normal;
+ font-size:24px;
+ font-family:"Open Sans", sans-serif;
+ fill:black;
+ }
+ </style>
+ <defs
+ id="defs203">
+ <!-- Directory -->
+ <symbol
+ id="directory"
+ stroke="blue"
+ stroke-width="0.3px"
+ fill="aqua">
+ <title
+ id="title183">Directory</title>
+ <rect
+ x="0"
+ y="10"
+ width="110"
+ height="20"
+ id="rect185" />
+ <path
+ d="M 0,10 l 0,-2 3,-3 35,0, 3,3 0,2"
+ id="path187" />
+ </symbol>
+ <!-- File -->
+ <symbol
+ id="file"
+ stroke="black"
+ fill="none">
+ <title
+ id="title190">File</title>
+ <rect
+ x="0"
+ y="0"
+ width="40"
+ height="50"
+ stroke="blue"
+ id="rect192" />
+ <path
+ d="M 5,10 h 20"
+ stroke-dasharray="4 2"
+ id="path194" />
+ <path
+ d="M 5,17 h 15"
+ stroke-dasharray="6 2"
+ id="path196" />
+ <path
+ d="M 5,24 h 25"
+ stroke-dasharray="4 2"
+ id="path198" />
+ <path
+ d="M 5,31 h 20"
+ stroke-dasharray="5 2"
+ id="path200" />
+ </symbol>
+ </defs>
+ <!-- start of rendering area -->
+ <!-- enclosing rectangle -->
+ <rect
+ x="1"
+ y="1"
+ rx="5"
+ width="99%"
+ height="99%"
+ stroke="black"
+ fill="none"
+ id="rect205" />
+ <!-- caption -->
+ <text
+ x="200"
+ y="50"
+ class="text_big"
+ id="text207">Directory Structure</text>
+ <!-- the directories -->
+ <g
+ transform="translate(20, 100)"
+ id="g215">
+ <use
+ xlink:href="#directory"
+ id="use209" />
+ <text
+ x="10"
+ y="26"
+ class="text_italic"
+ id="text211">/var/lib/pgsql/</text>
+ <text
+ x="300"
+ y="26"
+ class="text_normal"
+ id="text213">An arbitrary directory</text>
+ </g>
+ <g
+ transform="translate(70, 130)"
+ id="g223">
+ <use
+ xlink:href="#directory"
+ id="use217" />
+ <text
+ x="10"
+ y="26"
+ class="text_italic"
+ id="text219">data/</text>
+ <text
+ x="250"
+ y="26"
+ class="text_normal"
+ id="text221">Cluster's root directory (with an arbitrary name; see: PGDATA)</text>
+ </g>
+ <g
+ transform="translate(120, 160)"
+ id="g231">
+ <use
+ xlink:href="#directory"
+ id="use225" />
+ <text
+ x="10"
+ y="26"
+ class="text_normal"
+ id="text227">base/</text>
+ <text
+ x="200"
+ y="26"
+ class="text_normal"
+ id="text229">Subdirectory containing per-database subdirectories</text>
+ </g>
+ <!-- -->
+ <g
+ transform="translate(170, 190)"
+ id="g239">
+ <use
+ xlink:href="#directory"
+ id="use233" />
+ <text
+ x="10"
+ y="26"
+ class="text_normal"
+ id="text235">1/</text>
+ <text
+ x="150"
+ y="26"
+ class="text_normal"
+ id="text237">Subdirectory for data in default-tablespace of first database 'template0'</text>
+ </g>
+ <g
+ transform="translate(170, 220)"
+ id="g247">
+ <use
+ xlink:href="#directory"
+ id="use241" />
+ <text
+ x="10"
+ y="26"
+ class="text_normal"
+ id="text243">12992/</text>
+ <text
+ x="150"
+ y="26"
+ class="text_normal"
+ id="text245">Subdirectory for data in default-tablespace of second database 'template1'</text>
+ </g>
+ <g
+ transform="translate(170, 250)"
+ id="g255">
+ <use
+ xlink:href="#directory"
+ id="use249" />
+ <text
+ x="10"
+ y="26"
+ class="text_normal"
+ id="text251">12999/</text>
+ <text
+ x="150"
+ y="26"
+ class="text_normal"
+ id="text253">Subdirectory for data in default-tablespace of third database 'postgres'</text>
+ </g>
+ <g
+ transform="translate(170, 280)"
+ id="g263">
+ <use
+ xlink:href="#directory"
+ id="use257" />
+ <text
+ x="10"
+ y="26"
+ class="text_normal"
+ id="text259">nnnnn/</text>
+ <text
+ x="150"
+ y="26"
+ class="text_normal"
+ id="text261">Optional: one subdirectory for each new database, e.g. '23456' for 'my_db'</text>
+ </g>
+ <g
+ transform="translate(120, 310)"
+ id="g271">
+ <use
+ xlink:href="#directory"
+ id="use265" />
+ <text
+ x="10"
+ y="26"
+ class="text_normal"
+ id="text267">global/</text>
+ <text
+ x="200"
+ y="26"
+ class="text_normal"
+ id="text269">Subdirectory for information about Global SQL Objects</text>
+ </g>
+ <g
+ transform="translate(120, 340)"
+ id="g279">
+ <use
+ xlink:href="#directory"
+ id="use273" />
+ <text
+ x="10"
+ y="26"
+ class="text_normal"
+ id="text275">pg_tblspc/</text>
+ <text
+ x="200"
+ y="26"
+ class="text_normal"
+ id="text277">Subdirectory for symbolic links to non-default tablespaces</text>
+ </g>
+ <g
+ transform="translate(120, 370)"
+ id="g287">
+ <use
+ xlink:href="#directory"
+ id="use281" />
+ <text
+ x="10"
+ y="26"
+ class="text_normal"
+ id="text283">pg_wal/</text>
+ <text
+ x="200"
+ y="26"
+ class="text_normal"
+ id="text285">Subdirectory for Write Ahead Log files ('pg_xlog' before version 10)</text>
+ </g>
+ <g
+ transform="translate(120, 400)"
+ id="g295">
+ <use
+ xlink:href="#directory"
+ id="use289" />
+ <text
+ x="10"
+ y="26"
+ class="text_normal"
+ id="text291">pg_xact/</text>
+ <text
+ x="200"
+ y="26"
+ class="text_normal"
+ id="text293">Subdirectory for transaction commit status ('pg_clog' before version 10)</text>
+ </g>
+ <g
+ transform="translate(120, 430)"
+ id="g303">
+ <use
+ xlink:href="#directory"
+ id="use297" />
+ <text
+ x="10"
+ y="26"
+ class="text_normal"
+ id="text299">pg_... /</text>
+ <text
+ x="200"
+ y="26"
+ class="text_normal"
+ id="text301">Some more subdirectories</text>
+ </g>
+ <g
+ transform="translate(120, 465)"
+ id="g311">
+ <use
+ xlink:href="#file"
+ x="0"
+ y="0"
+ id="use305" />
+ <use
+ xlink:href="#file"
+ x="50"
+ y="0"
+ id="use307" />
+ <text
+ x="200"
+ y="26"
+ class="text_normal"
+ id="text309">'postmaster.pid' and other files with cluster-wide relevance</text>
+ </g>
+ <!-- next cluster -->
+ <g
+ transform="translate(20, 540)"
+ id="g319">
+ <use
+ xlink:href="#directory"
+ id="use313" />
+ <text
+ x="10"
+ y="26"
+ class="text_italic"
+ id="text315">...</text>
+ <text
+ x="300"
+ y="26"
+ class="text_normal"
+ id="text317">Same or another arbitrary directory</text>
+ </g>
+ <g
+ transform="translate(70, 570)"
+ id="g327">
+ <use
+ xlink:href="#directory"
+ id="use321" />
+ <text
+ x="10"
+ y="26"
+ class="text_italic"
+ id="text323">cluster_2/</text>
+ <text
+ x="250"
+ y="26"
+ class="text_normal"
+ id="text325">Root of another cluster</text>
+ </g>
+</svg>
diff --git a/doc/src/sgml/images/directories-raw.svg b/doc/src/sgml/images/directories-raw.svg
new file mode 100644
index 0000000000..5cce551b0c
--- /dev/null
+++ b/doc/src/sgml/images/directories-raw.svg
@@ -0,0 +1,150 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg xmlns="http://www.w3.org/2000/svg"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ version="1.1"
+ width="900px" height="640px"
+ viewBox="0 0 900 640">
+
+ <title>Directory structure of a cluster</title>
+
+ <style type="text/css">
+ .text_normal {font-style:normal;
+ font-weight:normal;
+ font-size:14px;
+ font-family:"Open Sans", sans-serif;
+ fill:black;
+ }
+ .text_italic {font-style:italic;
+ font-weight:normal;
+ font-size:14px;
+ font-family:"Open Sans", sans-serif;
+ fill:silver;
+ }
+ .text_big {font-style:normal;
+ font-weight:normal;
+ font-size:24px;
+ font-family:"Open Sans", sans-serif;
+ fill:black;
+ }
+ </style>
+
+ <defs>
+
+ <!-- Directory -->
+ <symbol id="directory" stroke="blue" stroke-width="0.3px" fill="aqua">
+ <title>Directory</title>
+ <rect x="0" y="10" width="110" height="20" />
+ <path d="M 0,10 l 0,-2 3,-3 35,0, 3,3 0,2" />
+ </symbol>
+
+ <!-- File -->
+ <symbol id="file" stroke="black" fill="none" >
+ <title>File</title>
+ <rect x="0" y="0" width="40" height="50" stroke="blue" />
+ <path d="M 5,10 h 20" stroke-dasharray="4 2" />
+ <path d="M 5,17 h 15" stroke-dasharray="6 2" />
+ <path d="M 5,24 h 25" stroke-dasharray="4 2" />
+ <path d="M 5,31 h 20" stroke-dasharray="5 2" />
+ </symbol>
+
+ </defs>
+
+
+ <!-- start of rendering area -->
+ <!-- enclosing rectangle -->
+ <rect x="1" y="1" rx="5" width="99%" height="99%" stroke="black" fill="none" />
+
+ <!-- caption -->
+ <text x="200" y="50" class="text_big">Directory Structure</text>
+
+ <!-- the directories -->
+ <g transform="translate(20, 100)">
+ <use xlink:href="#directory" />
+ <text x="10" y="26" class="text_italic">/var/lib/pgsql/</text>
+ <text x="300" y="26" class="text_normal">An arbitrary directory</text>
+ </g>
+
+ <g transform="translate(70, 130)">
+ <use xlink:href="#directory" />
+ <text x="10" y="26" class="text_italic">data/</text>
+ <text x="250" y="26" class="text_normal">Cluster's root directory (with an arbitrary name; see: PGDATA)</text>
+ </g>
+
+ <g transform="translate(120, 160)">
+ <use xlink:href="#directory" />
+ <text x="10" y="26" class="text_normal">base/</text>
+ <text x="200" y="26" class="text_normal">Subdirectory containing per-database subdirectories</text>
+ </g>
+
+ <!-- -->
+ <g transform="translate(170, 190)">
+ <use xlink:href="#directory" />
+ <text x="10" y="26" class="text_normal">1/</text>
+ <text x="150" y="26" class="text_normal">Subdirectory for data in default-tablespace of first database 'template0'</text>
+ </g>
+ <g transform="translate(170, 220)">
+ <use xlink:href="#directory" />
+ <text x="10" y="26" class="text_normal">12992/</text>
+ <text x="150" y="26" class="text_normal">Subdirectory for data in default-tablespace of second database 'template1'</text>
+ </g>
+ <g transform="translate(170, 250)">
+ <use xlink:href="#directory" />
+ <text x="10" y="26" class="text_normal">12999/</text>
+ <text x="150" y="26" class="text_normal">Subdirectory for data in default-tablespace of third database 'postgres'</text>
+ </g>
+ <g transform="translate(170, 280)">
+ <use xlink:href="#directory" />
+ <text x="10" y="26" class="text_normal">nnnnn/</text>
+ <text x="150" y="26" class="text_normal">Optional: one subdirectory for each new database, e.g. '23456' for 'my_db'</text>
+ </g>
+
+ <g transform="translate(120, 310)">
+ <use xlink:href="#directory" />
+ <text x="10" y="26" class="text_normal">global/</text>
+ <text x="200" y="26" class="text_normal">Subdirectory for information about Global SQL Objects</text>
+ </g>
+
+ <g transform="translate(120, 340)">
+ <use xlink:href="#directory" />
+ <text x="10" y="26" class="text_normal">pg_tblspc/</text>
+ <text x="200" y="26" class="text_normal">Subdirectory for symbolic links to non-default tablespaces</text>
+ </g>
+
+ <g transform="translate(120, 370)">
+ <use xlink:href="#directory" />
+ <text x="10" y="26" class="text_normal">pg_wal/</text>
+ <text x="200" y="26" class="text_normal">Subdirectory for Write Ahead Log files ('pg_xlog' before version 10)</text>
+ </g>
+
+ <g transform="translate(120, 400)">
+ <use xlink:href="#directory" />
+ <text x="10" y="26" class="text_normal">pg_xact/</text>
+ <text x="200" y="26" class="text_normal">Subdirectory for transaction commit status ('pg_clog' before version 10)</text>
+ </g>
+
+ <g transform="translate(120, 430)">
+ <use xlink:href="#directory" />
+ <text x="10" y="26" class="text_normal">pg_... /</text>
+ <text x="200" y="26" class="text_normal">Some more subdirectories</text>
+ </g>
+
+ <g transform="translate(120, 465)">
+ <use xlink:href="#file" x="0" y="0" />
+ <use xlink:href="#file" x="50" y="0" />
+ <text x="200" y="26" class="text_normal">'postmaster.pid' and other files with cluster-wide relevance</text>
+ </g>
+
+ <!-- next cluster -->
+ <g transform="translate(20, 540)">
+ <use xlink:href="#directory" />
+ <text x="10" y="26" class="text_italic">...</text>
+ <text x="300" y="26" class="text_normal">Same or another arbitrary directory</text>
+ </g>
+
+ <g transform="translate(70, 570)">
+ <use xlink:href="#directory" />
+ <text x="10" y="26" class="text_italic">cluster_2/</text>
+ <text x="250" y="26" class="text_normal">Root of another cluster</text>
+ </g>
+
+</svg>
diff --git a/doc/src/sgml/images/freeze-ink-svgo.svg b/doc/src/sgml/images/freeze-ink-svgo.svg
new file mode 100644
index 0000000000..b1543ffae5
--- /dev/null
+++ b/doc/src/sgml/images/freeze-ink-svgo.svg
@@ -0,0 +1,84 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="850" height="320" viewBox="0 0 850 320">
+ <title>
+ Freeze
+ </title>
+ <style>
+ .text_normal{font-style:normal;font-weight:400;font-size:14px;font-family:"Open Sans",sans-serif;fill:#000}
+ </style>
+ <defs>
+ <path id="Path_080" d="M-80 0A80 80 0 1180 0 80 80 0 11-80 0"/>
+ <path id="Path_095" d="M-95 0A95 95 0 1195 0 95 95 0 11-95 0"/>
+ <path id="Path_120" d="M-120 0a120 120 0 11240 0 120 120 0 11-240 0"/>
+ <circle id="frozenPoint" r="3" stroke="green" fill="green" transform="translate(-100)"/>
+ <circle id="unfrozenPoint" r="3" stroke="green" fill="none" transform="translate(-100)"/>
+ </defs>
+ <rect x="1" y="1" rx="5" width="99%" height="99%" stroke="black" fill="none"/>
+ <text x="70" y="40" font-weight="400" font-size="24" font-family=""Open Sans",sans-serif,Helvetica">
+ <tspan font-style="italic" font-weight="700">Freeze</tspan> to keep visible
+ </text>
+ <g fill="none" transform="translate(170 190)">
+ <circle r="100" stroke="blue"/>
+ <text class="text_normal">
+ <textPath xlink:href="#Path_095" startOffset=".5%">|</textPath> <textPath xlink:href="#Path_120" startOffset="0%">(0)</textPath> <textPath xlink:href="#Path_080" startOffset="1%" stroke="blue" stroke-width=".5"> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ></textPath> <textPath xlink:href="#Path_120" startOffset="11.2%">(1)</textPath> <textPath xlink:href="#Path_120" startOffset="61.2%">(5)</textPath> <textPath xlink:href="#Path_095" stroke="red" stroke-width="3" startOffset="34%">|</textPath> <textPath xlink:href="#Path_120" startOffset="34%">(2)</textPath> <textPath xlink:href="#Path_095" stroke="black" stroke-width="3" startOffset="45%">|</textPath> <textPath xlink:href="#Path_120" startOffset="45%">(3)</textPath> <textPath xlink:href="#Path_095" stroke="green" stroke-width="3" startOffset="55%">|</textPath> <textPath xlink:href="#Path_120" startOffset="55%">(4)</textPath>
+ </text>
+ <path d="M-80-80L80 80" stroke="black"/>
+ <text class="text_normal" letter-spacing="12" transform="rotate(45 40.78 -38.1)">
+ PAST
+ </text>
+ <text class="text_normal" letter-spacing="12" transform="rotate(-135 27.43 23.79)">
+ FUTURE
+ </text>
+ <use xlink:href="#frozenPoint" transform="rotate(10)"/>
+ <use xlink:href="#frozenPoint" transform="rotate(25)"/>
+ <use xlink:href="#frozenPoint" transform="rotate(40)"/>
+ <use xlink:href="#frozenPoint" transform="rotate(55)"/>
+ <use xlink:href="#frozenPoint" transform="rotate(70)"/>
+ <use xlink:href="#frozenPoint" transform="rotate(85)"/>
+ <use xlink:href="#frozenPoint" transform="rotate(100)"/>
+ <use xlink:href="#frozenPoint" transform="rotate(115)"/>
+ <use xlink:href="#frozenPoint" transform="rotate(130)"/>
+ <use xlink:href="#unfrozenPoint" transform="rotate(145)"/>
+ <use xlink:href="#frozenPoint" transform="rotate(160)"/>
+ <use xlink:href="#frozenPoint" transform="rotate(175)"/>
+ <use xlink:href="#unfrozenPoint" transform="rotate(190)"/>
+ <use xlink:href="#unfrozenPoint" transform="rotate(205)"/>
+ <use xlink:href="#unfrozenPoint" transform="rotate(220)"/>
+ </g>
+ <g class="text_normal" transform="translate(380 30)">
+ <text>
+ 0: 0 .. 2 <tspan dy="-5">^</tspan> <tspan dy="5">32</tspan> - 1
+ </text>
+ <text y="25">
+ 1: txid_current + 2 ^ 31 (split-point)
+ </text>
+ <text y="50">
+ 2: autovacuum_freeze_max_age (200 mio.)
+ </text>
+ <text y="75">
+ 3: vacuum_freeze_table_age (150 mio.)
+ </text>
+ <text y="100">
+ 4: vacuum_freeze_min_age (50 mio.)
+ </text>
+ <text y="125">
+ 5: txid_current (split-point, youngest xid)
+ </text>
+ <text y="155">
+ per table: pg_class.relfrozenxid <tspan font-weight="700">must</tspan> be between (1) and (5);
+ </text>
+ <text y="175" x="75">
+ normally it is between (3) and (4)
+ </text>
+ <use xlink:href="#unfrozenPoint" transform="translate(106 200)"/>
+ <text y="205" x="20">
+ Unfrozen xid
+ </text>
+ <use xlink:href="#frozenPoint" transform="translate(106 224)"/>
+ <text y="230" x="20">
+ Frozen xid
+ </text>
+ <text y="260">
+ (figure is out of scale)
+ </text>
+ </g>
+</svg>
diff --git a/doc/src/sgml/images/freeze-ink.svg b/doc/src/sgml/images/freeze-ink.svg
new file mode 100644
index 0000000000..316703d069
--- /dev/null
+++ b/doc/src/sgml/images/freeze-ink.svg
@@ -0,0 +1,365 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ version="1.1"
+ width="850px"
+ height="320px"
+ viewBox="0 0 850 320"
+ id="svg147"
+ sodipodi:docname="freeze-ink.svg"
+ inkscape:version="0.92.5 (2060ec1f9f, 2020-04-08)">
+ <metadata
+ id="metadata151">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title>Freeze</dc:title>
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <sodipodi:namedview
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1"
+ objecttolerance="10"
+ gridtolerance="10"
+ guidetolerance="10"
+ inkscape:pageopacity="0"
+ inkscape:pageshadow="2"
+ inkscape:window-width="1295"
+ inkscape:window-height="803"
+ id="namedview149"
+ showgrid="false"
+ inkscape:zoom="0.44"
+ inkscape:cx="425"
+ inkscape:cy="153.18182"
+ inkscape:window-x="0"
+ inkscape:window-y="27"
+ inkscape:window-maximized="0"
+ inkscape:current-layer="svg147" />
+ <title
+ id="title2">Freeze</title>
+ <!-- common text classes -->
+ <style
+ type="text/css"
+ id="style4">
+ .text_normal {font-style:normal;
+ font-weight:normal;
+ font-size:14px;
+ font-family:"Open Sans", sans-serif;
+ fill:black;
+ }
+ .text_big {font-style:normal;
+ font-weight:normal;
+ font-size:24px;
+ font-family:"Open Sans", sans-serif, Helvetica;
+ fill:black;
+ }
+ </style>
+ <defs
+ id="defs11">
+ <!-- SVG 1.x supports <texPath> only in combination with <path>. SVG 2 allows it with
+ every shape element, especially with <circle>. As of 2020 we must restrict ourselves
+ to SVG 1. Therefore we simulate a circle by defining two arcs, each of them is
+ a half-circle.
+ -->
+ <path
+ id="Path_080"
+ d="m -80 0 a 80 80 0 1 1 160 0 a 80 80 0 1 1 -160 0" />
+ <path
+ id="Path_095"
+ d="m -95 0 a 95 95 0 1 1 190 0 a 95 95 0 1 1 -190 0" />
+ <path
+ id="Path_120"
+ d="m -120 0 a 120 120 0 1 1 240 0 a 120 120 0 1 1 -240 0" />
+ <!-- split transform="translate(x y) rotate(arc)" into two steps for clarity -->
+ <circle
+ id="frozenPoint"
+ r="3"
+ stroke="green"
+ fill="green"
+ transform="translate(-100, 0)" />
+ <circle
+ id="unfrozenPoint"
+ r="3"
+ stroke="green"
+ fill="none"
+ transform="translate(-100, 0)" />
+ </defs>
+ <!-- start of rendering area -->
+ <!-- enclosing rectangle -->
+ <rect
+ x="1"
+ y="1"
+ rx="5"
+ width="99%"
+ height="99%"
+ stroke="black"
+ fill="none"
+ id="rect13" />
+ <text
+ class="text_big"
+ x="70"
+ y="40"
+ id="text17"><tspan
+ style="font-style:italic;font-weight:bold"
+ id="tspan15">
+ Freeze</tspan>
+ to keep visible</text>
+ <!-- set default values -->
+ <g
+ fill="none"
+ transform="translate(170 190)"
+ id="g111">
+ <circle
+ r="100"
+ stroke="blue"
+ id="circle19" />
+ <text
+ class="text_normal"
+ id="text43">
+ <textPath
+ xlink:href="#Path_095"
+ startOffset="0.5%"
+ id="textPath21">|</textPath>
+ <textPath
+ xlink:href="#Path_120"
+ startOffset="00%"
+ id="textPath23">(0)</textPath>
+ <textPath
+ xlink:href="#Path_080"
+ startOffset="01%"
+ stroke="blue"
+ stroke-width="0.5px"
+ id="textPath25">
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ></textPath>
+ <textPath
+ xlink:href="#Path_120"
+ startOffset="11.2%"
+ id="textPath27">(1)</textPath>
+ <textPath
+ xlink:href="#Path_120"
+ startOffset="61.2%"
+ id="textPath29">(5)</textPath>
+ <textPath
+ xlink:href="#Path_095"
+ stroke="red"
+ stroke-width="3"
+ startOffset="34%"
+ id="textPath31">|</textPath>
+ <textPath
+ xlink:href="#Path_120"
+ startOffset="34%"
+ id="textPath33">(2)</textPath>
+ <textPath
+ xlink:href="#Path_095"
+ stroke="black"
+ stroke-width="3"
+ startOffset="45%"
+ id="textPath35">|</textPath>
+ <textPath
+ xlink:href="#Path_120"
+ startOffset="45%"
+ id="textPath37">(3)</textPath>
+ <textPath
+ xlink:href="#Path_095"
+ stroke="green"
+ stroke-width="3"
+ startOffset="55%"
+ id="textPath39">|</textPath>
+ <textPath
+ xlink:href="#Path_120"
+ startOffset="55%"
+ id="textPath41">(4)</textPath>
+ </text>
+ <!-- split it into 'past' and 'future' -->
+ <path
+ d="M -80 -80 l 160 160"
+ stroke="black"
+ id="path45" />
+ <text
+ class="text_normal"
+ letter-spacing="12"
+ transform="translate(-15, -40) rotate(45)"
+ id="text47">PAST</text>
+ <text
+ class="text_normal"
+ letter-spacing="12"
+ transform="translate(30, 60) rotate(225)"
+ id="text49">FUTURE</text>
+ <g
+ transform="rotate(10)"
+ id="g53">
+ <use
+ xlink:href="#frozenPoint"
+ id="use51" />
+ </g>
+ <g
+ transform="rotate(25)"
+ id="g57">
+ <use
+ xlink:href="#frozenPoint"
+ id="use55" />
+ </g>
+ <g
+ transform="rotate(40)"
+ id="g61">
+ <use
+ xlink:href="#frozenPoint"
+ id="use59" />
+ </g>
+ <g
+ transform="rotate(55)"
+ id="g65">
+ <use
+ xlink:href="#frozenPoint"
+ id="use63" />
+ </g>
+ <g
+ transform="rotate(70)"
+ id="g69">
+ <use
+ xlink:href="#frozenPoint"
+ id="use67" />
+ </g>
+ <g
+ transform="rotate(85)"
+ id="g73">
+ <use
+ xlink:href="#frozenPoint"
+ id="use71" />
+ </g>
+ <g
+ transform="rotate(100)"
+ id="g77">
+ <use
+ xlink:href="#frozenPoint"
+ id="use75" />
+ </g>
+ <g
+ transform="rotate(115)"
+ id="g81">
+ <use
+ xlink:href="#frozenPoint"
+ id="use79" />
+ </g>
+ <g
+ transform="rotate(130)"
+ id="g85">
+ <use
+ xlink:href="#frozenPoint"
+ id="use83" />
+ </g>
+ <g
+ transform="rotate(145)"
+ id="g89">
+ <use
+ xlink:href="#unfrozenPoint"
+ id="use87" />
+ </g>
+ <g
+ transform="rotate(160)"
+ id="g93">
+ <use
+ xlink:href="#frozenPoint"
+ id="use91" />
+ </g>
+ <g
+ transform="rotate(175)"
+ id="g97">
+ <use
+ xlink:href="#frozenPoint"
+ id="use95" />
+ </g>
+ <g
+ transform="rotate(190)"
+ id="g101">
+ <use
+ xlink:href="#unfrozenPoint"
+ id="use99" />
+ </g>
+ <g
+ transform="rotate(205)"
+ id="g105">
+ <use
+ xlink:href="#unfrozenPoint"
+ id="use103" />
+ </g>
+ <g
+ transform="rotate(220)"
+ id="g109">
+ <use
+ xlink:href="#unfrozenPoint"
+ id="use107" />
+ </g>
+ </g>
+ <!-- legend -->
+ <g
+ class="text_normal"
+ transform="translate(380 30)"
+ id="g145">
+ <text
+ id="text117">0: 0 .. 2 <tspan
+ dy="-5"
+ id="tspan113">^</tspan>
+<tspan
+ dy="5"
+ id="tspan115">32</tspan>
+ - 1</text>
+ <text
+ y="25"
+ id="text119">1: txid_current + 2 ^ 31 (split-point)</text>
+ <text
+ y="50"
+ id="text121">2: autovacuum_freeze_max_age (200 mio.)</text>
+ <text
+ y="75"
+ id="text123">3: vacuum_freeze_table_age (150 mio.)</text>
+ <text
+ y="100"
+ id="text125">4: vacuum_freeze_min_age (50 mio.)</text>
+ <text
+ y="125"
+ id="text127">5: txid_current (split-point, youngest xid)</text>
+ <text
+ y="155"
+ id="text131">per table: pg_class.relfrozenxid
+ <tspan
+ style="font-weight:bold"
+ id="tspan129">must</tspan>
+ be between (1) and (5);</text>
+ <text
+ y="175"
+ x="75"
+ id="text133">normally it is between (3) and (4)</text>
+ <use
+ xlink:href="#unfrozenPoint"
+ transform="translate(106, 200)"
+ id="use135" />
+ <text
+ y="205"
+ x="20"
+ id="text137">Unfrozen xid</text>
+ <use
+ xlink:href="#frozenPoint"
+ transform="translate(106, 224)"
+ id="use139" />
+ <text
+ y="230"
+ x="20"
+ id="text141">Frozen xid</text>
+ <text
+ y="260"
+ id="text143">(figure is out of scale)</text>
+ </g>
+</svg>
diff --git a/doc/src/sgml/images/freeze-raw.svg b/doc/src/sgml/images/freeze-raw.svg
new file mode 100644
index 0000000000..9482167c3f
--- /dev/null
+++ b/doc/src/sgml/images/freeze-raw.svg
@@ -0,0 +1,123 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg xmlns="http://www.w3.org/2000/svg"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ version="1.1"
+ width="850px" height="320px"
+ viewBox="0 0 850 320" >
+
+ <title>Freeze</title>
+
+ <!-- common text classes -->
+ <style type="text/css">
+ .text_normal {font-style:normal;
+ font-weight:normal;
+ font-size:14px;
+ font-family:"Open Sans", sans-serif;
+ fill:black;
+ }
+ .text_big {font-style:normal;
+ font-weight:normal;
+ font-size:24px;
+ font-family:"Open Sans", sans-serif, Helvetica;
+ fill:black;
+ }
+ </style>
+
+ <defs>
+ <!-- SVG 1.x supports <texPath> only in combination with <path>. SVG 2 allows it with
+ every shape element, especially with <circle>. As of 2020 we must restrict ourselves
+ to SVG 1. Therefore we simulate a circle by defining two arcs, each of them is
+ a half-circle.
+ -->
+ <path id="Path_080" d="m -80 0
+ a 80 80 0 1 1 160 0
+ a 80 80 0 1 1 -160 0"/>
+ <path id="Path_095" d="m -95 0
+ a 95 95 0 1 1 190 0
+ a 95 95 0 1 1 -190 0"/>
+ <path id="Path_120" d="m -120 0
+ a 120 120 0 1 1 240 0
+ a 120 120 0 1 1 -240 0"/>
+
+ <!-- split transform="translate(x y) rotate(arc)" into two steps for clarity -->
+ <circle id="frozenPoint" r="3" stroke="green" fill="green" transform="translate(-100, 0)"/>
+ <circle id="unfrozenPoint" r="3" stroke="green" fill="none" transform="translate(-100, 0)"/>
+
+ </defs>
+
+
+ <!-- start of rendering area -->
+ <!-- enclosing rectangle -->
+ <rect x="1" y="1" rx="5" width="99%" height="99%" stroke="black" fill="none" />
+ <text class="text_big" x="70" y="40"><tspan style="font-style:italic;font-weight:bold">
+ Freeze</tspan> to keep visible</text>
+
+ <!-- set default values -->
+ <g fill="none" transform="translate(170 190)">
+
+ <circle r="100" stroke="blue" />
+
+ <text class="text_normal">
+ <textPath xlink:href="#Path_095" startOffset="0.5%" >|</textPath>
+ <textPath xlink:href="#Path_120" startOffset="00%" >(0)</textPath>
+ <textPath xlink:href="#Path_080" startOffset="01%" stroke="blue" stroke-width="0.5px" >
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ></textPath>
+ <textPath xlink:href="#Path_120" startOffset="11.2%" >(1)</textPath>
+ <textPath xlink:href="#Path_120" startOffset="61.2%" >(5)</textPath>
+
+ <textPath xlink:href="#Path_095" stroke="red" stroke-width="3" startOffset="34%" >|</textPath>
+ <textPath xlink:href="#Path_120" startOffset="34%" >(2)</textPath>
+
+ <textPath xlink:href="#Path_095" stroke="black" stroke-width="3" startOffset="45%" >|</textPath>
+ <textPath xlink:href="#Path_120" startOffset="45%" >(3)</textPath>
+
+ <textPath xlink:href="#Path_095" stroke="green" stroke-width="3" startOffset="55%" >|</textPath>
+ <textPath xlink:href="#Path_120" startOffset="55%" >(4)</textPath>
+
+ </text>
+
+ <!-- split it into 'past' and 'future' -->
+ <path d="M -80 -80 l 160 160" stroke="black" />
+ <text class="text_normal" letter-spacing="12" transform="translate(-15, -40) rotate(45)">PAST</text>
+ <text class="text_normal" letter-spacing="12" transform="translate(30, 60) rotate(225)">FUTURE</text>
+
+ <g transform="rotate(10)"><use xlink:href="#frozenPoint"/></g>
+ <g transform="rotate(25)"><use xlink:href="#frozenPoint"/></g>
+ <g transform="rotate(40)"><use xlink:href="#frozenPoint"/></g>
+ <g transform="rotate(55)"><use xlink:href="#frozenPoint"/></g>
+ <g transform="rotate(70)"><use xlink:href="#frozenPoint"/></g>
+ <g transform="rotate(85)"><use xlink:href="#frozenPoint"/></g>
+ <g transform="rotate(100)"><use xlink:href="#frozenPoint"/></g>
+ <g transform="rotate(115)"><use xlink:href="#frozenPoint"/></g>
+ <g transform="rotate(130)"><use xlink:href="#frozenPoint"/></g>
+ <g transform="rotate(145)"><use xlink:href="#unfrozenPoint"/></g>
+ <g transform="rotate(160)"><use xlink:href="#frozenPoint"/></g>
+ <g transform="rotate(175)"><use xlink:href="#frozenPoint"/></g>
+ <g transform="rotate(190)"><use xlink:href="#unfrozenPoint"/></g>
+ <g transform="rotate(205)"><use xlink:href="#unfrozenPoint"/></g>
+ <g transform="rotate(220)"><use xlink:href="#unfrozenPoint"/></g>
+
+ </g>
+
+ <!-- legend -->
+ <g class="text_normal" transform="translate(380 30)">
+ <text>0: 0 .. 2 <tspan dy="-5">^</tspan> <tspan dy="5">32</tspan> - 1</text>
+ <text y="25">1: txid_current + 2 ^ 31 (split-point)</text>
+ <text y="50">2: autovacuum_freeze_max_age (200 mio.)</text>
+ <text y="75">3: vacuum_freeze_table_age (150 mio.)</text>
+ <text y="100">4: vacuum_freeze_min_age (50 mio.)</text>
+ <text y="125">5: txid_current (split-point, youngest xid)</text>
+ <text y="155">per table: pg_class.relfrozenxid
+ <tspan style="font-weight:bold">must</tspan> be between (1) and (5);</text>
+ <text y="175" x="75">normally it is between (3) and (4)</text>
+
+ <use xlink:href="#unfrozenPoint" transform="translate(106, 200)"/>
+ <text y="205" x="20">Unfrozen xid</text>
+
+ <use xlink:href="#frozenPoint" transform="translate(106, 224)"/>
+ <text y="230" x="20">Frozen xid</text>
+
+ <text y="260">(figure is out of scale)</text>
+ </g>
+
+</svg>
diff --git a/doc/src/sgml/images/internal-objects-hierarchy-ink-svgo.svg b/doc/src/sgml/images/internal-objects-hierarchy-ink-svgo.svg
new file mode 100644
index 0000000000..e353ce4d87
--- /dev/null
+++ b/doc/src/sgml/images/internal-objects-hierarchy-ink-svgo.svg
@@ -0,0 +1,83 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="720" height="430" viewBox="0 0 720 430">
+ <title>
+ Hierarchy of Internal Objects
+ </title>
+ <style>
+ .text_normal{font-style:normal;font-weight:400;font-size:14px;font-family:"Open Sans",sans-serif;fill:#000}
+ </style>
+ <rect x="1" y="1" rx="5" width="99%" height="99%" stroke="black" fill="none"/>
+ <text x="200" y="40" font-weight="400" font-size="24" font-family=""Open Sans",sans-serif">
+ Hierarchy of Internal Objects
+ </text>
+ <g fill="none">
+ <g transform="translate(350 240)">
+ <ellipse rx="320" ry="170" stroke="blue"/>
+ <text class="text_normal" x="-140" y="-130">
+ Cluster
+ </text>
+ <g transform="translate(40 -125)">
+ <ellipse rx="80" ry="20" stroke="blue"/>
+ <text class="text_normal" x="-60" y="5">
+ Database Names
+ </text>
+ </g>
+ <g transform="translate(180 -70)">
+ <ellipse rx="60" ry="20" stroke="blue"/>
+ <text class="text_normal" x="-40" y="5">
+ Tablespace
+ </text>
+ </g>
+ <g transform="translate(230 -5)">
+ <ellipse rx="80" ry="20" stroke="blue"/>
+ <text class="text_normal" x="-70" y="5">
+ Replication Origins
+ </text>
+ </g>
+ <g transform="translate(200 70)">
+ <ellipse rx="78" ry="27" stroke="blue"/>
+ <text class="text_normal" x="-60" y="-3">
+ Subscription for
+ </text>
+ <text class="text_normal" x="-68" y="10">
+ Logical Replication
+ </text>
+ </g>
+ <g transform="translate(100 120)">
+ <ellipse rx="40" ry="20" stroke="blue"/>
+ <text class="text_normal" x="-15" y="5">
+ Role
+ </text>
+ </g>
+ </g>
+ <g transform="translate(270 250)">
+ <ellipse rx="220" ry="110" stroke="blue" stroke-width="2"/>
+ <text class="text_normal" x="-60" y="-80">
+ Database
+ </text>
+ <g transform="translate(-150 -30)">
+ <ellipse rx="50" ry="20" stroke="blue"/>
+ <text class="text_normal" x="-35" y="5">
+ Extension
+ </text>
+ </g>
+ <g transform="translate(-155 35)">
+ <ellipse rx="40" ry="20" stroke="blue"/>
+ <text class="text_normal" x="-35" y="5">
+ Collation
+ </text>
+ </g>
+ <g transform="translate(30 20)">
+ <ellipse rx="140" ry="70" stroke="blue"/>
+ <text class="text_normal" x="-80" y="-35">
+ Schema
+ </text>
+ <g transform="translate(20 10)">
+ <ellipse rx="90" ry="30" stroke="blue"/>
+ <text class="text_normal" x="-50" y="5">
+ Table, View, ...
+ </text>
+ </g>
+ </g>
+ </g>
+ </g>
+</svg>
diff --git a/doc/src/sgml/images/internal-objects-hierarchy-ink.svg b/doc/src/sgml/images/internal-objects-hierarchy-ink.svg
new file mode 100644
index 0000000000..3429266782
--- /dev/null
+++ b/doc/src/sgml/images/internal-objects-hierarchy-ink.svg
@@ -0,0 +1,255 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ version="1.1"
+ width="720px"
+ height="430px"
+ viewBox="0 0 720 430"
+ id="svg82"
+ sodipodi:docname="internal-objects-hierarchy-ink.svg"
+ inkscape:version="0.92.5 (2060ec1f9f, 2020-04-08)">
+ <metadata
+ id="metadata88">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title>Hierarchy of Internal Objects</dc:title>
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <defs
+ id="defs86" />
+ <sodipodi:namedview
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1"
+ objecttolerance="10"
+ gridtolerance="10"
+ guidetolerance="10"
+ inkscape:pageopacity="0"
+ inkscape:pageshadow="2"
+ inkscape:window-width="919"
+ inkscape:window-height="528"
+ id="namedview84"
+ showgrid="false"
+ inkscape:zoom="0.51944444"
+ inkscape:cx="360"
+ inkscape:cy="215"
+ inkscape:window-x="66"
+ inkscape:window-y="27"
+ inkscape:window-maximized="0"
+ inkscape:current-layer="svg82" />
+ <title
+ id="title2">Hierarchy of Internal Objects</title>
+ <!-- common text classes -->
+ <style
+ type="text/css"
+ id="style4">
+ .text_normal {font-style:normal;
+ font-weight:normal;
+ font-size:14px;
+ font-family:"Open Sans", sans-serif;
+ fill:black;
+ }
+ .text_big {font-style:normal;
+ font-weight:normal;
+ font-size:24px;
+ font-family:"Open Sans", sans-serif;
+ fill:black;
+ }
+ </style>
+ <!-- start of rendering area -->
+ <!-- enclosing rectangle -->
+ <rect
+ x="1"
+ y="1"
+ rx="5"
+ width="99%"
+ height="99%"
+ stroke="black"
+ fill="none"
+ id="rect6" />
+ <text
+ class="text_big"
+ x="200"
+ y="40"
+ id="text8">Hierarchy of Internal Objects</text>
+ <!-- set centre of figure and default values -->
+ <g
+ transform="translate(350 240)"
+ fill="none"
+ id="g80">
+ <g
+ id="g46">
+ <ellipse
+ rx="320"
+ ry="170"
+ stroke="blue"
+ id="ellipse10" />
+ <text
+ class="text_normal"
+ x="-140"
+ y="-130"
+ id="text12">Cluster</text>
+ <g
+ transform="translate(40 -125)"
+ id="g18">
+ <ellipse
+ rx="80"
+ ry="20"
+ stroke="blue"
+ id="ellipse14" />
+ <text
+ class="text_normal"
+ x="-60"
+ y="5"
+ id="text16">Database Names</text>
+ </g>
+ <g
+ transform="translate(180 -70)"
+ id="g24">
+ <ellipse
+ rx="60"
+ ry="20"
+ stroke="blue"
+ id="ellipse20" />
+ <text
+ class="text_normal"
+ x="-40"
+ y="5"
+ id="text22">Tablespace</text>
+ </g>
+ <g
+ transform="translate(230 -5)"
+ id="g30">
+ <ellipse
+ rx="80"
+ ry="20"
+ stroke="blue"
+ id="ellipse26" />
+ <text
+ class="text_normal"
+ x="-70"
+ y="5"
+ id="text28">Replication Origins</text>
+ </g>
+ <g
+ transform="translate(200 70)"
+ id="g38">
+ <ellipse
+ rx="78"
+ ry="27"
+ stroke="blue"
+ id="ellipse32" />
+ <text
+ class="text_normal"
+ x="-60"
+ y="-3"
+ id="text34">Subscription for</text>
+ <text
+ class="text_normal"
+ x="-68"
+ y="10"
+ id="text36">Logical Replication</text>
+ </g>
+ <g
+ transform="translate(100 120)"
+ id="g44">
+ <ellipse
+ rx="40"
+ ry="20"
+ stroke="blue"
+ id="ellipse40" />
+ <text
+ class="text_normal"
+ x="-15"
+ y="5"
+ id="text42">Role</text>
+ </g>
+ </g>
+ <g
+ transform="translate(-80 10)"
+ id="g78">
+ <ellipse
+ rx="220"
+ ry="110"
+ stroke="blue"
+ stroke-width="2px"
+ id="ellipse48" />
+ <text
+ class="text_normal"
+ x="-60"
+ y="-80"
+ id="text50">Database</text>
+ <g
+ transform="translate(-120 -50)"
+ id="g76">
+ <g
+ transform="translate(-30 20)"
+ id="g56">
+ <ellipse
+ rx="50"
+ ry="20"
+ stroke="blue"
+ id="ellipse52" />
+ <text
+ class="text_normal"
+ x="-35"
+ y="5"
+ id="text54">Extension</text>
+ </g>
+ <g
+ transform="translate(-35 85)"
+ id="g62">
+ <ellipse
+ rx="40"
+ ry="20"
+ stroke="blue"
+ id="ellipse58" />
+ <text
+ class="text_normal"
+ x="-35"
+ y="5"
+ id="text60">Collation</text>
+ </g>
+ <g
+ transform="translate(150 70)"
+ id="g74">
+ <ellipse
+ rx="140"
+ ry="70"
+ stroke="blue"
+ id="ellipse64" />
+ <text
+ class="text_normal"
+ x="-80"
+ y="-35"
+ id="text66">Schema</text>
+ <g
+ transform="translate(20 10)"
+ id="g72">
+ <ellipse
+ rx="90"
+ ry="30"
+ stroke="blue"
+ id="ellipse68" />
+ <text
+ class="text_normal"
+ x="-50"
+ y="5"
+ id="text70">Table, View, ...</text>
+ </g>
+ </g>
+ </g>
+ </g>
+ </g>
+</svg>
diff --git a/doc/src/sgml/images/internal-objects-hierarchy-raw.svg b/doc/src/sgml/images/internal-objects-hierarchy-raw.svg
new file mode 100644
index 0000000000..78850283d9
--- /dev/null
+++ b/doc/src/sgml/images/internal-objects-hierarchy-raw.svg
@@ -0,0 +1,95 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg xmlns="http://www.w3.org/2000/svg"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ version="1.1"
+ width="720px" height="430px"
+ viewBox="0 0 720 430" >
+
+ <title>Hierarchy of Internal Objects</title>
+
+ <!-- common text classes -->
+ <style type="text/css">
+ .text_normal {font-style:normal;
+ font-weight:normal;
+ font-size:14px;
+ font-family:"Open Sans", sans-serif;
+ fill:black;
+ }
+ .text_big {font-style:normal;
+ font-weight:normal;
+ font-size:24px;
+ font-family:"Open Sans", sans-serif;
+ fill:black;
+ }
+ </style>
+
+ <!-- start of rendering area -->
+ <!-- enclosing rectangle -->
+ <rect x="1" y="1" rx="5" width="99%" height="99%" stroke="black" fill="none" />
+ <text class="text_big" x="200" y="40">Hierarchy of Internal Objects</text>
+
+
+ <!-- set centre of figure and default values -->
+ <g transform="translate(350 240)" fill="none">
+
+ <g>
+ <ellipse rx="320" ry="170" stroke="blue" />
+ <text class="text_normal" x="-140" y="-130">Cluster</text>
+
+ <g transform="translate(40 -125)">
+ <ellipse rx="80" ry="20" stroke="blue" />
+ <text class="text_normal" x="-60" y="5">Database Names</text>
+ </g>
+
+ <g transform="translate(180 -70)">
+ <ellipse rx="60" ry="20" stroke="blue" />
+ <text class="text_normal" x="-40" y="5">Tablespace</text>
+ </g>
+
+ <g transform="translate(230 -5)">
+ <ellipse rx="80" ry="20" stroke="blue" />
+ <text class="text_normal" x="-70" y="5">Replication Origins</text>
+ </g>
+
+ <g transform="translate(200 70)">
+ <ellipse rx="78" ry="27" stroke="blue" />
+ <text class="text_normal" x="-60" y="-3">Subscription for</text>
+ <text class="text_normal" x="-68" y="10">Logical Replication</text>
+ </g>
+
+ <g transform="translate(100 120)">
+ <ellipse rx="40" ry="20" stroke="blue" />
+ <text class="text_normal" x="-15" y="5">Role</text>
+ </g>
+
+ </g>
+
+ <g transform="translate(-80 10)">
+ <ellipse rx="220" ry="110" stroke="blue" stroke-width="2px" />
+ <text class="text_normal" x="-60" y="-80">Database</text>
+
+ <g transform="translate(-120 -50)">
+ <g transform="translate(-30 20)">
+ <ellipse rx="50" ry="20" stroke="blue" />
+ <text class="text_normal" x="-35" y="5">Extension</text>
+ </g>
+
+ <g transform="translate(-35 85)">
+ <ellipse rx="40" ry="20" stroke="blue" />
+ <text class="text_normal" x="-35" y="5">Collation</text>
+ </g>
+
+ <g transform="translate(150 70)">
+ <ellipse rx="140" ry="70" stroke="blue" />
+ <text class="text_normal" x="-80" y="-35">Schema</text>
+
+ <g transform="translate(20 10)">
+ <ellipse rx="90" ry="30" stroke="blue" />
+ <text class="text_normal" x="-50" y="5">Table, View, ...</text>
+ </g>
+ </g>
+ </g>
+ </g>
+ </g>
+
+</svg>
diff --git a/doc/src/sgml/images/mvcc-ink-svgo.svg b/doc/src/sgml/images/mvcc-ink-svgo.svg
new file mode 100644
index 0000000000..6ff6a4da79
--- /dev/null
+++ b/doc/src/sgml/images/mvcc-ink-svgo.svg
@@ -0,0 +1,151 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="850" height="150" viewBox="0 0 850 150">
+ <title>
+ MVCC
+ </title>
+ <style>
+ .text_small{font-style:normal;font-weight:400;font-size:10px;font-family:"Open Sans",sans-serif;fill:#000}
+ </style>
+ <defs>
+ <marker id="triangle_1" markerWidth="10" markerHeight="10" refX="5" refY="5" orient="auto" stroke="black" fill="none">
+ <path d="M0 0l10 5-10 5"/>
+ </marker>
+ <path id="arrow" d="M0 0q20-15 40 0" stroke="black" marker-end="url(#triangle_1)"/>
+ <g id="tuple" stroke="black">
+ <path d="M80 0H0v20h80M29 0v20M60 0v20"/>
+ <path d="M80 0h15M80 20h15" stroke-dasharray="2 1"/>
+ </g>
+ </defs>
+ <rect x="1" y="1" rx="5" width="99%" height="99%" stroke="black" fill="none"/>
+ <g fill="none">
+ <g transform="translate(20 40)">
+ <text class="text_small" transform="translate(0 -18)">
+ T <tspan dx="-3" dy="5" font-size="8">123</tspan> <tspan dx="-2" dy="-5">: INSERT</tspan>
+ </text>
+ <use xlink:href="#arrow" transform="translate(5)"/>
+ <use xlink:href="#tuple" transform="translate(60 70)"/>
+ <text class="text_small" transform="translate(65 83)" fill="#00f">
+ 123
+ </text>
+ <text class="text_small" transform="translate(95 83)" fill="#00f">
+ 0
+ </text>
+ <text class="text_small" transform="translate(125 83)" fill="#00f">
+ 'x'
+ </text>
+ </g>
+ <g transform="translate(185 40)">
+ <text class="text_small" transform="translate(0 -18)">
+ T <tspan dx="-3" dy="5" font-size="8">135</tspan> <tspan dx="-2" dy="-5">: UPDATE</tspan>
+ </text>
+ <use xlink:href="#arrow" transform="translate(5)"/>
+ <use xlink:href="#tuple" transform="translate(60 40)"/>
+ <text class="text_small" transform="translate(65 53)" fill="#00f">
+ 135
+ </text>
+ <text class="text_small" transform="translate(95 53)" fill="#00f">
+ 0
+ </text>
+ <text class="text_small" transform="translate(125 53)" fill="#00f">
+ 'y'
+ </text>
+ <use xlink:href="#tuple" transform="translate(60 70)"/>
+ <text class="text_small" transform="translate(65 83)">
+ 123
+ </text>
+ <text class="text_small" transform="translate(95 83)" fill="#00f">
+ 135
+ </text>
+ <text class="text_small" transform="translate(125 83)">
+ 'x'
+ </text>
+ </g>
+ <g transform="translate(350 40)">
+ <text class="text_small" transform="translate(0 -18)">
+ T <tspan dx="-3" dy="5" font-size="8">142</tspan> <tspan dx="-2" dy="-5">: UPDATE</tspan>
+ </text>
+ <use xlink:href="#arrow" transform="translate(5)"/>
+ <use xlink:href="#tuple" transform="translate(60 10)"/>
+ <text class="text_small" transform="translate(65 23)" fill="#00f">
+ 142
+ </text>
+ <text class="text_small" transform="translate(95 23)" fill="#00f">
+ 0
+ </text>
+ <text class="text_small" transform="translate(125 23)" fill="#00f">
+ 'z'
+ </text>
+ <use xlink:href="#tuple" transform="translate(60 40)"/>
+ <text class="text_small" transform="translate(65 53)">
+ 135
+ </text>
+ <text class="text_small" transform="translate(95 53)" fill="#00f">
+ 142
+ </text>
+ <text class="text_small" transform="translate(125 53)">
+ 'y'
+ </text>
+ <use xlink:href="#tuple" transform="translate(60 70)"/>
+ <text class="text_small" transform="translate(65 83)">
+ 123
+ </text>
+ <text class="text_small" transform="translate(95 83)">
+ 135
+ </text>
+ <text class="text_small" transform="translate(125 83)">
+ 'x'
+ </text>
+ </g>
+ <g transform="translate(515 40)">
+ <text class="text_small" transform="translate(0 -18)">
+ T <tspan dx="-3" dy="5" font-size="8">821</tspan> <tspan dx="-2" dy="-5">: DELTE</tspan>
+ </text>
+ <use xlink:href="#arrow" transform="translate(5)"/>
+ <use xlink:href="#tuple" transform="translate(60 10)"/>
+ <text class="text_small" transform="translate(65 23)">
+ 142
+ </text>
+ <text class="text_small" transform="translate(95 23)" fill="#00f">
+ 821
+ </text>
+ <text class="text_small" transform="translate(125 23)">
+ 'z'
+ </text>
+ <use xlink:href="#tuple" transform="translate(60 40)"/>
+ <text class="text_small" transform="translate(65 53)">
+ 135
+ </text>
+ <text class="text_small" transform="translate(95 53)">
+ 142
+ </text>
+ <text class="text_small" transform="translate(125 53)">
+ 'y'
+ </text>
+ <use xlink:href="#tuple" transform="translate(60 70)"/>
+ <text class="text_small" transform="translate(65 83)">
+ 123
+ </text>
+ <text class="text_small" transform="translate(95 83)">
+ 135
+ </text>
+ <text class="text_small" transform="translate(125 83)">
+ 'x'
+ </text>
+ </g>
+ <g transform="translate(740 110)">
+ <path d="M102-20H-18v60" stroke="black"/>
+ <text font-weight="400" font-size="14" font-family=""Open Sans",sans-serif" fill="#000">
+ Legend
+ </text>
+ <use xlink:href="#tuple" transform="translate(0 10)"/>
+ <text class="text_small" transform="translate(3 23)">
+ xmin
+ </text>
+ <text class="text_small" transform="translate(32 23)">
+ xmax
+ </text>
+ <text class="text_small" transform="translate(65 23)">
+ data
+ </text>
+ </g>
+ </g>
+</svg>
diff --git a/doc/src/sgml/images/mvcc-ink.svg b/doc/src/sgml/images/mvcc-ink.svg
new file mode 100644
index 0000000000..80ae8d29e0
--- /dev/null
+++ b/doc/src/sgml/images/mvcc-ink.svg
@@ -0,0 +1,398 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ version="1.1"
+ width="850px"
+ height="150px"
+ viewBox="0 0 850 150"
+ id="svg4396"
+ sodipodi:docname="mvcc-ink.svg"
+ inkscape:version="0.92.5 (2060ec1f9f, 2020-04-08)">
+ <metadata
+ id="metadata4400">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title>MVCC</dc:title>
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <sodipodi:namedview
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1"
+ objecttolerance="10"
+ gridtolerance="10"
+ guidetolerance="10"
+ inkscape:pageopacity="0"
+ inkscape:pageshadow="2"
+ inkscape:window-width="1266"
+ inkscape:window-height="788"
+ id="namedview4398"
+ showgrid="false"
+ inkscape:zoom="0.44470588"
+ inkscape:cx="425"
+ inkscape:cy="68.253968"
+ inkscape:window-x="66"
+ inkscape:window-y="27"
+ inkscape:window-maximized="0"
+ inkscape:current-layer="svg4396" />
+ <title
+ id="title4251">MVCC</title>
+ <!-- common text classes -->
+ <style
+ type="text/css"
+ id="style4253">
+ .text_small {font-style:normal;
+ font-weight:normal;
+ font-size:10px;
+ font-family:"Open Sans", sans-serif;
+ fill:black;
+ }
+ .text_normal {font-style:normal;
+ font-weight:normal;
+ font-size:14px;
+ font-family:"Open Sans", sans-serif;
+ fill:black;
+ }
+ </style>
+ <defs
+ id="defs4264">
+ <marker
+ id="triangle_1"
+ markerWidth="10"
+ markerHeight="10"
+ refX="5"
+ refY="5"
+ orient="auto"
+ stroke="black"
+ fill="none">
+ <path
+ d="M 0,0 L 10,5 L 0,10"
+ id="path4255" />
+ </marker>
+ <g
+ id="tuple">
+ <!-- an rectangle, open at the right side -->
+ <path
+ d="M 80 0 h -80 v 20 h 80 M 29 0 v 20 M 60 0 v 20"
+ stroke="black"
+ id="path4258" />
+ <!-- prolong the rectangle -->
+ <path
+ d="M 80 0 h 15 M 80 20 h 15"
+ stroke="black"
+ stroke-dasharray="2 1"
+ id="path4260" />
+ </g>
+ <!-- an arrow in the form of a quadratic bezier curve -->
+ <path
+ id="arrow"
+ d="M 0 0 Q 20 -15 40 0"
+ stroke="black"
+ marker-end="url(#triangle_1)" />
+ </defs>
+ <!-- start of rendering area -->
+ <!-- enclosing rectangle -->
+ <rect
+ x="1"
+ y="1"
+ rx="5"
+ width="99%"
+ height="99%"
+ stroke="black"
+ fill="none"
+ id="rect4266" />
+ <!-- set default values -->
+ <g
+ fill="none"
+ id="g4394">
+ <!-- start plus first INSERT -->
+ <g
+ transform="translate(20, 40)"
+ id="g4284">
+ <text
+ class="text_small"
+ transform="translate(0, -18)"
+ id="text4272">T
+ <tspan
+ style="font-size:8px"
+ dx="-3"
+ dy="5"
+ id="tspan4268">123</tspan>
+<tspan
+ dx="-2"
+ dy="-5"
+ id="tspan4270">: INSERT</tspan>
+</text>
+ <use
+ xlink:href="#arrow"
+ transform="translate(5, 0)"
+ id="use4274" />
+ <use
+ xlink:href="#tuple"
+ transform="translate(60, 70)"
+ id="use4276" />
+ <text
+ class="text_small"
+ transform="translate(65, 83)"
+ style="fill:blue"
+ id="text4278">123</text>
+ <text
+ class="text_small"
+ transform="translate(95, 83)"
+ style="fill:blue"
+ id="text4280">0</text>
+ <text
+ class="text_small"
+ transform="translate(125, 83)"
+ style="fill:blue"
+ id="text4282">'x'</text>
+ </g>
+ <!-- first UPDATE -->
+ <g
+ transform="translate(185, 40)"
+ id="g4310">
+ <text
+ class="text_small"
+ transform="translate(0, -18)"
+ id="text4290">T
+ <tspan
+ style="font-size:8px"
+ dx="-3"
+ dy="5"
+ id="tspan4286">135</tspan>
+<tspan
+ dx="-2"
+ dy="-5"
+ id="tspan4288">: UPDATE</tspan>
+</text>
+ <use
+ xlink:href="#arrow"
+ transform="translate(5, 0)"
+ id="use4292" />
+ <use
+ xlink:href="#tuple"
+ transform="translate(60, 40)"
+ id="use4294" />
+ <text
+ class="text_small"
+ transform="translate(65, 53)"
+ style="fill:blue"
+ id="text4296">135</text>
+ <text
+ class="text_small"
+ transform="translate(95, 53)"
+ style="fill:blue"
+ id="text4298">0</text>
+ <text
+ class="text_small"
+ transform="translate(125, 53)"
+ style="fill:blue"
+ id="text4300">'y'</text>
+ <use
+ xlink:href="#tuple"
+ transform="translate(60, 70)"
+ id="use4302" />
+ <text
+ class="text_small"
+ transform="translate(65, 83)"
+ id="text4304">123</text>
+ <text
+ class="text_small"
+ transform="translate(95, 83)"
+ style="fill:blue"
+ id="text4306">135</text>
+ <text
+ class="text_small"
+ transform="translate(125, 83)"
+ id="text4308">'x'</text>
+ </g>
+ <!-- next UPDATE -->
+ <g
+ transform="translate(350, 40)"
+ id="g4344">
+ <text
+ class="text_small"
+ transform="translate(0, -18)"
+ id="text4316">T
+ <tspan
+ style="font-size:8px"
+ dx="-3"
+ dy="5"
+ id="tspan4312">142</tspan>
+<tspan
+ dx="-2"
+ dy="-5"
+ id="tspan4314">: UPDATE</tspan>
+</text>
+ <use
+ xlink:href="#arrow"
+ transform="translate(5, 0)"
+ id="use4318" />
+ <use
+ xlink:href="#tuple"
+ transform="translate(60, 10)"
+ id="use4320" />
+ <text
+ class="text_small"
+ transform="translate(65, 23)"
+ style="fill:blue"
+ id="text4322">142</text>
+ <text
+ class="text_small"
+ transform="translate(95, 23)"
+ style="fill:blue"
+ id="text4324">0</text>
+ <text
+ class="text_small"
+ transform="translate(125, 23)"
+ style="fill:blue"
+ id="text4326">'z'</text>
+ <use
+ xlink:href="#tuple"
+ transform="translate(60, 40)"
+ id="use4328" />
+ <text
+ class="text_small"
+ transform="translate(65, 53)"
+ id="text4330">135</text>
+ <text
+ class="text_small"
+ transform="translate(95, 53)"
+ style="fill:blue"
+ id="text4332">142</text>
+ <text
+ class="text_small"
+ transform="translate(125, 53)"
+ id="text4334">'y'</text>
+ <use
+ xlink:href="#tuple"
+ transform="translate(60, 70)"
+ id="use4336" />
+ <text
+ class="text_small"
+ transform="translate(65, 83)"
+ id="text4338">123</text>
+ <text
+ class="text_small"
+ transform="translate(95, 83)"
+ id="text4340">135</text>
+ <text
+ class="text_small"
+ transform="translate(125, 83)"
+ id="text4342">'x'</text>
+ </g>
+ <!-- DELETE -->
+ <g
+ transform="translate(515, 40)"
+ id="g4378">
+ <text
+ class="text_small"
+ transform="translate(0, -18)"
+ id="text4350">T
+ <tspan
+ style="font-size:8px"
+ dx="-3"
+ dy="5"
+ id="tspan4346">821</tspan>
+<tspan
+ dx="-2"
+ dy="-5"
+ id="tspan4348">: DELTE</tspan>
+</text>
+ <use
+ xlink:href="#arrow"
+ transform="translate(5, 0)"
+ id="use4352" />
+ <use
+ xlink:href="#tuple"
+ transform="translate(60, 10)"
+ id="use4354" />
+ <text
+ class="text_small"
+ transform="translate(65, 23)"
+ id="text4356">142</text>
+ <text
+ class="text_small"
+ transform="translate(95, 23)"
+ style="fill:blue"
+ id="text4358">821</text>
+ <text
+ class="text_small"
+ transform="translate(125, 23)"
+ id="text4360">'z'</text>
+ <use
+ xlink:href="#tuple"
+ transform="translate(60, 40)"
+ id="use4362" />
+ <text
+ class="text_small"
+ transform="translate(65, 53)"
+ id="text4364">135</text>
+ <text
+ class="text_small"
+ transform="translate(95, 53)"
+ id="text4366">142</text>
+ <text
+ class="text_small"
+ transform="translate(125, 53)"
+ id="text4368">'y'</text>
+ <use
+ xlink:href="#tuple"
+ transform="translate(60, 70)"
+ id="use4370" />
+ <text
+ class="text_small"
+ transform="translate(65, 83)"
+ id="text4372">123</text>
+ <text
+ class="text_small"
+ transform="translate(95, 83)"
+ id="text4374">135</text>
+ <text
+ class="text_small"
+ transform="translate(125, 83)"
+ id="text4376">'x'</text>
+ </g>
+ <!-- LEGEND -->
+ <g
+ transform="translate(740, 110)"
+ id="g4392">
+ <path
+ d="M 102 -20 h -120 v 60"
+ stroke="black"
+ id="path4380" />
+ <text
+ class="text_normal"
+ transform="translate(0, 0)"
+ id="text4382">Legend</text>
+ <use
+ xlink:href="#tuple"
+ transform="translate(0, 10)"
+ id="use4384" />
+ <text
+ class="text_small"
+ transform="translate(3, 23)"
+ id="text4386">xmin</text>
+ <text
+ class="text_small"
+ transform="translate(32, 23)"
+ id="text4388">xmax</text>
+ <text
+ class="text_small"
+ transform="translate(65, 23)"
+ id="text4390">data</text>
+ </g>
+ </g>
+</svg>
diff --git a/doc/src/sgml/images/mvcc-raw.svg b/doc/src/sgml/images/mvcc-raw.svg
new file mode 100644
index 0000000000..ee27e3df7b
--- /dev/null
+++ b/doc/src/sgml/images/mvcc-raw.svg
@@ -0,0 +1,145 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg xmlns="http://www.w3.org/2000/svg"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ version="1.1"
+ width="850px" height="150px"
+ viewBox="0 0 850 150" >
+
+ <title>MVCC</title>
+
+ <!-- common text classes -->
+ <style type="text/css">
+ .text_small {font-style:normal;
+ font-weight:normal;
+ font-size:10px;
+ font-family:"Open Sans", sans-serif;
+ fill:black;
+ }
+ .text_normal {font-style:normal;
+ font-weight:normal;
+ font-size:14px;
+ font-family:"Open Sans", sans-serif;
+ fill:black;
+ }
+ </style>
+
+ <defs>
+ <marker id="triangle_1"
+ markerWidth="10"
+ markerHeight="10"
+ refX="5"
+ refY="5"
+ orient="auto" stroke="black" fill="none">
+ <path d="M 0,0 L 10,5 L 0,10" />
+ </marker>
+
+ <g id="tuple">
+ <!-- an rectangle, open at the right side -->
+ <path d="M 80 0 h -80 v 20 h 80 M 29 0 v 20 M 60 0 v 20" stroke="black"/>
+ <!-- prolong the rectangle -->
+ <path d="M 80 0 h 15 M 80 20 h 15" stroke="black" stroke-dasharray="2 1"/>
+ </g>
+
+ <!-- an arrow in the form of a quadratic bezier curve -->
+ <path id="arrow" d="M 0 0 Q 20 -15 40 0" stroke="black" marker-end="url(#triangle_1)"/>
+
+ </defs>
+
+
+ <!-- start of rendering area -->
+ <!-- enclosing rectangle -->
+ <rect x="1" y="1" rx="5" width="99%" height="99%" stroke="black" fill="none" />
+
+ <!-- set default values -->
+ <g fill="none">
+
+ <!-- start plus first INSERT -->
+ <g transform="translate(20, 40)">
+
+ <text class="text_small" transform="translate(0, -18)">T
+ <tspan style="font-size:8px" dx="-3" dy="5">123</tspan>
+ <tspan dx="-2" dy="-5">: INSERT</tspan>
+ </text>
+ <use xlink:href="#arrow" transform="translate(5, 0)"/>
+
+ <use xlink:href="#tuple" transform="translate(60, 70)"/>
+ <text class="text_small" transform="translate(65, 83)" style="fill:blue">123</text>
+ <text class="text_small" transform="translate(95, 83)" style="fill:blue">0</text>
+ <text class="text_small" transform="translate(125, 83)" style="fill:blue">'x'</text>
+ </g>
+
+ <!-- first UPDATE -->
+ <g transform="translate(185, 40)">
+ <text class="text_small" transform="translate(0, -18)">T
+ <tspan style="font-size:8px" dx="-3" dy="5">135</tspan>
+ <tspan dx="-2" dy="-5">: UPDATE</tspan>
+ </text>
+ <use xlink:href="#arrow" transform="translate(5, 0)"/>
+
+ <use xlink:href="#tuple" transform="translate(60, 40)"/>
+ <text class="text_small" transform="translate(65, 53)" style="fill:blue">135</text>
+ <text class="text_small" transform="translate(95, 53)" style="fill:blue">0</text>
+ <text class="text_small" transform="translate(125, 53)" style="fill:blue">'y'</text>
+ <use xlink:href="#tuple" transform="translate(60, 70)"/>
+ <text class="text_small" transform="translate(65, 83)">123</text>
+ <text class="text_small" transform="translate(95, 83)" style="fill:blue">135</text>
+ <text class="text_small" transform="translate(125, 83)">'x'</text>
+ </g>
+
+ <!-- next UPDATE -->
+ <g transform="translate(350, 40)">
+ <text class="text_small" transform="translate(0, -18)">T
+ <tspan style="font-size:8px" dx="-3" dy="5">142</tspan>
+ <tspan dx="-2" dy="-5">: UPDATE</tspan>
+ </text>
+ <use xlink:href="#arrow" transform="translate(5, 0)"/>
+
+ <use xlink:href="#tuple" transform="translate(60, 10)"/>
+ <text class="text_small" transform="translate(65, 23)" style="fill:blue">142</text>
+ <text class="text_small" transform="translate(95, 23)" style="fill:blue">0</text>
+ <text class="text_small" transform="translate(125, 23)" style="fill:blue">'z'</text>
+ <use xlink:href="#tuple" transform="translate(60, 40)"/>
+ <text class="text_small" transform="translate(65, 53)">135</text>
+ <text class="text_small" transform="translate(95, 53)" style="fill:blue">142</text>
+ <text class="text_small" transform="translate(125, 53)">'y'</text>
+ <use xlink:href="#tuple" transform="translate(60, 70)"/>
+ <text class="text_small" transform="translate(65, 83)">123</text>
+ <text class="text_small" transform="translate(95, 83)">135</text>
+ <text class="text_small" transform="translate(125, 83)">'x'</text>
+ </g>
+
+ <!-- DELETE -->
+ <g transform="translate(515, 40)">
+ <text class="text_small" transform="translate(0, -18)">T
+ <tspan style="font-size:8px" dx="-3" dy="5">821</tspan>
+ <tspan dx="-2" dy="-5">: DELTE</tspan>
+ </text>
+ <use xlink:href="#arrow" transform="translate(5, 0)"/>
+
+ <use xlink:href="#tuple" transform="translate(60, 10)"/>
+ <text class="text_small" transform="translate(65, 23)">142</text>
+ <text class="text_small" transform="translate(95, 23)" style="fill:blue">821</text>
+ <text class="text_small" transform="translate(125, 23)">'z'</text>
+ <use xlink:href="#tuple" transform="translate(60, 40)"/>
+ <text class="text_small" transform="translate(65, 53)">135</text>
+ <text class="text_small" transform="translate(95, 53)">142</text>
+ <text class="text_small" transform="translate(125, 53)">'y'</text>
+ <use xlink:href="#tuple" transform="translate(60, 70)"/>
+ <text class="text_small" transform="translate(65, 83)">123</text>
+ <text class="text_small" transform="translate(95, 83)">135</text>
+ <text class="text_small" transform="translate(125, 83)">'x'</text>
+ </g>
+
+ <!-- LEGEND -->
+ <g transform="translate(740, 110)">
+ <path d="M 102 -20 h -120 v 60" stroke="black"/>
+ <text class="text_normal" transform="translate(0, 0)">Legend</text>
+ <use xlink:href="#tuple" transform="translate(0, 10)"/>
+ <text class="text_small" transform="translate(3, 23)">xmin</text>
+ <text class="text_small" transform="translate(32, 23)">xmax</text>
+ <text class="text_small" transform="translate(65, 23)">data</text>
+ </g>
+
+ </g>
+
+</svg>
diff --git a/doc/src/sgml/images/ram-proc-file-ink-svgo.svg b/doc/src/sgml/images/ram-proc-file-ink-svgo.svg
new file mode 100644
index 0000000000..aa0445352d
--- /dev/null
+++ b/doc/src/sgml/images/ram-proc-file-ink-svgo.svg
@@ -0,0 +1,285 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="900" height="600" viewBox="0 0 900 600">
+ <title>
+ PG Overall Server Architecture
+ </title>
+ <style>
+ .text_big{font-style:normal}.text_big,.text_comment,.text_normal,.text_small{font-weight:400;font-family:"Open Sans",sans-serif;fill:#000}.text_normal,.text_small{font-style:normal}.text_small{font-size:12px}.text_normal{font-size:14px}.text_big{font-size:24px}.text_comment{font-style:italic;font-size:14px}
+ </style>
+ <defs>
+ <symbol id="note_200x20" stroke="black" fill="lightyellow">
+ <title>
+ UML Note (200 x 20 px)
+ </title>
+ <path d="M200 10v10H0V0h190v10h10L190 0"/>
+ </symbol>
+ <symbol id="note_250x20" stroke="black" fill="lightyellow">
+ <title>
+ UML Note (250 x 20 px)
+ </title>
+ <path d="M250 10v10H0V0h240v10h10L240 0"/>
+ </symbol>
+ <symbol id="note_100x35" stroke="black" fill="lightyellow">
+ <title>
+ UML Note (100 x 35 px)
+ </title>
+ <path d="M100 10v25H0V0h90v10h10L90 0"/>
+ </symbol>
+ <symbol id="note_170x50" stroke="black" fill="lightyellow">
+ <title>
+ UML Note (170 x 50 px)
+ </title>
+ <path d="M170 10v40H0V0h160v10h10L160 0"/>
+ </symbol>
+ <symbol id="state_300x120">
+ <title>
+ UML State (300x120)
+ </title>
+ <rect width="300" height="120" rx="10" stroke="blue" fill="none"/>
+ </symbol>
+ <symbol id="state_350x120">
+ <title>
+ UML State (350x120)
+ </title>
+ <rect width="350" height="120" rx="10" stroke="blue" fill="none"/>
+ </symbol>
+ <symbol id="disc" stroke="blue" fill="none">
+ <title>
+ Disc
+ </title>
+ <ellipse cx="51" cy="13" rx="50" ry="12"/>
+ <path d="M1 13v60"/>
+ <path d="M101 13v60"/>
+ <path d="M1 73a50 12 0 00100 0"/>
+ </symbol>
+ <symbol id="laptop" stroke="black" fill="none">
+ <title>
+ Laptop
+ </title>
+ <path d="M20 40V0h54v40l15 15H5l15-15h54"/>
+ <path d="M23 3h48v34H23z"/>
+ <path d="M30 10h20"/>
+ <path d="M30 15h25"/>
+ <path d="M30 20h10"/>
+ <path d="M30 30h20"/>
+ <path d="M25 50h45l2 2H22z"/>
+ </symbol>
+ <marker id="arrowhead_start" markerWidth="10" markerHeight="10" refX="0" refY="3" orient="auto">
+ <path d="M6 0L0 3l6 3" stroke="black" fill="none"/>
+ </marker>
+ <marker id="arrowhead_end" markerWidth="10" markerHeight="10" refX="6" refY="3" orient="auto">
+ <path d="M0 0l6 3-6 3" stroke="black" fill="none"/>
+ </marker>
+ </defs>
+ <rect x="1" y="1" rx="5" width="99%" height="99%" stroke="black" fill="none"/>
+ <text x="15" y="40" class="text_big">
+ Client
+ </text>
+ <text x="140" y="40" class="text_big">
+ Server
+ </text>
+ <use xlink:href="#laptop" x="5" y="210"/>
+ <g transform="translate(130 70)">
+ <use xlink:href="#state_350x120"/>
+ <text x="5" y="20" class="text_normal">
+ maintenance_work_mem (per connection)
+ </text>
+ <text x="5" y="45" class="text_normal">
+ work_mem (per query operation)
+ </text>
+ <text x="5" y="70" class="text_normal">
+ autovacuum_work_mem (per worker process)
+ </text>
+ <text x="5" y="95" class="text_normal">
+ temp_buffer (per connection)
+ </text>
+ <text x="5" y="110" class="text_normal">
+ ...
+ </text>
+ <use xlink:href="#note_200x20" x="140" y="-15"/>
+ <text x="150" class="text_comment">
+ Individual Memory
+ </text>
+ </g>
+ <g transform="translate(520 70)">
+ <use xlink:href="#state_300x120"/>
+ <text x="10" y="30" class="text_normal">
+ shared_buffers (heap and index)
+ </text>
+ <text x="10" y="70" class="text_normal">
+ wal_buffers (WAL records)
+ </text>
+ <text x="10" y="100" class="text_normal">
+ ...
+ </text>
+ <use xlink:href="#note_250x20" x="40" y="-15"/>
+ <text x="50" class="text_comment">
+ Shared Memory (per Instance)
+ </text>
+ </g>
+ <path stroke="blue" fill="none" d="M180 215h250v30H180z"/>
+ <text x="10" y="20" class="text_normal" transform="translate(180 215)">
+ Postmaster
+ </text>
+ <path d="M90 230h75" stroke="black" fill="none" marker-end="url(#arrowhead_end)"/>
+ <g transform="translate(140 230)">
+ <circle r="8" stroke="black" fill="lightyellow"/>
+ <text x="-4" y="4" class="text_small">
+ 1
+ </text>
+ </g>
+ <path stroke="blue" fill="none" d="M150 315h370v30H150z"/>
+ <text x="10" y="20" class="text_normal" transform="translate(150 315)">
+ Backend processes (one per connection)
+ </text>
+ <path d="M155 315v-5h370v30h-5" stroke="blue" fill="none"/>
+ <path d="M160 310v-5h370v30h-5" stroke="blue" fill="none"/>
+ <path d="M90 240l63 63" stroke="black" fill="none" marker-start="url(#arrowhead_start)" marker-end="url(#arrowhead_end)"/>
+ <g transform="translate(140 290)">
+ <circle r="8" stroke="black" fill="lightyellow"/>
+ <text x="-4" y="4" class="text_small">
+ 3
+ </text>
+ </g>
+ <path d="M360 250v50" stroke="black" fill="none" marker-end="url(#arrowhead_end)"/>
+ <g transform="translate(180 255)">
+ <use xlink:href="#note_250x20"/>
+ <text x="10" y="15" class="text_comment">
+ Creates backend processes
+ </text>
+ </g>
+ <g transform="translate(360 281)">
+ <circle r="8" stroke="black" fill="lightyellow"/>
+ <text x="-4" y="4" class="text_small">
+ 2
+ </text>
+ </g>
+ <path d="M460 300V200" stroke="black" fill="none" marker-start="url(#arrowhead_start)" marker-end="url(#arrowhead_end)"/>
+ <path d="M498 300V95h30" stroke="black" fill="none" marker-start="url(#arrowhead_start)" marker-end="url(#arrowhead_end)"/>
+ <path d="M508 300V135h20" stroke="black" fill="none" marker-end="url(#arrowhead_end)"/>
+ <path stroke="blue" fill="none" d="M550 220h120v30H550z"/>
+ <text x="10" y="20" class="text_normal" transform="translate(550 220)">
+ WAL Writer
+ </text>
+ <path d="M590 150v65" stroke="black" fill="none" marker-end="url(#arrowhead_end)"/>
+ <path d="M590 255v230" stroke="black" fill="none" marker-end="url(#arrowhead_end)"/>
+ <path stroke="blue" fill="none" d="M610 340h140v30H610z"/>
+ <text x="10" y="20" class="text_normal" transform="translate(610 340)">
+ Checkpointer
+ </text>
+ <path d="M740 110v220" stroke="black" fill="none" marker-end="url(#arrowhead_end)"/>
+ <path d="M605 355H475v130" stroke="black" fill="none" marker-end="url(#arrowhead_end)"/>
+ <path d="M700 330V150" stroke="black" fill="none" marker-end="url(#arrowhead_end)"/>
+ <g transform="translate(570 330)">
+ <use xlink:href="#note_100x35" x="50" y="-50"/>
+ <text x="60" y="-35" class="text_comment">
+ Checkpoint
+ </text>
+ <text x="60" y="-20" class="text_comment">
+ Record
+ </text>
+ </g>
+ <path stroke="blue" fill="none" d="M610 380h180v30H610z"/>
+ <text x="10" y="20" class="text_normal" transform="translate(610 380)">
+ Background Writer
+ </text>
+ <path d="M770 110v260" stroke="black" fill="none" marker-end="url(#arrowhead_end)"/>
+ <path d="M605 395H485v90" stroke="black" fill="none" marker-end="url(#arrowhead_end)"/>
+ <path stroke="blue" fill="none" d="M610 420h180v30H610z"/>
+ <text x="10" y="20" class="text_normal" transform="translate(610 420)">
+ WAL Archiver
+ </text>
+ <path d="M620 485l30-30" stroke="black" fill="none" marker-end="url(#arrowhead_end)"/>
+ <path d="M690 455l30 30" stroke="black" fill="none" marker-end="url(#arrowhead_end)"/>
+ <path stroke="blue" fill="none" d="M135 380h120v30H135z"/>
+ <text x="10" y="20" class="text_normal" transform="translate(135 380)">
+ Autovacuum
+ </text>
+ <path d="M140 380v-5h120v30h-5" stroke="blue" fill="none"/>
+ <path d="M145 375v-5h120v30h-5" stroke="blue" fill="none"/>
+ <path stroke="blue" fill="none" d="M135 430h120v30H135z"/>
+ <text x="10" y="20" class="text_normal" transform="translate(135 430)">
+ Logger
+ </text>
+ <path stroke="blue" fill="none" d="M290 370h140v30H290z"/>
+ <text x="10" y="20" class="text_normal" transform="translate(290 370)">
+ Stats Collector
+ </text>
+ <g transform="translate(145 490)">
+ <use xlink:href="#disc"/>
+ <text x="35" y="45" class="text_normal">
+ Log
+ </text>
+ <text x="20" y="60" class="text_small">
+ text lines,
+ </text>
+ <text x="20" y="75" class="text_small">
+ sequential
+ </text>
+ </g>
+ <path d="M195 465v20" stroke="black" fill="none" marker-end="url(#arrowhead_end)"/>
+ <g transform="translate(410 490)">
+ <use xlink:href="#disc"/>
+ <text x="10" y="40" class="text_normal">
+ Heap and
+ </text>
+ <text x="25" y="55" class="text_normal">
+ Index
+ </text>
+ <text x="15" y="70" class="text_small">
+ binary blocks,
+ </text>
+ <text x="30" y="80" class="text_small">
+ random
+ </text>
+ </g>
+ <path d="M450 485V350" stroke="black" fill="none" marker-end="url(#arrowhead_end)"/>
+ <g transform="translate(295 420)">
+ <use xlink:href="#note_170x50"/>
+ <text x="5" y="15" class="text_comment">
+ Read heap and index
+ </text>
+ <text x="5" y="30" class="text_comment">
+ pages and transfer
+ </text>
+ <text x="5" y="45" class="text_comment">
+ them to shared_buffers
+ </text>
+ </g>
+ <g transform="translate(550 490)">
+ <use xlink:href="#disc"/>
+ <text x="30" y="45" class="text_normal">
+ WAL
+ </text>
+ <text x="10" y="60" class="text_small">
+ binary records,
+ </text>
+ <text x="20" y="75" class="text_small">
+ sequential
+ </text>
+ </g>
+ <g transform="translate(690 490)">
+ <use xlink:href="#disc"/>
+ <text x="16" y="45" class="text_normal">
+ Archived
+ </text>
+ <text x="36" y="60" class="text_normal">
+ WAL
+ </text>
+ </g>
+ <path d="M110 20v550" stroke="black" fill="none"/>
+ <g transform="rotate(90 -33.5 156.5)">
+ <use xlink:href="#note_200x20"/>
+ <text class="text_comment" x="10" y="15">
+ Via TCP/IP or socket
+ </text>
+ </g>
+ <text class="text_big" x="95" transform="rotate(90 425 425)">
+ RAM
+ </text>
+ <text class="text_big" x="250" transform="rotate(90 425 425)">
+ PROCESSES
+ </text>
+ <text class="text_big" x="500" transform="rotate(90 425 425)">
+ FILES
+ </text>
+</svg>
diff --git a/doc/src/sgml/images/ram-proc-file-ink.svg b/doc/src/sgml/images/ram-proc-file-ink.svg
new file mode 100644
index 0000000000..9ef89639c4
--- /dev/null
+++ b/doc/src/sgml/images/ram-proc-file-ink.svg
@@ -0,0 +1,841 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ version="1.1"
+ width="900px"
+ height="600px"
+ viewBox="0 0 900 600"
+ id="svg4706"
+ sodipodi:docname="ram-proc-file-ink.svg"
+ inkscape:version="0.92.5 (2060ec1f9f, 2020-04-08)">
+ <metadata
+ id="metadata4710">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title>PG Overall Server Architecture</dc:title>
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <sodipodi:namedview
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1"
+ objecttolerance="10"
+ gridtolerance="10"
+ guidetolerance="10"
+ inkscape:pageopacity="0"
+ inkscape:pageshadow="2"
+ inkscape:window-width="1282"
+ inkscape:window-height="733"
+ id="namedview4708"
+ showgrid="false"
+ inkscape:zoom="0.39333333"
+ inkscape:cx="450"
+ inkscape:cy="292.37288"
+ inkscape:window-x="66"
+ inkscape:window-y="27"
+ inkscape:window-maximized="0"
+ inkscape:current-layer="svg4706" />
+ <title
+ id="title4402">PG Overall Server Architecture</title>
+ <style
+ type="text/css"
+ id="style4404">
+ .text_small {font-style:normal;
+ font-weight:normal;
+ font-size:12px;
+ font-family:"Open Sans", sans-serif;
+ fill:black;
+ }
+ .text_normal {font-style:normal;
+ font-weight:normal;
+ font-size:14px;
+ font-family:"Open Sans", sans-serif;
+ fill:black;
+ }
+ .text_big {font-style:normal;
+ font-weight:normal;
+ font-size:24px;
+ font-family:"Open Sans", sans-serif;
+ fill:black;
+ }
+ .text_comment {font-style:italic;
+ font-weight:normal;
+ font-size:14px;
+ font-family:"Open Sans", sans-serif;
+ fill:black;
+ }
+ </style>
+ <defs
+ id="defs4470">
+ <!-- Some notes in different sizes -->
+ <symbol
+ id="note_200x20"
+ stroke="black"
+ fill="lightyellow">
+ <title
+ id="title4406">UML Note (200 x 20 px)</title>
+ <path
+ d="M 200,10 v 10 h -200 v -20 h 190 v 10 h 10 l -10,-10"
+ id="path4408" />
+ </symbol>
+ <symbol
+ id="note_250x20"
+ stroke="black"
+ fill="lightyellow">
+ <title
+ id="title4411">UML Note (250 x 20 px)</title>
+ <path
+ d="M 250,10 v 10 h -250 v -20 h 240 v 10 h 10 l -10,-10"
+ id="path4413" />
+ </symbol>
+ <symbol
+ id="note_100x35"
+ stroke="black"
+ fill="lightyellow">
+ <title
+ id="title4416">UML Note (100 x 35 px)</title>
+ <path
+ d="M 100,10 v 25 h -100 v -35 h 90 v 10 h 10 l -10,-10"
+ id="path4418" />
+ </symbol>
+ <symbol
+ id="note_170x50"
+ stroke="black"
+ fill="lightyellow">
+ <title
+ id="title4421">UML Note (170 x 50 px)</title>
+ <path
+ d="M 170,10 v 40 h -170 v -50 h 160 v 10 h 10 l -10,-10"
+ id="path4423" />
+ </symbol>
+ <!-- UML states (used for buffers) -->
+ <symbol
+ id="state_300x120">
+ <title
+ id="title4426">UML State (300x120)</title>
+ <rect
+ x="0"
+ y="0"
+ width="300"
+ height="120"
+ rx="10"
+ stroke="blue"
+ fill="none"
+ id="rect4428" />
+ </symbol>
+ <symbol
+ id="state_350x120">
+ <title
+ id="title4431">UML State (350x120)</title>
+ <rect
+ x="0"
+ y="0"
+ width="350"
+ height="120"
+ rx="10"
+ stroke="blue"
+ fill="none"
+ id="rect4433" />
+ </symbol>
+ <!-- Discs -->
+ <symbol
+ id="disc"
+ stroke="blue"
+ fill="none">
+ <title
+ id="title4436">Disc</title>
+ <ellipse
+ cx="51"
+ cy="13"
+ rx="50"
+ ry="12"
+ id="ellipse4438" />
+ <!-- top -->
+ <path
+ d="M 1,13 v 60"
+ id="path4440" />
+ <!-- left -->
+ <path
+ d="M 101,13 v 60"
+ id="path4442" />
+ <!-- right -->
+ <path
+ d="M 1,73 A 50, 12, 0, 0, 0, 101,73"
+ id="path4444" />
+ <!-- bottom -->
+ </symbol>
+ <!-- Laptop -->
+ <symbol
+ id="laptop"
+ stroke="black"
+ fill="none">
+ <title
+ id="title4447">Laptop</title>
+ <path
+ d="M 20,40 v -40 h 54 v 40 l 15,15 h -84 l 15,-15 h 54"
+ id="path4449" />
+ <rect
+ x="23"
+ y="3"
+ width="48"
+ height="34"
+ id="rect4451" />
+ <!-- symbolize some lines -->
+ <path
+ d="M 30,10 h 20"
+ id="path4453" />
+ <path
+ d="M 30,15 h 25"
+ id="path4455" />
+ <path
+ d="M 30,20 h 10"
+ id="path4457" />
+ <path
+ d="M 30,30 h 20"
+ id="path4459" />
+ <!-- symbolize keyboard -->
+ <path
+ d="M 25,50 h 45 l 2,2 h -50 z "
+ id="path4461" />
+ </symbol>
+ <!-- marker start/end -->
+ <marker
+ id="arrowhead_start"
+ markerWidth="10"
+ markerHeight="10"
+ refX="0"
+ refY="3"
+ orient="auto">
+ <path
+ d="M 6,0 l -6,3 l 6,3"
+ stroke="black"
+ fill="none"
+ id="path4464" />
+ </marker>
+ <marker
+ id="arrowhead_end"
+ markerWidth="10"
+ markerHeight="10"
+ refX="6"
+ refY="3"
+ orient="auto">
+ <path
+ d="M 0,0 l 6,3 l -6,3"
+ stroke="black"
+ fill="none"
+ id="path4467" />
+ </marker>
+ </defs>
+ <!-- start of rendering area -->
+ <!-- enclosing rectangle -->
+ <rect
+ x="1"
+ y="1"
+ rx="5"
+ width="99%"
+ height="99%"
+ stroke="black"
+ fill="none"
+ id="rect4472" />
+ <!-- caption, client side -->
+ <text
+ x="15"
+ y="40"
+ class="text_big"
+ id="text4474">Client</text>
+ <text
+ x="140"
+ y="40"
+ class="text_big"
+ id="text4476">Server</text>
+ <use
+ xlink:href="#laptop"
+ x="5"
+ y="210"
+ id="use4478" />
+ <!-- individual memory -->
+ <g
+ transform="translate(130, 70)"
+ id="g4496">
+ <use
+ xlink:href="#state_350x120"
+ x="0"
+ y="0"
+ id="use4480" />
+ <text
+ x="5"
+ y="20"
+ class="text_normal"
+ id="text4482">maintenance_work_mem (per connection)</text>
+ <text
+ x="5"
+ y="45"
+ class="text_normal"
+ id="text4484">work_mem (per query operation)</text>
+ <text
+ x="5"
+ y="70"
+ class="text_normal"
+ id="text4486">autovacuum_work_mem (per worker process)</text>
+ <text
+ x="5"
+ y="95"
+ class="text_normal"
+ id="text4488">temp_buffer (per connection)</text>
+ <text
+ x="5"
+ y="110"
+ class="text_normal"
+ id="text4490">...</text>
+ <use
+ xlink:href="#note_200x20"
+ x="140"
+ y="-15"
+ id="use4492" />
+ <text
+ x="150"
+ y="0"
+ class="text_comment"
+ id="text4494">Individual Memory</text>
+ </g>
+ <!-- shared memory -->
+ <g
+ transform="translate(520, 70)"
+ id="g4510">
+ <use
+ xlink:href="#state_300x120"
+ x="0"
+ y="0"
+ id="use4498" />
+ <text
+ x="10"
+ y="30"
+ class="text_normal"
+ id="text4500">shared_buffers (heap and index)</text>
+ <text
+ x="10"
+ y="70"
+ class="text_normal"
+ id="text4502">wal_buffers (WAL records)</text>
+ <text
+ x="10"
+ y="100"
+ class="text_normal"
+ id="text4504">...</text>
+ <use
+ xlink:href="#note_250x20"
+ x="40"
+ y="-15"
+ id="use4506" />
+ <text
+ x="50"
+ y="0"
+ class="text_comment"
+ id="text4508">Shared Memory (per Instance)</text>
+ </g>
+ <!-- postmaster -->
+ <g
+ transform="translate(180, 215)"
+ id="g4516">
+ <rect
+ width="250"
+ height="30"
+ stroke="blue"
+ fill="none"
+ id="rect4512" />
+ <text
+ x="10"
+ y="20"
+ class="text_normal"
+ id="text4514">Postmaster</text>
+ </g>
+ <path
+ d="M 90,230 h 75"
+ stroke="black"
+ fill="none"
+ marker-end="url(#arrowhead_end)"
+ id="path4518" />
+ <g
+ transform="translate(140, 230)"
+ id="g4524">
+ <circle
+ r="8"
+ stroke="black"
+ fill="lightyellow"
+ id="circle4520" />
+ <text
+ x="-4"
+ y="4"
+ class="text_small"
+ id="text4522">1</text>
+ </g>
+ <!-- backend processes -->
+ <g
+ transform="translate(150, 315)"
+ id="g4534">
+ <rect
+ width="370"
+ height="30"
+ stroke="blue"
+ fill="none"
+ id="rect4526" />
+ <text
+ x="10"
+ y="20"
+ class="text_normal"
+ id="text4528">Backend processes (one per connection)</text>
+ <path
+ d="M 5,0 v -5 h 370 v 30 h -5"
+ stroke="blue"
+ fill="none"
+ id="path4530" />
+ <path
+ d="M 10,-5 v -5 h 370 v 30 h -5"
+ stroke="blue"
+ fill="none"
+ id="path4532" />
+ </g>
+ <path
+ d="M 90,240 153,303"
+ stroke="black"
+ fill="none"
+ marker-start="url(#arrowhead_start)"
+ marker-end="url(#arrowhead_end)"
+ id="path4536" />
+ <g
+ transform="translate(140, 290)"
+ id="g4542">
+ <circle
+ r="8"
+ stroke="black"
+ fill="lightyellow"
+ id="circle4538" />
+ <text
+ x="-4"
+ y="4"
+ class="text_small"
+ id="text4540">3</text>
+ </g>
+ <!-- connection between postmaster and backend processes -->
+ <path
+ d="M 360,250 v 50"
+ stroke="black"
+ fill="none"
+ marker-end="url(#arrowhead_end)"
+ id="path4544" />
+ <g
+ transform="translate(180, 255)"
+ id="g4550">
+ <use
+ xlink:href="#note_250x20"
+ id="use4546" />
+ <text
+ x="10"
+ y="15"
+ class="text_comment"
+ id="text4548">Creates backend processes</text>
+ </g>
+ <g
+ transform="translate(360, 281)"
+ id="g4556">
+ <circle
+ r="8"
+ stroke="black"
+ fill="lightyellow"
+ id="circle4552" />
+ <text
+ x="-4"
+ y="4"
+ class="text_small"
+ id="text4554">2</text>
+ </g>
+ <!-- backend process' access to individual memory -->
+ <path
+ d="M 460,300 v -100"
+ stroke="black"
+ fill="none"
+ marker-start="url(#arrowhead_start)"
+ marker-end="url(#arrowhead_end)"
+ id="path4558" />
+ <!-- its access to shared buffers and WAL buffers -->
+ <path
+ d="M 498,300 v -205 h 30"
+ stroke="black"
+ fill="none"
+ marker-start="url(#arrowhead_start)"
+ marker-end="url(#arrowhead_end)"
+ id="path4560" />
+ <path
+ d="M 508,300 v -165 h 20"
+ stroke="black"
+ fill="none"
+ marker-end="url(#arrowhead_end)"
+ id="path4562" />
+ <!-- WAL writer -->
+ <g
+ transform="translate(550, 220)"
+ id="g4568">
+ <rect
+ width="120"
+ height="30"
+ stroke="blue"
+ fill="none"
+ id="rect4564" />
+ <text
+ x="10"
+ y="20"
+ class="text_normal"
+ id="text4566">WAL Writer</text>
+ </g>
+ <path
+ d="M 590,150 v 65"
+ stroke="black"
+ fill="none"
+ marker-end="url(#arrowhead_end)"
+ id="path4570" />
+ <path
+ d="M 590,255 v 230"
+ stroke="black"
+ fill="none"
+ marker-end="url(#arrowhead_end)"
+ id="path4572" />
+ <!-- Checkpoiner -->
+ <g
+ transform="translate(610, 340)"
+ id="g4578">
+ <rect
+ width="140"
+ height="30"
+ stroke="blue"
+ fill="none"
+ id="rect4574" />
+ <text
+ x="10"
+ y="20"
+ class="text_normal"
+ id="text4576">Checkpointer</text>
+ </g>
+ <path
+ d="M 740,110 v 220"
+ stroke="black"
+ fill="none"
+ marker-end="url(#arrowhead_end)"
+ id="path4580" />
+ <path
+ d="M 605,355 h -130 v 130"
+ stroke="black"
+ fill="none"
+ marker-end="url(#arrowhead_end)"
+ id="path4582" />
+ <path
+ d="M 700,330 v -180"
+ stroke="black"
+ fill="none"
+ marker-end="url(#arrowhead_end)"
+ id="path4584" />
+ <g
+ transform="translate(570, 330)"
+ id="g4592">
+ <use
+ xlink:href="#note_100x35"
+ x="50"
+ y="-50"
+ id="use4586" />
+ <text
+ x="60"
+ y="-35"
+ class="text_comment"
+ id="text4588">Checkpoint</text>
+ <text
+ x="60"
+ y="-20"
+ class="text_comment"
+ id="text4590">Record</text>
+ </g>
+ <!-- BG writer -->
+ <g
+ transform="translate(610, 380)"
+ id="g4598">
+ <rect
+ width="180"
+ height="30"
+ stroke="blue"
+ fill="none"
+ id="rect4594" />
+ <text
+ x="10"
+ y="20"
+ class="text_normal"
+ id="text4596">Background Writer</text>
+ </g>
+ <path
+ d="M 770,110 v 260"
+ stroke="black"
+ fill="none"
+ marker-end="url(#arrowhead_end)"
+ id="path4600" />
+ <path
+ d="M 605,395 h -120 v 90"
+ stroke="black"
+ fill="none"
+ marker-end="url(#arrowhead_end)"
+ id="path4602" />
+ <!-- Archiver -->
+ <g
+ transform="translate(610, 420)"
+ id="g4608">
+ <rect
+ width="180"
+ height="30"
+ stroke="blue"
+ fill="none"
+ id="rect4604" />
+ <text
+ x="10"
+ y="20"
+ class="text_normal"
+ id="text4606">WAL Archiver</text>
+ </g>
+ <path
+ d="M 620,485 l 30,-30"
+ stroke="black"
+ fill="none"
+ marker-end="url(#arrowhead_end)"
+ id="path4610" />
+ <path
+ d="M 690,455 l 30, 30"
+ stroke="black"
+ fill="none"
+ marker-end="url(#arrowhead_end)"
+ id="path4612" />
+ <!-- Vacuum -->
+ <g
+ transform="translate(135, 380)"
+ id="g4622">
+ <rect
+ width="120"
+ height="30"
+ stroke="blue"
+ fill="none"
+ id="rect4614" />
+ <text
+ x="10"
+ y="20"
+ class="text_normal"
+ id="text4616">Autovacuum</text>
+ <path
+ d="M 5,0 v -5 h 120 v 30 h -5"
+ stroke="blue"
+ fill="none"
+ id="path4618" />
+ <path
+ d="M 10,-5 v -5 h 120 v 30 h -5"
+ stroke="blue"
+ fill="none"
+ id="path4620" />
+ </g>
+ <!-- Log Writer -->
+ <g
+ transform="translate(135, 430)"
+ id="g4628">
+ <rect
+ width="120"
+ height="30"
+ stroke="blue"
+ fill="none"
+ id="rect4624" />
+ <text
+ x="10"
+ y="20"
+ class="text_normal"
+ id="text4626">Logger</text>
+ </g>
+ <!-- Stats Collector -->
+ <g
+ transform="translate(290, 370)"
+ id="g4634">
+ <rect
+ width="140"
+ height="30"
+ stroke="blue"
+ fill="none"
+ id="rect4630" />
+ <text
+ x="10"
+ y="20"
+ class="text_normal"
+ id="text4632">Stats Collector</text>
+ </g>
+ <!-- -->
+ <!-- files -->
+ <!-- -->
+ <g
+ transform="translate(145, 490)"
+ id="g4644">
+ <use
+ xlink:href="#disc"
+ id="use4636" />
+ <text
+ x="35"
+ y="45"
+ class="text_normal"
+ id="text4638">Log</text>
+ <text
+ x="20"
+ y="60"
+ class="text_small"
+ id="text4640">text lines,</text>
+ <text
+ x="20"
+ y="75"
+ class="text_small"
+ id="text4642">sequential</text>
+ </g>
+ <path
+ d="M 195,465 v 20"
+ stroke="black"
+ fill="none"
+ marker-end="url(#arrowhead_end)"
+ id="path4646" />
+ <g
+ transform="translate(410, 490)"
+ id="g4658">
+ <use
+ xlink:href="#disc"
+ id="use4648" />
+ <text
+ x="10"
+ y="40"
+ class="text_normal"
+ id="text4650">Heap and</text>
+ <text
+ x="25"
+ y="55"
+ class="text_normal"
+ id="text4652">Index</text>
+ <text
+ x="15"
+ y="70"
+ class="text_small"
+ id="text4654">binary blocks,</text>
+ <text
+ x="30"
+ y="80"
+ class="text_small"
+ id="text4656">random</text>
+ </g>
+ <path
+ d="M 450,485 v -135"
+ stroke="black"
+ fill="none"
+ marker-end="url(#arrowhead_end)"
+ id="path4660" />
+ <g
+ transform="translate(295, 420)"
+ id="g4670">
+ <use
+ xlink:href="#note_170x50"
+ id="use4662" />
+ <text
+ x="5"
+ y="15"
+ class="text_comment"
+ id="text4664">Read heap and index</text>
+ <text
+ x="5"
+ y="30"
+ class="text_comment"
+ id="text4666">pages and transfer</text>
+ <text
+ x="5"
+ y="45"
+ class="text_comment"
+ id="text4668">them to shared_buffers</text>
+ </g>
+ <g
+ transform="translate(550, 490)"
+ id="g4680">
+ <use
+ xlink:href="#disc"
+ id="use4672" />
+ <text
+ x="30"
+ y="45"
+ class="text_normal"
+ id="text4674">WAL</text>
+ <text
+ x="10"
+ y="60"
+ class="text_small"
+ id="text4676">binary records,</text>
+ <text
+ x="20"
+ y="75"
+ class="text_small"
+ id="text4678">sequential</text>
+ </g>
+ <g
+ transform="translate(690, 490)"
+ id="g4688">
+ <use
+ xlink:href="#disc"
+ id="use4682" />
+ <text
+ x="16"
+ y="45"
+ class="text_normal"
+ id="text4684">Archived</text>
+ <text
+ x="36"
+ y="60"
+ class="text_normal"
+ id="text4686">WAL</text>
+ </g>
+ <!-- boarder between client and server side -->
+ <path
+ d="M 110,20 v 550"
+ stroke="black"
+ fill="none"
+ id="path4690" />
+ <g
+ transform="translate(123, 190) rotate(90)"
+ id="g4696">
+ <use
+ xlink:href="#note_200x20"
+ id="use4692" />
+ <text
+ class="text_comment"
+ x="10"
+ y="15"
+ id="text4694">Via TCP/IP or socket</text>
+ </g>
+ <!-- right side -->
+ <g
+ transform="translate(850, 0) rotate(90)"
+ id="g4704">
+ <text
+ class="text_big"
+ x="95"
+ id="text4698">RAM</text>
+ <text
+ class="text_big"
+ x="250"
+ id="text4700">PROCESSES</text>
+ <text
+ class="text_big"
+ x="500"
+ id="text4702">FILES</text>
+ </g>
+</svg>
diff --git a/doc/src/sgml/images/ram-proc-file-raw.svg b/doc/src/sgml/images/ram-proc-file-raw.svg
new file mode 100644
index 0000000000..775ba91571
--- /dev/null
+++ b/doc/src/sgml/images/ram-proc-file-raw.svg
@@ -0,0 +1,301 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg xmlns="http://www.w3.org/2000/svg"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ version="1.1"
+ width="900px" height="600px"
+ viewBox="0 0 900 600">
+
+ <title>PG Overall Server Architecture</title>
+
+ <style type="text/css">
+ .text_small {font-style:normal;
+ font-weight:normal;
+ font-size:12px;
+ font-family:"Open Sans", sans-serif;
+ fill:black;
+ }
+ .text_normal {font-style:normal;
+ font-weight:normal;
+ font-size:14px;
+ font-family:"Open Sans", sans-serif;
+ fill:black;
+ }
+ .text_big {font-style:normal;
+ font-weight:normal;
+ font-size:24px;
+ font-family:"Open Sans", sans-serif;
+ fill:black;
+ }
+ .text_comment {font-style:italic;
+ font-weight:normal;
+ font-size:14px;
+ font-family:"Open Sans", sans-serif;
+ fill:black;
+ }
+ </style>
+
+ <defs>
+
+ <!-- Some notes in different sizes -->
+ <symbol id="note_200x20" stroke="black" fill="lightyellow">
+ <title>UML Note (200 x 20 px)</title>
+ <path d="M 200,10 v 10 h -200 v -20 h 190 v 10 h 10 l -10,-10" />
+ </symbol>
+ <symbol id="note_250x20" stroke="black" fill="lightyellow">
+ <title>UML Note (250 x 20 px)</title>
+ <path d="M 250,10 v 10 h -250 v -20 h 240 v 10 h 10 l -10,-10" />
+ </symbol>
+ <symbol id="note_100x35" stroke="black" fill="lightyellow">
+ <title>UML Note (100 x 35 px)</title>
+ <path d="M 100,10 v 25 h -100 v -35 h 90 v 10 h 10 l -10,-10" />
+ </symbol>
+ <symbol id="note_170x50" stroke="black" fill="lightyellow">
+ <title>UML Note (170 x 50 px)</title>
+ <path d="M 170,10 v 40 h -170 v -50 h 160 v 10 h 10 l -10,-10" />
+ </symbol>
+
+ <!-- UML states (used for buffers) -->
+ <symbol id="state_300x120">
+ <title>UML State (300x120)</title>
+ <rect x="0" y="0" width="300" height="120" rx="10" stroke="blue" fill="none"/>
+ </symbol>
+ <symbol id="state_350x120">
+ <title>UML State (350x120)</title>
+ <rect x="0" y="0" width="350" height="120" rx="10" stroke="blue" fill="none"/>
+ </symbol>
+
+ <!-- Discs -->
+ <symbol id="disc" stroke="blue" fill="none" >
+ <title>Disc</title>
+ <ellipse cx="51" cy="13" rx="50" ry="12" /> <!-- top -->
+ <path d="M 1,13 v 60" /> <!-- left -->
+ <path d="M 101,13 v 60" /> <!-- right -->
+ <path d="M 1,73 A 50, 12, 0, 0, 0, 101,73" /> <!-- bottom -->
+ </symbol>
+
+ <!-- Laptop -->
+ <symbol id="laptop" stroke="black" fill="none" >
+ <title>Laptop</title>
+ <path d="M 20,40 v -40 h 54 v 40 l 15,15 h -84 l 15,-15 h 54" />
+ <rect x="23" y="3" width="48" height="34" />
+ <!-- symbolize some lines -->
+ <path d="M 30,10 h 20" />
+ <path d="M 30,15 h 25" />
+ <path d="M 30,20 h 10" />
+ <path d="M 30,30 h 20" />
+ <!-- symbolize keyboard -->
+ <path d="M 25,50 h 45 l 2,2 h -50 z " />
+ </symbol>
+
+ <!-- marker start/end -->
+ <marker id="arrowhead_start"
+ markerWidth="10"
+ markerHeight="10"
+ refX="0"
+ refY="3"
+ orient="auto">
+ <path d="M 6,0 l -6,3 l 6,3" stroke="black" fill="none" />
+ </marker>
+ <marker id="arrowhead_end"
+ markerWidth="10"
+ markerHeight="10"
+ refX="6"
+ refY="3"
+ orient="auto">
+ <path d="M 0,0 l 6,3 l -6,3" stroke="black" fill="none" />
+ </marker>
+
+ </defs>
+
+
+ <!-- start of rendering area -->
+ <!-- enclosing rectangle -->
+ <rect x="1" y="1" rx="5" width="99%" height="99%" stroke="black" fill="none" />
+
+ <!-- caption, client side -->
+ <text x="15" y="40" class="text_big">Client</text>
+ <text x="140" y="40" class="text_big">Server</text>
+ <use xlink:href="#laptop" x="5" y="210" />
+
+
+ <!-- individual memory -->
+ <g transform="translate(130, 70)">
+ <use xlink:href="#state_350x120" x="0" y="0" />
+ <text x="5" y="20" class="text_normal">maintenance_work_mem (per connection)</text>
+ <text x="5" y="45" class="text_normal">work_mem (per query operation)</text>
+ <text x="5" y="70" class="text_normal">autovacuum_work_mem (per worker process)</text>
+ <text x="5" y="95" class="text_normal">temp_buffer (per connection)</text>
+ <text x="5" y="110" class="text_normal">...</text>
+ <use xlink:href="#note_200x20" x="140" y="-15" />
+ <text x="150" y="0" class="text_comment">Individual Memory</text>
+ </g>
+
+ <!-- shared memory -->
+ <g transform="translate(520, 70)">
+ <use xlink:href="#state_300x120" x="0" y="0" />
+ <text x="10" y="30" class="text_normal">shared_buffers (heap and index)</text>
+ <text x="10" y="70" class="text_normal">wal_buffers (WAL records)</text>
+ <text x="10" y="100" class="text_normal">...</text>
+ <use xlink:href="#note_250x20" x="40" y="-15" />
+ <text x="50" y="0" class="text_comment">Shared Memory (per Instance)</text>
+ </g>
+
+ <!-- postmaster -->
+ <g transform="translate(180, 215)">
+ <rect width="250" height="30" stroke="blue" fill="none" />
+ <text x="10" y="20" class="text_normal">Postmaster</text>
+ </g>
+ <path d="M 90,230 h 75" stroke="black" fill="none" marker-end="url(#arrowhead_end)"/>
+ <g transform="translate(140, 230)">
+ <circle r="8" stroke="black" fill="lightyellow" />
+ <text x="-4" y="4" class="text_small">1</text>
+ </g>
+
+ <!-- backend processes -->
+ <g transform="translate(150, 315)">
+ <rect width="370" height="30" stroke="blue" fill="none" />
+ <text x="10" y="20" class="text_normal">Backend processes (one per connection)</text>
+ <path d="M 5,0 v -5 h 370 v 30 h -5" stroke="blue" fill="none" />
+ <path d="M 10,-5 v -5 h 370 v 30 h -5" stroke="blue" fill="none" />
+ </g>
+
+ <path d="M 90,240 153,303" stroke="black" fill="none"
+ marker-start="url(#arrowhead_start)" marker-end="url(#arrowhead_end)"/>
+ <g transform="translate(140, 290)">
+ <circle r="8" stroke="black" fill="lightyellow" />
+ <text x="-4" y="4" class="text_small">3</text>
+ </g>
+
+ <!-- connection between postmaster and backend processes -->
+ <path d="M 360,250 v 50" stroke="black" fill="none" marker-end="url(#arrowhead_end)"/>
+ <g transform="translate(180, 255)">
+ <use xlink:href="#note_250x20" />
+ <text x="10" y="15" class="text_comment">Creates backend processes</text>
+ </g>
+ <g transform="translate(360, 281)">
+ <circle r="8" stroke="black" fill="lightyellow" />
+ <text x="-4" y="4" class="text_small">2</text>
+ </g>
+
+ <!-- backend process' access to individual memory -->
+ <path d="M 460,300 v -100" stroke="black" fill="none"
+ marker-start="url(#arrowhead_start)" marker-end="url(#arrowhead_end)"/>
+ <!-- its access to shared buffers and WAL buffers -->
+ <path d="M 498,300 v -205 h 30" stroke="black" fill="none"
+ marker-start="url(#arrowhead_start)" marker-end="url(#arrowhead_end)"/>
+ <path d="M 508,300 v -165 h 20" stroke="black" fill="none"
+ marker-end="url(#arrowhead_end)"/>
+
+ <!-- WAL writer -->
+ <g transform="translate(550, 220)">
+ <rect width="120" height="30" stroke="blue" fill="none" />
+ <text x="10" y="20" class="text_normal">WAL Writer</text>
+ </g>
+ <path d="M 590,150 v 65" stroke="black" fill="none" marker-end="url(#arrowhead_end)"/>
+ <path d="M 590,255 v 230" stroke="black" fill="none" marker-end="url(#arrowhead_end)"/>
+
+ <!-- Checkpoiner -->
+ <g transform="translate(610, 340)">
+ <rect width="140" height="30" stroke="blue" fill="none" />
+ <text x="10" y="20" class="text_normal">Checkpointer</text>
+ </g>
+ <path d="M 740,110 v 220" stroke="black" fill="none" marker-end="url(#arrowhead_end)"/>
+ <path d="M 605,355 h -130 v 130" stroke="black" fill="none" marker-end="url(#arrowhead_end)"/>
+ <path d="M 700,330 v -180" stroke="black" fill="none" marker-end="url(#arrowhead_end)"/>
+ <g transform="translate(570, 330)">
+ <use xlink:href="#note_100x35" x="50" y="-50" />
+ <text x="60" y="-35" class="text_comment">Checkpoint</text>
+ <text x="60" y="-20" class="text_comment">Record</text>
+ </g>
+
+ <!-- BG writer -->
+ <g transform="translate(610, 380)">
+ <rect width="180" height="30" stroke="blue" fill="none" />
+ <text x="10" y="20" class="text_normal">Background Writer</text>
+ </g>
+ <path d="M 770,110 v 260" stroke="black" fill="none" marker-end="url(#arrowhead_end)"/>
+ <path d="M 605,395 h -120 v 90" stroke="black" fill="none" marker-end="url(#arrowhead_end)"/>
+
+ <!-- Archiver -->
+ <g transform="translate(610, 420)">
+ <rect width="180" height="30" stroke="blue" fill="none" />
+ <text x="10" y="20" class="text_normal">WAL Archiver</text>
+ </g>
+ <path d="M 620,485 l 30,-30" stroke="black" fill="none" marker-end="url(#arrowhead_end)"/>
+ <path d="M 690,455 l 30, 30" stroke="black" fill="none" marker-end="url(#arrowhead_end)"/>
+
+ <!-- Vacuum -->
+ <g transform="translate(135, 380)">
+ <rect width="120" height="30" stroke="blue" fill="none" />
+ <text x="10" y="20" class="text_normal">Autovacuum</text>
+ <path d="M 5,0 v -5 h 120 v 30 h -5" stroke="blue" fill="none" />
+ <path d="M 10,-5 v -5 h 120 v 30 h -5" stroke="blue" fill="none" />
+ </g>
+
+ <!-- Log Writer -->
+ <g transform="translate(135, 430)">
+ <rect width="120" height="30" stroke="blue" fill="none" />
+ <text x="10" y="20" class="text_normal">Logger</text>
+ </g>
+
+ <!-- Stats Collector -->
+ <g transform="translate(290, 370)">
+ <rect width="140" height="30" stroke="blue" fill="none" />
+ <text x="10" y="20" class="text_normal">Stats Collector</text>
+ </g>
+
+ <!-- -->
+ <!-- files -->
+ <!-- -->
+ <g transform="translate(145, 490)">
+ <use xlink:href="#disc" />
+ <text x="35" y="45" class="text_normal">Log</text>
+ <text x="20" y="60" class="text_small">text lines,</text>
+ <text x="20" y="75" class="text_small">sequential</text>
+ </g>
+ <path d="M 195,465 v 20" stroke="black" fill="none" marker-end="url(#arrowhead_end)"/>
+
+ <g transform="translate(410, 490)">
+ <use xlink:href="#disc" />
+ <text x="10" y="40" class="text_normal">Heap and</text>
+ <text x="25" y="55" class="text_normal">Index</text>
+ <text x="15" y="70" class="text_small">binary blocks,</text>
+ <text x="30" y="80" class="text_small">random</text>
+ </g>
+ <path d="M 450,485 v -135" stroke="black" fill="none" marker-end="url(#arrowhead_end)"/>
+
+ <g transform="translate(295, 420)">
+ <use xlink:href="#note_170x50" />
+ <text x="5" y="15" class="text_comment">Read heap and index</text>
+ <text x="5" y="30" class="text_comment">pages and transfer</text>
+ <text x="5" y="45" class="text_comment">them to shared_buffers</text>
+ </g>
+
+ <g transform="translate(550, 490)">
+ <use xlink:href="#disc" />
+ <text x="30" y="45" class="text_normal">WAL</text>
+ <text x="10" y="60" class="text_small">binary records,</text>
+ <text x="20" y="75" class="text_small">sequential</text>
+ </g>
+
+ <g transform="translate(690, 490)">
+ <use xlink:href="#disc" />
+ <text x="16" y="45" class="text_normal">Archived</text>
+ <text x="36" y="60" class="text_normal">WAL</text>
+ </g>
+
+ <!-- boarder between client and server side -->
+ <path d="M 110,20 v 550" stroke="black" fill="none" />
+ <g transform="translate(123, 190) rotate(90)">
+ <use xlink:href="#note_200x20" />
+ <text class="text_comment" x="10" y ="15">Via TCP/IP or socket</text>
+ </g>
+
+ <!-- right side -->
+ <g transform="translate(850, 0) rotate(90)">
+ <text class="text_big" x="95">RAM</text>
+ <text class="text_big" x="250">PROCESSES</text>
+ <text class="text_big" x="500">FILES</text>
+ </g>
+
+</svg>
diff --git a/doc/src/sgml/images/wraparound-ink-svgo.svg b/doc/src/sgml/images/wraparound-ink-svgo.svg
new file mode 100644
index 0000000000..d5af6ce0b8
--- /dev/null
+++ b/doc/src/sgml/images/wraparound-ink-svgo.svg
@@ -0,0 +1,40 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="850" height="280" viewBox="0 0 850 280">
+ <title>
+ Cyclic usage of XIDs
+ </title>
+ <style>
+ .text_normal{font-style:normal;font-weight:400;font-size:14px;font-family:"Open Sans",sans-serif;fill:#000}
+ </style>
+ <defs>
+ <path id="Path_080" d="M-80 0A80 80 0 1180 0 80 80 0 11-80 0"/>
+ <path id="Path_095" d="M-95 0A95 95 0 1195 0 95 95 0 11-95 0"/>
+ <path id="Path_120" d="M-120 0a120 120 0 11240 0 120 120 0 11-240 0"/>
+ </defs>
+ <rect x="1" y="1" rx="5" width="99%" height="99%" stroke="black" fill="none"/>
+ <text x="370" y="40" font-weight="400" font-size="24" font-family=""Open Sans",sans-serif,Helvetica">
+ Cyclic usage of XIDs modulo 2 <tspan dy="-5">^</tspan> <tspan dy="5">32</tspan>
+ </text>
+ <g fill="none" transform="translate(170 150)">
+ <circle r="100" stroke="blue"/>
+ <text class="text_normal">
+ <textPath xlink:href="#Path_095" startOffset=".5%">|</textPath> <textPath xlink:href="#Path_120" startOffset="0%">(0)</textPath> <textPath xlink:href="#Path_080" startOffset="1%" stroke="blue" stroke-width=".5"> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ></textPath> <textPath xlink:href="#Path_095" startOffset="30.5%">|</textPath> <textPath xlink:href="#Path_120" startOffset="30%">(1)</textPath> <textPath xlink:href="#Path_095" startOffset="45.5%">|</textPath> <textPath xlink:href="#Path_120" startOffset="45%">(2)</textPath> <textPath xlink:href="#Path_095" startOffset="50.5%">|</textPath> <textPath xlink:href="#Path_120" startOffset="50%">(3)</textPath> <textPath xlink:href="#Path_095" startOffset="62.5%">|</textPath> <textPath xlink:href="#Path_120" startOffset="62%">(4)</textPath>
+ </text>
+ </g>
+ <g class="text_normal">
+ <text transform="translate(400 130)">
+ 0: 0 .. 2 <tspan dy="-5">^</tspan> <tspan dy="5">32</tspan> - 1
+ </text>
+ <text y="25" transform="translate(400 130)">
+ 1: oldest <tspan font-weight="700">active</tspan> xid (pg_stat_activity.backend_xmin)
+ </text>
+ <text y="50" transform="translate(400 130)">
+ 2: xmin of one row version
+ </text>
+ <text y="75" transform="translate(400 130)">
+ 3: xmax of the same row version
+ </text>
+ <text y="100" transform="translate(400 130)">
+ 4: youngest xid (txid_current)
+ </text>
+ </g>
+</svg>
diff --git a/doc/src/sgml/images/wraparound-ink.svg b/doc/src/sgml/images/wraparound-ink.svg
new file mode 100644
index 0000000000..51d35a9f85
--- /dev/null
+++ b/doc/src/sgml/images/wraparound-ink.svg
@@ -0,0 +1,198 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ version="1.1"
+ width="850px"
+ height="280px"
+ viewBox="0 0 850 280"
+ id="svg216"
+ sodipodi:docname="wraparound-ink.svg"
+ inkscape:version="0.92.5 (2060ec1f9f, 2020-04-08)">
+ <metadata
+ id="metadata220">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title>Cyclic usage of XIDs</dc:title>
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <sodipodi:namedview
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1"
+ objecttolerance="10"
+ gridtolerance="10"
+ guidetolerance="10"
+ inkscape:pageopacity="0"
+ inkscape:pageshadow="2"
+ inkscape:window-width="1247"
+ inkscape:window-height="650"
+ id="namedview218"
+ showgrid="false"
+ inkscape:zoom="0.44470588"
+ inkscape:cx="425"
+ inkscape:cy="133.25397"
+ inkscape:window-x="0"
+ inkscape:window-y="27"
+ inkscape:window-maximized="0"
+ inkscape:current-layer="svg216" />
+ <title
+ id="title153">Cyclic usage of XIDs</title>
+ <!-- common text classes -->
+ <style
+ type="text/css"
+ id="style155">
+ .text_normal {font-style:normal;
+ font-weight:normal;
+ font-size:14px;
+ font-family:"Open Sans", sans-serif;
+ fill:black;
+ }
+ .text_big {font-style:normal;
+ font-weight:normal;
+ font-size:24px;
+ font-family:"Open Sans", sans-serif, Helvetica;
+ fill:black;
+ }
+ </style>
+ <defs
+ id="defs160">
+ <!-- SVG 1.x supports <texPath> only in combination with <path>. SVG 2 allows the
+ combination with every shape element, especially with <circle>. As of 2020
+ we must restrict ourselves to SVG 1. Therefore: we simulate a circle by
+ defining two arcs, each of them is a half-circle.
+ -->
+ <path
+ id="Path_080"
+ d="m -80 0 a 80 80 0 1 1 160 0 a 80 80 0 1 1 -160 0" />
+ <path
+ id="Path_095"
+ d="m -95 0 a 95 95 0 1 1 190 0 a 95 95 0 1 1 -190 0" />
+ <path
+ id="Path_120"
+ d="m -120 0 a 120 120 0 1 1 240 0 a 120 120 0 1 1 -240 0" />
+ </defs>
+ <!-- start of rendering area -->
+ <!-- enclosing rectangle -->
+ <rect
+ x="1"
+ y="1"
+ rx="5"
+ width="99%"
+ height="99%"
+ stroke="black"
+ fill="none"
+ id="rect162" />
+ <text
+ class="text_big"
+ x="370"
+ y="40"
+ id="text168">Cyclic usage of XIDs modulo 2
+ <tspan
+ dy="-5"
+ id="tspan164">^</tspan>
+<tspan
+ dy="5"
+ id="tspan166">32</tspan>
+</text>
+ <!-- set default values -->
+ <g
+ fill="none"
+ transform="translate(170 150)"
+ id="g196">
+ <circle
+ r="100"
+ stroke="blue"
+ id="circle170" />
+ <text
+ class="text_normal"
+ id="text194">
+ <textPath
+ xlink:href="#Path_095"
+ startOffset="0.5%"
+ id="textPath172">|</textPath>
+ <textPath
+ xlink:href="#Path_120"
+ startOffset="00%"
+ id="textPath174">(0)</textPath>
+ <textPath
+ xlink:href="#Path_080"
+ startOffset="01%"
+ stroke="blue"
+ stroke-width="0.5px"
+ id="textPath176">
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ></textPath>
+ <textPath
+ xlink:href="#Path_095"
+ startOffset="30.5%"
+ id="textPath178">|</textPath>
+ <textPath
+ xlink:href="#Path_120"
+ startOffset="30%"
+ id="textPath180">(1)</textPath>
+ <textPath
+ xlink:href="#Path_095"
+ startOffset="45.5%"
+ id="textPath182">|</textPath>
+ <textPath
+ xlink:href="#Path_120"
+ startOffset="45%"
+ id="textPath184">(2)</textPath>
+ <textPath
+ xlink:href="#Path_095"
+ startOffset="50.5%"
+ id="textPath186">|</textPath>
+ <textPath
+ xlink:href="#Path_120"
+ startOffset="50%"
+ id="textPath188">(3)</textPath>
+ <textPath
+ xlink:href="#Path_095"
+ startOffset="62.5%"
+ id="textPath190">|</textPath>
+ <textPath
+ xlink:href="#Path_120"
+ startOffset="62%"
+ id="textPath192">(4)</textPath>
+ </text>
+ </g>
+ <g
+ class="text_normal"
+ transform="translate(400 130)"
+ id="g214">
+ <text
+ id="text202">0: 0 .. 2 <tspan
+ dy="-5"
+ id="tspan198">^</tspan>
+<tspan
+ dy="5"
+ id="tspan200">32</tspan>
+ - 1</text>
+ <text
+ y="25"
+ id="text206">1: oldest <tspan
+ style="font-weight:bold"
+ id="tspan204">active</tspan>
+ xid (pg_stat_activity.backend_xmin)</text>
+ <text
+ y="50"
+ id="text208">2: xmin of one row version</text>
+ <text
+ y="75"
+ id="text210">3: xmax of the same row version</text>
+ <text
+ y="100"
+ id="text212">4: youngest xid (txid_current)</text>
+ </g>
+</svg>
diff --git a/doc/src/sgml/images/wraparound-raw.svg b/doc/src/sgml/images/wraparound-raw.svg
new file mode 100644
index 0000000000..637e68bb82
--- /dev/null
+++ b/doc/src/sgml/images/wraparound-raw.svg
@@ -0,0 +1,79 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg xmlns="http://www.w3.org/2000/svg"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ version="1.1"
+ width="850px" height="280px"
+ viewBox="0 0 850 280" >
+
+ <title>Cyclic usage of XIDs</title>
+
+ <!-- common text classes -->
+ <style type="text/css">
+ .text_normal {font-style:normal;
+ font-weight:normal;
+ font-size:14px;
+ font-family:"Open Sans", sans-serif;
+ fill:black;
+ }
+ .text_big {font-style:normal;
+ font-weight:normal;
+ font-size:24px;
+ font-family:"Open Sans", sans-serif, Helvetica;
+ fill:black;
+ }
+ </style>
+
+ <defs>
+ <!-- SVG 1.x supports <texPath> only in combination with <path>. SVG 2 allows the
+ combination with every shape element, especially with <circle>. As of 2020
+ we must restrict ourselves to SVG 1. Therefore: we simulate a circle by
+ defining two arcs, each of them is a half-circle.
+ -->
+ <path id="Path_080" d="m -80 0
+ a 80 80 0 1 1 160 0
+ a 80 80 0 1 1 -160 0"/>
+ <path id="Path_095" d="m -95 0
+ a 95 95 0 1 1 190 0
+ a 95 95 0 1 1 -190 0"/>
+ <path id="Path_120" d="m -120 0
+ a 120 120 0 1 1 240 0
+ a 120 120 0 1 1 -240 0"/>
+ </defs>
+
+
+ <!-- start of rendering area -->
+ <!-- enclosing rectangle -->
+ <rect x="1" y="1" rx="5" width="99%" height="99%" stroke="black" fill="none" />
+ <text class="text_big" x="370" y="40">Cyclic usage of XIDs modulo 2
+ <tspan dy="-5">^</tspan> <tspan dy="5">32</tspan></text>
+
+ <!-- set default values -->
+ <g fill="none" transform="translate(170 150)">
+
+ <circle r="100" stroke="blue" />
+
+ <text class="text_normal">
+ <textPath xlink:href="#Path_095" startOffset="0.5%" >|</textPath>
+ <textPath xlink:href="#Path_120" startOffset="00%" >(0)</textPath>
+ <textPath xlink:href="#Path_080" startOffset="01%" stroke="blue" stroke-width="0.5px" >
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ></textPath>
+ <textPath xlink:href="#Path_095" startOffset="30.5%" >|</textPath>
+ <textPath xlink:href="#Path_120" startOffset="30%" >(1)</textPath>
+ <textPath xlink:href="#Path_095" startOffset="45.5%" >|</textPath>
+ <textPath xlink:href="#Path_120" startOffset="45%" >(2)</textPath>
+ <textPath xlink:href="#Path_095" startOffset="50.5%" >|</textPath>
+ <textPath xlink:href="#Path_120" startOffset="50%" >(3)</textPath>
+ <textPath xlink:href="#Path_095" startOffset="62.5%" >|</textPath>
+ <textPath xlink:href="#Path_120" startOffset="62%" >(4)</textPath>
+ </text>
+ </g>
+
+ <g class="text_normal" transform="translate(400 130)">
+ <text>0: 0 .. 2 <tspan dy="-5">^</tspan> <tspan dy="5">32</tspan> - 1</text>
+ <text y="25">1: oldest <tspan style="font-weight:bold">active</tspan> xid (pg_stat_activity.backend_xmin)</text>
+ <text y="50">2: xmin of one row version</text>
+ <text y="75">3: xmax of the same row version</text>
+ <text y="100">4: youngest xid (txid_current)</text>
+ </g>
+
+</svg>
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index 730d5fdc34..e9e9f9495f 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -248,6 +248,7 @@ break is not needed in a wider output rendering.
</para>
</partintro>
+ &architecture;
&arch-dev;
&catalogs;
&protocol;
diff --git a/doc/src/sgml/start.sgml b/doc/src/sgml/start.sgml
index 9bb5c1a6d5..abb61445f2 100644
--- a/doc/src/sgml/start.sgml
+++ b/doc/src/sgml/start.sgml
@@ -53,7 +53,7 @@
<sect1 id="tutorial-arch">
- <title>Architectural Fundamentals</title>
+ <title>Client/Server Model</title>
<para>
Before we proceed, you should understand the basic
@@ -68,34 +68,52 @@
client/server model. A <productname>PostgreSQL</productname>
session consists of the following cooperating processes
(programs):
+ </para>
- <itemizedlist>
- <listitem>
- <para>
- A server process, which manages the database files, accepts
- connections to the database from client applications, and
- performs database actions on behalf of the clients. The
- database server program is called
- <filename>postgres</filename>.
- <indexterm><primary>postgres</primary></indexterm>
- </para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para>
+ A process at the server site with the name
+ <glossterm linkend="glossary-postmaster">Postmaster</glossterm>.
+ <indexterm><primary>postgres</primary></indexterm>
+ <indexterm><primary>postmaster</primary></indexterm>
+ It accepts connection requests from client applications, starts
+ (<quote>forks</quote>) a new <glossterm linkend="glossary-backend">
+ Backend</glossterm> process for each of them, and passes
+ the connection to it. From that point on, the client and the new
+ Backend process communicate directly without intervention by the original
+ Postmaster process. Thus, the Postmaster process is always running,
+ waiting for new client connections, whereas clients and associated
+ Backend processes come and go. (All of this is of course invisible
+ to the user. We only mention it here for completeness.)
+ </para>
+ </listitem>
- <listitem>
- <para>
- The user's client (frontend) application that wants to perform
- database operations. Client applications can be very diverse
- in nature: a client could be a text-oriented tool, a graphical
- application, a web server that accesses the database to
- display web pages, or a specialized database maintenance tool.
- Some client applications are supplied with the
- <productname>PostgreSQL</productname> distribution; most are
- developed by users.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ A group of processes at the server site, the <glossterm
+ linkend="glossary-instance">Instance</glossterm>, to which also
+ the Postmaster process belongs. Their duties are handling of
+ central, common database activities like file access, transaction
+ handling, vacuum, checkpoints, replication, and more. The mentioned
+ Backend processes delegate those actions to the instance.
+ </para>
+ </listitem>
- </itemizedlist>
- </para>
+ <listitem>
+ <para>
+ The user's client (frontend) application that wants to perform
+ database operations. Client applications can be very diverse
+ in nature: a client could be a text-oriented tool, a graphical
+ application, a web server that accesses the database to
+ display web pages, or a specialized database maintenance tool.
+ Some client applications are supplied with the
+ <productname>PostgreSQL</productname> distribution; most are
+ developed by users.
+ </para>
+ </listitem>
+
+ </itemizedlist>
<para>
As is typical of client/server applications, the client and the
@@ -106,18 +124,6 @@
file name) on the database server machine.
</para>
- <para>
- The <productname>PostgreSQL</productname> server can handle
- multiple concurrent connections from clients. To achieve this it
- starts (<quote>forks</quote>) a new process for each connection.
- From that point on, the client and the new server process
- communicate without intervention by the original
- <filename>postgres</filename> process. Thus, the
- supervisor server process is always running, waiting for
- client connections, whereas client and associated server processes
- come and go. (All of this is of course invisible to the user. We
- only mention it here for completeness.)
- </para>
</sect1>
[text/x-patch] 0013-architecture.sgml.diff (28.3K, 4-0013-architecture.sgml.diff)
download | inline diff:
diff --git a/doc/src/sgml/architecture.sgml b/doc/src/sgml/architecture.sgml
index b7589f9a4f..4bbd6abb8a 100644
--- a/doc/src/sgml/architecture.sgml
+++ b/doc/src/sgml/architecture.sgml
@@ -6,8 +6,11 @@
<para>
Every DBMS implements basic strategies to ensure a fast
and robust system. This chapter provides an overview of the
- techniques <productname>PostgreSQL</productname> uses to
- achieve this.
+ basic techniques <productname>PostgreSQL</productname> uses to
+ achieve this aim. It does not offer anything which exceeds
+ the information content of other pages. Instead, it tries to
+ explain <emphasis>why</emphasis> certain implementation
+ decisions have been taken.
</para>
<sect1 id="tutorial-ram-proc-file">
@@ -28,10 +31,11 @@
</para>
<para>
- The first step when an Instance starts is the start of the
+ All aspects of an Instance are launched and managed using a single primary
+ process termed the
<glossterm linkend="glossary-postmaster">Postmaster</glossterm>.
- It loads the configuration files, allocates Shared Memory, and
- starts the other processes of the Instance:
+ It loads configuration files, allocates Shared Memory, and
+ starts the other collaborating processes of the Instance:
<glossterm linkend="glossary-background-writer">Background Writer</glossterm>,
<glossterm linkend="glossary-checkpointer">Checkpointer</glossterm>,
<glossterm linkend="glossary-wal-writer">WAL Writer</glossterm>,
@@ -39,9 +43,10 @@
<glossterm linkend="glossary-autovacuum">Autovacuum</glossterm>,
<glossterm linkend="glossary-stats-collector">Statistics Collector</glossterm>,
<glossterm linkend="glossary-logger">Logger</glossterm>, and more.
- Later, the Postmaster starts
+ Later, the Postmaster listens on its configured system port and in response
+ to client connection attempts launches
<glossterm linkend="glossary-backend">Backend</glossterm> processes
- which communicate with clients and handle their requests.
+ to which it delegates authentication, communication, and the handling of their requests.
<xref linkend="tutorial-ram-proc-file-figure"/> visualizes the processes
of an Instance and the main aspects of their collaboration.
</para>
@@ -62,14 +67,6 @@
</mediaobject>
</figure>
- <para>
- When a client application tries to connect to a
- <glossterm linkend="glossary-database">database</glossterm>,
- this request is handled initially by the Postmaster. It
- starts a new Backend process, which handles all further
- client's requests.
- </para>
-
<para>
Client requests like <command>SELECT</command> or
<command>UPDATE</command> usually lead to the
@@ -77,16 +74,16 @@
by the client's backend process. Reads involve a page-level
cache, located in Shared Memory (for details see:
<xref linkend="sysvipc"/>) for the benefit of all processes
- in the instance. Writes also use this cache, in addition
+ in the Instance. Writes also use this cache, in addition
to a journal, called the write-ahead-log or WAL.
</para>
<para>
Shared Memory is limited in size and it can become necessary
to evict pages. As long as the content of such pages hasn't
- changed, this is not a problem. But in Shared Memory also
- write actions take place. Modified pages are called dirty
- pages or dirty buffers and before they can be evicted they
+ changed, this is not a problem. But writes directly modify
+ the pages in Shared Memory. Modified pages are called dirty
+ pages (or dirty buffers) and before they can be evicted they
must be written to disk. This happens regularly by the
Checkpointer and the Background Writer processes to ensure
that the disk version of the pages are up-to-date.
@@ -98,7 +95,7 @@
<glossterm linkend="glossary-wal-record">WAL record</glossterm>
is created from the delta-information (difference between the
old and the new content) and stored in another area of
- Shared Memory. The parallel running WAL Writer process
+ Shared Memory. The concurrently running WAL Writer process
reads them and appends them to the end of the current
<glossterm linkend="glossary-wal-record">WAL file</glossterm>.
Such sequential writes are faster than writes to random
@@ -108,8 +105,8 @@
</para>
<para>
- Second, the transfer of dirty buffers from Shared Memory to
- files must take place. This is the primary task of the
+ Second, the Instance transfers dirty buffers from Shared Memory to
+ files. This is the primary task of the
Background Writer process. Because I/O activities can block
other processes, it starts periodically and
acts only for a short period. Doing so, its extensive (and
@@ -123,14 +120,8 @@
<glossterm linkend="glossary-checkpoint">Checkpoints</glossterm>.
A Checkpoint is a point in time when all older dirty buffers,
all older WAL records, and finally a special Checkpoint record
- are written and flushed to disk. Heap and index files,
- and WAL files are now in sync.
- Older WAL is no longer required. In other words,
- a possibly occurring recovery, which integrates the delta
- information of WAL into heap and index files, will happen
- by replaying only WAL past the last-recorded checkpoint.
- This limits the amount of WAL to be replayed
- during recovery in the event of a crash.
+ are written and flushed to disk.
+ Older WAL files are no longer required to recover the system from a crash.
</para>
<para>
@@ -141,8 +132,10 @@
less common). Options and details are covered
in the backup and restore section (<xref linkend="backup"/>).
For our purposes here, just note that the WAL Archiver process
- can be enabled and configured to run a script on filled WAL
- files — usually to copy them to a remote location.
+ can be enabled and configured to run a script on completed WAL
+ files — usually to copy them to a remote location. Note
+ that when a Checkpoint record is written to the WAL the current
+ file is immediately completed.
</para>
<para>
@@ -163,23 +156,35 @@
<title>The logical Perspective: Cluster, Database, Schema</title>
<para>
- A <glossterm linkend="glossary-server">server</glossterm> contains one or more
- <glossterm linkend="glossary-db-cluster">database clusters</glossterm>
- (<glossterm linkend="glossary-db-cluster">clusters</glossterm>
- for short). Each cluster contains three or more
- <glossterm linkend="glossary-database">databases</glossterm>.
- Each database can contain many
- <glossterm linkend="glossary-schema">schemas</glossterm>.
- A schema can contain
- <glossterm linkend="glossary-table">tables</glossterm>,
+ A <glossterm linkend="glossary-server">Server</glossterm> contains one or more
+ <glossterm linkend="glossary-db-cluster">Database Clusters</glossterm>
+ (<glossterm linkend="glossary-db-cluster">Clusters</glossterm>
+ for short). By default each newly initialized Cluster contains three
+ <glossterm linkend="glossary-database">databases</glossterm>
+ (one interactive and two templates, see <xref linkend="app-initdb"/>).
+ Each database can contain many user-writable
+ <glossterm linkend="glossary-schema">schemas</glossterm>
+ (public, by name and permissiveness, by default), the system
+ generated user-facing schemas <literal>pg_catalog</literal>,
+ <literal>pg_temp</literal>, and <literal>information_schema</literal>,
+ and some more system schemas.
+ <glossterm linkend="glossary-table">Tables</glossterm>,
<glossterm linkend="glossary-view">views</glossterm>, and a lot
- of other objects. Each table or view belongs to a single schema
- only; they cannot belong to another schema as well. The same is
- true for the schema/database and database/cluster relation.
+ of other objects uniquely reside in a single schema.
<xref linkend="tutorial-cluster-db-schema-figure"/> visualizes
this hierarchy.
</para>
+ <para>
+ <!-- is the para helpful at this position? -->
+ Client connections act at the database level and can access
+ its schemas simultaneously. Special techniques like
+ <link linkend="sql-createforeigndatawrapper">foreing data wrapper</link>
+ or <link linkend="dblink">dblink</link> are required
+ to access multiple databases, even within the same Cluster,
+ from a single client connection.
+ </para>
+
<figure id="tutorial-cluster-db-schema-figure">
<title>Cluster, Database, Schema</title>
<mediaobject>
@@ -197,31 +202,30 @@
</figure>
<para>
- A cluster is the outer container for a
+ A Cluster is the outer container for a
collection of databases. Clusters are created by the command
<xref linkend="app-initdb"/>.
</para>
<para>
<literal>template0</literal> is the very first
- database of any cluster. Database <literal>template0</literal>
- is created during the initialization phase of the cluster.
+ database of any Cluster. It
+ is created during the initialization phase of the Cluster.
In a second step, database <literal>template1</literal> is generated
as a copy of <literal>template0</literal>, and finally database
<literal>postgres</literal> is generated as a copy of
<literal>template1</literal>. Any
<glossterm linkend="app-createdb">new databases</glossterm>
- of the cluster that a user might need,
+ of the Cluster that a user might need,
such as <literal>my_db</literal>, will be copied from the
<literal>template1</literal> database. Due to the unique
role of <literal>template0</literal> as the pristine original
- of all other databases, no client can connect to it.
+ of all other databases, no client is allowed to connect to it.
</para>
<para>
- Every database must contain at least one schema because all
<glossterm linkend="glossary-sql-object">SQL Objects</glossterm>
- must be contained in a schema.
+ are contained in a schema.
Schemas are namespaces for SQL objects and ensure
(with one exception) that the SQL object names are used only once within
their scope across all types of SQL objects. E.g., it is not possible
@@ -243,26 +247,46 @@
without using an explicit schema name. <literal>public</literal>
should not contain user-defined SQL objects. Instead, it is
recommended to create a separate schema that holds individual
- objects like application-specific tables or views.
+ objects like application-specific tables or views. To access
+ objects in such a schema they can be fully qualified, e.g.
+ <literal>my_schema.my_table</literal>, or by changing the
+ <link linkend="ddl-schemas-path">schema search path</link>.
+ </para>
+
+ <para>
<literal>pg_catalog</literal> is a schema for all tables and views of the
<glossterm linkend="glossary-system-catalog">System Catalog</glossterm>.
- <literal>information_schema</literal> is a schema for several
- tables and views of the System Catalog in a way that conforms
- to the SQL standard.
+ <literal>information_schema</literal> is a similar schema. It
+ contains several tables and views of the System Catalog in a
+ way that conforms to the SQL standard.
</para>
<para>
- There are many different SQL object
- types: <firstterm>database, schema, table, view, materialized
- view, index, constraint, sequence, function, procedure,
- trigger, role, data type, operator, tablespace, extension,
- foreign data wrapper</firstterm>, and more. A few of them, the
+ There are many different SQL object types:
+ <glossterm linkend="glossary-database">database</glossterm>,
+ <glossterm linkend="glossary-schema">schema</glossterm>,
+ <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>,
+ <glossterm linkend="glossary-role">role</glossterm>,
+ <glossterm linkend="datatype">data type</glossterm>,
+ <glossterm linkend="functions">operator</glossterm>,
+ <glossterm linkend="glossary-tablespace">tablespace</glossterm>,
+ <glossterm linkend="glossary-extension">extension</glossterm>,
+ <glossterm linkend="glossary-foreign-data-wrapper">foreign data wrapper</glossterm>,
+ and more. A few of them, the
<firstterm>Global SQL Objects</firstterm>, are outside of the
strict hierarchy: All <firstterm>database names</firstterm>,
all <firstterm>tablespace names</firstterm>, and all
<firstterm>role names</firstterm> are automatically
- available throughout the cluster, independent from
- the database or schema in which they were defined originally.
+ available throughout the Cluster, not just the database in which
+ the SQL command was executed.
<xref linkend="tutorial-internal-objects-hierarchy-figure"/>
shows the relation between the object types.
</para>
@@ -286,7 +310,7 @@
</sect1>
<sect1 id="tutorial-directories">
- <title>The physical Perspective: Directories and Files</title>
+ <title>The Physical Perspective: Directories and Files</title>
<para>
<productname>PostgreSQL</productname> organizes long-lasting (persistent)
@@ -297,7 +321,7 @@
variable <literal>PGDATA</literal> points to this directory.
The example shown in
<xref linkend="tutorial-directories-figure"/> uses
- <literal>data</literal> as the name of this root directory.
+ <literal>data</literal> as the name of the cluster's root directory.
</para>
<figure id="tutorial-directories-figure">
@@ -317,27 +341,29 @@
</figure>
<para>
- <literal>data</literal> contains many subdirectories and
+ The cluster's root directory contains many subdirectories and
some files, all of which are necessary to store long-lasting
- as well as temporary data. The following paragraphs
- describe the files and subdirectories in
- <literal>data</literal>.
+ as well as temporary data. The root's name can be selected
+ as desired, but the names of its subdirectories and files
+ are more or less fix and detertermined by
+ <productname>PostgreSQL</productname>. The following
+ paragraphs describe the most important subdirectories
+ and files.
</para>
<para>
- <literal>base</literal> is a subdirectory in which one
- subdirectory per database exists. The names of those
+ <literal>base</literal> contains one
+ subdirectory per database. The names of those
subdirectories consist of numbers. These are the internal
Object Identifiers (OID), which are numbers to identify
- the database definition in the
+ their definition in the
<glossterm linkend="glossary-system-catalog">System Catalog</glossterm>.
</para>
<para>
- Within the database-specific
- subdirectories, there are many files: one or more for
- every table and every index to store heap and index
- data. Those files are accompanied by files for the
+ Within the database-specific subdirectories of <literal>base</literal>
+ there are many files: one or more for every table
+ and every index. Those files are accompanied by files for the
<link linkend="storage-fsm">Free Space Maps</link>
(suffixed <literal>_fsm</literal>) and
<link linkend="storage-vm">Visibility Maps</link>
@@ -345,20 +371,25 @@
</para>
<para>
- Another subdirectory is <literal>global</literal> which
+ Another subdirectory is <literal>global</literal>. It
contains files with information about
<glossterm linkend="glossary-sql-object">Global SQL Objects</glossterm>.
- One type of such Global SQL Objects are
- <glossterm linkend="glossary-tablespace">tablespaces</glossterm>.
- In <literal>global</literal> there is information about
- the tablespaces; not the tablespaces themselves.
+ </para>
+
+ <para>
+ In <literal>pg_tblspc</literal>, there are symbolic links
+ that point to directories that are outside of the root
+ directory tree, e.g. at a different disc. Files for tables
+ and indexes of non-default tablespaces reside there. As
+ previously mentioned, those defined within the default
+ tablespace reside in the database-specific subdirectories.
</para>
<para>
The subdirectory <literal>pg_wal</literal> contains the
<glossterm linkend="glossary-wal-file">WAL files</glossterm>.
They arise and grow in parallel with data changes in the
- cluster and remain as long as
+ Cluster and remain as long as
they are required for recovery, archiving, or replication.
</para>
@@ -370,19 +401,14 @@
</para>
<para>
- In <literal>pg_tblspc</literal>, there are symbolic links
- that point to directories containing SQL objects
- that exist within a non-default tablespace.
- </para>
-
- <para>
- In the root directory <literal>data</literal>
+ In the root directory
there are also some files. In many cases, the configuration
- files of the cluster are stored here. If the
- instance is up and running, the file
+ files of the Cluster are stored here. If the
+ Instance is up and running, the file
<literal>postmaster.pid</literal> exists here
+ (by default)
and contains the process ID (pid) of the
- Postmaster which started the instance.
+ Postmaster which started the Instance.
</para>
<para>
@@ -413,8 +439,8 @@
<productname>PostgreSQL</productname> implements a
sophisticated technique which avoids locking:
<firstterm>Multiversion Concurrency Control</firstterm> (MVCC).
- The advantage of MVCC
- over technologies that use row locks becomes evident in multiuser OLTP
+ The advantage of MVCC over technologies that use row locks
+ becomes evident in multiuser Online Transaction Processing (OLTP)
environments with a massive number of concurrent write
actions. There, MVCC generally performs better than solutions
using locks. In a <productname>PostgreSQL</productname>
@@ -439,15 +465,15 @@
</para>
<para>
- When we speak about transaction IDs, you need to know that xids are like
- sequences. Every new transaction receives the next number as its ID.
- Therefore, this flow of xids represents the flow of transaction
- start events over time. But keep in mind that xids are independent of
- any time measurement — in milliseconds or otherwise. If you dive
- deeper into <productname>PostgreSQL</productname>, you will recognize
- parameters with names such as 'xxx_age'. Despite their names,
- these '_age' parameters do not specify a period of time but represent
- a certain number of transactions, e.g., 100 million.
+ Xids are sequences (with a reserved value to handle wrap-around
+ in pre-9.4 <productname>PostgreSQL</productname> versions).
+ Age computations involving them measure a transaction
+ count as opposed to a time interval (in milliseconds or otherwise).
+ If you dive deeper into <productname>PostgreSQL</productname>,
+ you will recognize parameters with names such as 'xxx_age'.
+ Despite their names, these '_age' parameters do not specify
+ a period of time but represent a certain number of transactions,
+ e.g., 100 million.
</para>
<para>
@@ -498,7 +524,7 @@
executes an <command>UPDATE</command> of this row by
changing the user data from <literal>'x'</literal> to
<literal>'y'</literal>. According to the MVCC principles,
- the data in the old version of the row is not changed!
+ the data in the old version of the row is not changed.
The value <literal>'x'</literal> remains as it was before.
Only <literal>xmax</literal> changes to <literal>135</literal>.
Now, this version is treated as valid exclusively for
@@ -526,7 +552,7 @@
<para>
Finally, a row may be deleted by a <command>DELETE</command>
command. Even in this case, all versions of the row remain as
- before. Nothing is thrown away! Only <literal>xmax</literal>
+ before; nothing is thrown away. Only <literal>xmax</literal>
of the last version is set to the xid of the <command>DELETE</command>
transaction, which indicates that (if committed) it is only visible to
transactions with xids older than that (from
@@ -545,7 +571,8 @@
Over time, also the older ones get out of scope
for ALL transactions and therefore become unnecessary.
Nevertheless, they do exist physically on the disk and occupy
- space.
+ space. They are called <firstterm>dead rows</firstterm> and are part
+ of the <glossterm linkend="glossary-bloat">bloat</glossterm>.
</para>
<para>
@@ -560,12 +587,7 @@
<firstterm>row versions</firstterm> are valid (visible) for transactions.
This range doesn't imply any direct temporal meaning;
the sequence of xids reflects only the sequence of
- transaction begin events. As
- xids grow, old row versions get out of scope over time.
- If an old row version is no longer relevant for ANY existing
- transactions, it can be marked <firstterm>dead</firstterm>. The
- space occupied by dead row versions is part of the
- <glossterm linkend="glossary-bloat">bloat</glossterm>.
+ transaction begin events.
</simpara>
</listitem>
@@ -581,9 +603,9 @@
<simpara>
Nothing is removed — with the consequence that the database
occupies more and more disk space. It is obvious that
- this behavior has to be corrected in some
- way. The next chapter explains how <firstterm>autovacuum</firstterm>
- fulfills this task.
+ this behavior has to be corrected in some way. The next
+ chapter explains how <firstterm>vacuum</firstterm> and
+ <firstterm>autovacuum</firstterm> fulfill this task.
</simpara>
</listitem>
@@ -601,12 +623,12 @@
This chapter explains how the SQL command
<command>VACUUM</command> and the automatically running
<firstterm>Autovacuum</firstterm> processes clean up
- and avoid continued growth.
+ and prevent continued growth.
</para>
<note>
<para>
- Autovacuum runs automatically by
+ Autovacuum runs automatically, by
default. Its default parameters as well as those for
<command>VACUUM</command> are appropriate for most standard
situations. Therefore a novice database manager can
@@ -617,11 +639,11 @@
<para>
Client processes can issue the SQL command <command>VACUUM</command>
- at arbitrary points in time. DBAs do this when they recognize
+ at any time. DBAs do this when they recognize
special situations, or they start it in batch jobs which run
- periodically. Autovacuum processes run as part of the
- <link linkend="glossary-instance">Instance</link> at the server.
- There is a constantly running Autovacuum daemon. It continuously
+ periodically. Additionally, there is a constantly running
+ Autovacuum daemon which is part of the
+ <link linkend="glossary-instance">Instance</link>. It continuously
monitors the state of all databases based on values that are collected by the
<link linkend="glossary-stats-collector">Statistics Collector</link>
and starts Autovacuum processes whenever it detects
@@ -1234,7 +1256,7 @@ UPDATE accounts SET balance = balance + 100.00 WHERE name = 'Bob';
<para>
Lastly, it is worth noticing that changes done by a
committed transaction will survive all failures in the application or
- database cluster. The next chapter explains the
+ the Database Cluster. The next chapter explains the
<glossterm linkend="glossary-durability">durability</glossterm>
guarantees.
</para>
@@ -1276,7 +1298,7 @@ UPDATE accounts SET balance = balance + 100.00 WHERE name = 'Bob';
<bridgehead renderas="sect3">Instance failure</bridgehead>
<para>
- The instance may suddenly fail because of <emphasis>power off</emphasis>
+ The Instance may suddenly fail because of <emphasis>power off</emphasis>
or other problems. This will affect all running processes, the RAM,
and possibly the consistency of disk files.
</para>
@@ -1284,7 +1306,7 @@ UPDATE accounts SET balance = balance + 100.00 WHERE name = 'Bob';
<para>
After a restart, <productname>PostgreSQL</productname>
automatically recognizes that the last shutdown of the
- instance did not happen as expected: files might not be
+ Instance did not happen as expected: files might not be
closed properly and the <literal>postmaster.pid</literal>
file unexpectedly exists. <productname>PostgreSQL</productname>
tries to clean up the situation. This is possible because
@@ -1330,7 +1352,7 @@ UPDATE accounts SET balance = balance + 100.00 WHERE name = 'Bob';
<para>
They obviously need a backup. How to take such a backup
and use it as a starting point for a recovery of the
- cluster is explained in more detail in the next
+ Cluster is explained in more detail in the next
<link linkend="tutorial-backup">chapter</link>.
</para>
@@ -1396,7 +1418,7 @@ UPDATE accounts SET balance = balance + 100.00 WHERE name = 'Bob';
<para>
You can use any appropriate OS tool to create a
<link linkend="backup-file">copy</link>
- of the cluster's directory structure and files. In
+ of the Cluster's directory structure and files. In
case of severe problems such a copy can serve as
the source of recovery. But in order to get a
<emphasis>USABLE</emphasis> backup by this method,
@@ -1416,7 +1438,7 @@ UPDATE accounts SET balance = balance + 100.00 WHERE name = 'Bob';
<para>
The tool <command>pg_dump</command> is able to take a
<link linkend="backup-dump">copy</link>
- of the complete cluster or certain parts of it. It stores
+ of the complete Cluster or certain parts of it. It stores
the copy in the form of SQL commands like <command>CREATE</command>
and <command>COPY</command>. It runs in
parallel with other processes, in its own transaction.
@@ -1430,9 +1452,9 @@ UPDATE accounts SET balance = balance + 100.00 WHERE name = 'Bob';
<para>
The main advantage over the other two methods is that it
- can pick parts of the cluster, e.g., a single table or one
+ can pick parts of the Cluster, e.g., a single table or one
database. The other two methods work only at the level of
- the complete cluster.
+ the complete Cluster.
</para>
<bridgehead renderas="sect2">Continuous archiving based on pg_basebackup and WAL files</bridgehead>
@@ -1447,7 +1469,7 @@ UPDATE accounts SET balance = balance + 100.00 WHERE name = 'Bob';
<firstterm>basebackup</firstterm> with the tool
<command>pg_basebackup</command>. The result is a
directory structure plus files which contain a
- consistent copy of the original cluster.
+ consistent copy of the original Cluster.
<command>pg_basebackup</command> runs in
parallel with other processes in its own transaction.
</para>
@@ -1456,9 +1478,9 @@ UPDATE accounts SET balance = balance + 100.00 WHERE name = 'Bob';
The second step is recommended but not necessary. All
changes to the data are stored in WAL files. If you
continuously save such WAL files, you have the history
- of the cluster. This history can be applied to a
+ of the Cluster. This history can be applied to a
basebackup in order to recreate
- any state of the cluster between the time of
+ any state of the Cluster between the time of
<command>pg_basebackup</command>'s start time and
any later point in time. This technique
is called 'Point-in-Time Recovery (PITR)'.
@@ -1478,7 +1500,7 @@ UPDATE accounts SET balance = balance + 100.00 WHERE name = 'Bob';
</para>
<para>
- If it becomes necessary to restore the cluster, you have to
+ If it becomes necessary to restore the Cluster, you have to
copy the basebackup and the archived WAL files to
their original directories. The configuration of this
<link linkend="backup-pitr-recovery">recovery procedure</link>
[text/x-patch] 0013-images.diff (14.5K, 5-0013-images.diff)
download | inline diff:
diff --git a/doc/src/sgml/images/cluster-db-schema-raw.svg b/doc/src/sgml/images/cluster-db-schema-raw.svg
index 022bc45560..8534b18ec2 100644
--- a/doc/src/sgml/images/cluster-db-schema-raw.svg
+++ b/doc/src/sgml/images/cluster-db-schema-raw.svg
@@ -36,36 +36,49 @@
<!-- the database -->
<rect width="225" height="155" rx="10" stroke="blue" fill="none"/>
+ </symbol>
+
+ <!-- a rectangle with rounded corners and inner definitions for schemas -->
+ <symbol id="rectangle_special_1">
+
+ <!-- the database -->
+ <rect width="225" height="155" rx="10" stroke="blue" fill="none"/>
+
<!-- schemas -->
<rect x="15" y="40" width="195" height="50" rx="10" stroke="blue" fill="none" stroke-dasharray="4 2" />
<text class="text_normal" x="20" y="60">schema 'public'</text>
- <text class="text_small" x="20" y="80">tables, views, ...</text>
+ <text class="text_small" x="25" y="80">tables, views, ...</text>
<rect x="15" y="105" width="195" height="30" rx="10" stroke="blue" fill="none" stroke-dasharray="4 2" />
- <text class="text_small" x="20" y="125">(more system schemas)</text>
+ <text class="text_small" x="20" y="125">System schemas</text>
</symbol>
<!-- same as before, but one more schema -->
- <symbol id="rectangle_special_1">
+ <symbol id="rectangle_special_2">
<!-- the database -->
<rect width="245" height="225" rx="10" stroke="blue" fill="none"/>
<!-- schemas -->
<rect x="15" y="40" width="205" height="50" rx="10" stroke="blue" fill="none" stroke-dasharray="4 2" />
<text class="text_normal" x="20" y="60">schema 'public'</text>
- <text class="text_small" x="20" y="80">tables, views, ...</text>
+ <text class="text_small" x="25" y="80">tables, views, ...</text>
- <rect x="15" y="105" width="205" height="50" rx="10" stroke="blue" fill="none" stroke-dasharray="4 2" />
- <text class="text_normal" x="20" y="125">'my_schema' (optional)</text>
- <text class="text_small" x="20" y="145">tables, views, ...</text>
+ <rect x="15" y="105" width="205" height="30" rx="10" stroke="blue" fill="none" stroke-dasharray="4 2" />
+ <text class="text_small" x="20" y="125">System schemas</text>
- <rect x="15" y="170" width="205" height="30" rx="10" stroke="blue" fill="none" stroke-dasharray="4 2" />
- <text class="text_small" x="20" y="190">(more system schemas)</text>
+ <rect x="15" y="150" width="205" height="50" rx="10" stroke="blue" fill="none" stroke-dasharray="4 2" />
+ <text class="text_normal" x="20" y="170">'my_schema' (optional)</text>
+ <text class="text_small" x="25" y="185">tables, views, ...</text>
</symbol>
- <symbol id="note" stroke="black" fill="lightyellow">
+ <symbol id="note_0" stroke="black" fill="lightyellow">
<title>UML Note</title>
- <path d="M 450,10 v 230 h -450 v -240 h 440 v 10 h 10 l -10,-10" />
+ <path d="M 190,10 v 70 h -190 v -80 h 180 v 10 h 10 l -10,-10" />
+ </symbol>
+
+ <symbol id="note_1" stroke="black" fill="lightyellow">
+ <title>UML Note</title>
+ <path d="M 450,10 v 240 h -450 v -250 h 440 v 10 h 10 l -10,-10" />
</symbol>
<!-- marker start/end -->
@@ -109,23 +122,28 @@
<g transform="translate(40 155)">
<use xlink:href="#rectangle_special_0" />
<text class="text_normal" x="10" y="25">database 'template0'</text>
+ <use xlink:href="#note_0" x="20" y="40" />
+ <text class="text_small" x="30" y="60">'template0' is a pristine</text>
+ <text class="text_small" x="30" y="75">and unchangeable template.</text>
+ <text class="text_small" x="30" y="90">It is used to generate</text>
+ <text class="text_small" x="30" y="105">database 'template1'.</text>
</g>
<!-- database template 1 -->
<g transform="translate(290 155)">
- <use xlink:href="#rectangle_special_0" />
+ <use xlink:href="#rectangle_special_1" />
<text class="text_normal" x="10" y="25">database 'template1'</text>
</g>
<!-- database postgres -->
<g transform="translate(540 155)">
- <use xlink:href="#rectangle_special_1" />
+ <use xlink:href="#rectangle_special_2" />
<text class="text_normal" x="10" y="25">database 'postgres'</text>
</g>
<!-- database my_db -->
<g transform="translate(40 350)">
- <use xlink:href="#rectangle_special_1" />
+ <use xlink:href="#rectangle_special_2" />
<text class="text_normal" x="10" y="25">database 'my_db' (optional)</text>
</g>
@@ -133,7 +151,6 @@
<g transform="translate(320 330)">
<rect x="0" y="0" width="180" height="45" rx="10" stroke="blue" fill="none" stroke-dasharray="10 4 4 4" />
<text class="text_normal" x="15" y="27">Global SQL objects</text>
- <path d="M 0,5 l-65,-35" stroke="black" fill="none" marker-end="url(#arrowhead_end)" />
<path d="M 80,0 v-30" stroke="black" fill="none" marker-end="url(#arrowhead_end)" />
<path d="M 180,40 h50" stroke="black" fill="none" marker-end="url(#arrowhead_end)" />
<path d="M 0,40 l-45,20" stroke="black" fill="none" marker-end="url(#arrowhead_end)" />
@@ -141,32 +158,33 @@
<!-- Some comments -->
<g transform="translate(335 405)">
- <use xlink:href="#note" x="0" y="0" />
+ <use xlink:href="#note_1" x="0" y="0" />
<text class="text_small" x="10" y="20">1)</text>
- <text class="text_small" x="30" y="20">By default, you work in the cluster 'data', database 'postgres',</text>
- <text class="text_small" x="30" y="35">schema 'public'.</text>
-
- <text class="text_small" x="10" y="55">2)</text>
- <text class="text_small" x="30" y="55">More system schemas: pg_catalog, information_schema,</text>
- <text class="text_small" x="30" y="70">pg_temp, pg_toast.</text>
-
- <text class="text_small" x="10" y="90">3)</text>
- <text class="text_small" x="30" y="90">Global SQL objects: Some SQL objects are automatically active</text>
- <text class="text_small" x="30" y="105">and known database- or even cluster-wide.</text>
-
- <text class="text_small" x="10" y="125">4)</text>
- <text class="text_small" x="30" y="125">The command 'initdb' creates a new cluster with the three</text>
- <text class="text_small" x="30" y="140">databases 'template0', 'template1', and 'postgres'. The command</text>
- <text class="text_small" x="30" y="155">'createdb' creates a new database.</text>
-
- <text class="text_small" x="10" y="175">5)</text>
- <text class="text_small" x="30" y="175">If multiple clusters are active on one server at the same time,</text>
- <text class="text_small" x="30" y="190">each one is managed by an individual instance. Each such instance</text>
- <text class="text_small" x="30" y="205">uses a different port.</text>
-
- <text class="text_small" x="10" y="225">6)</text>
- <text class="text_small" x="30" y="225">No client application is allowed to connect to 'template0'.</text>
+ <text class="text_small" x="30" y="20">By default, clients connect via port '5432' to Cluster 'data',</text>
+ <text class="text_small" x="30" y="35">database 'postgres', schema 'public'. Of course, they can</text>
+ <text class="text_small" x="30" y="50">specify other connection properties.</text>
+
+ <text class="text_small" x="10" y="70">2)</text>
+ <text class="text_small" x="30" y="70">System schemas: pg_catalog, information_schema,</text>
+ <text class="text_small" x="30" y="85">pg_temp, ...</text>
+
+ <text class="text_small" x="10" y="105">3)</text>
+ <text class="text_small" x="30" y="105">Global SQL objects: Objects which are shared among all</text>
+ <text class="text_small" x="30" y="120">databases within a Cluster.</text>
+
+ <text class="text_small" x="10" y="140">4)</text>
+ <text class="text_small" x="30" y="140">The command 'initdb' creates a new cluster with the three</text>
+ <text class="text_small" x="30" y="155">databases 'template0', 'template1', and 'postgres'. The command</text>
+ <text class="text_small" x="30" y="170">'createdb' creates a new database.</text>
+
+ <text class="text_small" x="10" y="190">5)</text>
+ <text class="text_small" x="30" y="190">If multiple clusters are active on one server at the same time,</text>
+ <text class="text_small" x="30" y="205">each one is managed by an individual instance. Each such instance</text>
+ <text class="text_small" x="30" y="220">uses a different port.</text>
+
+ <text class="text_small" x="10" y="240">6)</text>
+ <text class="text_small" x="30" y="240">Client application are prohibited from connecting to 'template0'.</text>
</g>
diff --git a/doc/src/sgml/images/directories-raw.svg b/doc/src/sgml/images/directories-raw.svg
index 757342a554..5cce551b0c 100644
--- a/doc/src/sgml/images/directories-raw.svg
+++ b/doc/src/sgml/images/directories-raw.svg
@@ -14,6 +14,12 @@
font-family:"Open Sans", sans-serif;
fill:black;
}
+ .text_italic {font-style:italic;
+ font-weight:normal;
+ font-size:14px;
+ font-family:"Open Sans", sans-serif;
+ fill:silver;
+ }
.text_big {font-style:normal;
font-weight:normal;
font-size:24px;
@@ -54,14 +60,14 @@
<!-- the directories -->
<g transform="translate(20, 100)">
<use xlink:href="#directory" />
- <text x="10" y="26" class="text_normal">... /pg/</text>
+ <text x="10" y="26" class="text_italic">/var/lib/pgsql/</text>
<text x="300" y="26" class="text_normal">An arbitrary directory</text>
</g>
<g transform="translate(70, 130)">
<use xlink:href="#directory" />
- <text x="10" y="26" class="text_normal">data/</text>
- <text x="250" y="26" class="text_normal">Root of cluster 'data' (see: PGDATA)</text>
+ <text x="10" y="26" class="text_italic">data/</text>
+ <text x="250" y="26" class="text_normal">Cluster's root directory (with an arbitrary name; see: PGDATA)</text>
</g>
<g transform="translate(120, 160)">
@@ -74,46 +80,46 @@
<g transform="translate(170, 190)">
<use xlink:href="#directory" />
<text x="10" y="26" class="text_normal">1/</text>
- <text x="150" y="26" class="text_normal">Subdirectory for data of first database 'template0'</text>
+ <text x="150" y="26" class="text_normal">Subdirectory for data in default-tablespace of first database 'template0'</text>
</g>
<g transform="translate(170, 220)">
<use xlink:href="#directory" />
<text x="10" y="26" class="text_normal">12992/</text>
- <text x="150" y="26" class="text_normal">Subdirectory for data of second database 'template1'</text>
+ <text x="150" y="26" class="text_normal">Subdirectory for data in default-tablespace of second database 'template1'</text>
</g>
<g transform="translate(170, 250)">
<use xlink:href="#directory" />
<text x="10" y="26" class="text_normal">12999/</text>
- <text x="150" y="26" class="text_normal">Subdirectory for data of third database 'postgres'</text>
+ <text x="150" y="26" class="text_normal">Subdirectory for data in default-tablespace of third database 'postgres'</text>
</g>
<g transform="translate(170, 280)">
<use xlink:href="#directory" />
<text x="10" y="26" class="text_normal">nnnnn/</text>
- <text x="150" y="26" class="text_normal">Optional: more subdirectories for databases, e.g. 'my_db'</text>
+ <text x="150" y="26" class="text_normal">Optional: one subdirectory for each new database, e.g. '23456' for 'my_db'</text>
</g>
<g transform="translate(120, 310)">
<use xlink:href="#directory" />
<text x="10" y="26" class="text_normal">global/</text>
- <text x="200" y="26" class="text_normal">Subdirectory with information about Global SQL Objects</text>
+ <text x="200" y="26" class="text_normal">Subdirectory for information about Global SQL Objects</text>
</g>
<g transform="translate(120, 340)">
<use xlink:href="#directory" />
- <text x="10" y="26" class="text_normal">pg_wal/</text>
- <text x="200" y="26" class="text_normal">Subdirectory for Write Ahead Log files ('pg_xlog' before version 10)</text>
+ <text x="10" y="26" class="text_normal">pg_tblspc/</text>
+ <text x="200" y="26" class="text_normal">Subdirectory for symbolic links to non-default tablespaces</text>
</g>
<g transform="translate(120, 370)">
<use xlink:href="#directory" />
- <text x="10" y="26" class="text_normal">pg_xact/</text>
- <text x="200" y="26" class="text_normal">Subdirectory for transaction commit status ('pg_clog' before version 10)</text>
+ <text x="10" y="26" class="text_normal">pg_wal/</text>
+ <text x="200" y="26" class="text_normal">Subdirectory for Write Ahead Log files ('pg_xlog' before version 10)</text>
</g>
<g transform="translate(120, 400)">
<use xlink:href="#directory" />
- <text x="10" y="26" class="text_normal">pg_tblspc/</text>
- <text x="200" y="26" class="text_normal">Subdirectory containing symbolic links to tablespaces</text>
+ <text x="10" y="26" class="text_normal">pg_xact/</text>
+ <text x="200" y="26" class="text_normal">Subdirectory for transaction commit status ('pg_clog' before version 10)</text>
</g>
<g transform="translate(120, 430)">
@@ -131,14 +137,14 @@
<!-- next cluster -->
<g transform="translate(20, 540)">
<use xlink:href="#directory" />
- <text x="10" y="26" class="text_normal">... /xyz/</text>
+ <text x="10" y="26" class="text_italic">...</text>
<text x="300" y="26" class="text_normal">Same or another arbitrary directory</text>
</g>
<g transform="translate(70, 570)">
<use xlink:href="#directory" />
- <text x="10" y="26" class="text_normal">cluster_2/</text>
- <text x="250" y="26" class="text_normal">Root of another cluster 'cluster_2'</text>
+ <text x="10" y="26" class="text_italic">cluster_2/</text>
+ <text x="250" y="26" class="text_normal">Root of another cluster</text>
</g>
</svg>
diff --git a/doc/src/sgml/images/internal-objects-hierarchy-raw.svg b/doc/src/sgml/images/internal-objects-hierarchy-raw.svg
index a58f334fe3..78850283d9 100644
--- a/doc/src/sgml/images/internal-objects-hierarchy-raw.svg
+++ b/doc/src/sgml/images/internal-objects-hierarchy-raw.svg
@@ -26,7 +26,7 @@
<!-- start of rendering area -->
<!-- enclosing rectangle -->
<rect x="1" y="1" rx="5" width="99%" height="99%" stroke="black" fill="none" />
- <text class="text_big" x="200" y="40">Hierarchy of internal Objects</text>
+ <text class="text_big" x="200" y="40">Hierarchy of Internal Objects</text>
<!-- set centre of figure and default values -->
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: [email protected]
Cc: [email protected], [email protected], [email protected], [email protected], [email protected]
Subject: Re: Additional Chapter for Tutorial
In-Reply-To: <[email protected]>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox