| name | aurelius-mapping |
| description | Map Delphi classes to a relational database using TMS Aurelius ORM attributes. Use when the user asks to create entity classes, add Aurelius mapping to existing classes, fix or review mapping attributes, explain how a class is mapped, or work with associations, inheritance, automapping, nullable fields, blobs, or composite identifiers. Triggers on requests like "create Aurelius entities for...", "map this class to Aurelius", "add ORM mapping", "fix the mapping on this class", "how do I map a one-to-many in Aurelius". |
Aurelius Mapping
Map Delphi classes to a relational database using TMS Aurelius attributes. All attributes are declared in unit Aurelius.Mapping.Attributes.
Read references/mapping.md for all attribute syntax, options tables, and code examples. The guidance below covers decisions and rules that the reference does not emphasize.
Approach
New schema (no existing tables): Default to [Automapping]. It infers table names, column names, nullability, and the identifier from field naming conventions, requiring no extra attributes for simple cases.
Legacy or fixed schema: Use explicit attributes ([Table], [Column], [Id], etc.) to match the existing column and table names exactly.
Mixed: Automapping is not all-or-nothing — add explicit attributes only where the defaults need to be overridden.
When the user hasn't specified, ask or infer from context (existing table definitions → explicit; greenfield → automapping).
Critical Rules
These are the most common mistakes. Apply them without exception.
Object lifetime — associations
- Never create or free a many-to-one associated object in the parent's constructor or destructor. Aurelius owns the lifetime of associated entity objects.
- Use plain
T field type for eager associations; use Proxy<T> field type for lazy associations.
- Expose lazy associations through a property that returns
FArtist.Value.
Object lifetime — collections
- Do create and free the
TList<T> container in the parent's constructor and destructor.
- Never create or free the child entity objects inside the list — Aurelius manages them.
- Do not use
TObjectList<T> with OwnsObjects = True.
- For lazy collections, use
Proxy<TList<T>> as the field type. Use SetInitialValue/DestroyValue instead of accessing .Value in constructor/destructor.
Registering entities
Always add RegisterEntity calls in the initialization section of the unit:
initialization
RegisterEntity(TCustomer);
RegisterEntity(TCountry);
This prevents the Delphi linker from removing the class. It is especially important in server applications (XData services) where entity classes may not be directly referenced in code.
Reference
For all attribute signatures, options, and full code examples, read references/mapping.md.
The reference covers: basic entity mapping, automapping rules and overrides, abstract entities, nullable fields, blob fields, many-to-one associations (eager and lazy), one-to-many associations (bidirectional and unidirectional, eager and lazy), collection ordering and filtering, foreign key naming, single-table and joined-tables inheritance, composite identifiers.
