Entity Mapping & Annotations

@Column names the column and describes its shape — length, precision/scale, nullable, unique, columnDefinition — and controls whether it appears in INSERT/UPDATE via insertable/updatable. Omit it and the attribute still maps, using a default name and defaults such as length 255.

@Embeddable marks a value type with no identity. Its fields become extra columns in the owner's table: no separate table, no primary key, no lifecycle of its own. An @Entity has an identifier, its own row, and is tracked individually by the persistence context.

By default (ORDINAL) JPA stores the enum constant's declaration index as a number, so reordering or inserting constants silently remaps existing rows. EnumType.STRING stores the constant's name, which is stable under reordering and readable, but breaks if you rename a constant.

Object.equals compares references. That is correct only while every instance comes from one open persistence context, which guarantees one object per row. As soon as entities are detached, re-loaded in another session, merged, or compared across sessions, two objects represent the same row and reference equality says false — so you override equals/hashCode using a stable identifier.

IDENTITY uses an auto-increment column, so the id is known only after the INSERT. SEQUENCE calls a database sequence, so the id is known before. TABLE keeps counters in a table row. UUID generates one in the JVM. Hibernate's AUTO picks SEQUENCE, or UUID for UUID-typed ids.

Access type is decided by where the mapping annotations — specifically @Id or @EmbeddedId — are placed. On fields it is FIELD access; on getters it is PROPERTY access, and the provider then calls getters and setters instead of touching fields. @Access overrides the default.

AttributeConverter<X,Y> defines convertToDatabaseColumn and convertToEntityAttribute, translating between a Java type and a column type. Attach it per attribute with @Convert, or globally for the type with @Converter(autoApply = true). Identifiers, version attributes and associations cannot be converted.

@EmbeddedId puts the key in one @Embeddable field, so you access and query it through that field (entity.id.orderId). @IdClass declares the key properties directly on the entity with @Id each, plus a mirror class listing them; queries use flat paths. Both key classes need Serializable, a no-arg constructor and equals/hashCode.

LocalDate maps to DATE, LocalTime to TIME, LocalDateTime to a timestamp without zone (wall-clock, no instant), Instant to a point on the timeline, and OffsetDateTime/ZonedDateTime carry an offset that survives only with a with-time-zone column or explicit offset storage. Use Instant for events, LocalDate/LocalDateTime for calendar facts.

Before persist the generated id is null, so hashCode is computed from null; at flush the id is assigned and hashCode changes, but the object still sits in the bucket chosen by the old hash — contains() and remove() miss it. Fix: constant hashCode plus id-equality, or an identifier assigned before persist.

allocationSize is how many ids Hibernate reserves per sequence call and hands out from memory — default 50. If the database sequence increments by 1 while Hibernate assumes 50, the reserved block overlaps values a later call returns, producing duplicate primary keys.

With IDENTITY the id only exists once the row is inserted, but Hibernate needs an id to key the entity in the persistence context. So it executes the INSERT immediately at persist(), one statement per entity — nothing is queued, so nothing can batch. A sequence gives the id up front, letting inserts queue and batch at flush.

SINGLE_TABLE puts the whole hierarchy in one table with a discriminator column; fastest, but subclass columns must be nullable. JOINED gives each class its own table joined by primary key; normalized with NOT NULL constraints, costs joins. TABLE_PER_CLASS gives each concrete class a full standalone table; polymorphic queries become UNIONs.

ImplicitNamingStrategy invents a logical name when the mapping does not state one (entity name, field name, join-table name). PhysicalNamingStrategy then turns every logical name - invented or explicitly annotated - into the actual database identifier Hibernate emits in SQL.

@Formula maps a property to a raw SQL expression that Hibernate splices into the entity's SELECT. It is read-only: never written on INSERT or UPDATE, recomputed by the database on each load, and stale in memory until the entity is refreshed.

They tell Hibernate which concrete subclass a row belongs to. @DiscriminatorColumn names that column on the root entity; @DiscriminatorValue sets the value stored per subclass. Defaults: a String column named DTYPE holding the entity name. Hibernate writes it on insert and filters on it when querying a subclass.

Set hibernate.physical_naming_strategy to a snake-casing implementation - Hibernate ships CamelCaseToUnderscoresNamingStrategy. It rewrites every table, column and sequence name, including ones written explicitly in annotations, so you do not annotate each field.

Both exclude a field from persistence, but the Java keyword also excludes it from Java serialization while @Transient does not. @Basic is optional metadata for simple attributes: optional=false is a nullability hint and fetch=LAZY is only a hint too.

They remove the column from generated INSERT and UPDATE statements while it is still read on SELECT. Use them for database-maintained columns and for a foreign key mapped twice — once as an association, once as a plain field. The in-memory value can go stale.

Use @AttributeOverride on each embedded attribute to rename the columns, one per property. Nested embeddable properties are addressed with dotted paths like "geo.latitude". Associations inside the embeddable are renamed with @AssociationOverride instead.

@Temporal exists only for the legacy types java.util.Date and java.util.Calendar, which are ambiguous: it tells the provider whether to map DATE, TIME or TIMESTAMP. java.time types already carry that meaning, so @Temporal is unnecessary and not permitted on them.

Mark the property with Hibernate's @Generated, naming the events (INSERT, UPDATE) at which the database produces it. Hibernate then omits the column from the write statement and reads the value back — with an extra SELECT, or via INSERT ... RETURNING on dialects that support it.

@CreationTimestamp and @UpdateTimestamp are produced in the JVM by Hibernate when it inserts or updates the entity, so they depend on the app server's clock and are skipped by bulk JPQL updates and native SQL. Database defaults and triggers fire for every writer but need a read-back to appear in the entity.

@NaturalId marks the domain's real business key alongside the surrogate @Id. Hibernate then offers byNaturalId()/bySimpleNaturalId() lookups that resolve the natural key to the primary key and load through the normal identity map and caches, so a repeat lookup can avoid SQL entirely. It also enforces immutability by default.

@MappedSuperclass only shares column mappings: it has no table, cannot be queried, and nothing can reference it as an association — each subclass table simply gets copies of its columns. Entity inheritance makes the base a real queryable type with polymorphic queries and associations. Choose by whether you need polymorphism.

The implicit strategy is skipped - a name was given. The physical strategy still runs: the annotated string is the logical name, and every logical name is converted by the physical pass, so it can be rewritten.

name, schema and catalog become the qualified table name in every statement, so they are runtime. uniqueConstraints and indexes are consumed only by schema generation — the provider never enforces them in memory, so violations surface as database errors at flush.

Conversion happens at parameter binding and result extraction only. Bound query parameters are converted; native SQL is not, and any database-side expression — sorting, LIKE, functions, index order — sees the stored form ('Y'/'N'), not the Java value.

In Hibernate 6, annotate the attribute @JdbcTypeCode(SqlTypes.JSON) and give the column a json/jsonb definition; Hibernate serializes the object for you. Watch dirty checking of mutable payloads, whole-document rewrites, and that JPQL cannot navigate inside the document.