Installation de l'extension [ASGARD]

Installation de l'extension

Compatibilité
Livrables
Où trouver les fichiers ?
Préparation de l'installation
- Serveur Eole/PostgreSQL
- Autres serveurs
Activation de l'extension sur une base
Initialisation de la table de gestion

Compatibilité⚓

Chaque nouvelle version d’ASGARD fait a minima l’objet d’une recette approfondie sur toutes les versions de PostgreSQL officiellement diffusées au moment de sa préparation.

	PostgreSQL 9.5	PostgreSQL 10	PostgreSQL 11	PostgreSQL 12	PostgreSQL 13	PostgreSQL 14	PostgreSQL 15
ASGARD 1.2.0	X	X	X	X	X
ASGARD 1.2.2	X	X	X	X	X
ASGARD 1.2.3	X	X	X	X	X
ASGARD 1.2.4	X	X	X	X	X
ASGARD 1.3.0	X	X	X	X	X
ASGARD 1.3.1	X	X	X	X	X
ASGARD 1.3.2	X	X	X	X	X	X
ASGARD 1.4.0	X	X	X	X	X	X	X

Complément : Objets non pris en charge avant la version 1.4.0 ⚓

Les versions 1.2 et 1.3 de l'extension PostgreSQL ASGARD ne prenaient pas en charge les objets statistiques étendus (extended statistics), les classes d’opérateurs (operator class) et les familles d’opérateurs (operator family).

PostgreSQL ne prévoit pas l'attribution de privilèges sur ces objets, mais la cohérence de leur propriétaire avec celui du schéma qui les contient n’était pas contrôlée en cas de modification du propriétaire de l’objet et/ou de producteur du schéma. Ils étaient toutefois considérés par la fonction de diagnostic, qui alertait en cas d'incohérence entre leur propriétaire et le producteur du schéma.

À compter d'ASGARD 1.4, tous les objets supportés par les versions compatibles de PostgreSQL qui sont rattachés à un schéma (au contraire, par exemple, des serveurs distants) et ont au moins un propriétaire paramétrable (au contraire, par exemple, des analyseurs et modèles de recherche plein texte, sur lesquels ASGARD n'aurait rien à faire) sont pris en charge.

Attention :

PostgreSQL 9.5 n'est plus maintenue par PostgreSQL et n'est plus prise en charge par les dernières versions de pgAdmin.

Sa prise en charge par ASGARD est désormais en sursis.

Des adaptations notables ont déjà dû être réalisées pour assurer la compatibilité d'ASGARD avec cette version. Il est vraisemblable que, si une telle situation se reproduit, les prochaines versions d'ASGARD renonceront à la compatibilité avec PostgreSQL 9.5 plutôt que de complexifier le code de l'extension.

Livrables⚓

ASGARD est fourni sous la forme d’une extension pour PostgreSQL, soit deux fichiers :

un script : asgard--x.x.x.sql (« x.x.x » étant le numéro de version) ;
un fichier de définition des paramètres de l’extension : asgard.control.

Où trouver les fichiers ?⚓

L’extension PostgreSQL ASGARD (© République Française, 2020-2021) est publiée sur le site intranet Géoinformations et sur GitHub sous licence CeCILL-B.

Complément : Pour télécharger la dernière version sur le GitHub ⚓

Dans le bandeau de droite sur la page d'accueil du dépôt, l'onglet Release met en raccourci un accès à la page de téléchargement de la dernière version publiée.

Préparation de l'installation⚓

Serveur Eole/PostgreSQL⚓

Si le serveur PostgreSQL s’inscrit dans le cadre de l’offre Eole/PostgreSQL du pôle interministériel MTE-MCTRC-Mer, alors l’administrateur de données n’a rien de particulier à faire. Les nouvelles versions de l’extension sont mises à disposition automatiquement sur les serveurs Eole (synchronisation quotidienne, cf. Configuration dans l'interface Zephir des serveurs Eole pour plus de détails).

On pourra donc se reporter directement au point Activation de l'extension sur une base pour la suite de la procédure.

Complément : Plus d'informations sur l’offre Eole/PostgreSQL ⚓

Description de l’offre EOLE/PostgreSQL sur Géoinformations (intranet) ou sur SPOTE.

Autres serveurs⚓

Les fichiers asgard--x.x.x.sql et asgard.control doivent être copiés dans le répertoire des extensions du serveur PostgreSQL.

Exemple : Pour PostgreSQL 10 sous Windows :⚓

C:\Program Files\PostgreSQL\10\share\extension

Exemple : Pour une installation PostgreSQL 10 sous Linux, on aura plutôt :⚓

/usr/share/postgresql/10/extension

Activation de l'extension sur une base⚓

Remarque :

Si le serveur PostgreSQL compte plusieurs bases, on répétera l’opération d'activation pour toutes les bases dont on souhaite gérer les droits avec ASGARD. La table de gestion^[1] d’ASGARD est monobase : pour chaque base, elle ne montre que les schémas de la base courante.

Pour activer ASGARD dans une base de données, un super-utilisateur^[2] doit lancer la commande SQL de création de l’extension :

CREATE EXTENSION asgard ;

CREATE EXTENSION asgard ;

Si, comme ci-avant, aucun numéro de version n’est précisé, c’est la version « par défaut » spécifiée par l’extension elle-même qui sera installée.

Complément : Précisions sur la version de référence ⚓

La version de référence est définie dans le fichier asgard.control, par le paramètre default_version.

# extension asgard
default_version = '1.2.2'
comment = 'ASGARD. Gestion des droits pour PostgreSQL.'
superuser = true
encoding = 'UTF8'
requires = 'plpgsql'
relocatable = false

# extension asgard
default_version = '1.2.2'
comment = 'ASGARD. Gestion des droits pour PostgreSQL.'
superuser = true
encoding = 'UTF8'
requires = 'plpgsql'
relocatable = false

Depuis pgAdmin, elle peut être consultée avec la commande suivante (champ default_version) :

SELECT * FROM pg_available_extensions WHERE name = 'asgard' ;

SELECT * FROM pg_available_extensions WHERE name = 'asgard' ;

Pour installer une version spécifique, il faut l’ajouter avec une clause VERSION. Il est toutefois recommandé d’utiliser la version par défaut – cf. Sauvegarde et restauration de la base pour plus d’explications.

Exemple :

Pour installer la version 0.6.1, antérieure à la version de référence :

CREATE EXTENSION asgard VERSION '0.6.1' ;

Il est possible d’obtenir la liste des versions disponibles pour l’installation avec la commande SQL suivante (ou en regardant les fichiers présents dans le répertoire des extensions) :

SELECT * FROM pg_available_extension_versions WHERE name = 'asgard' ;

La version effectivement installée est indiquée dans cette liste et peut par ailleurs être consultée via :

SELECT * FROM pg_available_extensions WHERE name = 'asgard' ;

… ou encore, via pgAdmin, dans les propriétés de l’extension :

pgAdmin permet également d'installer l'extension, en choisissant la version s'il y a lieu, à partir d'un menu.

Complément : Installation avec pgAdmin ⚓

Dans l'arborescence des objets de la base, clic droit sur le menu `Extensions`, puis `Créer > Extension...`

Dans l'onglet `Général`, champ `Nom`, choisir « asgard » dans la liste des extensions disponibles.

Si la version par défaut ne convient pas, dans l'onglet `Définition`, champ `Version`, il est possible de spécifier une version à installer.

Initialisation de la table de gestion⚓

À l’installation, la table de gestion^[1] d’ASGARD ne contient aucun schéma.

Reprise de l'existant⚓

Si ASGARD est installé dans une base de données contenant déjà des schémas, il est possible d’intégrer les schémas souhaités dans la gestion d’ASGARD :

en masse, par la fonction asgard_initialisation_gestion_schema (schéma z_asgard_admin), qui enregistre dans la table de gestion tous les schémas existants hors schémas système et hors une éventuelle liste d’exceptions fournie en argument de la fonction ;
un par un, avec la fonction asgard_initialise_schema (schéma z_asgard).

On se reportera aux descriptifs de ces fonctions pour de plus amples précisions sur leurs modalités d'utilisation.

Dans la grande majorité des cas, asgard_initialisation_gestion_schema pourra être lancée sans risque sur l’ensemble des schémas et il est recommandé de le faire. Son seul effet concret, au-delà de l’enregistrement dans la table de gestion^[1], est d’attribuer au propriétaire du schéma la propriété de tous les objets qui s’y trouvent, s’il n’en disposait pas déjà.

Conseil :

Après l’installation d’ASGARD, utiliser la fonction asgard_initialisation_gestion_schema pour initialiser sa table de gestion.

Remarque :

L'initialisation peut échouer si l'administrateur ne dispose pas des droits nécessaires sur certains schémas.

En particulier, si certains schémas (ou des objets qu’ils contiennent) ont comme propriétaire un super-utilisateur^[2], il sera nécessaire de lancer la fonction avec ledit super-utilisateur pour les référencer, ou de les exclure (temporairement) du référencement grâce à la liste d’exceptions.

Exemple :

L'administrateur, connecté avec un rôle non super-utilisateur membre de g_admin^[3], tente de référencer le schéma c_librairie, propriété du super-utilisateur postgres.

La fonction asgard_initialise_schema lui renvoie une erreur telle que :

ERREUR : ERREUR:  FIS0 > FIS3. Echec. Vous ne disposez pas des permissions nécessaires sur le schéma c_librairie pour réaliser cette opération.
DETAIL:  
HINT:  Il vous faut être membre du rôle propriétaire postgres.

ERREUR : ERREUR:  FIS0 > FIS3. Echec. Vous ne disposez pas des permissions nécessaires sur le schéma c_librairie pour réaliser cette opération.
DETAIL:  
HINT:  Il vous faut être membre du rôle propriétaire postgres.

Avec asgard_initialisation_gestion_schema, il verra :

ERREUR : ERREUR:  FIG0 > TB25. Opération interdite (schéma c_librairie).
DETAIL:  Seul le super-utilisateur postgres peut référencer dans ASGARD un schéma dont il est identifié comme producteur.
HINT:  

ERREUR : ERREUR:  FIG0 > TB25. Opération interdite (schéma c_librairie).
DETAIL:  Seul le super-utilisateur postgres peut référencer dans ASGARD un schéma dont il est identifié comme producteur.
HINT:

D'une manière générale, asgard_initialisation_gestion_schema (utilisable uniquement par un membre de g_admin ou un super-utilisateur) est plus puissante qu'asgard_initialise_schema. En particulier, elle saura prendre en charge les schémas dont le propriétaire n'est pas un super-utilisateur, mais seulement un rôle de groupe^[4] dont g_admin n'est pas (encore) membre.

Ainsi, en cas d'erreur avec asgard_initialise_schema, on pourra :

si c'est possible, utiliser asgard_initialisation_gestion_schema au lieu d'asgard_initialise_schema. Lorsqu'il ne l'était pas déjà, elle rendra automatiquement g_admin membre des rôles propriétaires des schémas (producteurs^[5], au sens d'ASGARD), ainsi que prévu par ASGARD pour tous les producteurs ;
lancer la fonction asgard_initialise_schema avec un super-utilisateur. Là aussi, l'un des effets du référencement sera de rendre g_admin membre du producteur du schéma ;
rendre manuellement g_admin membre du rôle propriétaire en question avant de lancer la fonction asgard_initialise_schema.

Complément : Comment rendre manuellement `g_admin` membre d'un rôle de groupe ?⚓

On suppose que l'administrateur est connecté avec un rôle membre de g_admin, comme prévu par ASGARD.

Si son rôle de connexion dispose en lui-même de l'attribut CREATEROLE, il peut simplement lancer une commande GRANT :

GRANT %g_role_proprietaire TO g_admin ;

GRANT %g_role_proprietaire TO g_admin ;

Sinon, il doit endosser le rôle g_admin avant d'exécuter la commande :

SET ROLE g_admin ;
GRANT %g_role_proprietaire TO g_admin ;

SET ROLE g_admin ;
GRANT %g_role_proprietaire TO g_admin ;

Attention : ASGARD déteste les rôles de connexion...⚓

... lorsqu'ils sont propriétaires de schémas.

Toute tentative d'intégration à ASGARD d'un schéma dont le propriétaire est un rôle de connexion^[6] contrevient à une règle fondamentale d'ASGARD et, par conséquent, est vouée à l'échec.

Exemple :

Le rôle de connexion jon.snow a été désigné (avant l'installation d'ASGARD) comme propriétaire du schéma c_bibliotheque.

Si l'administrateur tente de référencer ce schéma :

SELECT z_asgard.asgard_initialise_schema('c_bibliotheque') ;

ASGARD lui retourne le message d'erreur suivant :

ERREUR : ERREUR:  FIS0 > TA0 > TA3. Opération interdite (schéma c_bibliotheque). Le producteur/propriétaire du schéma ne doit pas être un rôle de connexion.
DETAIL:  
HINT:  

ERREUR : ERREUR:  FIS0 > TA0 > TA3. Opération interdite (schéma c_bibliotheque). Le producteur/propriétaire du schéma ne doit pas être un rôle de connexion.
DETAIL:  
HINT:

Dans cette situation, il n'y a que deux alternatives :

changer le propriétaire du schéma avant le référencement (en désignant un rôle de groupe) ;
à défaut, exclure le schéma du référencement et donc du système de gestion des droits d'ASGARD.

Nettoyage des droits⚓

À l’issue du référencement, on souhaitera souvent remettre en ordre les droits, si ce n’est tout remettre à plat pour repartir à zéro avec le système producteur^[5]/éditeur^[7]/lecteur^[8] d’ASGARD. Ce sujet est traité dans la partie Nettoyage des droits et résolution des problèmes.

Import de la nomenclature⚓

Par ailleurs, ASGARD permet d’importer tout ou partie de la nomenclature nationale^[9] dans la table de gestion^[1], sous la forme de schémas pré-référencés^[10] qui pourront ensuite être créés. L’import se fait avec la fonction asgard_import_nomenclature.

Remarque :

Si ASGARD est installé dans une base déjà peuplée et que le service entend normaliser le nom de ses schémas selon la nomenclature nationale, il est recommandé de procéder à ces corrections avant d’initialiser la table de gestion avec la fonction asgard_initialisation_gestion_schema. L’opération sera alors moins fastidieuse.

Exemple :

Intégration d’un schéma transport_ferroviaire qui, d’après la nomenclature, aurait vocation à s’appeler c_tr_infra_ferroviaire.

Si le nom du schéma est modifié en préalable, trois commandes simples amènent au résultat attendu :

-- import de la nomenclature :
SELECT z_asgard_admin.asgard_import_nomenclature() ;
-- changement de nom :
ALTER SCHEMA transport_ferroviaire
    RENAME TO c_tr_infra_ferroviaire ;
-- enregistrement dans la table de gestion :
SELECT z_asgard.asgard_initialise_schema('c_tr_infra_ferroviaire') ;

-- import de la nomenclature :
SELECT z_asgard_admin.asgard_import_nomenclature() ;

-- changement de nom :
ALTER SCHEMA transport_ferroviaire
    RENAME TO c_tr_infra_ferroviaire ;

-- enregistrement dans la table de gestion :
SELECT z_asgard.asgard_initialise_schema('c_tr_infra_ferroviaire') ;

Alors que si le schéma avait été intégré d’abord, il aurait fallu cinq commandes pour arriver au même résultat :

-- import de la nomenclature :
SELECT z_asgard_admin.asgard_import_nomenclature() ;
-- enregistrement du schéma dans la table de gestion :
SELECT z_asgard.asgard_initialise_schema('transport_ferroviaire') ;

-- import de la nomenclature :
SELECT z_asgard_admin.asgard_import_nomenclature() ;

-- enregistrement du schéma dans la table de gestion :
SELECT z_asgard.asgard_initialise_schema('transport_ferroviaire') ;

-- copie des données :
UPDATE z_asgard.gestion_schema_usr
    SET (niv1, niv1_abr, niv2, niv2_abr, nomenclature, lecteur) = (
        SELECT
             a.niv1,
             a.niv1_abr,
             a.niv2,
             a.niv2_abr,
             a.nomenclature,
             a.lecteur
             FROM z_asgard.gestion_schema_usr AS a
             WHERE a.nom_schema = 'c_tr_infra_ferroviaire'
        )
    WHERE nom_schema = 'transport_ferroviaire' ;
-- sortie de c_tr_infra_ferroviaire de la nomenclature
-- (nécessaire pour pouvoir le supprimer) :
UPDATE z_asgard.gestion_schema_usr
    SET nomenclature = False
    WHERE nom_schema = 'c_tr_infra_ferroviaire' ;
-- suppression :
DELETE FROM z_asgard.gestion_schema_usr
    WHERE nom_schema = 'c_tr_infra_ferroviaire' ;
-- changement de nom :
ALTER SCHEMA transport_ferroviaire
    RENAME TO c_tr_infra_ferroviaire ;

-- copie des données :
UPDATE z_asgard.gestion_schema_usr
    SET (niv1, niv1_abr, niv2, niv2_abr, nomenclature, lecteur) = (
        SELECT
             a.niv1,
             a.niv1_abr,
             a.niv2,
             a.niv2_abr,
             a.nomenclature,
             a.lecteur
             FROM z_asgard.gestion_schema_usr AS a
             WHERE a.nom_schema = 'c_tr_infra_ferroviaire'
        )
    WHERE nom_schema = 'transport_ferroviaire' ;

-- sortie de c_tr_infra_ferroviaire de la nomenclature
-- (nécessaire pour pouvoir le supprimer) :
UPDATE z_asgard.gestion_schema_usr
    SET nomenclature = False
    WHERE nom_schema = 'c_tr_infra_ferroviaire' ;

-- suppression :
DELETE FROM z_asgard.gestion_schema_usr
    WHERE nom_schema = 'c_tr_infra_ferroviaire' ;

-- changement de nom :
ALTER SCHEMA transport_ferroviaire
    RENAME TO c_tr_infra_ferroviaire ;