You use database evolve to update a database schema so that it matches the current model in MDriven Designer or MDrivenServer.
What database evolve does
Database evolve compares the mapping script for your current model with the mapping script saved from the previous successful state. It then calculates the SQL changes needed to bring the database schema in line with the model.
For example, if you add a ReleaseDate attribute to the Album class, evolve can calculate an ALTER TABLE operation that adds the corresponding column. If you add a new class, evolve can calculate the table and mapping changes needed for that class.
The evolve operation changes the database schema. It does not replace the need to consider existing production data, database constraints, and database objects that are not described by the model.
Before you evolve
Make sure that MDriven has an earlier mapping script to compare with the current model.
For a database created from the model, the required administrative and mapping information is normally present from the start.
For a reverse-engineered database, you must first save the current mapping script to the database. This gives MDriven an old script to compare against when you later change the model. The mapping is stored in the database, including in the Eco_Ormapping table.
- Connect the model to the database.
- Save the current mapping script before making schema changes through evolve.
- Make the required model change.
- Run evolve and inspect the generated SQL before executing it.
If no old mapping script is available, MDriven cannot calculate the difference between the previous and current model mappings.
Typical workflow
- Change the model in MDriven Designer. For example, add an attribute or association.
- Run the application or use the available evolve action for the connected database.
- Review the SQL script and any warnings or errors.
- Resolve database-specific issues that MDriven cannot safely handle.
- Execute the evolve operation.
- Confirm that the operation completed successfully and retain the resulting current mapping script for the next evolve.
When working through MDrivenServer, use the server connection and evolve operation appropriate to the application. If the MDrivenServer administration database has an empty current evolve script or cannot evolve after an upgrade, follow MDriven Server problem with evolve instead of treating it as an application-model change.
Read evolve messages
MDriven may report:
This change will not be evolved.
This means the evolve engine has identified a model change that it will not apply automatically. You must make the corresponding change manually with the database tool for the SQL Server you use, then run evolve again as appropriate.
A common case with reverse-engineered databases is a database index or other existing database object that is not fully represented in the model mapping. For example, deleting a model element can require removal of an existing index, but evolve may stop because it cannot remove that index. Inspect the reported table and index, make the required database change manually, and retry evolve.
Do not ignore warnings. Compare the generated SQL with the database objects and data that already exist, especially when the database was created outside MDriven or contains manually maintained schema objects.
Model settings that affect evolve
Attribute settings affect the SQL generated during evolve:
| Setting or topic | Effect on evolve | Example |
|---|---|---|
| DefaultDBValue | Controls how evolve creates an attribute's default value in SQL Server. | A new required date column can be created with the database default defined by the attribute. |
| InitialValue, DefaultDBValue, and Allow Null | Determines how initial object values, database defaults, and nullability differ. | Choose a database default when existing rows need a value during a schema change; do not assume an object initial value changes existing database rows. |
| Attribute.CheckIdNameConflict | Controls the naming-conflict check used by evolve and database generation. | Set it to false only when you deliberately accept a name that may conflict with SQL Server naming rules.
|
Evolving from code and automated delivery
You can calculate, generate, inspect, and execute evolve scripts from code through the MDriven Framework. See HowTos:Evolve Database with Code for the available evolutor operations, including calculating the script, generating warnings and errors, executing the script, and retrieving executed statements.
For automated build and deployment practices, see Documentation:ContinuousIntegration. If you need to run additional work after a successful evolve, see Documentation:ScriptAfterEvolve.