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:

• Adding new classes
• Dropping classes
• Adding new fields to a class
• Dropping fields from a class
• Changing the type of a field (a loss of precision, e.g. INT2 to INT4 is allowed but may cause loss of precision; there is no error or warning)
• Adding/dropping indexes
• Adding/dropping fields from existing indexes
• Changing an index from unique to nonunique (allowing duplicates) and vice versa,

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:

• When adding a new class at the end of the schema file eXtremeDB is able to perform a limited kind of schema evolution "on the fly" during mco_db_connect() automatically; this does not emit error code MCO_E_DISK_SCHEMA_CHANGED and there is no need to call the mco_db_save() / mco_db_load()sequence for BSE to be applied.
• Inserting a new class in the middle of the static schema file should be done with caution. Normally it will trigger error code MCO_E_DISK_SCHEMA_CHANGED on the attempt to connect without performing BSE. However, in the very specific case when the new class definition replaces another class definition with exactly the same structure (but a different name) eXtremeDB won't treat it as a new class definition and instead will assume that the old class was renamed. Hence MCO_E_DISK_SCHEMA_CHANGED will not be emitted and references to the new class will expose confusing behavior. It is recommended to avoid this situation.

Example

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