Mapping & Identity

An always-on filter is a predicate declared once on a mapped type, such as live-rows-only or current-tenant-only, that the layer adds to the WHERE clause of the statements it generates for that type, so no caller has to restate it.

Only when the insert actually runs. Until that statement reaches the store the key field is empty, so asking a pending object for its identifier forces the layer to write that row immediately and read the generated value back.

Either a type-marker column stored with the row names the class, or the layer discovers which subtype table holds a row for that key. The marker is free with the read; discovery costs a join or a probe per subtype.

Mapping rules have four possible homes: on the class itself, in an external configuration document, in a startup configuration API, or nowhere — derived by convention from class and property names. Most layers mix conventions with targeted overrides.

Flattening stores a composite value's fields as extra columns on the owner's own row rather than in a table of its own. The value gets no key and no independent lifecycle: it is loaded, written and discarded with the owner.

The collection is the inverse end, and the layer builds link statements only from the owning end, so the flush finds nothing to write. Fix it with one method that sets both ends, and keep the raw setters private.

Because the statement follows where the subtypes' columns live: one shared table means one SELECT, per-subtype tables mean an outer join per subtype, and per-class tables mean a union arm each, so cost grows per subtype.

A naming strategy derives every identifier nobody declared, turning class names into table names and property names into column names, usually with case conversion. Replace the strategy for a schema-wide rule; declare one name for a legacy exception.

Position stores the constant's index in declaration order, so inserting or reordering constants silently re-points every existing row. The name survives reordering but breaks on a rename. An explicit, stable code declared per constant avoids both failure modes.

Any path where the layer does not compose the SQL: hand-written statements, set-based updates and deletes, a key lookup answered from objects already tracked, an object served from a long-lived cache, and rows the database itself changes.

Usually the predicate never went through the converter, so the object-side value was compared against the stored encoding. Set-based and hand-written statements bypass conversion entirely, and ordering compares the stored form rather than the domain's order.

The stored column is identical; the services differ. A key value is an ordinary field with no navigation, no deferred loading and no cascade. A mapped reference buys those, at the cost of loads that fire behind a field access.

Registered callbacks run around insert, update and delete and set the fields before the statement is built — the time from an injected clock, the actor from ambient context — so callers never assign audit columns.

That it behave as a value: all parts populated, equality and hashing over every part, and no mutation once the row exists. The layer files objects under that whole value, so a changed key loses the row it addressed.

The layer claims a whole range from a store-side counter in one round trip, then hands values out from memory. The identifier therefore exists the moment the object is constructed; whatever is left in the range when the process stops is discarded.

A deferred stand-in has to be built as some class, and the key alone does not say which subtype the target is. So the layer either reads the target anyway or returns a base-typed stand-in that fails type tests.

Most mappers need a construction path taking no arguments, members they can read and write, and classes open enough to substitute an intercepting stand-in; assigned collections are replaced by tracked wrappers. Each demand weakens an invariant the constructor would enforce.

Layers differ: some return an object whose fields are all null, others return a null reference for the whole value. Either way the round trip can be asymmetric, producing null checks that never fire and updates with nothing to update.

A declared cascade is an in-memory graph walk at flush: the layer follows marked links and emits one ordinary statement per object. A schema cascade runs inside the engine and covers every writer.

Because it can no longer compute a difference. Assigning a new collection to the mapped field discards the snapshot the layer diffed against, leaving a wholesale delete-and-reinsert as the only safe write.

Only for a narrow, explicit block that genuinely must see excluded rows — a support view, a purge, a restore. What breaks is downstream: unfiltered objects stay in the tracked set and reach code that still assumes the filter.

Never let the hash depend on a key that is filled in later: it changes when the row is written and strands the object inside any hash container it already joined. Keep the hash stable, and compare identifiers only when both exist.

Usually by a marker meaning never-written: an empty identifier, an absent version, or the layer's own tracking. An application-assigned key is populated from birth, so the layer reads a new object as existing and updates a row that never existed.

Hydration cannot resolve the marker to a class, so the read fails, usually the whole query rather than the row, and it surfaces on base-type queries that select every marker. Fix the reader first, then the rows.

Undeclared elements still get values: which members are mapped, nullability, text length, numeric precision, the derived identifier. The risk is not that defaults are wrong but that a later reader cannot tell an unconsidered default from a deliberate decision.

Change detection compares the current state against the snapshot taken at load. If the snapshot holds the same mutable instance the code edited, both sides show the edit, the comparison finds no difference, and no update is emitted.

Map a hierarchy only when the database must resolve the type: base-typed references, authoritative cross-type queries, shared keys or hierarchy-wide rules. Otherwise keep the base class unmapped, or serve cross-type screens from a read-only projection.

Map the domain class directly while its shape and the row's shape stay close and the mapper's demands are tolerable. Introduce a separate persistence model when the shapes genuinely diverge — accepting duplicated types and translation that must move together.

Treat them differently: a missing tenant should fail the unit of work, since filtering on nothing either leaks or silently matches no rows, while a missing actor should resolve to a named synthetic principal rather than null.