Object-Relational Mapping

## What an Identity Field is An Identity Field is a property added to a mapped class - conventionally called `id` - whose value mirrors the primary key of the table row that object represents. Mechanically, the lifecycle looks like this: 1. An application creates a new domain object with no identity value set (null, zero, or another 'unsaved' sentinel). 2. When the object is saved, the mapper issues an `INSERT`; the database (or the application, for client-assigned keys such as UUIDs) produces a primary key value, and the mapper writes that value back into the object's identity field. 3. From that moment the object is 'persistent': future `SELECT`, `UPDATE`, and `DELETE` statements target the row identified by that field, and the mapper can tell apart 'this object needs an INSERT' from 'this object needs an UPDATE' purely by checking whether the identity field is set. ## Two notions of sameness The pattern exists because in-memory objects and database rows have two different notions of sameness that do not naturally line up. - **An object** has reference identity (is this the exact same object in memory) and, if you define one, value equality (do two objects have equal fields). - **A database row** has row identity, defined by its primary key, which is stable and independent of the row's current column values. Without an explicit identity field, there is no way for application code to ask 'are these two Customer objects, loaded by two different queries, actually the same customer row?' - they might be two distinct object instances with (momentarily) identical field values, or one might be stale. The identity field is the anchor that survives across queries, across sessions, and across process boundaries (for example, an object serialized to JSON for a web form and then deserialized on form submission still carries its id, so the server knows which row to update). ## Surrogate versus natural key The main design trade-off is surrogate versus natural key as the identity field. - **A surrogate key** (autoincrement integer, database sequence, or UUID) decouples identity from business data: identity never changes even if every business attribute of the row changes, and it stays a single, simple column regardless of how many attributes make the entity 'unique' in business terms. The cost is that it's meaningless outside the application, requires an extra column, and - for autoincrement/sequence keys - complicates distributed or offline object creation, since the ID often isn't known until the row is actually inserted (this is one reason systems that create IDs offline, like mobile apps with local-first writes, favor UUIDs despite their larger size and index-fragmentation cost). - **A natural key** (e.g. an email address or national ID) avoids the extra column and is meaningful on its own, but breaks the assumption that identity should never change: if the 'natural' value must later be edited, every foreign key referencing it has to cascade, and composite natural keys make foreign-key mapping and `equals()` implementations noticeably more complex. ## The two failure modes 1. **The most common production failure mode** is building `equals()`/`hashCode()` naively off the identity field. If a newly created (transient) object is placed into a `HashSet` or used as a `HashMap` key before it is saved, its hash code is computed from a null or default identity value; once the object is persisted and the identity field is populated, its hash code changes, and the object effectively 'disappears' from the collection it was already stored in, because the collection is still bucketed by the old hash. This is a well-known gotcha with JPA/Hibernate entities and is usually fixed by excluding the identity field from `equals()`/`hashCode()` until it is set, or by using a business key, or by overriding `equals()` to fall back to reference equality for transient instances. 2. **A second failure mode** is conflating identity with business meaning: reusing a mutable natural key as the identity field means an innocuous business change (a customer changes their email) turns into a data-integrity migration across every table that stores a foreign key to it. ## Where you have already seen it Hibernate/JPA's `@Id` annotation, Rails ActiveRecord's implicit `id` column, and Django's automatic `pk` field are all direct applications of this pattern - and in each case the identity field also powers the ORM's first-level identity map, so within one unit of work, two loads of the row with id=42 return the very same object reference, not just equal ones. The pattern isn't ORM-specific either: a REST API returning {"id": 42, ...} is exposing the identity field to clients precisely so a later PUT or PATCH request can say which resource it means to modify.