3 .. _migration: |
3 .. _migration: |
4 |
4 |
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 and 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 changes applied to the data model |
10 of an application, and in particular to handle the changes to be applied |
11 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 an application model 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 needs 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 nammed accordingly: |
20 application 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 |
26 in which : |
26 in which : |
27 |
27 |
28 * X.Y.Z is the model version number to which the script enable to migrate |
28 * X.Y.Z is the model version number to which the script enables to migrate. |
29 |
29 |
30 * *mode* (between the last "_" and the extension ".py") indicates which part |
30 * *mode* (between the last "_" and the extension ".py") is used for |
31 of the application (RQL server, web server) the script applies to in case |
31 distributed installation. It indicates to which part |
32 of distributed installation. Its value could be : |
32 of the application (RQL server, web server) the script applies. |
|
33 Its value could be : |
33 |
34 |
34 * `common`, applies to the RQL server as well as the web server and updates |
35 * `common`, applies to the RQL server as well as the web server and updates |
35 files on the hard drive (configuration files migration for example). |
36 files on the hard drive (configuration files migration for example). |
36 |
37 |
37 * `web`, applies only to the web server and updates files on the hard drive |
38 * `web`, applies only to the web server and updates files on the hard drive. |
38 |
39 |
39 * `repository`, applies only to the RQL server and updates files on the |
40 * `repository`, applies only to the RQL server and updates files on the |
40 hard drive |
41 hard drive. |
41 |
42 |
42 * `Any`, applies only to the RQL server and updates data in the database |
43 * `Any`, applies only to the RQL server and updates data in the database |
43 (schema and data migration for example) |
44 (schema and data migration for example). |
44 |
45 |
45 Again in the directory `migration`, the file `depends.map` allows to indicate |
46 Again in the directory `migration`, the file `depends.map` allows to indicate |
46 that to migrate to a particular model version, you always have to first migrate |
47 that to migrate to a particular model version, you always have to first migrate |
47 to a particular `CubicWeb` version. This file can contains comments (lines |
48 to a particular `CubicWeb` version. This file can contain comments (lines |
48 starting by `#`) and a dependancy is listed as follows: :: |
49 starting by `#`) and a dependancy is listed as follows: :: |
49 |
50 |
50 <model version n° X.Y.Z> : <cubicweb version n° X.Y.Z> |
51 <model version n° X.Y.Z> : <cubicweb version n° X.Y.Z> |
51 |
52 |
52 For example: :: |
53 For example: :: |
53 |
54 |
54 0.12.0: 2.26.0 |
55 0.12.0: 2.26.0 |
55 0.13.0: 2.27.0 |
56 0.13.0: 2.27.0 |
56 # 0.14 works with 2.27 <= erudi <= 2.28 at least |
57 # 0.14 works with 2.27 <= cubicweb <= 2.28 at least |
57 0.15.0: 2.28.0 |
58 0.15.0: 2.28.0 |
58 |
59 |
59 Base context |
60 Base context |
60 ------------ |
61 ------------ |
61 |
62 |
66 * `interactive_mode`, boolean indicating that the script is executed in |
67 * `interactive_mode`, boolean indicating that the script is executed in |
67 an intercative mode or not |
68 an intercative mode or not |
68 |
69 |
69 * `appltemplversion`, application model version of the instance |
70 * `appltemplversion`, application model version of the instance |
70 |
71 |
71 * `applerudiversion`, cubicweb instance version |
|
72 |
|
73 * `templversion`, installed application model version |
72 * `templversion`, installed application model version |
74 |
73 |
75 * `erudiversion`, installed cubicweb version |
74 * `cubicwebversion`, installed cubicweb version |
76 |
75 |
77 * `confirm(question)`, function interrogating the user and returning true |
76 * `confirm(question)`, function interrogating the user and returning true |
78 if the user answers yes, false otherwise (always returns true when in a |
77 if the user answers yes, false otherwise (always returns true in |
79 non-interactive mode) |
78 non-interactive mode) |
80 |
79 |
81 * `_`, function fonction equivalent to `unicode` allowing to flag the strings |
80 * the function `_`, it is equivalent to `unicode` allowing to flag the strings |
82 to internationalize in the migration scripts |
81 to internationalize in the migration scripts. |
83 |
82 |
84 In the `repository` scripts, the following identifiers are also defined: |
83 In the `repository` scripts, the following identifiers are also defined: |
85 |
84 |
86 * `checkpoint`, request confirming and executing a "commit" at checking point |
85 * `checkpoint`, request confirming and executing a "commit" at checking point |
87 |
86 |
88 * `repo_schema`, instance persisting schema (e.g. instance schema of the |
87 * `repo_schema`, instance persisting schema (e.g. instance schema of the |
89 current migration) |
88 current migration) |
90 |
89 |
91 * `newschema`, installed schema on the file system (e.g. schema of |
90 * `newschema`, installed schema on the file system (e.g. schema of |
92 the updated model and erudi) |
91 the updated model and cubicweb) |
93 |
92 |
94 * `sqlcursor`, SQL cursor for very rare cases where it is really |
93 * `sqlcursor`, SQL cursor for very rare cases where it is really |
95 necessary or beneficial to go through the sql |
94 necessary or beneficial to go through the sql |
96 |
95 |
97 * `repo`, repository object |
96 * `repo`, repository object |
107 then it is extracted from the updated schema. |
106 then it is extracted from the updated schema. |
108 |
107 |
109 * `drop_attribute(etype, attrname, commit=True)`, removes an attribute from an |
108 * `drop_attribute(etype, attrname, commit=True)`, removes an attribute from an |
110 existing entity type. |
109 existing entity type. |
111 |
110 |
112 * `rename_attribute(etype, oldname, newname, commit=True)`, rename an attribute |
111 * `rename_attribute(etype, oldname, newname, commit=True)`, renames an attribute |
113 |
112 |
114 * `add_entity_type(etype, auto=True, commit=True)`, adds a new entity type. |
113 * `add_entity_type(etype, auto=True, commit=True)`, adds a new entity type. |
115 If `auto` is True, all the relations using this entity type and having a known |
114 If `auto` is True, all the relations using this entity type and having a known |
116 entity type on the other hand will automatically be added. |
115 entity type on the other hand will automatically be added. |
117 |
116 |