Changes between Version 9 and Version 10 of PluginDevelopmentGuide


Ignore:
Timestamp:
08.04.2013 21:46:10 (7 years ago)
Author:
jri
Comment:

The migration machinery

Legend:

Unmodified
Added
Removed
Modified
  • PluginDevelopmentGuide

    v9 v10  
    379379 
    380380So, the purpose expressed in points 2. and 3. is to make your plugin //upgradable//. That is, keeping existing database content //in-snyc// with the plugin logic. By providing the corresponding migrations you make your plugin //compatible// with the previous plugin version. 
     381 
     382=== The migration machinery === 
     383 
     384Each plugin comes with its own data model. For each plugin DeepaMehta keeps track what data model version is currently installed. It does so by storing the version of the installed data model in the database as well. The data model version is an integer number that starts at 0 and is increased consecutively: 0, 1, 2, and so on. Each version number (except 0) corresponds with a particular migration. The migration with number //n// is responsible for transforming the database content from version //n-1// to version //n//. 
     385 
     386You as the developer know 2 things about your plugin: a) Which plugin version relies on which data model version, and b) How to transform the database content in order to advance from a given data model version to the next. So, when you ship your plugin you must equip it with 2 things: 
     387 
     388    * The information what data model version the plugin requires. 
     389    * All the migrations required to update to that data model version. 
     390 
     391The relationship between plugin version and data model version might look as follows: 
     392 
     393||= Plugin Version =||= Data Model Version =|| 
     394|| 0.1 || 2 || 
     395|| 0.2 || 5 || 
     396|| 0.2.1 || 5 || 
     397|| 0.3 || 6 || 
     398 
     399If e.g. version 0.1 of the plugin is currently installed, the database holds "2" as the current data model version. When the user updates to version 0.3 of the plugin, DeepaMehta's migration machinery will recognize that data model version 2 is present but version 6 is required. As a consequence DeepaMehta will consecutively run migrations 3 through 6. Once completed, the database holds "6" as the current data model version. 
     400 
     401Thus, the users database will always be compatible with the installed version of the plugin. Furthermore, the user is free to skip versions when upgrading the plugin.