doc/book/en/devrepo/migration.rst
branchstable
changeset 5394 105011657405
parent 5231 40f53867e332
child 6059 47f84adcd676
equal deleted inserted replaced
5393:875bdc0fe8ce 5394:105011657405
       
     1 .. -*- coding: utf-8 -*-
       
     2 
       
     3 .. _migration:
       
     4 
       
     5 Migration
       
     6 =========
       
     7 
       
     8 One of the main design goals of *CubicWeb* was to support iterative and agile
       
     9 development. For this purpose, multiple actions are provided to facilitate the
       
    10 improvement of an instance, and in particular to handle the changes to be
       
    11 applied to the data model, without loosing existing data.
       
    12 
       
    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.
       
    15 
       
    16 Migration scripts management
       
    17 ----------------------------
       
    18 
       
    19 Migration scripts has to be located in the directory `migration` of your
       
    20 cube 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 * `versions_map`, dictionary of migrated versions  (key are cubes
       
    71   names, including 'cubicweb', values are (from version, to version)
       
    72 
       
    73 * `confirm(question)`, function asking the user and returning true
       
    74   if the user answers yes, false otherwise (always returns true in
       
    75   non-interactive mode)
       
    76 
       
    77 * `_()` is equivalent to `unicode` allowing to flag the strings to
       
    78   internationalize in the migration scripts.
       
    79 
       
    80 In the `repository` scripts, the following identifiers are also defined:
       
    81 
       
    82 * `commit(ask_confirm=True)`, request confirming and executing a "commit"
       
    83 
       
    84 * `schema`, instance schema (readen from the database)
       
    85 
       
    86 * `fsschema`, installed schema on the file system (e.g. schema of
       
    87   the updated model and cubicweb)
       
    88 
       
    89 * `repo`, repository object
       
    90 
       
    91 * `session`, repository session object
       
    92 
       
    93 
       
    94 Schema migration
       
    95 ----------------
       
    96 The following functions for schema migration are available in `repository`
       
    97 scripts:
       
    98 
       
    99 * `add_attribute(etype, attrname, attrtype=None, commit=True)`, adds a new
       
   100   attribute to an existing entity type. If the attribute type is not specified,
       
   101   then it is extracted from the updated schema.
       
   102 
       
   103 * `drop_attribute(etype, attrname, commit=True)`, removes an attribute from an
       
   104   existing entity type.
       
   105 
       
   106 * `rename_attribute(etype, oldname, newname, commit=True)`, renames an attribute
       
   107 
       
   108 * `add_entity_type(etype, auto=True, commit=True)`, adds a new entity type.
       
   109   If `auto` is True, all the relations using this entity type and having a known
       
   110   entity type on the other hand will automatically be added.
       
   111 
       
   112 * `drop_entity_type(etype, commit=True)`, removes an entity type and all the
       
   113   relations using it.
       
   114 
       
   115 * `rename_entity_type(oldname, newname, commit=True)`, renames an entity type
       
   116 
       
   117 * `add_relation_type(rtype, addrdef=True, commit=True)`, adds a new relation
       
   118   type. If `addrdef` is True, all the relations definitions of this type will
       
   119   be added.
       
   120 
       
   121 * `drop_relation_type(rtype, commit=True)`, removes a relation type and all the
       
   122   definitions of this type.
       
   123 
       
   124 * `rename_relation(oldname, newname, commit=True)`, renames a relation.
       
   125 
       
   126 * `add_relation_definition(subjtype, rtype, objtype, commit=True)`, adds a new
       
   127   relation definition.
       
   128 
       
   129 * `drop_relation_definition(subjtype, rtype, objtype, commit=True)`, removes
       
   130   a relation definition.
       
   131 
       
   132 * `sync_schema_props_perms(ertype=None, syncperms=True, syncprops=True, syncrdefs=True, commit=True)`,
       
   133   synchronizes properties and/or permissions on:
       
   134   - the whole schema if ertype is None
       
   135   - an entity or relation type schema if ertype is a string
       
   136   - a relation definition  if ertype is a 3-uple (subject, relation, object)
       
   137 
       
   138 * `change_relation_props(subjtype, rtype, objtype, commit=True, **kwargs)`, changes
       
   139   properties of a relation definition by using the named parameters of the properties
       
   140   to change.
       
   141 
       
   142 * `set_widget(etype, rtype, widget, commit=True)`, changes the widget used for the
       
   143   relation <rtype> of entity type <etype>.
       
   144 
       
   145 * `set_size_constraint(etype, rtype, size, commit=True)`, changes the size constraints
       
   146   for the relation <rtype> of entity type <etype>.
       
   147 
       
   148 Data migration
       
   149 --------------
       
   150 The following functions for data migration are available in `repository` scripts:
       
   151 
       
   152 * `rql(rql, kwargs=None, cachekey=None, ask_confirm=True)`, executes an arbitrary RQL
       
   153   query, either to interrogate or update. A result set object is returned.
       
   154 
       
   155 * `add_entity(etype, *args, **kwargs)`, adds a nes entity type of the given
       
   156   type. The attribute and relation values are specified using the named and
       
   157   positionned parameters.
       
   158 
       
   159 Workflow creation
       
   160 -----------------
       
   161 
       
   162 The following functions for workflow creation are available in `repository`
       
   163 scripts:
       
   164 
       
   165 * `add_workflow(label, workflowof, initial=False, commit=False, **kwargs)`, adds a new workflow
       
   166   for a given type(s)
       
   167 
       
   168 You can find more details about workflows in the chapter :ref:`Workflow` .
       
   169 
       
   170 Configuration migration
       
   171 -----------------------
       
   172 
       
   173 The following functions for configuration migration are available in all
       
   174 scripts:
       
   175 
       
   176 * `option_renamed(oldname, newname)`, indicates that an option has been renamed
       
   177 
       
   178 * `option_group_change(option, oldgroup, newgroup)`, indicates that an option does not
       
   179   belong anymore to the same group.
       
   180 
       
   181 * `option_added(oldname, newname)`, indicates that an option has been added.
       
   182 
       
   183 * `option_removed(oldname, newname)`, indicates that an option has been deleted.
       
   184 
       
   185 
       
   186 Others migration functions
       
   187 --------------------------
       
   188 Those functions are only used for low level operations that could not be
       
   189 accomplished otherwise or to repair damaged databases during interactive
       
   190 session. They are available in `repository` scripts:
       
   191 
       
   192 * `sql(sql, args=None, ask_confirm=True)`, executes an arbitrary SQL query on the system source
       
   193 * `add_entity_type_table(etype, commit=True)`
       
   194 * `add_relation_type_table(rtype, commit=True)`
       
   195 * `uninline_relation(rtype, commit=True)`
       
   196 
       
   197 
       
   198 [FIXME] Add explanation on how to use cubicweb-ctl shell