5 Migration |
5 Migration |
6 ========= |
6 ========= |
7 |
7 |
8 One of the main concept in *CubicWeb* is to create incremental applications. |
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 |
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 |
10 of an instance, and in particular to handle the changes to be applied |
11 to the data model, without loosing existing data. |
11 to the data model, without loosing existing data. |
12 |
12 |
13 The current version of an application model is provided in the file |
13 The current version of a cube (and of cubicweb itself) is provided in the file |
14 `__pkginfo__.py` as a tuple of 3 integers. |
14 `__pkginfo__.py` as a tuple of 3 integers. |
15 |
15 |
16 Migration scripts management |
16 Migration scripts management |
17 ---------------------------- |
17 ---------------------------- |
18 |
18 |
19 Migration scripts has to be located in the directory `migration` of your |
19 Migration scripts has to be located in the directory `migration` of your |
20 application and named accordingly: |
20 cube and named accordingly: |
21 |
21 |
22 :: |
22 :: |
23 |
23 |
24 <version n° X.Y.Z>[_<description>]_<mode>.py |
24 <version n° X.Y.Z>[_<description>]_<mode>.py |
25 |
25 |
65 * `config`, instance configuration |
65 * `config`, instance configuration |
66 |
66 |
67 * `interactive_mode`, boolean indicating that the script is executed in |
67 * `interactive_mode`, boolean indicating that the script is executed in |
68 an interactive mode or not |
68 an interactive mode or not |
69 |
69 |
70 * `appltemplversion`, application model version of the instance |
70 * `versions_map`, dictionary of versions used by this instance (key are cubes |
71 |
71 names, including 'cubicweb', values are version, eg 3-uple) |
72 * `templversion`, installed application model version |
|
73 |
|
74 * `cubicwebversion`, installed cubicweb version |
|
75 |
72 |
76 * `confirm(question)`, function asking the user and returning true |
73 * `confirm(question)`, function asking the user and returning true |
77 if the user answers yes, false otherwise (always returns true in |
74 if the user answers yes, false otherwise (always returns true in |
78 non-interactive mode) |
75 non-interactive mode) |
79 |
76 |
82 |
79 |
83 In the `repository` scripts, the following identifiers are also defined: |
80 In the `repository` scripts, the following identifiers are also defined: |
84 |
81 |
85 * `checkpoint`, request confirming and executing a "commit" at checking point |
82 * `checkpoint`, request confirming and executing a "commit" at checking point |
86 |
83 |
87 * `repo_schema`, instance persisting schema (e.g. instance schema of the |
84 * `schema`, instance schema (readen from the database) |
88 current migration) |
85 |
89 |
86 * `fsschema`, installed schema on the file system (e.g. schema of |
90 * `newschema`, installed schema on the file system (e.g. schema of |
|
91 the updated model and cubicweb) |
87 the updated model and cubicweb) |
92 |
88 |
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 |
89 * `repo`, repository object |
|
90 |
|
91 * `session`, repository session object |
97 |
92 |
98 |
93 |
99 Schema migration |
94 Schema migration |
100 ---------------- |
95 ---------------- |
101 The following functions for schema migration are available in `repository` |
96 The following functions for schema migration are available in `repository` |
132 relation definition. |
127 relation definition. |
133 |
128 |
134 * `drop_relation_definition(subjtype, rtype, objtype, commit=True)`, removes |
129 * `drop_relation_definition(subjtype, rtype, objtype, commit=True)`, removes |
135 a relation definition. |
130 a relation definition. |
136 |
131 |
137 * `synchronize_permissions(ertype, commit=True)`, synchronizes permissions on |
132 * `sync_schema_props_perms(ertype=None, syncperms=True, |
138 an entity type or relation type. |
133 syncprops=True, syncrdefs=True, commit=True)`, |
139 |
134 synchronizes properties and/or permissions on: |
140 * `synchronize_rschema(rtype, commit=True)`, synchronizes properties and permissions |
135 * the whole schema if ertype is None |
141 on a relation type. |
136 * an entity or relation type schema if ertype is a string |
142 |
137 * a relation definition if ertype is a 3-uple (subject, relation, object) |
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 |
138 |
150 * `change_relation_props(subjtype, rtype, objtype, commit=True, **kwargs)`, changes |
139 * `change_relation_props(subjtype, rtype, objtype, commit=True, **kwargs)`, changes |
151 properties of a relation definition by using the named parameters of the properties |
140 properties of a relation definition by using the named parameters of the properties |
152 to change. |
141 to change. |
153 |
142 |
202 -------------------------- |
191 -------------------------- |
203 Those functions are only used for low level operations that could not be |
192 Those functions are only used for low level operations that could not be |
204 accomplished otherwise or to repair damaged databases during interactive |
193 accomplished otherwise or to repair damaged databases during interactive |
205 session. They are available in `repository` scripts: |
194 session. They are available in `repository` scripts: |
206 |
195 |
207 * `sqlexec(sql, args=None, ask_confirm=True)`, executes an arbitrary SQL query |
196 * `sql(sql, args=None, ask_confirm=True)`, executes an arbitrary SQL query on the system source |
208 * `add_entity_type_table(etype, commit=True)` |
197 * `add_entity_type_table(etype, commit=True)` |
209 * `add_relation_type_table(rtype, commit=True)` |
198 * `add_relation_type_table(rtype, commit=True)` |
210 * `uninline_relation(rtype, commit=True)` |
199 * `uninline_relation(rtype, commit=True)` |
211 |
200 |
212 |
201 |