Skip to content

Commit

Permalink
In the documentation, replace the word "cluster" by "instance" when a…
Browse files Browse the repository at this point in the history
…ppropriate.
  • Loading branch information
beaud76 committed Jul 21, 2017
1 parent dc1673a commit 416b263
Show file tree
Hide file tree
Showing 18 changed files with 44 additions and 44 deletions.
2 changes: 1 addition & 1 deletion docs/en/architecture.rst
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
Architecture
============

In order to be able to perform a rollback operation without having previously kept a physical image of the PostgreSQL cluster's files, all updates applied on application tables must be recorded, so that they can be cancelled.
In order to be able to perform a rollback operation without having previously kept a physical image of the PostgreSQL instance's files, all updates applied on application tables must be recorded, so that they can be cancelled.

With E-Maj, this updates recording takes the following form.

Expand Down
6 changes: 3 additions & 3 deletions docs/en/extractionFunctions.rst
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ It may be useful to take images of all tables and sequences belonging to a group

SELECT emaj.emaj_snap_group('<group.name>', '<storage.directory>', '<COPY.options>');
The directory/folder name must be supplied as an absolute pathname and must have been previously created. This directory/folder must have the appropriate permission so that the PostgreSQL cluster can write in it.
The directory/folder name must be supplied as an absolute pathname and must have been previously created. This directory/folder must have the appropriate permission so that the PostgreSQL instance can write in it.

The third parameter defines the output files format. It is a character string that matches the precise syntax available for the *COPY TO* SQL statement.

Expand Down Expand Up @@ -58,7 +58,7 @@ A *NULL* value or an empty string may be used as end mark, representing the curr

The keyword *'EMAJ_LAST_MARK'* can be used as mark name, representing the last set mark.

The directory/folder name must be supplied as an absolute pathname and must have been previously created. This directory/folder must have the appropriate permission so that the PostgreSQL cluster can write in it.
The directory/folder name must be supplied as an absolute pathname and must have been previously created. This directory/folder must have the appropriate permission so that the PostgreSQL instance can write in it.

The fifth parameter defines the output files format. It is a character string that matches the precise syntax available for the *COPY TO* SQL statement.

Expand Down Expand Up @@ -105,7 +105,7 @@ A *NULL* value or an empty string may be used as end mark, representing the curr

The keyword *'EMAJ_LAST_MARK'* can be used as mark name, representing the last set mark.

The output file name must be supplied as an absolute pathname. It must have the appropriate permission so that the PostgreSQL cluster can write to it. If the file already exists, its content is overwritten.
The output file name must be supplied as an absolute pathname. It must have the appropriate permission so that the PostgreSQL instance can write to it. If the file already exists, its content is overwritten.

The last parameter is optional. It allows filtering of the tables and sequences to process. If the parameter is omitted or has a *NULL* value, all tables and sequences of the tables group are processed. If specified, the parameter must be expressed as a non empty array of text elements, each of them representing a schema qualified table or sequence name. Both syntaxes can be used::

Expand Down
22 changes: 11 additions & 11 deletions docs/en/impactsAdmin.rst
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
Impacts on cluster and database administration
==============================================
Impacts on instance and database administration
===============================================

Stopping and restarting the cluster
-----------------------------------
Stopping and restarting the instance
------------------------------------

Using E-Maj doesn't bring any particular constraint regarding stopping and restarting a PostgreSQL cluster.
Using E-Maj doesn't bring any particular constraint regarding stopping and restarting a PostgreSQL instance.

General rule
^^^^^^^^^^^^

At cluster restart, all E-Maj objects are in the same state as at cluster stop: log triggers of tables groups in *LOGGING* state remains enabled and log tables contain cancel-able updates already recorded.
At instance restart, all E-Maj objects are in the same state as at instance stop: log triggers of tables groups in *LOGGING* state remains enabled and log tables contain cancel-able updates already recorded.

If a transaction with table updates were not committed at cluster stop, it would be rolled back during the recovery phase of the cluster start, the application tables updates and the log tables updates being cancelled at the same time.
If a transaction with table updates were not committed at instance stop, it would be rolled back during the recovery phase of the instance start, the application tables updates and the log tables updates being cancelled at the same time.

This rule also applies of course to transactions that execute E-Maj functions, like a tables group start or stop, a rollback, a mark deletion,...

Expand All @@ -20,7 +20,7 @@ Sequences rollback

Due to a PostgreSQL constraint, the rollback of application sequences assigned to a tables group is the only operation that is not protected by transactions. That is the reason why application sequences are processed at the very end of the :ref:`rollback operations <emaj_rollback_group>`. (For the same reason, at set mark time, application sequences are processed at the beginning of the operation.)

In case of a cluster stop during an E-Maj rollback execution, it is recommended to rerun this rollback just after the cluster restart, to ensure that application sequences and tables remain properly synchronised.
In case of an instance stop during an E-Maj rollback execution, it is recommended to rerun this rollback just after the instance restart, to ensure that application sequences and tables remain properly synchronised.

Saving and restoring the database
---------------------------------
Expand All @@ -31,7 +31,7 @@ Saving and restoring the database
File level saves and restores
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

When saving or restoring clusters at file level, it is essential to save or restore **ALL** cluster files, including those stored on dedicated tablespaces.
When saving or restoring instances at file level, it is essential to save or restore **ALL** instance files, including those stored on dedicated tablespaces.

After a file level restore, tables groups are in the very same state as at the save time, and the database activity can be restarted without any particular E-Maj operation.

Expand Down Expand Up @@ -95,9 +95,9 @@ Using E-Maj with replication
Integrated physical replication
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

E-Maj is totally compatible with the use of the different PostgreSQL integrated physical replication modes (*WAL* archiving and *PITR*, asynchronous and synchronous *Streaming Replication*). Indeed, all E-Maj objects hosted in the cluster are replicated like all other objects of the cluster.
E-Maj is totally compatible with the use of the different PostgreSQL integrated physical replication modes (*WAL* archiving and *PITR*, asynchronous and synchronous *Streaming Replication*). Indeed, all E-Maj objects hosted in the instance are replicated like all other objects of the instance.

However, because of the way PostgreSQL manages sequences, the sequences' current values may be a little forward on slave clusters than on the master cluster. For E-Maj, this may lightly overestimate the number of log rows in general statistics. But there is no consequence on the data integrity.
However, because of the way PostgreSQL manages sequences, the sequences' current values may be a little forward on slave instances than on the master instance. For E-Maj, this may lightly overestimate the number of log rows in general statistics. But there is no consequence on the data integrity.

Integrated logical replication
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand Down
2 changes: 1 addition & 1 deletion docs/en/introduction.rst
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ In other words, E-Maj is a PostgreSQL extension which enables fine-grained write
It provides a good solution to :

* define save points at precise time on a set of tables,
* restore, if needed, this table set into a stable state, without stopping the cluster,
* restore, if needed, this table set into a stable state, without stopping the instance,
* manage several save points, each of them being usable at any time as a restore point.

So, in a **production environment**, E-Maj may simplify the technical architecture, by offering a smooth and efficient alternative to time and/or disk consuming intermediate saves (pg_dump, mirror disks,...). E-Maj may also bring a help to the debugging by giving a way to precisely analyse how suspicious programs update application tables.
Expand Down
2 changes: 1 addition & 1 deletion docs/en/parallelRollbackClient.rst
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ To build the most balanced sessions as possible, E-Maj takes into account:
Prerequisites
-------------

The command to run parallel rollbacks is written in *php*. As a consequence, **php** software and its PostgreSQL interface has to be installed on the server that executes the command (which is not necessarily the same as the one that hosts the PostgreSQL cluster).
The command to run parallel rollbacks is written in *php*. As a consequence, **php** software and its PostgreSQL interface has to be installed on the server that executes the command (which is not necessarily the same as the one that hosts the PostgreSQL instance).

Rolling back each session on behalf of a unique transaction implies the use of two phase commit. As a consequence, the **max_prepared_transaction** parameter of the *postgresql.conf* file must be adjusted. As the default value of this parameter equals 0, it must be modified by specifying a value at least equal to the maximum number of *sessions* that will be used.

Expand Down
2 changes: 1 addition & 1 deletion docs/en/rollbackMonitorClient.rst
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ E-Maj delivers an external client to run as a command that monitors the progress
Prerequisite
------------

The command to monitor rollback operations is written in *php*. As a consequence, **php** software and its PostgreSQL interface has to be installed on the server that executes the command (which is not necessarily the same as the one that hosts the PostgreSQL cluster).
The command to monitor rollback operations is written in *php*. As a consequence, **php** software and its PostgreSQL interface has to be installed on the server that executes the command (which is not necessarily the same as the one that hosts the PostgreSQL instance).

Syntax
------
Expand Down
4 changes: 2 additions & 2 deletions docs/en/setup.rst
Original file line number Diff line number Diff line change
Expand Up @@ -44,12 +44,12 @@ Then the script creates the *emaj* schema with its technical tables, types and f

If they are not already present, both *emaj_adm* and *emaj_viewer* roles are created.

Finally, the installation script looks at the cluster configuration and may display a warning message regarding the *-max-prepared-statements* parameter.
Finally, the installation script looks at the instance configuration and may display a warning message regarding the *-max-prepared-statements* parameter.

Changes in postgresql.conf configuration file
---------------------------------------------

Main E-Maj functions set a lock on each table of a processed tables group. If some groups contains a large number of tables, it may be necessary to increase the value of the **max_locks_per_transaction** parameter in the *postgresql.conf* configuration file. This parameter is used by PostgreSQL to compute the size of the *shared lock table* that tracks locks for the whole cluster. Its default value equals 64. It can be increased if an E-Maj operation fails with a message indicating that all entries of the *shared lock table* have been used.
Main E-Maj functions set a lock on each table of a processed tables group. If some groups contains a large number of tables, it may be necessary to increase the value of the **max_locks_per_transaction** parameter in the *postgresql.conf* configuration file. This parameter is used by PostgreSQL to compute the size of the *shared lock table* that tracks locks for the whole instance. Its default value equals 64. It can be increased if an E-Maj operation fails with a message indicating that all entries of the *shared lock table* have been used.

Furthermore, if the :doc:`parallel rollback client <parallelRollbackClient>` may be used, it will be probably necessary to adjust the **max_prepared_transaction** parameter.

Expand Down
2 changes: 1 addition & 1 deletion docs/en/systemTime.rst
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
Sensitivity to system time change
=================================

To ensure the integrity of tables managed by E-Maj, it is important that the rollback mechanism be insensitive to potential date or time change of the server that hosts the PostgreSQL cluster.
To ensure the integrity of tables managed by E-Maj, it is important that the rollback mechanism be insensitive to potential date or time change of the server that hosts the PostgreSQL instance.

The date and time of each update or each mark is recorded. But nothing other than sequence values recorded when marks are set, are used to frame operation in time. So **rollbacks and mark deletions are insensitive to potential system date or time change**.

Expand Down
2 changes: 1 addition & 1 deletion docs/en/uninstall.rst
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ This script performs the following steps:
* it stops the tables groups in *LOGGING* state, if any,
* it drops the tables groups, removing in particular the triggers on application tables,
* it drops the extension and the main *emaj* schema,
* it drops roles *emaj_adm* and *emaj_viewer* if they are not linked to any objects in the current database or in other databases of the cluster.
* it drops roles *emaj_adm* and *emaj_viewer* if they are not linked to any objects in the current database or in other databases of the instance.

The uninstallation script execution displays::

Expand Down
2 changes: 1 addition & 1 deletion docs/fr/architecture.rst
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
Architecture
============

Pour mener à bien l'opération de rollback sans avoir conservé au préalable une image physique des fichiers du cluster PostgreSQL, il faut pouvoir enregistrer les mises à jour effectuées sur les tables applicatives de manière à pouvoir les annuler.
Pour mener à bien l'opération de rollback sans avoir conservé au préalable une image physique des fichiers de l'instance PostgreSQL, il faut pouvoir enregistrer les mises à jour effectuées sur les tables applicatives de manière à pouvoir les annuler.

Avec E-Maj, cela prend la forme suivante.

Expand Down
6 changes: 3 additions & 3 deletions docs/fr/extractionFunctions.rst
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Il peut s'avérer utile de prendre des images de toutes les tables et séquences

SELECT emaj.emaj_snap_group('<nom.du.groupe>', '<répertoire.de.stockage>', '<options.COPY>');

Le nom du répertoire fourni doit être un chemin absolu. Ce répertoire doit exister au préalable et avoir les permissions adéquates pour que le cluster PostgreSQL puisse y écrire.
Le nom du répertoire fourni doit être un chemin absolu. Ce répertoire doit exister au préalable et avoir les permissions adéquates pour que l'instance PostgreSQL puisse y écrire.

Le troisième paramètre précise le format souhaité pour les fichiers générés. Il prend la forme d'une chaîne de caractères reprenant la syntaxe précise des options disponibles pour la commande SQL *COPY TO*.

Expand Down Expand Up @@ -56,7 +56,7 @@ Un *NULL* ou une chaîne vide peuvent être utilisés comme marque de fin. Ils r

Le mot clé *'EMAJ_LAST_MARK'* peut être utilisé comme marque de fin. Il représente alors la dernière marque posée.

Le nom du répertoire fourni doit être un chemin absolu. Ce répertoire doit exister au préalable et avoir les permissions adéquates pour que le cluster PostgreSQL puisse y écrire.
Le nom du répertoire fourni doit être un chemin absolu. Ce répertoire doit exister au préalable et avoir les permissions adéquates pour que l'instance PostgreSQL puisse y écrire.

Le cinquième paramètre précise le format souhaité pour les fichiers générés. Il prend la forme d'une chaîne de caractères reprenant la syntaxe précise des options disponibles pour la commande SQL *COPY TO*.

Expand Down Expand Up @@ -105,7 +105,7 @@ Un *NULL* ou une chaîne vide peuvent être utilisés comme marque de fin. Ils r

Le mot clé *'EMAJ_LAST_MARK'* peut être utilisé comme marque de fin. Il représente alors la dernière marque posée.

Le nom du fichier de sortie doit être exprimé sous forme de chemin absolu. Le fichier doit disposer des permissions adéquates pour que le cluster postgreSQL puisse y écrire. Si le fichier existe déjà, son contenu sera écrasé.
Le nom du fichier de sortie doit être exprimé sous forme de chemin absolu. Le fichier doit disposer des permissions adéquates pour que l'instance postgreSQL puisse y écrire. Si le fichier existe déjà, son contenu sera écrasé.

Le dernier paramètre, optionnel, permet de filtrer la liste des tables et séquences à traiter. Si le paramètre est omis ou a la valeur *NULL*, toutes les tables et séquences du groupe de tables sont traitées. S'il est spécifié, le paramètre doit être exprimé sous la forme d'un tableau non vide d'éléments texte, chacun d'eux représentant le nom d'une table ou d'une séquence préfixé par le nom de schéma. On peut utiliser indifféremment les syntaxes ::

Expand Down

0 comments on commit 416b263

Please sign in to comment.