You can evolve an existing database from application code when you use MDriven Framework persistence mapping and need to calculate and execute the database changes that match your current model.

What database evolve does

Database evolve compares the database mapping derived from the current model with the previously stored mapping script. It then produces SQL for the changes it can handle.

For example, if you add an attribute to a class, the generated SQL can add the corresponding column. Changes that the evolve engine cannot handle automatically must be made manually in your database server. Check the generated warnings and errors before executing a script.

Prerequisite: preserve the previous mapping

An evolve operation needs an old mapping script to compare with the mapping generated from the current model. For a database created from a model, this information is present from the start. For a reverse-engineered database, you must first allow MDriven to save the current mapping script to the database.

The stored mapping is held in the database so later evolve operations can determine what has changed. Without it, there is no old script to compare against.

Evolve a database from code

Use PersistenceMapperAdo2.GetEvolutor to obtain an IDBEvolutor for the application's type-system service. Then calculate the change, generate the scripts and diagnostics, execute the script, and retrieve the statements that were executed.

1. Obtain the PersistenceMapperAdo2 instance used by your application.
2. Get the type-system service from the EcoSpace.
3. Create the evolutor.
4. Calculate the change and generate the database and mapping scripts.
5. Generate warnings and errors. Resolve any issues that require manual database work before execution.
6. Execute the generated script.
7. Read the executed statements for logging or display.

PersistenceMapperAdo2 pmapp = /* the persistence mapper used by the application */;

var systemService = YourEcoSpace.GetTypeSystemService();
IDBEvolutor evolutor = pmapp.GetEvolutor(systemService);

evolutor.CalculateScript();
evolutor.GenerateDbScript();
evolutor.GenerateMappingScript();
evolutor.GenerateWarnings();
evolutor.GenerateErrors();

evolutor.ExecuteScript();

string result = "Evolve success\r\n";
string[] executedStatements = evolutor.GenerateExecutedStatements();
foreach (string statement in executedStatements)
{
    result += statement + "\r\n";
}

The executedStatements value gives you the SQL statements reported as executed. Record it in your application's diagnostics when you need an audit trail of an evolve operation.

Create the schema for the first time

Use CreateDatabaseSchema when you need to fill a database with schema information for the first time. This is a schema-creation operation, not an incremental evolve operation.

PersistenceMapperAdo2 pmapp = /* the persistence mapper used by the application */;

pmapp.CreateDatabaseSchema(
    YourEcoSpace.GetTypeSystemService(),
    new DefaultCleanPsConfig(true));

For later changes to that model and database, use the evolve workflow rather than recreating the schema.

Reverse-engineered databases

A reverse-engineered database can contain indexes, keys, or other database details that are not fully represented in the model. An evolve may therefore generate an SQL error for an existing database object that the mapping does not know how to remove or alter.

For example, when an evolve cannot remove an existing index, identify the named index and table in the database server, handle that database-specific object there, and run the evolve again. Review the reverse-engineered mapping before making structural changes; see HowTos:Reverse Engineer a Database.

Choose the right workflow

Situation	Recommended action
You have an application using MDriven Framework persistence mapping and need to apply a model change from code.	Use IDBEvolutor as shown on this page.
You need to understand what evolve can and cannot change automatically.	Read Documentation:Database evolve.
You are working with a database that was reverse engineered into a model.	Store the mapping script before relying on future evolves, then follow HowTos:Reverse Engineer a Database.
You use MDriven Turnkey and are switching to SQL Server or need MDrivenServer to create an empty schema.	Follow HowTos:Use SqlServer with MDriven Turnkey.
You need to discard the current database schema and recreate it through MDrivenServer.	Follow HowTos:Recreate the SQL Database.
MDrivenServer has an empty Evolve-Script field or cannot continue evolving its administrative database.	Follow Documentation:MDriven Server problem with evolve.

See also

• Documentation:Database evolve
• Documentation:Working with Code and Persistence Mapping
• HowTos:Reverse Engineer a Database
• HowTos:Recreate the SQL Database
• HowTos:Migrating Data Between Databases

Review the evolve script before applying it

Database Evolve calculates required database changes by comparing a new database script with an old one. The new script is derived from the current model; therefore, an old script must be available for comparison.

For a reversed database, MDriven documents a one-time step to allow the current script to be stored in the database if Database Evolve will be used. Without an old script, Evolve has nothing to compare with the script derived from the current model.

When using the evolve dialog:

1. Run the evolve operation.
2. Open the SQL Script tab.
3. Review the SQL shown there before applying the change.
4. Apply the evolve only after the required reviewers have approved the proposed database change.

The documented example shows that adding ReleaseDate to Album can result in SQL that adds a ReleaseDate column as DATETIME, with a default value and a NOT NULL constraint. Review generated SQL for these database-level effects rather than relying only on the model change.

Reversed databases and incomplete schema metadata

Reverse engineering creates classes from tables, attributes from fields, and associations from primary-key and foreign-key pairs. The resulting model can be incomplete when relationships or other details are not explicitly represented in the database schema.

MDriven documents manual persistence-mapping work for missing classes and associations. Its Reverse worker can also inspect tables and columns and suggest model actions, such as adding an association or class. Review these mapping decisions before evolving the database.

Missing stored evolve script

A missing stored script prevents Evolve from comparing the current model-derived script with a prior script. For the MDrivenServer administration database, the documented symptom is an empty Evolve-Script text box. The recovery instructions direct administrators to read the current evolve script, write the version-appropriate script if it is absent, verify that it can be read back, and then try the admin evolve again.

See Documentation:MDriven Server problem with evolve for the version-specific recovery files and instructions.

See also

• HowTos:Reverse Engineer a Database
• Documentation:MDriven Server problem with evolve