The topic is described in Manual: http://goo.gl/WHuj

I also recommend you to see upgrade samples - there are 3 different apps, the first is this one. By running them sequentially (or not - this is detected & asserted), you'll see how schema upgrade really works.

The most serious limitation of current schema upgrade layer is its inability to support movements of a class inside class hierachy (AFAIK, this isn't problem only with single-table-per-hierarchy inheritance mapping schema). I.e. creations and removals of new types are ok, but if you'll decide to turn some DescendantOfX to AncestorOfX, it won't be easy (simply, there are no such upgrade hints).

So such upgrades must be performed manually by your own, and there are two ways:

• You may rely on recycled types to access & copy the old content to new types

• Or you may use DirectSqlAccessor to execute your own data migration or schema upgrade script directly from upgrade handler.

The second case is a bit tricky: you can do this only in Initializing stage - domain that is built on this stage contains just system persistent types (to fetch verious metainfo from Metadata.* tables, such as type identifiers and versions of each assembly with persistent types), so you can safely make any schema changes that don't affect these tables. Basically, you need to override this method in one of your upgrade handlers:

public override void OnStage()
    {
      if (UpgradeContext.Stage==UpgradeStage.Initializing) {
        // Do schema changes here!
        break;
      }
      base.OnStage();
    }

Remember, that normally you must implement one handler per each assembly (to make each assembly with persistent types self-consistent). All event-like methods on handlers are invoked in dependencies-to-dependent-handlers orders.