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 application, and in particular to handle the changes to be applied to the data model, without loosing existing data.

The current version of an application model 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 application 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

  • appltemplversion, application model version of the instance

  • templversion, installed application model version

  • cubicwebversion, installed cubicweb version

  • 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

  • repo_schema, instance persisting schema (e.g. instance schema of the current migration)

  • newschema, installed schema on the file system (e.g. schema of the updated model and cubicweb)

  • sqlcursor, SQL cursor for very rare cases where it is really

    necessary or beneficial to go through the sql

  • repo, repository 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.

  • synchronize_permissions(ertype, commit=True), synchronizes permissions on an entity type or relation type.

  • synchronize_rschema(rtype, commit=True), synchronizes properties and permissions on a relation type.

  • synchronize_eschema(etype, commit=True), synchronizes properties and persmissions on an entity type.

  • synchronize_schema(commit=True), synchronizes the persisting schema with the updated schema (but without adding or removing new entity types, relations types or even relations definitions).

  • 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 An Example: Workflow definition .

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:

  • sqlexec(sql, args=None, ask_confirm=True), executes an arbitrary SQL query

  • 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