aurelius-objects

Approach

Always work through a TObjectManager instance. All persistence methods (Save, Flush, Remove, etc.) are called on the manager, never written as raw SQL.

Loading a known id: use Manager.Find<T>(Id) — returns the cached instance if already loaded, otherwise hits the database.

Loading multiple objects with criteria: use Manager.Find<T> (no argument) to get a fluent query builder, then call .List.

Saving a new object: call Manager.Save(obj) — the manager takes ownership and tracks changes from that point. Save executes the INSERT immediately. Do not call Flush after Save for a new object; that is only for persisting changes to already-managed objects.

Updating a managed object: just change its properties and call Manager.Flush (or Manager.Flush(obj) for a single object). No explicit "update" call needed.

Updating a transient object (from outside the manager): call Manager.Update(obj) — but be aware this writes all properties on flush, not just the changed ones.

Conflicting identity: if an object with the same id is already cached, use Manager.Merge<T>(transient) instead of Update — it copies data into the existing managed instance.

Deleting: call Manager.Remove(obj) — the object must be managed (loaded through this manager or registered via Save/Update).

Critical Rules

Object lifetime

• Managed entities are owned by the manager and destroyed when it is destroyed — do not free them manually.
• When a query returns a list (TList<T>), free the list but not the items inside it — the items remain managed.
• Projection queries (ListValues) return lists with OwnsObjects = True; destroying the list also destroys the items.
• If you need entities to survive after the manager is freed, set Manager.OwnsObjects := False before calling Free.
• Call Manager.AddOwnership(obj) before Save if you want the manager to own the object even when Save raises an exception.