Data Access & ORM Concepts

The owning end is the side whose state the mapper turns into the foreign-key or junction-row statement. The other end is mapped for reading and navigation: changing it alone normally produces no SQL at all.

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.

Rather than one statement per touched stand-in, the layer gathers the keys of other unfilled stand-ins of the same kind and fetches them together with a set-membership predicate, turning N secondary statements into roughly N divided by the batch size.

The join returns one row per matching child, with the parent's columns repeated on every one of them. A layer that produces one result entry per row therefore hands back the same parent once per child row.

Eager means the linked data is loaded as part of the read that returns its owner - in the same statement through a join, or in an immediate follow-up statement - so nothing has to load later when code touches the link.

Any access that needs data the row has not supplied fires the load: reading a mapped field, iterating or sizing a collection, or calling a behaviour method on the stand-in. Reading the identifier it already holds does not.

The read fails at that moment. A deferred link still needs its own query to fill itself, and the unit of work and connection that would run it are gone, so most layers raise an error instead of returning data.

A statement count exposes the shape of the access pattern - one statement per row versus a fixed few - independently of machine speed or data volume. Duration says only that something was slow, once it already is.

Batching sends many same-shaped statements in one round trip, one parameter set per row, instead of a request-and-wait per row. The database still does each row's work; what disappears is the per-row waiting.

Four families: pull the link into the parents' statement with a join fetch, load the whole page's links in one extra bulk statement, project the read down to the fields it needs, or serve the link from a cache.

The line that first touches a deferred link while iterating — an ordinary field read, not a query call. The list read is one statement; every touch inside the iteration adds another.

A mapper holds saved objects in an in-memory identity map and defers the write until a flush. A read by the same id hands back that instance, so the assertion passes whether or not a statement ever reached the database.

A tracking layer copies each loaded row's column values into a private snapshot beside the object. At flush it compares the live object against that snapshot; fields that differ become the UPDATE, and an object with no difference produces none.

Detaching removes the object from change tracking: later edits are no longer noticed or written, edits not yet flushed are usually lost, and links left as unresolved stand-ins have no set behind them to load through.

A flush turns the unit of work's accumulated in-memory changes into SQL statements sent on the already-open transaction. A commit ends that transaction, making the changes durable and visible to others. Flushed-but-uncommitted work is still discarded by a rollback.

You get the same object both times. A tracked set's identity map, keyed by type plus identifier, makes one row exactly one object for the life of that set; a by-key lookup it already holds needs no statement.

Transient means never stored and not watched. Managed means the tracked set holds it and will write its edits. Detached means it once was managed but its set has ended. Removed means a delete is planned.

An after-commit callback runs only once the transaction has actually committed, so its side effect can never announce a change that later disappears. Code written in line after the last save still sits inside the open, undecided transaction.

A transaction commits or rolls back as a whole, so the boundary must enclose everything that has to be all-or-nothing - usually one use case. Per-call commits make each write permanent on its own, so a later failure leaves half-written data.

A translation step maps engine-specific codes and messages onto a small portable set of failure kinds - constraint violation, deadlock victim, serialization failure, lock or statement timeout, lost connection - so calling code branches on the kind, not on a number.

The layer turns the read into a locking read, so the row is claimed for your transaction as it is fetched. Other writers of that row wait. The lock is released only when the transaction boundary ends.

A read-only unit stops keeping a value snapshot of each loaded object, so no dirty check and no flush run at the end. Reads get a lighter, cheaper path, and anything modified inside the unit is simply not written.

Schema-from-mapping modes differ in how far the layer will change the database: re-create drops and rebuilds the mapped tables, auto-alter adds what is missing in place, validate-only compares and refuses to start on a mismatch, and none touches nothing.

Replaying every change unit from empty proves the chain itself still builds a valid schema, catching ordering and dependency errors that a developer's long-lived database hides. Running only the newest unit leaves the rest of the chain untested.

Write the predicate so it selects only outstanding work, compute values absolutely from source columns rather than adding to the current one, guard inserts on a unique key, and commit progress so a restart continues where it stopped.

SQL statements run set-based against the schema as that point in history left it; no later code edit can alter them. Running the change through the mapping adds logic the database lacks, but ties a historical step to moving code.

A diff compares two end states, not the edit that produced them, so it cannot see intent. A renamed field reaches the script as a dropped column plus an added one, which destroys the data unless a human rewrites it.

A set-based update sends one UPDATE ... WHERE statement to the database through the layer. Load-modify-flush instead reads matching rows into objects, changes them in memory, and lets the layer write each changed object back.

An absent filter should contribute no predicate at all. A constant-true pad is only a concatenation crutch, a self-comparison silently drops rows holding no value, and a parameter-driven catch-all emits a different statement whose one plan must serve every combination.

A native statement is SQL you write in the database's own language and hand to the layer unchanged, rather than an object-level query it translates. Its rows map back to entity objects, transfer models, or scalars.

An object-level query is text naming mapped classes and fields, not tables and columns; the layer parses it and emits SQL. Being text, a typo or a renamed field surfaces only at parse time - startup or first run.

A projection asks the statement for only the fields a use case needs and materialises them as a scalar, a tuple or a small transfer type, so the row is never turned into a tracked mapped object.

A cached entry goes stale when the row it copies changes and nothing removes the copy. Any write the caching layer never sees can leave one behind: a set-based statement, a native statement, another service, or an operator at a console.

A shared cache holds mapped row state by type and identifier outside any single unit of work, so a load by key that hits it returns an object with no statement sent. Filtered queries still reach the database.

Read before the unit of work opens, so a hit costs no connection or transaction. Populate only after the commit returns, never from inside the transaction or the mapper's flush path, so nothing that could still roll back is published.

Identity, deferred completion and change detection. A cached answer is a detached snapshot with nothing behind it, so no shared instance, no link that can still load, no dirty checking. In exchange it skips the whole assembly path and travels between processes.

Removing before the write stops further hits on a copy about to become wrong; removing again after the commit drops the pre-image that a concurrent reader reloaded and put back during the write. Populate only after a real commit.