.. -*- coding: utf-8 -*-

.. _migration:

Migration

=========

One of the main concept in *CubicWeb* is to create incremental applications.

For this purpose, multiple actions are provided to facilitate the improvement

to the data model, without loosing existing data.

`__pkginfo__.py` as a tuple of 3 integers.

Migration scripts management

----------------------------

Migration scripts has to be located in the directory `migration` of your

::

  <version n° X.Y.Z>[_<description>]_<mode>.py

in which :

* X.Y.Z is the model version number to which the script enables to migrate.

* *mode* (between the last "_" and the extension ".py") is used for

  distributed installation. It indicates to which part

  of the application (RQL server, web server) the script applies.

  Its value could be :

  * `common`, applies to the RQL server as well as the web server and updates

    files on the hard drive (configuration files migration for example).

  * `web`, applies only to the web server and updates files on the hard drive.

  * `repository`, applies only to the RQL server and updates files on the

    hard drive.

  * `Any`, applies only to the RQL server and updates data in the database

    (schema and data migration for example).

Again in the directory `migration`, the file `depends.map` allows to indicate

that for the migration to a particular model version, you always have to first

migrate to a particular *CubicWeb* version. This file can contain comments (lines

starting by `#`) and a dependancy is listed as follows: ::

  <model version n° X.Y.Z> : <cubicweb version n° X.Y.Z>

For example: ::

  0.12.0: 2.26.0

  0.13.0: 2.27.0

  # 0.14 works with 2.27 <= cubicweb <= 2.28 at least

  0.15.0: 2.28.0

Base context

------------

The following identifiers are pre-defined in migration scripts:

* `config`, instance configuration

* `interactive_mode`, boolean indicating that the script is executed in

  an interactive mode or not

* `confirm(question)`, function asking the user and returning true

  if the user answers yes, false otherwise (always returns true in

  non-interactive mode)

* the function `_`, it is equivalent to `unicode` allowing to flag the strings

  to internationalize in the migration scripts.

In the `repository` scripts, the following identifiers are also defined:

* `checkpoint`, request confirming and executing a "commit" at checking point

  the updated model and cubicweb)

Schema migration

----------------

The following functions for schema migration are available in `repository`

scripts:

* `add_attribute(etype, attrname, attrtype=None, commit=True)`, adds a new

  attribute to an existing entity type. If the attribute type is not specified,

  then it is extracted from the updated schema.

* `drop_attribute(etype, attrname, commit=True)`, removes an attribute from an

  existing entity type.

* `rename_attribute(etype, oldname, newname, commit=True)`, renames an attribute

* `add_entity_type(etype, auto=True, commit=True)`, adds a new entity type.

  If `auto` is True, all the relations using this entity type and having a known

  entity type on the other hand will automatically be added.

* `drop_entity_type(etype, commit=True)`, removes an entity type and all the

  relations using it.

* `rename_entity_type(oldname, newname, commit=True)`, renames an entity type

* `add_relation_type(rtype, addrdef=True, commit=True)`, adds a new relation

  type. If `addrdef` is True, all the relations definitions of this type will

  be added.

* `drop_relation_type(rtype, commit=True)`, removes a relation type and all the

  definitions of this type.

* `rename_relation(oldname, newname, commit=True)`, renames a relation.

* `add_relation_definition(subjtype, rtype, objtype, commit=True)`, adds a new

  relation definition.

* `drop_relation_definition(subjtype, rtype, objtype, commit=True)`, removes

  a relation definition.

* `change_relation_props(subjtype, rtype, objtype, commit=True, **kwargs)`, changes

  properties of a relation definition by using the named parameters of the properties

  to change.

* `set_widget(etype, rtype, widget, commit=True)`, changes the widget used for the

  relation <rtype> of entity type <etype>.

* `set_size_constraint(etype, rtype, size, commit=True)`, changes the size constraints

  for the relation <rtype> of entity type <etype>.

Data migration

--------------

The following functions for data migration are available in `repository` scripts:

* `rql(rql, kwargs=None, cachekey=None, ask_confirm=True)`, executes an arbitrary RQL

  query, either to interrogate or update. A result set object is returned.

* `add_entity(etype, *args, **kwargs)`, adds a nes entity type of the given

  type. The attribute and relation values are specified using the named and

  positionned parameters.

Workflow creation

-----------------

The following functions for workflow creation are available in `repository`

scripts:

* `add_state(name, stateof, initial=False, commit=False, **kwargs)`, adds a new state

  in the workflow.

* `add_transition(name, transitionof, fromstates, tostate, requiredgroups=(), commit=False, **kwargs)`,

  adds a new transition in the workflow.

You can find more details about workflows in the chapter :ref:`Workflow` .

Configuration migration

-----------------------

The following functions for configuration migration are available in all

scripts:

* `option_renamed(oldname, newname)`, indicates that an option has been renamed

* `option_group_change(option, oldgroup, newgroup)`, indicates that an option does not

  belong anymore to the same group.

* `option_added(oldname, newname)`, indicates that an option has been added.

* `option_removed(oldname, newname)`, indicates that an option has been deleted.

Others migration functions

--------------------------

Those functions are only used for low level operations that could not be

accomplished otherwise or to repair damaged databases during interactive

session. They are available in `repository` scripts:

* `add_entity_type_table(etype, commit=True)`

* `add_relation_type_table(rtype, commit=True)`

* `uninline_relation(rtype, commit=True)`

[FIXME] Add explanation on how to use cubicweb-ctl shell