“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.
INT4is 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
nonunique(allowing duplicates) and vice versa,
Note that changing an index to unique will fail if duplicate values are present with
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
uniqueis 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
uniqueindex and the intention is to add both the field and the
uniqueindex 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
uniqueindex should not cause
MCO_S_DUPLICATEas it would not introduce new duplicates.
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.
BSE for Persistent Databases
Binary schema evolution is automatically applied when the database dictionary is loaded during the database
openprocedure 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_CHANGEDand there is no need to call the
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_CHANGEDon 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_CHANGEDwill not be emitted and references to the new class will expose confusing behavior. It is recommended to avoid this situation.
The SDK sample 18-backup/Migrate demonstrates how to migrate an existing persistent database to a different schema.