Tuesday, November 11, 2008

Upgrade path declaration for automatic upgrade and downgrade of persistent data

In persistence frameworks peer synchronization and restore of backups requires knowledge about older versions. To follow the SCSE pattern from x-tensive upgrade paths should be declared in the object model.

If the domain-model changes, it is in general necessary to upgrade the clients too. In windows installer terms, these kind of upgrades are called "major upgrade", because the change of the model will almost always break the interoperability to related assemblies.

Important: The term "major upgrade" has nothing to do with the version numbering schema of assemblies which has a major version and minor version. But a major upgrade should have at least a minor version number upgrade.

An upgrade path is a linear path along major upgrades (releases):
V1.1.x -> V1.2.x -> V2.0.x -> V2.1.x -> V2.2.x
There are at least six primitive upgrade operations:
  • persistent class added
  • persistent class renamed
  • persistent class removed
  • persistent field added
  • persistent field renamed
  • persistent field removed
To declare this, three attributes are announced:
  • RelAdded for adding a class or a field
  • RelRenamed for renaming a class or a field
  • RelDeleted for deleting a class or a field


This is an example of a class with release attributes:

[assembly: RelGroup("MseIt.Persistency.UnitTests")]
[assembly: RelDeleted("MseIt.Persistency.UnusedClass", Release.B_0_2)]

namespace MseIt.Persistency
{
static public class Release
{
public const int B_0_1 = 1;
public const int B_0_2 = 2;
}

[Sync]
[RelAdded(Release.B_0_1)]
[RelRenamed("MseIt.Persistency.UpdatedClass",Release.B_0_2)]
[RelDeleted("Payload",Release.B_0_2)]
class UpdatedEntity : SyncEntity
{
[Field]
[RelAdded(Release.B_0_1)]
public string Payload1 { get; set; }

[Field]
[RelAdded(Release.B_0_2)]
public string Payload2 { get; set; }
}
}


A upgrade path is extractable from this declarations. So a automatic upgrade can be performed on restoring old data or synchronizing with peers having previous versions.

Additionaly it is a nice documentation which modifications are done on a specific release. External tools could check this update information for consistency.

No comments: