On 2020-11-07 13:24, Jürgen Purtz wrote:
Because there have been no more comments in the last days I created a
consolidated patch. It contains Erik's suggestion and some tweaks for
the text size within graphics.
[0011-architecture.patch]
Hi,
I went through architecture.sgml once more; some proposed changes
attached.
And in some .svg files I noticed 'jungest' which should be 'youngest', I
suppose.
I did not change them but below is filelist of grep -l 'jung'.
./doc/src/sgml/images/freeze-ink.svg
./doc/src/sgml/images/freeze-ink-svgo.svg
./doc/src/sgml/images/freeze-raw.svg
./doc/src/sgml/images/wraparound-ink.svg
./doc/src/sgml/images/wraparound-ink-svgo.svg
./doc/src/sgml/images/wraparound-raw.svg
Thanks,
Erik
--- doc/src/sgml/architecture.sgml.orig 2020-11-07 14:05:50.188396026 +0100
+++ doc/src/sgml/architecture.sgml 2020-11-07 20:04:27.890983873 +0100
@@ -24,7 +24,7 @@
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 utilize threading.
+ Shared Memory. PostgreSQL does not use threading.
</para>
<para>
@@ -78,7 +78,7 @@
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 a write-ahead-log or WAL.
+ to a journal, called the write-ahead-log or WAL.
</para>
<para>
@@ -90,20 +90,20 @@
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 synchronisation from RAM to disk consists of two steps.
+ 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 out of the delta-information (difference between the
+ 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
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
- out of one dirty page must be transferred to disk before the
+ from one dirty page must be transferred to disk before the
dirty page itself can be transferred to disk in the second step.
</para>
@@ -123,22 +123,22 @@
<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
- on the one hand and WAL files on the other hand are in sync.
- Previous WAL is no longer required. In other words,
+ 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 which needs to be replayed
+ 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.
</para>
<para>
- While the Checkpointer ensures that the database system can crash
- and restart itself in a valid state, the administrator needs
+ 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). The options and details are covered extensively
+ 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
@@ -153,7 +153,7 @@
<para>
The Logger writes text lines about serious and less serious
- events which can happen during database access, e.g., wrong
+ events that may happen during database access, e.g., wrong
password, no permission, long-running queries, etc.
</para>
@@ -262,7 +262,7 @@
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 where defined originally.
+ the database or schema in which they were defined originally.
<xref linkend="tutorial-internal-objects-hierarchy-figure"/>
shows the relation between the object types.
</para>
@@ -410,13 +410,11 @@
</para>
<para>
- A first approach to implement protections against concurrent
- access to the same data may be the locking of critical rows.
- <productname>PostgreSQL</productname> implements a more
- sophisticated technique which avoids any locking:
+ <productname>PostgreSQL</productname> implements a
+ sophisticated technique which avoids locking:
<firstterm>Multiversion Concurrency Control</firstterm> (MVCC).
- The crucial advantage of MVCC
- over other technologies becomes evident in multiuser OLTP
+ The advantage of MVCC
+ over technologies that use row locks becomes evident in multiuser OLTP
environments with a massive number of concurrent write
actions. There, MVCC generally performs better than solutions
using locks. In a <productname>PostgreSQL</productname>
@@ -455,7 +453,7 @@
<para>
The description in this chapter simplifies by omitting details.
When many transactions are running simultaneously, things can
- get complicated. Sometimes transactions get aborted via
+ 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
@@ -551,14 +549,14 @@
</para>
<para>
- Please keep in mind:
+ Keep in mind:
</para>
<itemizedlist>
<listitem>
<simpara>
<literal>xmin</literal> and <literal>xmax</literal>
- indicate the range from where to where
+ 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
@@ -581,7 +579,7 @@
<listitem>
<simpara>
- Nothing gets wiped away — with the consequence that the database
+ 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>
@@ -609,7 +607,7 @@
<note>
<para>
Autovacuum runs automatically by
- default. Its default parameters as well as such for
+ 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
@@ -629,7 +627,7 @@
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.
+ up whenever it is appropriate.
</para>
<para>
@@ -672,7 +670,7 @@
</itemizedlist>
<para>
- The eagerness — you can call it 'aggressiveness' — of the
+ 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
@@ -689,7 +687,7 @@
<para>
To determine which of the row versions are no longer needed, the
elimination operation must evaluate <literal>xmax</literal>
- against several criteria which all must apply:
+ against several criteria which must all apply:
</para>
<itemizedlist>
@@ -830,13 +828,13 @@
<para>
The use of a limited range of IDs for transactions leads
to the necessity to restart the sequence sooner or later.
- This does not only have the rare consequence previously
- described that sometimes <literal>xmin</literal> is
- higher than <literal>xmax</literal>. The far
+ 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 this query. If a wraparound couldn't happen,
+ 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>
@@ -884,7 +882,7 @@
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
+ but also in the 'future'-half, as well as in all coming
<glossterm linkend="glossary-xid">epochs</glossterm>.
</simpara>
</listitem>
@@ -1162,21 +1160,21 @@
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' in absolute contrast to the all-or-nothing
+ 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 is
+ 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 priviledged mode where it cannot be
+ runs in a privileged mode that cannot be
interrupted by other processes.
</para>
@@ -1184,7 +1182,7 @@
<para>
Transactions relieve applications from many standard
- actions that must be implemented for nearly every use case.
+ actions that would otherwise need to be implemented for nearly every use case.
</para>
<para>
@@ -1192,7 +1190,7 @@
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 and the increase of the
+ 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>
@@ -1266,7 +1264,7 @@
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,
+ 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
@@ -1294,9 +1292,9 @@
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. Second,
- the data itself shall exist in the heap and index files.
- In constrast with the WAL records, this part may or may
+ 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>
@@ -1308,14 +1306,14 @@
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 the remaining WAL records
- to heap and index. As a result, the heap files contain all
+ 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. Such recovery actions run
- completely automatically, it is not necessary that a
+ changes are never shown. These recovery actions run
+ automatically; it is not necessary that a
database administrator configure or start anything by
himself.
</para>
@@ -1330,7 +1328,7 @@
</para>
<para>
- They obviously needs a backup. How to take such a backup
+ 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>.
@@ -1421,7 +1419,7 @@
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.
+ parallel with other processes, in its own transaction.
</para>
<para>
@@ -1484,7 +1482,7 @@
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 reverse copy command: from
+ contains a string with the reversed copy command: from
archive location to database location.
</para>
