Changes between Version 9 and Version 10 of PluginDevelopmentGuide

Timestamp:

08.04.2013 21:46:10 (12 years ago)

Author:

jri

Comment:

The migration machinery

PluginDevelopmentGuide

@@ -379 +379 @@
 
 So, 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.
+
+=== The migration machinery ===
+
+Each 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//.
+
+You 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:
+
+    * The information what data model version the plugin requires.
+    * All the migrations required to update to that data model version.
+
+The relationship between plugin version and data model version might look as follows:
+
+||= Plugin Version =||= Data Model Version =||
+|| 0.1 || 2 ||
+|| 0.2 || 5 ||
+|| 0.2.1 || 5 ||
+|| 0.3 || 6 ||
+
+If 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.
+
+Thus, 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.