You use persistence to keep the objects defined in your MDriven model available after an application stops, so users can create, change, and retrieve the same business data in later sessions.

Persistence in MDriven

In MDriven, persistence mapping maps model elements to a storage representation. For relational storage, this is an object-relational mapping (ORM): classes map to database tables, attributes map to columns, and the MDriven Framework translates work with objects into the SQL needed to store and retrieve them.

For example, if your model contains a Customer class with a Name attribute, persistence mapping can represent that class as a customer table and Name as a column. Your application works with the Customer object; the persistence mapper handles the database representation.

This separation lets you model and work with business concepts rather than writing database-access code for every object operation. It also means that database-mapping decisions are kept together with the MDriven model and persistence configuration.

Choose a persistence mapper

A persistence mapper is the component that defines how MDriven stores and reads modeled objects. MDriven includes persistence mappers for the following storage options:

Mapper/storage option	Use it when	Example
XML file	You want modeled objects persisted in an XML file.	A model is stored and later read from an XML-based persistence store.
SQL Server	Your application persists model objects in a SQL Server database.	A Customer object is represented by rows and columns in SQL Server.
MySQL	Your application persists model objects in a MySQL database.	A class and its attributes are mapped to a MySQL table and columns.
SQLite	Your application persists model objects in a SQLite database.	A local SQLite database stores the modeled objects.

Read Documentation:Persistence mappers for the mapper overview and available built-in options.

Work from the model

The usual MDriven workflow is to define the business model first, then let MDriven derive the persistence mapping from that model.

1. Create or update classes, attributes, and associations in MDriven Designer.
2. Select a persistence mapper appropriate for the target store.
3. Evolve the database when using SQL persistence. MDriven compares the mapping from the current database with a newly generated mapping to determine the database changes implied by your model changes.
4. Run the application against the runtime mapping, which is the mapping used when the application accesses persisted objects.

For example, adding a Email attribute to Customer changes the model. During database evolution, the generated mapping includes the corresponding persistence change so that the attribute can be stored and retrieved.

Mapping defaults and advanced control

MDriven uses defaults for much of SQL persistence mapping. In normal work, you do not need to generate and maintain mapping XML manually. MDriven stores mapping information in the database during database evolution and uses the prior mapping together with a newly generated mapping to calculate changes.

When you need to tune how a SQL database is represented, you can configure mapping behavior. Examples include:

• Choosing how a package default superclass is mapped. A superclass can be child-mapped so that its attributes are stored in each inheriting class table rather than in a table of its own.
• Changing generated foreign-key column names.
• Changing generated identity-column names.
• Controlling mapping settings for an individual ordinary class after enabling the applicable package mapping configuration mode.

These are database-representation decisions, not changes to the business meaning of the model. Follow Documentation:Working with Code and Persistence Mapping for the SQL-specific configuration, mapping providers, and generated mapping XML workflow.

Attribute-level mapper overrides

MDriven can use a non-standard persistence mapper for an individual attribute. This is an advanced compatibility technique, often used when an existing database stores a value differently from MDriven's standard representation.

For example, MDriven's standard enum storage is the enum value's text representation. A legacy database may instead store an enum as an integer. You can configure an integer mapper for that enum attribute, but queries that use an enum parameter must also be able to resolve an appropriate mapper for the parameter type. Otherwise, a database query can compare text to an integer and fail.

Attribute-level specialization can prevent generic tooling, including MDriven Prototyping and MDriven Server, from working correctly because those tools use the standard mapping conventions. Use it only when the database requirement calls for it, and follow Documentation:Using other than standard Persistence Mappers per attribute for the mapper-resolution rules and enum example.

Identity values

Persistence mapping also controls how object identity is represented in the database. AutoGuid represents a database-generated Guid value. It is a persistence-mapping concern; leave the default behavior in place unless you have a specific database requirement to change it.

Diagnose SQL persistence

When you need to understand database activity, you can enable SQL tracing from the persistence server and capture SQL trace messages. This helps you inspect what is sent to the database and investigate loading behavior. For example, an object list can call EnsureObjects() to load its rows in as few batches as possible.

See Documentation:Ever felt the need to log what your ECO persistence server is up to? for the tracing code and loading example.

Scope and limitations

This page describes MDriven persistence at a conceptual level. The SQL mapping configuration described in Documentation:Working with Code and Persistence Mapping applies to SQL database persistence; it does not apply to XML persistence mappers or MDrivenServer, for which the described settings are defaults.

MDriven does not provide built-in NoSQL database support. To persist to a wanted NoSQL database, you must provide your own persistence mapper.

See also

• Documentation:Persistence mappers
• Documentation:Working with Code and Persistence Mapping
• Documentation:Using other than standard Persistence Mappers per attribute
• Documentation:SQL Server
• Documentation:MDriven Architecture

MDriven persistence mappers

Persistence is the ability of an application to store and retrieve data after the application has ended or the system has shut down. MDriven provides built-in ways to persist modeled objects through different persistence mappers.

MDriven persistence mappers

A persistence mapper connects the modeled object-oriented application to persistent storage. In relational storage, this is object-relational mapping (ORM): classes map to database tables, attributes map to table columns, and the framework translates object-oriented operations into SQL statements.

MDriven provides an abstraction layer so that developers can work with classes, objects, and inheritance rather than directly handling database implementation details.

The documented built-in persistence mappers are:

Mapper	Storage target
XML file	XML-file storage
SQL Server	Microsoft SQL Server
MySQL	MySQL
SQLite	SQLite

Relational mapping configuration

The relational-mapping configuration described here applies to SQL databases. It does not apply to systems using XmlPersistenceMappers. MDrivenServer has the described settings as defaults.

MDriven uses default values for much relational mapping. You can configure those values when the generated mapping must follow particular database conventions.

For a package default superclass, the default behavior is for the superclass to receive its own database table. A default superclass can instead be configured as ChildMapped. In that case, its attributes are stored in the tables of inheriting classes rather than in a table of their own.

You can also configure generated foreign-key and identity-column names. The documented defaults are <Name> for foreign-key fields and Eco_Id for identity columns. For example, foreign-key fields can use <Name>ID, and identity columns can use <TableName>ID.

To influence generated mapping:

1. Add a DefaultORMappingBuilder component to the PMP designer.
2. Set NewMappingProvider to the DefaultORMappingBuilder.
3. Set RunTimeMappingProvider to the mapping used at runtime.
4. If ordinary classes do not show mapping properties, set OrMappingConfigMode on the package.

To inspect generated mapping XML, generate code, build the project, switch to PMP view, validate the model, and generate the default mapping XML.

Mapping provider	Purpose
NewMappingProvider	Provides information about how mapping should look after database evolution.
OldMappingProvider	Provides information about mapping in the current database.
RunTimeMappingProvider	Provides the mapping used at runtime when the application accesses the database.

Normally, generating the mapping XML file is unnecessary. During database evolution, MDriven stores mapping information in the database. It uses the previous mapping and compares it with a newly generated mapping to determine the database-mapping implications of model changes.

Attribute-level mapper customization

MDriven allows persistence mappers to be selected or created for individual attributes. This can be useful when an existing database uses a representation that differs from the standard mapper.

For example, MDriven's standard enum representation is the enum value's text representation in the database. A legacy database may instead store application-level enums as integers. In that situation, an integer-oriented enum mapper such as GenericEnumAsInteger may be used for the attribute.

Limitation: Attribute-level mapper specialization prevents generic tools such as MDriven Prototyping and MDrivenServer from functioning properly because those tools use MDriven's standard mapping.

NoSQL databases

MDriven does not support NoSQL databases unless you provide a persistence mapper for the selected NoSQL database.

See also

• Documentation:Persistence mappers
• Documentation:Working with Code and Persistence Mapping
• Documentation:Using other than standard Persistence Mappers per attribute