# 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.