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)`