You use object-relational (OR) mapping to persist the classes and relationships in your MDriven model to a database, while working with the model rather than writing the database access mapping yourself.
What OR mapping does
OR mapping, also called persistence mapping or ORM, describes how an object-oriented model is stored in a relational database.
In MDriven, the mapping connects model elements to database structures:
| Model element | Database representation | Example |
|---|---|---|
| Class | Table | A Customer class is persisted in a customer table.
|
| Attribute | Column | A Customer.Name attribute is persisted in a name column.
|
| Association | Link between persisted rows | A customer-to-order association is represented so that orders can be connected to their customer. |
| Inheritance | Configured table strategy | A superclass can have its own table, or its attributes can be mapped into child-class tables. |
The MDriven Framework uses the mapping to translate object-oriented operations into the SQL operations required to select, insert, update, and delete persisted data. This separates your model from database-specific storage details.
Start with the model and default mapping
For normal SQL persistence, MDriven derives a default mapping from your model. You usually keep that default mapping and evolve the database from the model.
For example, if your model contains a Customer class with Name and Email attributes, the default mapping defines how the class and its attributes are persisted. When you later add Customer.Status, MDriven can compare the previous mapping with a newly calculated mapping to determine the database changes needed during evolution.
The calculated mapping is normally stored in the database as part of the evolution process. You do not normally need to generate and maintain a mapping XML file yourself.
For the complete SQL persistence workflow, mapping providers, and database evolution behavior, see Documentation:Working with Code and Persistence Mapping.
Use the right mapping topic
OR mapping includes several related concerns. Use the dedicated page for the concern you need to change.
| If you need to... | Go to |
|---|---|
| Understand available persistence mapper implementations and the persistence abstraction | Documentation:Persistence mappers |
| Configure table names, key-column naming, inheritance mapping, or mapping providers for SQL persistence | Documentation:Working with Code and Persistence Mapping |
| Map a modeled attribute type to a .NET type or select a persistence mapper for a type | Documentation:Type mapping, OR-Mapping |
| Change the default mapping for a particular database or legacy schema | Documentation:Custom OR Mapping |
| Create a model from an existing database | HowTos:Reverse Engineer a Database |
Persistence mappers
A persistence mapper is the part of the persistence setup that knows how values and objects are handled by the data store. MDriven provides built-in persistence mappers for:
- XML files
- SQL Server
- MySQL
- SQLite
See Documentation:Persistence mappers for the available mapper options and their role in the architecture.
Type mapping and attribute persistence
The type written on an attribute in the model is a common name. Before code is derived and the runtime model is created, that common name must resolve to a .NET type. The type can then be handled by one or more persistence mappers.
For example, a modeled Text attribute can resolve to System.String. A persistence mapper then determines how that value is stored in the database.
The preferred approach is to leave an attribute's PersistenceMapper property set to <Default>. MDriven then resolves the common name to a .NET type and selects the persistence mapper for that type. Set a specific persistence mapper on an attribute only when that attribute has storage requirements that differ from the default.
To expose the PersistenceMapper property on model attributes, set the package's ORMappingConfigMode to Medium or All. For configuration details, including EcoDataTypes.xml and custom type handling, see Documentation:Type mapping, OR-Mapping.
Configure mapping when the defaults do not fit
Default mapping is intended to cover common models. Configure it when you need the generated schema to follow an existing database convention or when an inheritance strategy must be changed.
One example is an abstract default superclass. By default, a default superclass can receive its own table. If you want its attributes stored in each inheriting class's table instead, configure the superclass for child mapping through a DefaultORMappingBuilder.
A DefaultORMappingBuilder can also control conventions such as:
- Foreign-key column naming. For example, use a pattern ending in
ID. - Primary-key column naming. For example, use
<TableName>IDinstead of the defaultEco_Id. - Mapping behavior for the default superclass.
Clear key naming makes a schema easier to inspect and reverse engineer: a column ending in ID is easier to recognize as a key or foreign-key value. Configure these conventions deliberately, because they affect the generated schema. Follow the procedure in Documentation:Working with Code and Persistence Mapping or the focused example in Documentation:Custom OR Mapping.
Mapping providers
When working with a DefaultORMappingBuilder, distinguish the mapping providers by purpose:
| Provider | Purpose |
|---|---|
NewMappingProvider
|
Describes how the mapping should look after the database is evolved. |
OldMappingProvider
|
Describes the mapping in the current database. |
RunTimeMappingProvider
|
Supplies the mapping used when the application accesses the database at runtime. |
For a custom default mapping builder, connect it to both NewMappingProvider and RunTimeMappingProvider. The first is used for design-time create and evolve operations; the second is used when the application runs.
Scope and limitations
The SQL mapping configuration described in Documentation:Working with Code and Persistence Mapping applies to persistence in an SQL database. It does not apply to systems using XML persistence mappers or MDrivenServer; MDrivenServer has the described settings as defaults.
If you are integrating with a legacy database, begin by understanding or reverse engineering the existing schema, then apply only the mapping customizations needed to match it. See HowTos:Reverse Engineer a Database and Documentation:Custom OR Mapping.