Evolution BDD et migrations

[camillemonchicourt]

Jusqu'à présent à chaque évolution de la BDD de GeoNature, on écrit à la main des scripts SQL permettant de'appliquer manuellement les évolutions de la BDD entre chaque versions : https://github.com/PnX-SI/GeoNature/tree/master/data/migrations

Dans le cadre du workshop "Industrialisation" de février 2020, il a été envisagé d'automatiser les migrations de la BDD avec des solutions Python comme Flask-Migrate. Cependant la BDD de GeoNature est au coeur du projet et le pilote, et elle contient beaucoup de fonctions, de triggers et de vues qui ne sont pas migrables automatiquement. Même si cela n'est pas totalement incompatible, cette solution de Flask-Migrate a semblé peu adaptée et a été écartée.

Une solution maison a été mise en place pour gérer et automatiser l'application des mises à jour de la BDD, détaillée par @gildeluermoz :

Différents cas :

• La base n'est pas prête (prochaine version, la base n'aura pas la table gn_commons.t_migrations)
  

• La base est déjà à jour
  

• Une erreur se produit durant l'exécution d'un des scripts
  

• Tout se passe comme prévu
  

Un seul script pour le moment : install_db.sh. Je vais le renommer setup_db.sh car il gère install et migration)

Stratégie :

• Le script sera utilisable directement en sh ou avec le .deb
• Le mécanisme va lire en base le N° actuel de la base et va récupérer le N° cible en lisant les fichiers présents dans /geonature/data/migrations (sh) ou dans une arborescence /usr/share/geonature/geonature-db/sql/migrations/ (.deb)
• Il utilise en entrée un fichier de variables qui viennent soit de config/settings.ini (rétrocompatibilité) soit de /etc/geonature/geonature-db.conf pour le .deb. Les variables actuelles dans le settings.ini sont converties en variable d'environnement. Pour la création de la BDD, si aucun fichier de config n'est disponible le script prompt l'utilisateur.
• Il attend aussi la version des releases de UH, TH, GN et du sous module nomenclatures (NM ?) où se trouve les bons scripts SQL. Ces N° de versions ne sont plus des variables car la cohérence exige qu'elle soit fixée. Elles sont donc à définir en tant que constantes au début du script. Le script ira ensuite faire les wget qui vont bien pour récupérer ses petits dans les dépôts Github (release correspondante à la constante). Donc on garde la maintenance de ces scripts à un endroit unique dans chacun des dépôts UH, TH, GN, nomenclatures.
• Pour mettre tous les SQL dans un même répertoire accessible par le script, j'ai créé un répertoire "imported" dans le répertoire data du dépôt GeoNature. Ce travail d'import en wget reste à faire pour les scripts de migration UH, TH et nomenclature. Il nécessite une modification dans chacun des dépôts et donc potentiellement une release pour chacun.
• Le nommage des scripts SQL de migration changent. Il doivent désormais impérativement être nommés update_to_GN_xx.sql ou update_to_UH_xx.sql ou update_to_TH_xx.sql ou update_to_NM_xx.sql où xx est la version de la base. Si une migration nécessite d'appliquer par ex un script UH puis un script GN et que la base est par exemple en version 15, les scripts selon leur ordre d'exécution devront se nommer update_to_UH_15.sql et update_to_GN_16.sql. Pour le moment seul le N° est utilisé par le script de migration (le UH ou GN reste une convention de nommage). Par ailleurs les scripts SQL devront impérativement comporter un "INSERT INTO" vers la table gn_commons.t_migrations d'une ligne avec ce N° correspondant à la version de la base (N°= xx comme dans le nom du script).
• Le chemin d'installation du répertoire "geonature" est détecté par le script.

TODO

• Passer le chemin du fichier de config en paramètre du script.
• Tester avec de vrais scripts de migration
• Importer les scripts des dépôts dépendants (UH, TH, NM). Voir si besoin de modif selon l'arborescence des dépôts
• Utiliser tout ça avec le mécanisme .deb (ça devrait rouler pas mal)

Tout est actuellement dans la branche "deb_compat" du dépôt GeoNature (https://github.com/PnX-SI/GeoNature/commits/deb_compat).

[bouttier]

J’ai commencé à travailler sur la gestion des migrations avec Alembic (et Flask-Migrate pour l’intégration d’Alembic dans Flask).
L’idée est de garder les scripts SQL de GeoNature, mais de déléguer leur application à Alembic. Ainsi, on garde une grande souplesse toute en reposant sur un outil standard de référence pour la gestion des versions de la base de données.
Les différents modules devront être packagé, avec les fichiers SQL dans les data. Ces fichiers SQL pourront être chargé par les fichiers de migrations qui les trouverons aisément à l’aide de pkg_resources. D’autre part, le fichier de configuration Alembic de GeoNature indiquera les chemins (sous forme de nom de module) des migrations des modules requis (UsersHub, TaxHub, …) lui permettant ainsi de les trouver.
On gagnera également la gestion des dépendances entre les modules (création du schéma de nomenclature avant celui de taxhub par exemple).
De manière annexe, le packaging des modules est un pas vers une installation des modules GeoNature avec des outils standards.
Je vais commiter tout ceci prochainement dans des branches dédiées.

[jusana]

Hello à tous,
Super good news !
Si on peut avoir une gestion de dépendances sur pypi ça serait énorme !!
J'en profite aussi pour mentionner le fait que pour certains scripts SQL (notamment) il faut prévoir les éventuelles modifications faites en local (par ex "synthèse GN" VS "synthèse ginco")
merci !

[bouttier]

À priori pas de soucis pour faire des modifications :

• clone du repo (ou décompression d’une tarball)
• installation avec pip install --editable <path>
• modifications (python et/ou fichiers SQL)

[camillemonchicourt]

Oui, il faut aussi veiller à ce que chaque application tierce (UsersHub, TaxHub...) soit installable et puisse être mis à jour indépendamment, si ils sont utilisés sans GeoNature.
A différencier des modules de GeoNature (module import, module Export, Module Zones humides...) qui sont dépendants de GeoNature et peuvent avoir aussi leur propre schéma de BDD à installer ou mettre à jour.
Certains modules sont intégrés dans GeoNature, d'autres ont leur dépôt à part et peuvent être installés ou non.

Concernant les SQL de mises à jour, ils sont normalement tous génériques, les éventuelles adaptations spécifiques à chaque instance sont à gérer à part, après la mise à jour.
Le cas évoqué par @jusana est un cas particulier où un modèle d'import du module d'import a été renommé sur les instances GINCO, mais on aurait du gérer ça autrement.
Sinon comme indique @bouttier, dans des cas spécifiques et rares (qui ne devraient plus exister), reprendre localement et en amont le SQL avant de lancer la migration.

[bouttier]

Premier exemple d’utilisation de Flask-Migrate / Alembic pour UsersHub :

• https://github.com/PnX-SI/UsersHub/tree/alembic

• https://github.com/PnX-SI/UsersHub-authentication-module/tree/alembic

• Initialisation de Flask-Migrate dans server.py : migrate.init_app(app, db, directory='app/migrations')

• Dans la conf d’Alembic (app/migrations/alembic.ini) on indique de chercher les fichiers de migrations dans le module pypnusershub :
  version_locations = pypnusershub.migrations:versions

• On a un fichier de migrations a01a6dcce662_create_utilisateurs_schema.py

• Le script install_db.sh a été mis-à-jour pour utiliser Flask-Migrate :
  FLASK_APP=server:app flask db upgrade utilisateurs@head -x data=$insert_minimal_data -x sample-data=$insert_sample_data

Note : les fichiers SQL de création du schéma et d’insertion de données minimal / d’exemple ont été copié de UsersHub à UsersHub-authentication-module puisque c’est ce dernier module qui gère le schéma. La raison derrière cela est de permettre à d’autres applications telle que TaxHub qui dépendent du schéma utilisateurs de pouvoir créer ce dernier sans devoir installer UsersHub mais uniquement le module UsersHub-authentication-module (qui par ailleurs contient le models.py).

[bouttier]

Création des migrations pour TaxHub : 3bd7b0e031bb5a6960bdc0ce2fa59823b019be67

La migration c59c225e1c42 de TaxHub dépend du schéma utilisateurs : depends_on = ('utilisateurs',) (utilisateurs est ici le nom de la branche alembic des migrations de UsersHub-authentication-module).
Dans la conf alembic.ini de TaxHub, on a cette fois-ci :
version_locations = apptax.migrations:versions pypnusershub.migrations:versions
Ceci permet à Alembic de trouver les fichiers de migrations du schéma utilisateurs en plus des migrations TaxHub.

Il y a une petite astuce pour le mode « foreign » (schéma utilisateurs externe) : on saute la création du schéma utilisateurs et on indique à Alembic que la migration a bien été appliquée (/!\ pas encore testé).

[bouttier]

Créations des migrations pour :

• Nomenclature
• Habref
• GeoNature

GeoNature a un fichier de configuration Alembic allant chercher les migrations de tous les modules :
version_locations = geonature.migrations:versions apptax.migrations:versions pypnnomenclature.migrations:versions pypnusershub.migrations:versions pypn_habref_api.migrations:versions

Le fichier install_db.sh a été coupé en deux : create_db.sh + populate_db.sh.
Avant d’exécuter populate_db.sh, il faut installer le package geonature (pip install -e .).
Il reste encore un peu de travail :

• Reprendre les scripts d’installations pour arriver à ce processus :
  • Installation de GeoNature
  • Création de la base de données et de son schéma (nécessite que Flask-Migrate, GeoNature, … soit déjà installé)
  • Installation des modules GeoNature (nécessite que la base de données soit initialisée pour accéder à la table où sont enregistré les modules)
• Intégrer l’installation des données de sensibilité dans les migrations
• Documenter
• Tester !

[bouttier]

Intégration d’alembic à GeoNature sur la branche develop : a7cdeaf
Les schémas de GeoNature ne sont pas encore géré par alembic, il s’agit pour le moment uniquement :

• de rendre la commande flask db disponible
• d’auto-détecter les fichiers de migrations des modules (ces derniers les déclarant grâce à un entry point bien définie)

[bouttier]

Plusieurs avancées :

• Il est possible d’installer les grilles 1×1, 5×5, 10×10 ainsi que le référentiel des communes et celui des départements grâce à des branches alembic dédié, voir les fichiers de révision alembic ref_geo_* ici : https://github.com/PnX-SI/GeoNature/tree/develop/backend/geonature/migrations/versions
• La révision f06cc80cc8ba symbolise le schéma 2.7.5 de GeoNature. Cette révision ne permet pas encore d’installer le schéma de base de données avec alembic, mais il permet d’indiquer à alembic que l’on possède une base de données GeoNature version 2.7.5.
• Les évolutions du schéma de base de données doivent, à partir de la 2.7.5, passer par une révision alembic.
• Au schéma taxonomie version 1.8.1 correspond la révision 9c2c0254aadc (fournie par le paquet TaxHub, non fonctionnelle)
  Les évolutions future du schéma taxonomie doivent donc être faites via alembic. TaxHub a été mis-à-jour afin de pouvoir utiliser alembic via flask db dans le cadre d’une installation sans GeoNature.
• Au schéma utilisateurs version 1.4.7 correspond la révision fa35dfe5ff27 (fournie par paquet UsersHub-authentication-module)
  Cette dernière révision est fonctionnelle, et permet d’installer le schéma utilisateurs via alembic. De ce fait, les fichiers SQL liés au schéma utilisateurs sont désormais dans le dépôt UsersHub-authentication-module et non plus dans le dépôt UsersHub.
  Le processus de mise-à-jour de UsersHub a été simplifié pour installer le schéma utilisateurs via alembic (UsersHub permet également d’utiliser alembic via flask db).
  Remarque : l’installation des données d’exemples est optionnel grâce aux branches alembic.

Pour plus d’informations sur l’utilisation d’alembic, voir la documentation de GeoNature qui a été mise-à-jour en conséquence.

Je mettrais très prochainement le processus d’installation de GeoNature à jour pour ne plus installer le schéma utilisateurs manuellement, mais via alembic.

La prochaine étape sera l’installation du schéma taxonomie par alembic (cela veut dire rendre la révision 9c2c0254aadc fonctionnelle).

[camillemonchicourt]

Mis en place dans la 2.8.0.
Documenté ici : http://docs.geonature.fr/admin-manual.html#administration-avec-alembic

Cela va permettre de simplifier la gestion et l'application des évolutions de la BDD.

Pour les schémas, tables et vues custom, voir #1499

Reste une discussion/réflexion en cours sur le fait que c'est désormais GeoNature qui se charge de lancer les évolutions des schémas taxonomie et utilisateurs pilotés par TaxHub et UsersHub.