You can use an additional or custom persistence mapper (PMapper) when your database is not covered by the built-in mappers and you have a .NET ADO-based driver for it.
A persistence mapper, also called an object-relational mapping (ORM) mapper, translates the model's object and attribute operations to the SQL and database types used by a specific database. Start by checking the built-in persistence mappers: XML file, SQL Server, MySQL, and SQLite. If your target database is not among them, use an existing mapper for a similar database as the starting point.
Additional mapper archive
An archive of persistence mappers that were not included in the official build is available at PMsNotInOfficialBuild2014. The archive includes examples for:
- Firebird
- Dbx
- Blackfish
- Mimer
- NexusDB
- Sybase
- Bdp
Treat these as implementation patterns rather than interchangeable database drivers. Select the sample that is closest to the database and driver you use, then review and adapt it for your environment.
Build a mapper for another database
Use this process when no supplied or archived mapper fits your database.
- Confirm that the database has a .NET ADO-based driver. The mapper must work with that driver's database access behavior.
- Choose a mapper from the archive as a pattern. For example, when your driver has SQL syntax or type behavior that differs from the built-in SQL Server mapper, begin with an archived mapper that has similar conventions instead of assuming SQL Server SQL will work unchanged.
- Adapt the mapper to the target database's SQL dialect and type handling.
- Test the mapper against the database before relying on it in an application.
The required changes are usually driven by subtle SQL-dialect differences. Compare the target database with the sample mapper for areas such as the SQL it produces and how model attribute types are represented by the database driver. The archived mappers provide examples of variations that have already been handled for other databases.
Choose the right level of customization
A database-specific PMapper is different from choosing a different mapper for one attribute. Use a database-specific mapper when the database or its driver requires different general SQL or type behavior. Use an attribute-level selection when one modeled attribute needs special persistence behavior.
For example, an application that stores an enum as an integer in a legacy database may need an attribute-specific enum mapper rather than a new database mapper. See Using other than standard Persistence Mappers per attribute for that scenario and its query implications.
For details on registering a mapper, selecting it by common name or .NET type, and overriding the mapper selected for an attribute, see Type mapping, OR-Mapping. Register a mapper before the EcoSpace starts; registering it after startup is too late.
Mapping design considerations
A PMapper controls database-oriented type and SQL behavior. It does not replace the model's object-relational mapping decisions. If you need to alter how classes, keys, inheritance, or tables are mapped, use Custom OR Mapping in addition to the appropriate persistence mapper.
For example, you might use a custom PMapper because a database requires different SQL syntax, while separately configuring custom OR mapping to avoid creating a table for a modeled default superclass. These are related but distinct changes.
Limitations
- The additional mappers are not part of the official build.
- A mapper that works with one database driver is not guaranteed to work with another driver for the same database.
- Per-attribute persistence-mapper specialization can prevent generic tools such as MDriven Prototyping and MDriven Server from functioning correctly when those tools depend on the standard mappers.