Add an emaj_comment_rollback() function to set/change/reset a comment…

… on an E-Maj rollback. The rollback is identified by its id, as reported by the emaj_rollback_activity() report when the operation is in-progress, or in the rollback execution report at its completion. An existing comment can be reset by supplying a NULL comment to the function. If the dblink_user_password emaj parameter is set, the rollback state is visible while in execution and its comment can be set or adjusted before its completion. Restructure the documentation to gather all rollback administration functions descriptions into a new dedicated chapter.
dalibo · Apr 26, 2023 · 958c9ce · 958c9ce
1 parent 2d33084
commit 958c9ce
Show file tree

Hide file tree

Showing 46 changed files with 1,434 additions and 938 deletions.
diff --git a/CHANGES.md b/CHANGES.md
@@ -5,11 +5,13 @@ E-Maj - Change log
 ###Enhancements:###
   * When launching an E-Maj rollback, allow to set a comment about the
     operation.
+  * Add a emaj_comment_rollback() function to set/change/reset a comment on
+    an E-Maj rollback.
+  * In the E-Maj rollback execution report, add a Notice message indicating
+    the rollback id.
   * Record the E-Maj rollback start, initialization end and locking end
     timestamps into the emaj_rlbk table and let the emaj_rollback_activity()
     function report both rollback planning and locking phases duration.
-  * In the E-Maj rollback execution report, add a Notice message indicating
-    the rollback id.
   * Minor code changes.
 
 ###Bug fixes:###

diff --git a/docs/en/functionsList.rst b/docs/en/functionsList.rst
@@ -295,6 +295,9 @@ General purpose functions
 | :ref:`emaj_cleanup_rollback_state                |                               | #.rollback INT                        |
 | <emaj_cleanup_rollback_state>`                   |                               |                                       |
 +--------------------------------------------------+-------------------------------+---------------------------------------+
+| :ref:`emaj_comment_rollback                      | | rollback.id INT,            |                                       |
+| <emaj_comment_rollback>`                         | | comment TEXT                |                                       |
++--------------------------------------------------+-------------------------------+---------------------------------------+
 | :ref:`emaj_disable_protection_by_event_triggers  |                               | #.triggers INT                        |
 | <emaj_disable_protection_by_event_triggers>`     |                               |                                       |
 +--------------------------------------------------+-------------------------------+---------------------------------------+

diff --git a/docs/en/index.rst b/docs/en/index.rst
@@ -40,6 +40,7 @@ Welcome to the E-Maj's documentation!
    alterGroups
    otherGroupsFunctions
    marksFunctions
+   rollbackAdminFunctions
    statFunctions
    extractionFunctions
    otherFunctions

diff --git a/docs/en/mainFunctions.rst b/docs/en/mainFunctions.rst
@@ -92,7 +92,7 @@ The '*EMAJ_LAST_MARK*' keyword can be used as mark name, meaning the last set ma
 
 The third parameter is a boolean that indicates whether the rollback operation may target a mark set before an :doc:`alter group <alterGroups>` operation. Depending on their nature, changes performed on tables groups in *LOGGING* state can be automatically cancelled or not. In some cases, this cancellation can be partial. By default, this parameter is set to *FALSE*.
 
-A comment associated to the rollback can be supplied as 4th parameter. It allows the administrator to annotate the operation, indicating for instance the reason for it has been launched or the reverted processing.
+A comment associated to the rollback can be supplied as 4th parameter. It allows the administrator to annotate the operation, indicating for instance the reason for it has been launched or the reverted processing. The comment can also be added by the :ref:`emaj_comment_rollback() <emaj_comment_rollback>` function, this function allowing also its update or deletion.
 
 The function returns a set of rows with a severity level set to either “*Notice*” or “*Warning*” values, and a textual message. The function returns 3 “*Notice*” rows reporting the generated rollback identifier, the number of tables and the number of sequences that have been effectively modified by the rollback operation. Other messages of type “*Warning*” may also be reported when the rollback operation has processed tables group changes.
 
@@ -136,7 +136,7 @@ The '*EMAJ_LAST_MARK*' keyword can be used as mark name, meaning the last set ma
 
 The third parameter is a boolean that indicates whether the rollback operation may target a mark set before an :doc:`alter group <alterGroups>` operation. Depending on their nature, changes performed on tables groups in *LOGGING* state can be automatically cancelled or not. In some cases, this cancellation can be partial. By default, this parameter is set to *FALSE*.
 
-A comment associated to the rollback can be supplied as 4th parameter. It allows the administrator to annotate the operation, indicating for instance the reason for it has been launched or the reverted processing.
+A comment associated to the rollback can be supplied as 4th parameter. It allows the administrator to annotate the operation, indicating for instance the reason for it has been launched or the reverted processing. The comment can also be added by the :ref:`emaj_comment_rollback() <emaj_comment_rollback>` function, this function allowing also its update or deletion.
 
 The function returns a set of rows with a severity level set to either “*Notice*” or “*Warning*” values, and a textual message. The function returns 3 “*Notice*” rows reporting the generated rollback identifier, the number of tables and the number of sequences that have been effectively modified by the rollback operation. Other messages of type “*Warning*” may also be reported when the rollback operation has processed tables group changes.
 

diff --git a/docs/en/otherFunctions.rst b/docs/en/otherFunctions.rst
@@ -127,115 +127,6 @@ It is possible to build a statement accessing a log table. For instance::
 		|| quote_ident(log_schema) || '.' || quote_ident(log_table)
 		FROM emaj.emaj_get_current_log_table('myschema','mytable');
 
-.. _emaj_rollback_activity:
-
-Monitoring rollback operations
-------------------------------
-
-When the volume of recorded updates to cancel leads to a long rollback, it may be interesting to monitor the operation to appreciate how it progresses. A function, named *emaj_rollback_activity()*, and a client, :doc:`emajRollbackMonitor.php <rollbackMonitorClient>`, fit this need. 
-
-Prerequisite
-^^^^^^^^^^^^
-
-To allow E-Maj administrators to monitor the progress of a rollback operation, the activated functions update several technical tables as the process progresses. To ensure that these updates are visible while the transaction managing the rollback is in progress, they are performed through a *dblink* connection.
-
-As a result, monitoring rollback operations requires the :doc:`installation of the dblink extension <setup>` as well as the insertion of a connection identifier usable by *dblink* into the :ref:`emaj_param <emaj_param>` table.
-
-Recording the connection identifier can be performed with a statement like::
-
-   INSERT INTO emaj.emaj_param (param_key, param_value_text) 
-   VALUES ('dblink_user_password','user=<user> password=<password>');
-
-The declared connection role must have been granted the *emaj_adm* rights (or be a *superuser*).
-
-Lastly, the main transaction managing the rollback operation must be in a “*read committed*” concurrency mode (the default value).
-
-Monitoring function
-^^^^^^^^^^^^^^^^^^^
-
-The *emaj_rollback_activity()* function allows one to see the progress of rollback operations.
-
-Invoke it with the following statement::
-
-   SELECT * FROM emaj.emaj_rollback_activity();
-
-The function does not require any input parameter.
-
-It returns a set of rows of type *emaj.emaj_rollback_activity_type*. Each row represents an in progress rollback operation, with the following columns:
-
-+-----------------------------+-------------+---------------------------------------------------------------+
-| Column                      | Type        | Description                                                   |
-+=============================+=============+===============================================================+
-| rlbk_id                     | INT         | rollback identifier                                           |
-+-----------------------------+-------------+---------------------------------------------------------------+
-| rlbk_groups                 | TEXT[]      | tables groups array associated to the rollback                |
-+-----------------------------+-------------+---------------------------------------------------------------+
-| rlbk_mark                   | TEXT        | mark to rollback to                                           |
-+-----------------------------+-------------+---------------------------------------------------------------+
-| rlbk_mark_datetime          | TIMESTAMPTZ | date and time when the mark to rollback to has been set       |
-+-----------------------------+-------------+---------------------------------------------------------------+
-| rlbk_is_logged              | BOOLEAN     | boolean taking the “true” value for logged rollbacks          |
-+-----------------------------+-------------+---------------------------------------------------------------+
-| rlbk_is_alter_group_allowed | BOOLEAN     | | boolean indicating whether the rollback can target a mark   |
-|                             |             | | set before a tables groups structure change                 |
-+-----------------------------+-------------+---------------------------------------------------------------+
-| rlbk_comment                | TEXT        | comment                                                       |
-+-----------------------------+-------------+---------------------------------------------------------------+
-| rlbk_nb_session             | INT         | number of parallel sessions                                   |
-+-----------------------------+-------------+---------------------------------------------------------------+
-| rlbk_nb_table               | INT         | number of tables contained in the processed tables groups     |
-+-----------------------------+-------------+---------------------------------------------------------------+
-| rlbk_nb_sequence            | INT         | number of sequences contained in the processed tables groups  |
-+-----------------------------+-------------+---------------------------------------------------------------+
-| rlbk_eff_nb_table           | INT         | number of tables having updates to cancel                     |
-+-----------------------------+-------------+---------------------------------------------------------------+
-| rlbk_eff_nb_sequence        | INT         | number of sequences having attributes to change               |
-+-----------------------------+-------------+---------------------------------------------------------------+
-| rlbk_status                 | ENUM        | rollback operation state                                      |
-+-----------------------------+-------------+---------------------------------------------------------------+
-| rlbk_start_datetime         | TIMESTAMPTZ | rollback operation start timestamp                            |
-+-----------------------------+-------------+---------------------------------------------------------------+
-| rlbk_planning_duration      | INTERVAL    | planning phase duration                                       |
-+-----------------------------+-------------+---------------------------------------------------------------+
-| rlbk_locking_duration       | INTERVAL    | tables locking phase duration                                 |
-+-----------------------------+-------------+---------------------------------------------------------------+
-| rlbk_elapse                 | INTERVAL    | elapse time spent since the rollback operation start          |
-+-----------------------------+-------------+---------------------------------------------------------------+
-| rlbk_remaining              | INTERVAL    | estimated remaining duration                                  |
-+-----------------------------+-------------+---------------------------------------------------------------+
-| rlbk_completion_pct         | SMALLINT    | estimated percentage of the completed work                    |
-+-----------------------------+-------------+---------------------------------------------------------------+
-
-An in progress rollback operation is in one of the following state:
-
-* PLANNING : the operation is in its initial planning phase,
-* LOCKING : the operation is setting locks,
-* EXECUTING : the operation is currently executing one of the planned steps.
-
-If the functions executing rollback operations cannot use *dblink* connections (extension not installed, missing or incorrect connection parameters,...), the *emaj_rollback_activity()* does not return any rows.
-
-The remaining duration estimate is approximate. Its precision is similar to the precision of the :ref:`emaj_estimate_rollback_group() <emaj_estimate_rollback_group>` function.
-
-.. _emaj_cleanup_rollback_state:
-
-Updating rollback operations state
-----------------------------------
-
-The *emaj_rlbk* technical table and its derived tables contain the history of E-Maj rollback operations.
-
-When rollback functions cannot use *dblink* connections, all updates of these technical tables are all performed inside a single transaction. Therefore:
-
-* any rollback operation that has not been completed is invisible in these technical tables,
-* any rollback operation that has been validated is visible in these technical tables with a “*COMMITTED*” state.
-
-When rollback functions can use *dblink* connections, all updates of *emaj_rlbk* and its related tables are performed in autonomous transactions. In this working mode, rollback functions leave the operation in a “*COMPLETED*” state when finished. A dedicated internal function is in charge of transforming the “*COMPLETED*” operations either into a “*COMMITTED*” state or into an “*ABORTED*” state, depending on how the main rollback transaction has ended. This function is automatically called when a new mark is set and when the rollback monitoring function is used.
-
-If the E-Maj administrator wishes to check the status of recently executed rollback operations, he can use the *emaj_cleanup_rollback_state()* function at any time::
-
-   SELECT emaj.emaj_cleanup_rollback_state();
-
-The function returns the number of modified rollback operations.
-
 .. _emaj_purge_histories:
 
 History data purge

diff --git a/docs/en/otherGroupsFunctions.rst b/docs/en/otherGroupsFunctions.rst
@@ -100,74 +100,6 @@ This *emaj_force_drop_group()* functions performs the same actions than the :ref
 
    Since the :ref:`emaj_force_stop_group()<emaj_force_stop_group>` function has been created, this *emaj_force_drop_group()* function becomes useless. It may be removed in a future version.
 
-.. _emaj_consolidate_rollback_group:
-
-Logged rollback consolidation
------------------------------
-
-Following the execution of a “*logged rollback*”, and once the rollback operation recording becomes useless, it is possible to “*consolidate*” this rollback, meaning to some extent to transform it into “*unlogged rollback*”. A the end of the consolidation operation, marks and logs between the rollback target mark and the end rollback mark are deleted. The *emaj_consolidate_rollback_group()* function fits this need.::
-
-   SELECT emaj.emaj_consolidate_rollback_group('<group.name>', <end.rollback.mark>);
-
-The concerned logged rollback operation is identified by the name of the mark generated at the end of the rollback. This mark must always exist, but may have been renamed.
-
-The *'EMAJ_LAST_MARK'* keyword may be used as mark name to reference the last set mark.
-
-The :ref:`emaj_get_consolidable_rollbacks() <emaj_get_consolidable_rollbacks>` function may help to identify the rollbacks that may be condolidated.
-
-Like rollback functions, the *emaj_consolidate_rollback_group()* function returns the number of effectively processed tables and sequences.
-
-The tables group may be in *LOGGING* or in *IDLE* state.
-
-The rollback target mark must always exist but may have been renamed. However, intermediate marks may have been deleted.
-
-When the consolidation is complete, only the rollback target mark and the end rollback mark are kept.
-
-The disk space of deleted rows will become reusable as soon as these log tables will be “vacuumed”.
-
-Of course, once consolidated, a “*logged rollback*” cannot be cancelled (or rolled back) any more, the start rollback mark and the logs covering this rollback being deleted.
-
-The consolidation operation is not sensitive to the protections set on groups or marks, if any.
-
-If a database has enough disk space, it may be interesting to replace a simple *unlogged rollback* by a *logged rollback* followed by a *consolidation* so that the application tables remain readable during the rollback operation, thanks to the lower locking mode used for logged rollbacks.
-
-.. _emaj_get_consolidable_rollbacks:
-
-List of “consolidable rollbacks”
---------------------------------
-
-The *emaj_get_consolidable_rollbacks()* function help to identify the rollbacks that may be consolidated.::
-
-   SELECT * FROM emaj.emaj_get_consolidable_rollbacks();
-
-The function returns a set of rows with the following columns:
-
-+-------------------------------+-------------+-------------------------------------------+
-| Column                        | Type        | Description                               |
-+===============================+=============+===========================================+
-| cons_group                    | TEXT        | rolled back tables group                  |
-+-------------------------------+-------------+-------------------------------------------+
-| cons_target_rlbk_mark_name    | TEXT        | rollback target mark name                 |
-+-------------------------------+-------------+-------------------------------------------+
-| cons_target_rlbk_mark_time_id | BIGINT      | temporal reference of the target mark (*) |
-+-------------------------------+-------------+-------------------------------------------+
-| cons_end_rlbk_mark_name       | TEXT        | rollback end mark name                    |
-+-------------------------------+-------------+-------------------------------------------+
-| cons_end_rlbk_mark_time_id    | BIGINT      | temporal reference of the end mark (*)    |
-+-------------------------------+-------------+-------------------------------------------+
-| cons_rows                     | BIGINT      | number of intermediate updates            |
-+-------------------------------+-------------+-------------------------------------------+
-| cons_marks                    | INT         | number of intermediate marks              |
-+-------------------------------+-------------+-------------------------------------------+
-
-(*) emaj_time_stamp table identifiers ; this table contains the time stamps of the most important events of the tables groups life.
-
-Using this function, it is easy to consolidate at once all “*consolidable*” rollbacks for all tables groups in order to recover as much as possible disk space::
-
-   SELECT emaj.emaj_consolidate_rollback_group(cons_group, cons_end_rlbk_mark__name) FROM emaj.emaj_get_consolidable_rollbacks();
-
-The *emaj_get_consolidable_rollbacks()* function may be used by *emaj_adm* and *emaj_viewer* roles.
-
 Exporting and importing tables groups configurations
 ----------------------------------------------------