Add capabilities to save and restore parameters configuration. Two ne…

…w emaj_export_parameters_configuration() functions allow to export the parameters as a JSON structure, either directly or into a file. Two other new emaj_import_parameters_configuration() functions allow to import parameters as a JSON structure, either directly or from a file. The "emaj_version" parameter is not processed by these functions.

CHANGES.md

@@ -3,6 +3,10 @@ E-Maj - Change log
 <devel>
 ------
 ###Enhancements:###
+  * Two new emaj_export_parameters_configuration() functions allow to export
+    the E-Maj parameters as a JSON structure, either directly or into a file.
+  * Two new emaj_import_parameters_configuration() functions allow to import
+    E-Maj parameters as a JSON structure, either directly or from a file.
   * The emaj_verify_all() function now warns about sequences linked to serial
     columns which related tables are not in the same tables group.
   * The emaj_verify_all() function now warns about tables linked by foreign

docs/en/functionsList.rst

@@ -312,9 +312,21 @@ General purpose functions
 | :ref:`emaj_enable_protection_by_event_triggers   |                               | #.triggers INT                        |
 | <emaj_enable_protection_by_event_triggers>`      |                               |                                       |
 +--------------------------------------------------+-------------------------------+---------------------------------------+
+| :ref:`emaj_export_parameters_configuration       |                               | parameters JSON                       |
+| <export_param_conf>`                             |                               |                                       |
++--------------------------------------------------+-------------------------------+---------------------------------------+
+| :ref:`emaj_export_parameters_configuration       | file.path TEXT                | #.parameters INT                      |
+| <export_param_conf>`                             |                               |                                       |
++--------------------------------------------------+-------------------------------+---------------------------------------+
 | :ref:`emaj_get_consolidable_rollbacks            |                               | SETOF emaj_consolidable_rollback_type |
 | <emaj_get_consolidable_rollbacks>` (V)           |                               |                                       |
 +--------------------------------------------------+-------------------------------+---------------------------------------+
+| :ref:`emaj_import_parameters_configuration       | | parameters JSON,            | #.parameters INT                      |
+| <import_param_conf>`                             | | [delete.conf BOOLEAN)]      |                                       |
++--------------------------------------------------+-------------------------------+---------------------------------------+
+| :ref:`emaj_import_parameters_configuration       | | file.path TEXT,             | #.parameters INT                      |
+| <import_param_conf>`                             | | [delete.conf BOOLEAN)]      |                                       |
++--------------------------------------------------+-------------------------------+---------------------------------------+
 | :ref:`emaj_rollback_activity                     |                               | SETOF emaj_rollback_activity_type     |
 | <emaj_rollback_activity>` (V)                    |                               |                                       |
 +--------------------------------------------------+-------------------------------+---------------------------------------+

docs/en/otherFunctions.rst

@@ -31,6 +31,80 @@ The *emaj_verify_all()* function can be executed by any role belonging to *emaj_
 
 If errors are detected, for instance after an application table referenced in a tables group has been dropped, appropriate measures must be taken. Typically, the potential orphan log tables or functions must be manually dropped. 
 
+.. _export_import_param_conf:
+
+Exporting and importing parameters configurations
+-------------------------------------------------
+
+Two functions sets allow to respectively export and import parameters configurations. They can be useful to deploy a standardized parameters set on several databases, or during :doc:`E-Maj version upgrades<upgrade>` by a full extension uninstallation and reinstallation.
+
+.. _export_param_conf:
+
+Exporting a parameters configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Two versions of the *emaj_export_parameters_configuration()* function export all the parameters registered in the *emaj_param* table in a JSON structure, except the parameter of key *"emaj_version"*, which is linked to the *emaj* extension itself and is not really a configuration parameter.
+
+The parameters data can be written to a file with::
+
+   SELECT emaj_export_parameters_configuration('<file.path>');
+
+The file path must be accessible in write mode by the PostgreSQL instance.
+
+The function returns the number of exported parameters.
+
+If the file path is not supplied, the function directly returns the JSON structure containing the parameters value. This structure looks like this::
+
+   {
+     "comment": "E-Maj parameters, generated from the database <db> with E-Maj version <version> at <date_heure>",
+     "parameters": [
+       {
+          "key": "...",
+          "value": "..."
+       },
+       {
+          ...
+       }
+     ]
+   }
+
+.. _import_param_conf:
+
+Importing a parameters configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Two versions of the *emaj_import_parameters_configuration()* function import parameters from a JSON structure into the *emaj_param* table.
+
+A file containing parameters to load can be read with::
+
+   SELECT emaj_import_parameters_configuration('<file.path>', <delete.current.configuration>);
+
+The file path must be accessible by the PostgreSQL instance.
+
+The file must contain a JSON structure having an attribute named *"parameters"*, of array type, and containing sub-structures with the attributes *"key"* and *"value"*::
+
+   {"parameters": [
+     {
+       "key": "...",
+       "value": "..."
+     },
+     {
+   	   ...
+     }
+   ]}
+
+The function can directly load a file generated by the *emaj_export_parameters_configuration()* function.
+
+If present, the paramètre of key *"emaj_version"* is not processed.
+
+The second parameter, boolean, is optional. It tells whether the current parameter configuration has to be deleted before the load. It is *FALSE* by default, meaning that the keys currenly stored into the *emaj_param* table, but not listed in the JSON structure are kept (differential mode load). If the value of this second parameter is set to *TRUE*, the function performs a full replacement of the parameters configuration (full mode load).
+
+The function returns the number of imported parameters.
+
+As an alternative, the first input parameter of the function directly contains the JSON structure of the parameters to load::
+
+   SELECT emaj_import_parameters_configuration('<JSON.structure>', <delete.current.configuration>);
+
 .. _emaj_get_current_log_table:
 
 Getting the current log table linked to an application table

docs/en/parameters.rst

@@ -48,3 +48,4 @@ Only *superuser* and roles having *emaj_adm* rights can access the *emaj_param*
 
 Roles having *emaj_viewer* rights can only access a part of the *emaj_param* table, through the *emaj.emaj_visible_param* view. This view just masks the real value of the *param_value_text* column for the *'dblink_user_password'* key.
 
+The :ref:`emaj_export_parameters_configuration()<export_param_conf>` and :ref:`emaj_import_parameters_configuration()<import_param_conf>` functions allow to save the parameters values and restore them.

docs/en/upgrade.rst

@@ -37,14 +37,18 @@ It may be useful to save the content of the *emaj_group_def* table in order to b
    SELECT group_name, emaj.emaj_sync_def_group(group_name) FROM emaj.emaj_group;
    CREATE TABLE public.sav_group_def AS SELECT * FROM emaj.emaj_group_def;
 
-The same way, if the E-Maj administrator had changed parameters value into the *emaj_param* table, it may also be useful to keep a trace of these changes, for instance with::
-
-   CREATE TABLE public.sav_param AS SELECT * FROM emaj.emaj_param WHERE param_key <> 'emaj_version';
-
 If the installed E-Maj version is 3.1.0 or higher, and if the E-Maj administrator has registered application triggers as “not to be automatically disabled at E-Maj rollback time”, it is advisable to save this triggers list, for instance with::
 
    CREATE TABLE public.sav_ignored_app_trigger AS SELECT * FROM emaj.emaj_ignored_app_trigger;
 
+The same way, if the E-Maj administrator had changed parameters value into the *emaj_param* table, it may also be useful to keep a trace of these changes with::
+
+   SELECT emaj.emaj_export_parameters_configuration('<file.path>');
+
+If the installed version is prior <devel>, it is possible to execute something like::
+
+   CREATE TABLE public.sav_param AS SELECT * FROM emaj.emaj_param WHERE param_key <> 'emaj_version';
+
 
 E-Maj deletion and re-installation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -66,12 +70,17 @@ Data previously saved can now be restored into E-Maj both technical tables, for
 			grpdef_priority, grpdef_log_dat_tsp, grpdef_log_idx_tsp
 		FROM public.sav_group_def;
 
-   INSERT INTO emaj.emaj_param SELECT * FROM public.sav_param;
-
    INSERT INTO emaj.emaj_ignored_app_trigger SELECT * FROM public.sav_ignored_app_trigger;
 
+   INSERT INTO emaj.emaj_param SELECT * FROM public.sav_param;
+
 Once data are copied, temporary tables or files can be deleted.
 
+If the parameters configuration has been exported on a file with the *emaj_export_parameters_configuration()* function, this configuration can be reloaded with::
+
+   SELECT emaj.emaj_import_parameters_configuration('<file.path>', TRUE);
+
+
 Upgrade from an E-Maj version between 0.11.0 to 1.3.1
 -----------------------------------------------------
 

docs/fr/functionsList.rst

@@ -312,9 +312,21 @@ Fonctions de niveau général
 | :ref:`emaj_enable_protection_by_event_triggers   |                               | nb.triggers INT                       |
 | <emaj_enable_protection_by_event_triggers>`      |                               |                                       |
 +--------------------------------------------------+-------------------------------+---------------------------------------+
+| :ref:`emaj_export_parameters_configuration       |                               | paramètres JSON                       |
+| <export_param_conf>`                             |                               |                                       |
++--------------------------------------------------+-------------------------------+---------------------------------------+
+| :ref:`emaj_export_parameters_configuration       | fichier TEXT                  | nb.paramètres INT                     |
+| <export_param_conf>`                             |                               |                                       |
++--------------------------------------------------+-------------------------------+---------------------------------------+
 | :ref:`emaj_get_consolidable_rollbacks            |                               | SETOF emaj_consolidable_rollback_type |
 | <emaj_get_consolidable_rollbacks>` (V)           |                               |                                       |
 +--------------------------------------------------+-------------------------------+---------------------------------------+
+| :ref:`emaj_import_parameters_configuration       | | paramètres JSON,            | nb.paramètres INT                     |
+| <import_param_conf>`                             | | [suppression.conf BOOLEAN)] |                                       |
++--------------------------------------------------+-------------------------------+---------------------------------------+
+| :ref:`emaj_import_parameters_configuration       | | fichier TEXT,               | nb.paramètres INT                     |
+| <import_param_conf>`                             | | [suppression.conf BOOLEAN)] |                                       |
++--------------------------------------------------+-------------------------------+---------------------------------------+
 | :ref:`emaj_rollback_activity                     |                               | SETOF emaj_rollback_activity_type     |
 | <emaj_rollback_activity>` (V)                    |                               |                                       |
 +--------------------------------------------------+-------------------------------+---------------------------------------+

docs/fr/otherFunctions.rst

@@ -30,6 +30,80 @@ La fonction *emaj_verify_all()* peut être exécutée par les rôles membres de
 
 Si des anomalies sont détectées, par exemple suite à la suppression d'une table applicative référencée dans un groupe, les mesures appropriées doivent être prises. Typiquement, les éventuelles tables de log ou fonctions orphelines doivent être supprimées manuellement.
 
+.. _export_import_param_conf:
+
+Exporter et importer des configurations de paramètres
+-----------------------------------------------------
+
+Deux jeux de fonctions permettent de respectivement exporter et importer des jeux de paramètres. Elles peuvent être utiles pour déployer un jeu standardisé de paramètres sur plusieurs bases de données ou lors de :doc:`changements de version E-Maj<upgrade>` par désinstallation et réinstallation complète de l’extension.
+
+.. _export_param_conf:
+
+Export d’une configuration de paramètres
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Deux versions de la fonction *emaj_export_parameters_configuration()* exportent sous forme de structure JSON l’ensemble des paramètres de la configuration présents dans la table *emaj_param*, à l’exception du paramètre de clé *"emaj_version"*, lié à l’extension *emaj* elle-même et qui n’est pas à proprement parler un paramètre de configuration.
+
+On peut écrire dans un fichier les données de paramétrage par ::
+
+   SELECT emaj_export_parameters_configuration('<chemin.fichier>');
+
+Le chemin du fichier doit être accessible en écriture par l’instance PostgreSQL.
+
+La fonction retourne le nombre de paramètres exportés.
+
+Si le chemin du fichier n’est pas renseigné, la fonction retourne directement la structure JSON contenant les valeurs de paramètres. Cette structure ressemble à ceci ::
+
+   {
+     "comment": "E-Maj parameters, generated from the database <db> with E-Maj version <version> at <date_heure>",
+     "parameters": [
+       {
+          "key": "...",
+          "value": "..."
+       },
+       {
+          ...
+       }
+     ]
+   }
+
+.. _import_param_conf:
+
+Import d’une configuration de paramètres
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Deux versions de la fonction *emaj_import_parameters_configuration()* importent des paramètres sous forme de structure JSON dans la table *emaj_param*.
+
+On peut lire dans un fichier des paramètres à charger par ::
+
+   SELECT emaj_import_parameters_configuration('<chemin.fichier>', <suppression.configuration.courante>);
+
+Le chemin du fichier doit être accessible par l’instance PostgreSQL.
+
+Le fichier doit contenir une structure JSON ayant un attribut nommé *"parameters"* de type tableau, et contenant des sous-structures avec les attributs *"key"* et *"value"* ::
+
+   {"parameters": [
+     {
+       "key": "...",
+       "value": "..."
+     },
+     {
+   	   ...
+     }
+   ]}
+
+La fonction peut directement charger un fichier généré par la fonction *emaj_export_parameters_configuration()*.
+
+S’il est présent, le paramètre de clé *"emaj_version"* n’est pas traité.
+
+Le second paramètre, de type booléen, est optionnel. Il indique si l’ensemble de la configuration présente doit être supprimée avant le chargement. Par défaut, sa valeur *FALSE* indique que les clés présentes dans la table *emaj_param* mais absentes de la structure JSON sont conservées (chargement en mode différentiel). Si la valeur du second paramètre est positionnée à *TRUE*, la fonction effectue un remplacement complet de la configuration de paramétrage (chargement en mode complet).
+
+La fonction retourne le nombre de paramètres importés.
+
+Dans une variante de la fonction, le premier paramètre en entrée contient directement la structure JSON des valeurs à charger ::
+
+   SELECT emaj_import_parameters_configuration('<structure.JSON>', <suppression.configuration.courante>);
+
 .. _emaj_get_current_log_table:
 
 Obtenir l’identité de la table de log courante associée à une table applicative

docs/fr/parameters.rst

@@ -47,3 +47,5 @@ Toute modification de la table *emaj_param* est tracée dans la table :ref:`emaj
 Seuls les super-utilisateurs et les utilisateurs ayant acquis les droits *emaj_adm* ont accès à la table *emaj_param*.
 
 Les utilisateurs ayant acquis les droits *emaj_viewer* n'ont accès qu'à une partie de la table *emaj_param*. au travers de la vue *emaj.emaj_visible_param*. Cette vue masque simplement le contenu réel de la colonne *param_value_text* pour la clé *'dblink_user_password'*.
+
+Des fonctions :ref:`emaj_export_parameters_configuration()<export_param_conf>` et :ref:`emaj_import_parameters_configuration()<import_param_conf>` permettent de sauver les valeurs de paramètres et de les restaurer.

docs/fr/upgrade.rst

@@ -37,14 +37,18 @@ Il peut en effet être utile de sauvegarder le contenu de la table *emaj_group_d
    SELECT group_name, emaj.emaj_sync_def_group(group_name) FROM emaj.emaj_group;
    CREATE TABLE public.sav_group_def AS SELECT * FROM emaj.emaj_group_def;
 
-De la même manière, si l'administrateur E-Maj a modifié des paramètres dans la table *emaj_param*, il peut être souhaitable d'en conserver les valeurs, avec par exemple ::
-
-   CREATE TABLE public.sav_param AS SELECT * FROM emaj.emaj_param WHERE param_key <> 'emaj_version';
-
 Si la version E-Maj installée est une version 3.1.0 ou supérieure, et si l’administrateur E-Maj a enregistré des triggers applicatifs comme "ne devant pas être automatiquement désactivés lors des opérations de rollback E-Maj", il est souhaitable de conserver cette liste, avec par exemple ::
 
    CREATE TABLE public.sav_ignored_app_trigger AS SELECT * FROM emaj.emaj_ignored_app_trigger;
 
+De la même manière, si l'administrateur E-Maj a modifié des paramètres dans la table *emaj_param*, il peut être souhaitable d'en conserver les valeurs, avec ::
+
+   SELECT emaj.emaj_export_parameters_configuration('<chemin.fichier>');
+
+Si la version E-Maj installée est antérieure à <devel>, on peut aussi exécuter ::
+
+   CREATE TABLE public.sav_param AS SELECT * FROM emaj.emaj_param WHERE param_key <> 'emaj_version';
+
 
 Suppression et réinstallation d'E-Maj
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -61,7 +65,7 @@ NB : à partir de la version 2.0.0, le script de désinstallation se nomme *ema
 Restauration des données utilisateurs
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Les données sauvegardées au préalable peuvent alors être restaurées dans les deux tables techniques d’E-Maj, par exemple avec des requêtes de type *INSERT SELECT*. ::
+Les données sauvegardées au préalable peuvent alors être restaurées dans les tables techniques d’E-Maj, par exemple avec des requêtes de type *INSERT SELECT*. ::
 
    INSERT INTO emaj.emaj_group_def
 		SELECT grpdef_group, grpdef_schema, grpdef_tblseq,
@@ -74,6 +78,10 @@ Les données sauvegardées au préalable peuvent alors être restaurées dans le
 
 Une fois les données copiées, les tables ou fichiers temporaires peuvent être supprimés.
 
+Si la configuration des paramètres a été exportée dans un fichier avec la fonction *emaj_export_parameters_configuration()*, cette configuration peut être rechargée par ::
+
+   SELECT emaj.emaj_import_parameters_configuration('<chemin.fichier>', TRUE);
+
 
 Mise à jour à partir d’une version E-Maj comprise entre 0.11.0 et 1.3.1
 -----------------------------------------------------------------------