Binary Schema Evolution

“Binary schema evolution” (BSE) is a feature that allows an application to alter the database schema of a stored database image to a new definition contained in the dictionary of the currently running application.

Supported schema changes include:

Note that changing an index to unique will fail if duplicate values are present with mco_db_load() returning MCO_S_DUPLICATE. The application should not proceed to mco_db_connect() in such a case as this may result in a fatal error. The recommended practice for changing an index from nonunique to unique is to first traverse the index, detecting (by comparing the current key value with the previous key value) and removing all duplicates before changing the schema and performing schema evolution.

If a new field is being added to a unique index and the intention is to add both the field and the unique index with it, this should be done in two steps:

1) first add the field to the schema and assign unique values to it,

2) then add the unique index to the schema and perform schema evolution on this second pass.

The case of adding a new field to an existing unique index should not cause mco_db_load() to return MCO_S_DUPLICATE as it would not introduce new duplicates.


A class cannot be renamed. The runtime will treat the old class as having been dropped , and the new class as new.

BSE with eXtremeDB High Availability

The eXtremeDB High Availability runtime automatically converts objects from the master schema to the replica's schema. And the eXtremeDB Cluster runtime allows a single cluster to have different database schemas.

Please view the HA Synchronization and the Cluster Implementation Details pages for further details.

BSE for Persistent Databases

Binary schema evolution is automatically applied when the database dictionary is loaded during the database open procedure for persistent databases (or when a database image file is specified). The eXtremeDB runtime automatically converts data fields present in the dictionary of the saved image to the type defined in the currently opened database dictionary and sets data fields not present in the saved image to default values.

However note that:


The SDK sample 18-backup/Migrate demonstrates how to migrate an existing persistent database to a different schema.