aurelius-mapping

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);