.. -*- 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

of an instance, and in particular to handle the changes to be applied

to the data model, without loosing existing data.

The current version of a cube (and of cubicweb itself) is provided in the file

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

Migration scripts management

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

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

cube and named accordingly:

::

  <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

* `schema`, instance schema (readen from the database)

* `fsschema`, installed schema on the file system (e.g. schema of

  the updated model and cubicweb)

* `repo`, repository object

* `session`, repository session object

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.

* `sync_schema_props_perms(ertype=None, syncperms=True,

                           syncprops=True, syncrdefs=True, commit=True)`,

  synchronizes properties and/or permissions on:

  * the whole schema if ertype is None

  * an entity or relation type schema if ertype is a string

  * a relation definition  if ertype is a 3-uple (subject, relation, object)

* `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:

* `sql(sql, args=None, ask_confirm=True)`, executes an arbitrary SQL query on the system source

* `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