+
−Migration
+
−=========
+
−
+
−Une des id�es de base d'CubicWeb est la cr�ation incr�mentale d'application, et
+
−pour cela de nombreuses actions sont fournies afin de facilement faire �voluer
+
−une application et tout particuli�rement le mod�le de donn�es manipul� sans
+
−perdre les donn�es des instances existantes.
+
−
+
−La version courante d'un mod�le d'application est donn�es dans le fichier
+
−`__pkginfo__.py` sous forme d'un tuple de 3 entiers.
+
−
+
−
+
−Gestion des scripts de migrations
+
−---------------------------------
+
−Les scripts des migrations doivent �tre plac�s dans le r�pertoire `migration` de
+
−l'application, et nomm� de la mani�re suivante :
+
−
+
−  <n� de version X.Y.Z>[_<description>]_<mode>.py
+
−
+
−dans lequel : 
+
−
+
−* X.Y.Z correspond au n� de version du mod�le vers lequel le script permet de
+
−  migrer,
+
−
+
−* le *mode* (entre le dernier "_" et l'extension ".py") indique � quelle partie
+
−  de l'application (serveur RQL, serveur web) le script s'applique en cas
+
−  d'installation distribu�e. Il peut valoir : 
+
−
+
−  * `common`, s'applique aussi bien sur le serveur RQL que sur le serveur web,
+
−    et met � jour des fichiers sur le disque (migration de fichier de
+
−    configuration par exemple).
+
−
+
−  * `web`, s'applique uniquement sur le serveur web, et met � jour des fichiers
+
−    sur le disque 
+
−
+
−  * `repository`, s'applique uniquement sur le serveur RQL, et met � jour des
+
−    fichiers sur le disque 
+
−
+
−  * `Any`, s'applique uniquement sur le serveur RQL, et met � jour des
+
−    donn�es en base (migrations de sch�ma et de donn�es par ex.)
+
−
+
−
+
−Toujours dans le r�pertoire `migration`, le fichier sp�cial `depends.map` permet
+
−d'indiquer que pour migrer vers une version sp�cifique du mod�le, il faut tout
+
−d'abord avoir migrer vers une version donn�es de cubicweb. Ce fichier peut contenir
+
−des commentaires (lignes commen�ant par un "#"), et une d�pendance est not�e sur
+
−une ligne de la mani�re suivante : ::
+
−
+
−  <n� de version du mod�le X.Y.Z> : <n� de version cubicweb X.Y.Z>
+
−
+
−Par exemple ::
+
−
+
−  0.12.0: 2.26.0
+
−  0.13.0: 2.27.0
+
−  # 0.14 works with 2.27 <= cubicweb <= 2.28 at least
+
−  0.15.0: 2.28.0
+
−
+
−
+
−Contexte de base
+
−----------------
+
−Les identifiants suivants sont pr�f�finis dans les scripts de migration : 
+
−
+
−* `config`, configuration de l'instance
+
−
+
−* `interactive_mode`, bool�en indiquant si le script est �x�cut� en mode
+
−  interactif ou non
+
−
+
−* `appltemplversion`, version du mod�le d'application de l'instance
+
−
+
−* `applcubicwebversion`, version cubicweb de l'instance
+
−
+
−* `templversion`, version du mod�le d'application install�e
+
−
+
−* `cubicwebversion`, version cubicweb install�e
+
−
+
−* `confirm(question)`, fonction posant une question et retournant vrai si
+
−  l'utilisateur a r�pondu oui, faux sinon (retourne toujours vrai en mode non
+
−  interactif) 
+
−
+
−* `_`, fonction �quivalente � `unicode` permettant de marquer des chaines �
+
−  internationaliser dans les scripts de migration
+
−
+
−Dans les scripts "repository", les identifiants suivant sont �galement d�finis :
+
−
+
−* `checkpoint`, demande confirmant et effectue un "commit" au point d'appel
+
−
+
−* `repo_schema`, sch�ma persistent de l'instance (i.e. sch�ma de l'instance en
+
−  cours de migration)
+
−
+
−* `newschema`, sch�ma install� sur le syst�me de fichier (i.e. sch�ma de la
+
−  version � jour du mod�le et de cubicweb)
+
−
+
−* `sqlcursor`, un curseur SQL pour les tr�s rares cas o� il est r�ellement
+
−  n�cessaire ou avantageux de passer par du sql
+
−
+
−* `repo`, l'objet repository
+
−
+
−                        
+
−Migration de sch�ma
+
−-------------------
+
−Les fonctions de migration de sch�ma suivantes sont disponibles dans les scripts
+
−"repository" : 
+
−
+
−* `add_attribute(etype, attrname, attrtype=None, commit=True)`, ajoute un
+
−  nouvel attribut � un type d'entit� existante. Si le type de celui-ci n'est pas
+
−  sp�cifi� il est extrait du sch�ma � jour.
+
−        
+
−* `drop_attribute(etype, attrname, commit=True)`, supprime un
+
−  attribut � un type d'entit� existante.
+
−
+
−* `rename_attribute(etype, oldname, newname, commit=True)`, renomme un attribut
+
−            
+
−* `add_entity_type(etype, auto=True, commit=True)`, ajoute un nouveau type
+
−  d'entit�. Si `auto` est vrai, toutes les relations utilisant ce type d'entit�
+
−  et ayant un type d'entit� connu � l'autre extr�mit� vont �galement �tre
+
−  ajout�es.
+
−
+
−* `drop_entity_type(etype, commit=True)`, supprime un type d'entit� et toutes
+
−  les relations l'utilisant.
+
−
+
−* `rename_entity_type(oldname, newname, commit=True)`, renomme un type d'entit�
+
−            
+
−* `add_relation_type(rtype, addrdef=True, commit=True)`, ajoute un nouveau type
+
−  de relation. Si `addrdef` est vrai, toutes les d�finitions de relation de ce
+
−  type seront �galement ajout�es.
+
−
+
−* `drop_relation_type(rtype, commit=True)`, supprime un type de relation et
+
−  toutes les d�finitions de ce type.
+
−
+
−* `rename_relation(oldname, newname, commit=True)`, renomme une relation.
+
−
+
−* `add_relation_definition(subjtype, rtype, objtype, commit=True)`, ajoute une
+
−  d�finition de relation.
+
−
+
−* `drop_relation_definition(subjtype, rtype, objtype, commit=True)`, supprime
+
−  une d�finition de relation.
+
−
+
−* `synchronize_permissions(ertype, commit=True)`, synchronise les permissions
+
−  d'un type d'entit� ou de relation
+
−        
+
−* `synchronize_rschema(rtype, commit=True)`, synchronise les propri�t�s et
+
−  permissions d'un type de relation.
+
−                
+
−* `synchronize_eschema(etype, commit=True)`, synchronise les propri�t�s et
+
−  permissions d'un type d'entit�.
+
−    
+
−* `synchronize_schema(commit=True)`, synchronise le sch�ma persistent avec le
+
−  sch�ma � jour (mais sans ajouter ni supprimer de nouveaux types d'entit�s ou
+
−  de relations ni de d�finitions de relation).
+
−        
+
−* `change_relation_props(subjtype, rtype, objtype, commit=True, **kwargs)`, change
+
−  les propri�t�s d'une definition de relation en utilisant les arguments nomm�s
+
−  pour les propri�t�s � changer.
+
−
+
−* `set_widget(etype, rtype, widget, commit=True)`, change le widget � utiliser
+
−  pour la relation <rtype> du type d'entit� <etype>
+
−
+
−* `set_size_constraint(etype, rtype, size, commit=True)`, change la contrainte
+
−  de taille pour la relation <rtype> du type d'entit� <etype>
+
−
+
−
+
−Migration de donn�es
+
−--------------------
+
−Les fonctions de migration de donn�es suivantes sont disponibles dans les scripts
+
−"repository" : 
+
−
+
−* `rqlexec(rql, kwargs=None, cachekey=None, ask_confirm=True)`, �x�cute une
+
−  requ�te rql arbitraire, d'interrogation ou de modification. Un objet result
+
−  set est retourn�.
+
−
+
−* `rqlexecall(rqliter, cachekey=None, ask_confirm=True)`, �x�cute une s�rie
+
−  de requ�tes rql arbitraires, d'interrogation ou de modification. rqliter est
+
−  un it�rateur retournant des couples (rql, kwargs). Le result set de la
+
−  derni�re requ�te �x�cut�e est retourn�.
+
−
+
−* `add_entity(etype, *args, **kwargs)`, ajoute une nouvelle entit� du type
+
−  donn�es. La valeur des attributs et relations est sp�cifi�e en utilisant les
+
−  arguments nomm�s et positionnels.
+
−
+
−  
+
−Cr�ation de workflow
+
−--------------------
+
−Les fonctions de cr�ation de workflow suivantes sont disponibles dans les scripts
+
−"repository" : 
+
−
+
−* `add_state(name, stateof, initial=False, commit=False, **kwargs)`, ajoute un
+
−  nouvel �tat de workflow
+
−    
+
−* `add_transition(name, transitionof, fromstates, tostate, requiredgroups=(), commit=False, **kwargs)`, 
+
−  ajoute une nouvelle transtion de workflow
+
−
+
−Migration de configuration
+
−--------------------------
+
−Les fonctions de migration de configuration suivantes sont disponibles dans tout
+
−les scripts : 
+
−
+
−* `option_renamed(oldname, newname)`, indique qu'une option a �t� renomm�e
+
−
+
−* `option_group_change(option, oldgroup, newgroup)`, indique qu'une option a
+
−  chang� de groupe
+
−
+
−* `option_added(oldname, newname)`, indique qu'une option a �t� ajout�e
+
−
+
−* `option_removed(oldname, newname)`, indique qu'une option a �t� supprim�e
+
−
+
−
+
−Autres fonctions de migration
+
−-----------------------------
+
−Ces fonctions ne sont utilis�s que pour des op�rations de bas niveau
+
−irr�alisables autrement ou pour r�parer des bases cass�es lors de session
+
−interactive. Elles sont disponibles dans les scripts "repository".
+
−
+
−* `sqlexec(sql, args=None, ask_confirm=True)`, �x�cute une requ�te sql
+
−  arbitraire, � n'utiliser 
+
−
+
−* `add_entity_type_table(etype, commit=True)`
+
−* `add_relation_type_table(rtype, commit=True)`
+
−* `uninline_relation(rtype, commit=True)`