1 .. -*- coding: utf-8 -*- |
|
2 |
|
3 .. _migration: |
|
4 |
|
5 Migration |
|
6 ========= |
|
7 |
|
8 One of the main concept in `CubicWeb` is to create incremental applications. |
|
9 For this purpose, multiple actions are provided to facilitate the improvement |
|
10 of an application, and in particular to handle the changes to be applied |
|
11 to the data model, without loosing existing data. |
|
12 |
|
13 The current version of an application model is provided in the file |
|
14 `__pkginfo__.py` as a tuple of 3 integers. |
|
15 |
|
16 Migration scripts management |
|
17 ---------------------------- |
|
18 |
|
19 Migration scripts has to be located in the directory `migration` of your |
|
20 application and named accordingly: |
|
21 |
|
22 :: |
|
23 |
|
24 <version n° X.Y.Z>[_<description>]_<mode>.py |
|
25 |
|
26 in which : |
|
27 |
|
28 * X.Y.Z is the model version number to which the script enables to migrate. |
|
29 |
|
30 * *mode* (between the last "_" and the extension ".py") is used for |
|
31 distributed installation. It indicates to which part |
|
32 of the application (RQL server, web server) the script applies. |
|
33 Its value could be : |
|
34 |
|
35 * `common`, applies to the RQL server as well as the web server and updates |
|
36 files on the hard drive (configuration files migration for example). |
|
37 |
|
38 * `web`, applies only to the web server and updates files on the hard drive. |
|
39 |
|
40 * `repository`, applies only to the RQL server and updates files on the |
|
41 hard drive. |
|
42 |
|
43 * `Any`, applies only to the RQL server and updates data in the database |
|
44 (schema and data migration for example). |
|
45 |
|
46 Again in the directory `migration`, the file `depends.map` allows to indicate |
|
47 that for the migration to a particular model version, you always have to first |
|
48 migrate to a particular `CubicWeb` version. This file can contain comments (lines |
|
49 starting by `#`) and a dependancy is listed as follows: :: |
|
50 |
|
51 <model version n° X.Y.Z> : <cubicweb version n° X.Y.Z> |
|
52 |
|
53 For example: :: |
|
54 |
|
55 0.12.0: 2.26.0 |
|
56 0.13.0: 2.27.0 |
|
57 # 0.14 works with 2.27 <= cubicweb <= 2.28 at least |
|
58 0.15.0: 2.28.0 |
|
59 |
|
60 Base context |
|
61 ------------ |
|
62 |
|
63 The following identifiers are pre-defined in migration scripts: |
|
64 |
|
65 * `config`, instance configuration |
|
66 |
|
67 * `interactive_mode`, boolean indicating that the script is executed in |
|
68 an interactive mode or not |
|
69 |
|
70 * `appltemplversion`, application model version of the instance |
|
71 |
|
72 * `templversion`, installed application model version |
|
73 |
|
74 * `cubicwebversion`, installed cubicweb version |
|
75 |
|
76 * `confirm(question)`, function asking the user and returning true |
|
77 if the user answers yes, false otherwise (always returns true in |
|
78 non-interactive mode) |
|
79 |
|
80 * the function `_`, it is equivalent to `unicode` allowing to flag the strings |
|
81 to internationalize in the migration scripts. |
|
82 |
|
83 In the `repository` scripts, the following identifiers are also defined: |
|
84 |
|
85 * `checkpoint`, request confirming and executing a "commit" at checking point |
|
86 |
|
87 * `repo_schema`, instance persisting schema (e.g. instance schema of the |
|
88 current migration) |
|
89 |
|
90 * `newschema`, installed schema on the file system (e.g. schema of |
|
91 the updated model and cubicweb) |
|
92 |
|
93 * `sqlcursor`, SQL cursor for very rare cases where it is really |
|
94 necessary or beneficial to go through the sql |
|
95 |
|
96 * `repo`, repository object |
|
97 |
|
98 |
|
99 Schema migration |
|
100 ---------------- |
|
101 The following functions for schema migration are available in `repository` |
|
102 scripts: |
|
103 |
|
104 * `add_attribute(etype, attrname, attrtype=None, commit=True)`, adds a new |
|
105 attribute to an existing entity type. If the attribute type is not specified, |
|
106 then it is extracted from the updated schema. |
|
107 |
|
108 * `drop_attribute(etype, attrname, commit=True)`, removes an attribute from an |
|
109 existing entity type. |
|
110 |
|
111 * `rename_attribute(etype, oldname, newname, commit=True)`, renames an attribute |
|
112 |
|
113 * `add_entity_type(etype, auto=True, commit=True)`, adds a new entity type. |
|
114 If `auto` is True, all the relations using this entity type and having a known |
|
115 entity type on the other hand will automatically be added. |
|
116 |
|
117 * `drop_entity_type(etype, commit=True)`, removes an entity type and all the |
|
118 relations using it. |
|
119 |
|
120 * `rename_entity_type(oldname, newname, commit=True)`, renames an entity type |
|
121 |
|
122 * `add_relation_type(rtype, addrdef=True, commit=True)`, adds a new relation |
|
123 type. If `addrdef` is True, all the relations definitions of this type will |
|
124 be added. |
|
125 |
|
126 * `drop_relation_type(rtype, commit=True)`, removes a relation type and all the |
|
127 definitions of this type. |
|
128 |
|
129 * `rename_relation(oldname, newname, commit=True)`, renames a relation. |
|
130 |
|
131 * `add_relation_definition(subjtype, rtype, objtype, commit=True)`, adds a new |
|
132 relation definition. |
|
133 |
|
134 * `drop_relation_definition(subjtype, rtype, objtype, commit=True)`, removes |
|
135 a relation definition. |
|
136 |
|
137 * `synchronize_permissions(ertype, commit=True)`, synchronizes permissions on |
|
138 an entity type or relation type. |
|
139 |
|
140 * `synchronize_rschema(rtype, commit=True)`, synchronizes properties and permissions |
|
141 on a relation type. |
|
142 |
|
143 * `synchronize_eschema(etype, commit=True)`, synchronizes properties and persmissions |
|
144 on an entity type. |
|
145 |
|
146 * `synchronize_schema(commit=True)`, synchronizes the persisting schema with the |
|
147 updated schema (but without adding or removing new entity types, relations types |
|
148 or even relations definitions). |
|
149 |
|
150 * `change_relation_props(subjtype, rtype, objtype, commit=True, **kwargs)`, changes |
|
151 properties of a relation definition by using the named parameters of the properties |
|
152 to change. |
|
153 |
|
154 * `set_widget(etype, rtype, widget, commit=True)`, changes the widget used for the |
|
155 relation <rtype> of entity type <etype>. |
|
156 |
|
157 * `set_size_constraint(etype, rtype, size, commit=True)`, changes the size constraints |
|
158 for the relation <rtype> of entity type <etype>. |
|
159 |
|
160 Data migration |
|
161 -------------- |
|
162 The following functions for data migration are available in `repository` scripts: |
|
163 |
|
164 * `rql(rql, kwargs=None, cachekey=None, ask_confirm=True)`, executes an arbitrary RQL |
|
165 query, either to interrogate or update. A result set object is returned. |
|
166 |
|
167 * `add_entity(etype, *args, **kwargs)`, adds a nes entity type of the given |
|
168 type. The attribute and relation values are specified using the named and |
|
169 positionned parameters. |
|
170 |
|
171 Workflow creation |
|
172 ----------------- |
|
173 |
|
174 The following functions for workflow creation are available in `repository` |
|
175 scripts: |
|
176 |
|
177 * `add_state(name, stateof, initial=False, commit=False, **kwargs)`, adds a new state |
|
178 in the workflow. |
|
179 |
|
180 * `add_transition(name, transitionof, fromstates, tostate, requiredgroups=(), commit=False, **kwargs)`, |
|
181 adds a new transition in the workflow. |
|
182 |
|
183 You can find more details about workflows in the chapter :ref:`Workflow` . |
|
184 |
|
185 Configuration migration |
|
186 ----------------------- |
|
187 |
|
188 The following functions for configuration migration are available in all |
|
189 scripts: |
|
190 |
|
191 * `option_renamed(oldname, newname)`, indicates that an option has been renamed |
|
192 |
|
193 * `option_group_change(option, oldgroup, newgroup)`, indicates that an option does not |
|
194 belong anymore to the same group. |
|
195 |
|
196 * `option_added(oldname, newname)`, indicates that an option has been added. |
|
197 |
|
198 * `option_removed(oldname, newname)`, indicates that an option has been deleted. |
|
199 |
|
200 |
|
201 Others migration functions |
|
202 -------------------------- |
|
203 Those functions are only used for low level operations that could not be |
|
204 accomplished otherwise or to repair damaged databases during interactive |
|
205 session. They are available in `repository` scripts: |
|
206 |
|
207 * `sqlexec(sql, args=None, ask_confirm=True)`, executes an arbitrary SQL query |
|
208 * `add_entity_type_table(etype, commit=True)` |
|
209 * `add_relation_type_table(rtype, commit=True)` |
|
210 * `uninline_relation(rtype, commit=True)` |
|
211 |
|
212 |
|
213 [FIXME] Add explanation on how to use cubicweb-ctl shell |
|