Package: db_migration
Cet outil permet de gérer les migrations d’une base de données. On doit
écrire les scripts de migration et les disposer dans des répertoires par
version et par plate-forme. Par exemple, pour migrer la PRP vers la
version 1.2.3, on placera le script dans le fichier1.2.3/prp.sql.Le script de migration maintient deux tables : -_scriptsliste les
scripts passés -_installliste les installations réalisées.Par conséquent, le script sait quels scripts doivent être passés pour
migrer vers la version cible et l’on n’a pas à connaître la version de
départ de la migration.Conventions de nommageLes données d’initialisation de la base de données se trouvent dans un
répertoire appeléinit. Dans ce répertoire doit se trouver un script
appeléall.sqlqui sera passé sur toutes les plateformes et qui
contiendra les schémas de la base de données. On pourra y placer des
scriptsitg.sql,prp.sqletprod.sqlpar exemple contenant
les données par environnement.Les scripts d’initialisation qui créent des tables doivent auparavent
les effacer avec une clauseDROP TABLE IF EXISTS. Par exemple, on
écrira pour créer la tableAureus_Creancier:DROPTABLEIFEXISTS`Aureus_Creancier`;CREATETABLEAureus_Creancier(idINT(10)NOTNULLDEFAULT'0',LibelleVARCHAR(20)NOTNULLDEFAULT'',id_telefactINT(10)DEFAULTNULL,sirenVARCHAR(15)DEFAULTNULL,PRIMARYKEY(id));Pour chaque évolution du schéma ou des données, on placera les scripts
dans le répertoire de la version (de la base de données ou du logiciel
si la base est liée à un logiciel spécifique). On placera dans ce
répertoire un scriptall.sqlpour les modifications de schéma ou des
données communes à toutes les plates-formes et des scriptsitg.sql,prp.sqletprod.sqlpour les données spécifiques aux
plates-formes.A noter qu’il n’est pas nécessaire de préciser la base de donnée
utilisée dans les scripts par une clause USE car la base de données
spécifiée dans le fichier de configuration est utilisée pour exécuter
les scripts.Les versions doivent être de la formeX.Y.Z(ou un sous ensembleX.YouX), où X, Y et Z sont des entiers, sans quoi le script de
migration ne peut les gérer.Fichier de configurationVoici un exemple de fichier de configuration :# encoding: UTF-8# platform listPLATFORMS=['itg','prp','prod']# default platformDEFAULT_PLATFORM=PLATFORMS[0]# platform where init is forbiddenCRITICAL_PLATFORMS=PLATFORMS[1:]# charset of the databaseCHARSET='utf8'# directory where live SQL scripts (None means directory of the script)SQL_DIR=None# Database configuration for environmentsCONFIGURATION={'itg':{'hostname':'localhost','database':'test','username':'test','password':'test',},'prp':{'hostname':'localhost','database':'test','username':'test','password':'test',},'prod':{'hostname':'localhost','database':'test','username':'test','password':'test',},}C’est un fichier Python qui comporte les propriétés de configuration
suivantes :PLATFORMS: la liste des plates-formes à gérer. Typiquement
‘itg’, ‘prp’ et ‘prod’. Les scripts de migration seront nommés en
conséquence.DEFAULT_PLATFORM: la plate-forme par défaut (celle qui est
utilisée lorsqu’aucune plate-forme n’est passée en ligne de
commande). L’expression ‘PLATFORMS[0]’ indique que l’on prend la
première plate-forme de la liste.CRITICAL_PLATFORMS: la liste des plates-formes sur lesquelles
l’option ‘-i’ qui réinitialise la base de données (et efface toutes
ses tables) est interdite. L’expression ‘PLATFORMS[1:]’ indique que
l’on prend toutes les plateformes sauf la première.CHARSET: le nom du jeu de caractères utilisé par la base de
données (‘utf8’ ou ‘latin1’).SQL_DIR: le répertoire des scripts SQL de migration. Si cette
valeur vaut None, alors les scripts sont cherchés dans le répertoire
du script de migration.CONFIGURATION: un dictionnaire par plate-forme indiquant pour
chacune : l’hôte de la base, le nom de la base de données, le nom de
l’utilisateur et son mot de passe.Les lignes de code à la fin du fichier ne servent qu’à afficher la
configuration de manière lisible pour le commun des mortels.Script de migrationLe répertoire sql contient le scripts de migration de base de données,db_migration.py, le fichier de configuration de la base de données,db_configuration.pyainsi que des scripts de migration d’exemple.
C’est typiquement le répertoire que l’on trouve dans un projet pour
gérer la migration de la base de données.Pour obtenir de l’aide sur le script, taper la ligne de commande
suivante :$./db_migration.py-hpythondb_migration.py[-h][-d][-i][-a][-l][-u][-ssql_dir][-cconfig][-pfichier][-mfrom]platform[version]-hPouraffichercettepaged'aide.
-d          Affiche les scripts a installer mais ne les execute pas.
-i          Initialisation de la base ATTENTION ! Efface toutes les donnees.
-a          Pour installer les scripts de toutes les versions du repertoire.
-l          Pour installer sur la base de donnees locale en mode test.
-u          Pour ne rien afficher sur la console (si tout se passe bien).
-s sql_dir  Le répertoire où se trouvent les fichiers SQL (répertoire du script
            par défaut).
-c config   Indique le fichier de configuration à utiliser (db_configuration.py
            dans le répertoire du script par défaut).
-m from     Ecrit le script de migration de la version 'from' vers 'version'
            sur la console. La valeur 'init' indique que tous les scripts de
            migration doivent être inclus.
platform    La plate-forme sur laquelle on doit installer (les valeurs
            possibles sont 'itg', 'prp' et 'prod'). La valeur par defaut est 'itg'.
version     La version a installer (la version de l'archivepardefaut).L’option-d(pour dry run) permet de lister les scripts qui
seront passés lors de la migration sans les exécuter réellement.L’option-iintialise la base de données, c’est à dire qu’elle
passe d’abord les scripts du répetoireinit. Les tables de la
base de donnée seront effacées. ATTENTION ! Cette commande peut être
dangereuse sur les plateformes de PRP ou PROD par exemple. Cependant,
cette option est refusée sur les plateformes listées dans la
propriétéCRITICAL_PLATFORMSde la configuration.L’option-apasse les scripts de migration pour toutes les
versions. On ne doit donc pas passer la version en paramètre avec
cette option.L’option-lpasse les scripts en local, c’est à dire sur la base
MySQL surlocalhostavec l’utilisateurtestet le mot de
passetest. Cet utlisateur et ce mot de passe sont disponibles
dans la configuration par défaut de MySQL. A noter que l’utilisateurtestdoit avoir les droits sur la base de donnée de la
configuration.L’option-upasse les scripts silencieusement (sauf en cas
d’erreur).L’option-ssql_dirindique où se trouvent les scripts de
migration SQL. Par défaut, les scripts sont cherchés dans le
répertoire du script de migration.L’option-mfrompermet de générer la requête SQL de migration de
la versionfromvers la versionversionpassée en ligne de
commande. A noter que cette option est incompatble avec les options-d,-let-p. Cette option est pratique pour mettre à
jour la base de donnée sur des plateformes où le script de migration
ne peut pas tourner. Cependant, les tables méta ne sont pas mises à
jour et l’on doit connaître la version depuis laquelle on migre la
base de données.Si un fichierVERSIONse trouve dans le répertoire du script, alors
la version vers laquelle on migrera la base est extraite de ce fichier.
Dans ce cas une extension-SNAPSHOTpeut se trouver à la fin de la
version et elle est ignorée lors des comparaisons.ExemplesPour migrer la base d’ITG vers la version 1.2.3 :./db_migration.pyitg1.2.3Pour afficher les scripts à passer pour migrer la base d’ITG vers la
version 1.2.3 sans les exécuter (dry run) :./db_migration.py-ditg1.2.3Pour intialiser la base de donnée et la migrer vers la version 1.2.3 :./db_migration.py-iitg1.2.3Pour migrer la base d’ITG vers la dernière version :./db_migration.py-aitgPour installer la base d’ITG en version 1.2.3 en local :./db_migration.py-litg1.2.3Pour générer le script de migration SQL de la base d’ITG de la version
1.0.0 vers la version 1.2.3 :./db_migration.py-m1.0.0itg1.2.3>migration-1.0.0-1.2.3.sqlInstallation du scriptPour installer le script dans votre projet, créer un répertoire dédié à
la base de donnée (par exemplesql) et y recopier le contenu du
répertoire sql (en particulier les scriptsdb_migration.pyetdb_configuration.py). On personalisera le fichier de configurationdb_configuration.py.Placer ensuite les scripts d’initialisation dans un répertoireinitet ceux de migration dans des répertoiresx.y.z. Le script de
migration cherche les répertoires des scripts de migration dans son
propre répertoire.On pourra alors livrer le script de migration (avec sa configuration et
les scripts SQL qui l’accompagnent) lors des releases. On peut même
automatiser la migration des bases à l’aide d’un script de post
installation appelant la procédure de migration que l’on aura packagée
dans l’archive.Pré-requis pour faire tourner le scriptPour faire tourner le script, on doit disposer des pré-requis suivants :Une version récente de python (le script a été testé avec des
versions 2.5.2, 2.6.6 et 2.7.2).La commande mysql doit être installée. Elle est utilisée pour
exécuter les scripts de migration.Si la plateforme ne dispose pas de ces pré-requis, il est toujours
possible de gérer les migrations en générant des scripts de migration
avec l’option-m(voir l’option dans la sectionScript de migrationci-dessus).Tables des méta donnéesLe script de migration gère deux tables de méta données dans la base :Table_scriptsElle contient les informations relatives au passage des scripts de
migration. Exemple d’une telle table :+--------------+---------------------+---------+------------+---------------+|filename|install_date|success|install_id|error_message|+--------------+---------------------+---------+------------+---------------+|init/all.sql|2012-04-1814:17:20|1|1|NULL||init/itg.sql|2012-04-1814:17:20|1|1|NULL||0.1/all.sql|2012-04-1814:17:20|1|1|NULL|+--------------+---------------------+---------+------------+---------------+Cette table liste les scripts passés (avec le chemin relatif au
répertoire du script) avec leur date d’installation, le succès et un
éventuel message d’erreur. De plus elle indique la référence de
l’installation correspondante dans la table_install.Table_installElle liste les migrations de la base :+----+---------+------------------+------------------+---------+|id|version|start_date|end_date|success|+----+---------+------------------+------------------+---------+|1|0.1|2012-04-1814...|2012-04-1814...|1||2|1.0|2012-04-1814...|2012-04-1814...|1|+----+---------+------------------+------------------+---------+La table liste les migrations avec leur version (sous la forme
‘major.minor. debug’), les dates de début et de fin de migration ainsi
que le succès de la migration.Comment créer les tables des méta données à la mainLes tables de méta données sont générées automatiquement à l’init
(option -i). Néanmoins, si vous devez les créer à la main, voici les
instructions :CREATETABLEIFNOTEXISTS_install(idintegerNOTNULLAUTO_INCREMENT,versionvarchar(20)NOTNULLCOMMENT'Numero de version de la base',start_datedatetimeNOTNULLCOMMENT'Date de debut d''installation',end_datedatetimeCOMMENT'Date de fin d''installation',successbooleanNOTNULLCOMMENT'Indicateur de succes de l''installation',PRIMARYKEY(id))ENGINE=InnoDBDEFAULTCHARSET=utf8COMMENT='Versionning de la base';CREATETABLEIFNOTEXISTS_scripts(filenamevarchar(255)NOTNULLCOMMENT'Nom du fichier SQL installe',install_datedatetimeNOTNULLCOMMENT'Date d''installation du script',successbooleanNOTNULLCOMMENT'Indicateur de succes de l''installation',install_idintegerNOTNULLCOMMENT'ID de l''installation en cours',error_messagetextCOMMENT'Error message, null if script was successful',CONSTRAINTfk_install_idFOREIGNKEY(install_id)REFERENCES_install(id))ENGINE=InnoDBDEFAULTCHARSET=utf8COMMENT='Historique de passage des scripts';TodoTest with Python 2.6Port to Python 3Port on PostgreSQL