17.7 Migration de modules

17.7.1 Scripts de pré-migration et de post-migration

Lors de la mise à jour d'un module, il est possible d'exécuter des scripts pour effectuer des opérations de migrations ou des traitements spécifiques.

Ces scripts de migration ne peuvent être utilisés que dans le cadre de mise à jours d'application.
Un module sans application ne peut pas utiliser cette mécanique de migration.

Deux types de scripts sont possibles :

• scripts de pré-migration (premigr) : les scripts de pré-migration (premigr) sont prévus pour être exécutés avant que l'application et les familles en base de données soient mis-à-jour,
• scripts de post-migration (postmigr) : les scripts de post-migration (postmigr) sont prévus pour être exécutés après que l'application et les familles en base de données aient été mis-à-jour.

Les scripts doivent être situés dans le sous-répertoire de l'application et leur nom doit être de la forme :

• scripts de pré-migration (premigr) : ${APPNAME}_premigr_${VERSION}
• scripts de post-migration (postmigr) : ${APPNAME}_postmigr_${VERSION}

Remarques :

• Le script peut être écrit dans n'importe quel langage que peut exécuter la plateforme hébergeant le contexte sur lequel il est exécuté. Toutefois, il ne doit pas avoir d'extension, il faut donc utiliser la notation shebang en première ligne de script pour indiquer le langage d'exécution,
• les scripts de migration sont exécutés sur les changements de VERSION sans tenir compte des RELEASE. On ne peut donc pas exécuter de script de migration lors d'un changement de RELEASE,
• les scripts de migration doivent être exécutables.

17.7.2 Exécution des scripts

Le lancement de ces scripts est commandé dans le fichier info.xml du module par l'utilisation d'une directive <process command="programs/(pre|post)_migration ${APPNAME}" /> dans la section <post-upgrade/>.

Exemple de déclaration type pour le lancement de scripts de pré-migration et de post-migration :

<module name="FOO" version="VERSION" release="1">
  ...
  <post-upgrade>
    <process command="programs/pre_migration FOO" />
    <process command="programs/record_application FOO" />
    <process command="programs/app_post FOO U" />
    <process command="programs/post_migration FOO" />
    <process command="programs/update_catalog" />
  </post-upgrade>
</module>

Les programmes pre_migration et post_migration exécutent tous les scripts de "premigr" ou "postmigr" dont la version est comprise entre la version de l'application actuellement installé, et la version de l'application mise-à-jour.

17.7.3 Variables d'environnement

Lorsque les scripts "premigr" et "postmigr" sont exécutés, les variables d'environnement suivantes sont disponibles :

17.7.4 Création de script PHP utilisant l'API de Dynacase

Les scripts de migrations doivent pouvoir être de bas niveau comme ceux présentés ci-dessus. Il s'exécute en ayant un minium de dépendances et permettent de faire des mise à jour sur des parties très bas niveau de Dynacase (base de données, mécanisme de persistances, etc.). Toutefois, dans le cas d'une application, il est souvent plus pratique d'utiliser les API de Dynacase soit via les scripts, soit via les applications actions.

Pour ce faire, vous pouvez utiliser l'exemple suivant :

 
#!/bin/bash
 
set -o errexit
set -o nounset
 
ME=$(basename "$0")
 
function wsh_api {
  logger -t "$ME" -- "BEGIN:$@"
  "$wpub/wsh.php" "$@"
  logger -t "$ME" -- "END:$@"
}
 
# Pour un script CLI
wsh_api --api=[NOM_DU_SCRIPT_CLI] --from="$MODULE_VERSION_FROM" --to="$MODULE_VERSION_TO"
 
# Pour une action
wsh_api --app=[NOM_APPLICATION] --action=[NOM_ACTION] --from="$MODULE_VERSION_FROM" --to="$MODULE_VERSION_TO"

Le code ci-dessus appelle une action ou un script cli en passant en paramètres entrant les numéros de version (le passage des numéros de version est facultatif).

Note : Pour comparer les numéros de version passés en paramètres, vous pouvez utiliser la fonction version_compare.

17.7.5 Comparaison de versions pour les scripts bash

Il peut être nécessaire, pour un script de migration, d'effectuer des opérations différentes en fonction de la version de départ du module. Pour cela, la variable d'environnement $MODULE_VERSION_FROM peut-être utilisée pour obtenir la version du module actuellement installé. Ensuite, pour comparer des versions représentés sous forme de chaîne de caractères, il vous faudra utiliser la fonction bash versionCompare déclarée dans le fichier bash $wpub/libutil.sh :

Syntaxe :

versionCompare $V1 $V2

La fonction prend deux arguments, qui sont les versions à comparer, et affiche sur STDOUT un entier : inférieur à 0 si $V1 est inférieur à $V2 supérieur à 0 si $V1 est supérieur à $V2 égal à 0 si $V1 est égal à $V2

Il faut ensuite utiliser les opérateurs de comparaison arithmétique ("-lt", "-gt", "-le", "-ge", "-eq", "-ne") de bash :

#!/bin/bash
 
. "$wpub/libutil.sh"
 
CMP=$(versionCompare "$MODULE_VERSION_FROM" "1.0.0")
if [ $CMP -lt 0 ]; then
  echo "La version de départ est inférieure à 1.0.0"
else
  echo "La version de départ est supérieure ou égale à 1.0.0"
fi