|
1 Migration |
|
2 ========= |
|
3 |
|
4 Une des idées de base d'CubicWeb est la création incrémentale d'application, et |
|
5 pour cela de nombreuses actions sont fournies afin de facilement faire évoluer |
|
6 une application et tout particulièrement le modèle de données manipulé sans |
|
7 perdre les données des instances existantes. |
|
8 |
|
9 La version courante d'un modèle d'application est données dans le fichier |
|
10 `__pkginfo__.py` sous forme d'un tuple de 3 entiers. |
|
11 |
|
12 |
|
13 Gestion des scripts de migrations |
|
14 --------------------------------- |
|
15 Les scripts des migrations doivent être placés dans le répertoire `migration` de |
|
16 l'application, et nommé de la manière suivante : |
|
17 |
|
18 <n° de version X.Y.Z>[_<description>]_<mode>.py |
|
19 |
|
20 dans lequel : |
|
21 |
|
22 * X.Y.Z correspond au n° de version du modèle vers lequel le script permet de |
|
23 migrer, |
|
24 |
|
25 * le *mode* (entre le dernier "_" et l'extension ".py") indique à quelle partie |
|
26 de l'application (serveur RQL, serveur web) le script s'applique en cas |
|
27 d'installation distribuée. Il peut valoir : |
|
28 |
|
29 * `common`, s'applique aussi bien sur le serveur RQL que sur le serveur web, |
|
30 et met à jour des fichiers sur le disque (migration de fichier de |
|
31 configuration par exemple). |
|
32 |
|
33 * `web`, s'applique uniquement sur le serveur web, et met à jour des fichiers |
|
34 sur le disque |
|
35 |
|
36 * `repository`, s'applique uniquement sur le serveur RQL, et met à jour des |
|
37 fichiers sur le disque |
|
38 |
|
39 * `Any`, s'applique uniquement sur le serveur RQL, et met à jour des |
|
40 données en base (migrations de schéma et de données par ex.) |
|
41 |
|
42 |
|
43 Toujours dans le répertoire `migration`, le fichier spécial `depends.map` permet |
|
44 d'indiquer que pour migrer vers une version spécifique du modèle, il faut tout |
|
45 d'abord avoir migrer vers une version données de cubicweb. Ce fichier peut contenir |
|
46 des commentaires (lignes commençant par un "#"), et une dépendance est notée sur |
|
47 une ligne de la manière suivante : :: |
|
48 |
|
49 <n° de version du modèle X.Y.Z> : <n° de version cubicweb X.Y.Z> |
|
50 |
|
51 Par exemple :: |
|
52 |
|
53 0.12.0: 2.26.0 |
|
54 0.13.0: 2.27.0 |
|
55 # 0.14 works with 2.27 <= cubicweb <= 2.28 at least |
|
56 0.15.0: 2.28.0 |
|
57 |
|
58 |
|
59 Contexte de base |
|
60 ---------------- |
|
61 Les identifiants suivants sont préféfinis dans les scripts de migration : |
|
62 |
|
63 * `config`, configuration de l'instance |
|
64 |
|
65 * `interactive_mode`, booléen indiquant si le script est éxécuté en mode |
|
66 interactif ou non |
|
67 |
|
68 * `appltemplversion`, version du modèle d'application de l'instance |
|
69 |
|
70 * `applcubicwebversion`, version cubicweb de l'instance |
|
71 |
|
72 * `templversion`, version du modéle d'application installée |
|
73 |
|
74 * `cubicwebversion`, version cubicweb installée |
|
75 |
|
76 * `confirm(question)`, fonction posant une question et retournant vrai si |
|
77 l'utilisateur a répondu oui, faux sinon (retourne toujours vrai en mode non |
|
78 interactif) |
|
79 |
|
80 * `_`, fonction équivalente à `unicode` permettant de marquer des chaines à |
|
81 internationaliser dans les scripts de migration |
|
82 |
|
83 Dans les scripts "repository", les identifiants suivant sont également définis : |
|
84 |
|
85 * `checkpoint`, demande confirmant et effectue un "commit" au point d'appel |
|
86 |
|
87 * `repo_schema`, schéma persistent de l'instance (i.e. schéma de l'instance en |
|
88 cours de migration) |
|
89 |
|
90 * `newschema`, schéma installé sur le système de fichier (i.e. schéma de la |
|
91 version à jour du modèle et de cubicweb) |
|
92 |
|
93 * `sqlcursor`, un curseur SQL pour les très rares cas où il est réellement |
|
94 nécessaire ou avantageux de passer par du sql |
|
95 |
|
96 * `repo`, l'objet repository |
|
97 |
|
98 |
|
99 Migration de schéma |
|
100 ------------------- |
|
101 Les fonctions de migration de schéma suivantes sont disponibles dans les scripts |
|
102 "repository" : |
|
103 |
|
104 * `add_attribute(etype, attrname, attrtype=None, commit=True)`, ajoute un |
|
105 nouvel attribut à un type d'entité existante. Si le type de celui-ci n'est pas |
|
106 spécifié il est extrait du schéma à jour. |
|
107 |
|
108 * `drop_attribute(etype, attrname, commit=True)`, supprime un |
|
109 attribut à un type d'entité existante. |
|
110 |
|
111 * `rename_attribute(etype, oldname, newname, commit=True)`, renomme un attribut |
|
112 |
|
113 * `add_entity_type(etype, auto=True, commit=True)`, ajoute un nouveau type |
|
114 d'entité. Si `auto` est vrai, toutes les relations utilisant ce type d'entité |
|
115 et ayant un type d'entité connu à l'autre extrémité vont également être |
|
116 ajoutées. |
|
117 |
|
118 * `drop_entity_type(etype, commit=True)`, supprime un type d'entité et toutes |
|
119 les relations l'utilisant. |
|
120 |
|
121 * `rename_entity_type(oldname, newname, commit=True)`, renomme un type d'entité |
|
122 |
|
123 * `add_relation_type(rtype, addrdef=True, commit=True)`, ajoute un nouveau type |
|
124 de relation. Si `addrdef` est vrai, toutes les définitions de relation de ce |
|
125 type seront également ajoutées. |
|
126 |
|
127 * `drop_relation_type(rtype, commit=True)`, supprime un type de relation et |
|
128 toutes les définitions de ce type. |
|
129 |
|
130 * `rename_relation(oldname, newname, commit=True)`, renomme une relation. |
|
131 |
|
132 * `add_relation_definition(subjtype, rtype, objtype, commit=True)`, ajoute une |
|
133 définition de relation. |
|
134 |
|
135 * `drop_relation_definition(subjtype, rtype, objtype, commit=True)`, supprime |
|
136 une définition de relation. |
|
137 |
|
138 * `synchronize_permissions(ertype, commit=True)`, synchronise les permissions |
|
139 d'un type d'entité ou de relation |
|
140 |
|
141 * `synchronize_rschema(rtype, commit=True)`, synchronise les propriétés et |
|
142 permissions d'un type de relation. |
|
143 |
|
144 * `synchronize_eschema(etype, commit=True)`, synchronise les propriétés et |
|
145 permissions d'un type d'entité. |
|
146 |
|
147 * `synchronize_schema(commit=True)`, synchronise le schéma persistent avec le |
|
148 schéma à jour (mais sans ajouter ni supprimer de nouveaux types d'entités ou |
|
149 de relations ni de définitions de relation). |
|
150 |
|
151 * `change_relation_props(subjtype, rtype, objtype, commit=True, **kwargs)`, change |
|
152 les propriétés d'une definition de relation en utilisant les arguments nommés |
|
153 pour les propriétés à changer. |
|
154 |
|
155 * `set_widget(etype, rtype, widget, commit=True)`, change le widget à utiliser |
|
156 pour la relation <rtype> du type d'entité <etype> |
|
157 |
|
158 * `set_size_constraint(etype, rtype, size, commit=True)`, change la contrainte |
|
159 de taille pour la relation <rtype> du type d'entité <etype> |
|
160 |
|
161 |
|
162 Migration de données |
|
163 -------------------- |
|
164 Les fonctions de migration de données suivantes sont disponibles dans les scripts |
|
165 "repository" : |
|
166 |
|
167 * `rqlexec(rql, kwargs=None, cachekey=None, ask_confirm=True)`, éxécute une |
|
168 requête rql arbitraire, d'interrogation ou de modification. Un objet result |
|
169 set est retourné. |
|
170 |
|
171 * `rqlexecall(rqliter, cachekey=None, ask_confirm=True)`, éxécute une série |
|
172 de requêtes rql arbitraires, d'interrogation ou de modification. rqliter est |
|
173 un itérateur retournant des couples (rql, kwargs). Le result set de la |
|
174 dernière requête éxécutée est retourné. |
|
175 |
|
176 * `add_entity(etype, *args, **kwargs)`, ajoute une nouvelle entité du type |
|
177 données. La valeur des attributs et relations est spécifiée en utilisant les |
|
178 arguments nommés et positionnels. |
|
179 |
|
180 |
|
181 Création de workflow |
|
182 -------------------- |
|
183 Les fonctions de création de workflow suivantes sont disponibles dans les scripts |
|
184 "repository" : |
|
185 |
|
186 * `add_state(name, stateof, initial=False, commit=False, **kwargs)`, ajoute un |
|
187 nouvel état de workflow |
|
188 |
|
189 * `add_transition(name, transitionof, fromstates, tostate, requiredgroups=(), commit=False, **kwargs)`, |
|
190 ajoute une nouvelle transtion de workflow |
|
191 |
|
192 Migration de configuration |
|
193 -------------------------- |
|
194 Les fonctions de migration de configuration suivantes sont disponibles dans tout |
|
195 les scripts : |
|
196 |
|
197 * `option_renamed(oldname, newname)`, indique qu'une option a été renommée |
|
198 |
|
199 * `option_group_change(option, oldgroup, newgroup)`, indique qu'une option a |
|
200 changé de groupe |
|
201 |
|
202 * `option_added(oldname, newname)`, indique qu'une option a été ajoutée |
|
203 |
|
204 * `option_removed(oldname, newname)`, indique qu'une option a été supprimée |
|
205 |
|
206 |
|
207 Autres fonctions de migration |
|
208 ----------------------------- |
|
209 Ces fonctions ne sont utilisés que pour des opérations de bas niveau |
|
210 irréalisables autrement ou pour réparer des bases cassées lors de session |
|
211 interactive. Elles sont disponibles dans les scripts "repository". |
|
212 |
|
213 * `sqlexec(sql, args=None, ask_confirm=True)`, éxécute une requête sql |
|
214 arbitraire, à n'utiliser |
|
215 |
|
216 * `add_entity_type_table(etype, commit=True)` |
|
217 * `add_relation_type_table(rtype, commit=True)` |
|
218 * `uninline_relation(rtype, commit=True)` |