ORM

Object-relational mapping is a technique for storing and loading objects in a relational database without writing SQL by hand for every operation. Classes are mapped to tables, fields to columns and associations to foreign keys, usually through annotations such as @Entity, @Id and @ManyToOne. The ORM provider generates SQL, tracks changes to loaded objects and writes them back at commit. In Jakarta EE the standard API is Jakarta Persistence, implemented by providers such as Hibernate and EclipseLink. ORM removes a lot of repetitive data-access code, but developers still need to understand the SQL it produces to avoid performance problems.

A persistence unit is a named configuration that tells Jakarta Persistence which entity classes to manage, which data source to use and which provider and properties apply. Traditionally it is declared in META-INF/persistence.xml; Jakarta Persistence 3.2 also allows it to be defined programmatically. The application server or framework uses it to create an EntityManagerFactory, from which EntityManager instances are obtained. An application can have several persistence units, for example one per database. In Spring Boot the persistence unit is usually configured automatically from properties, but the concept is the same.

The impedance mismatch is the set of structural differences between object models and relational schemas. Objects can be fine-grained, while tables group many values into rows. Objects use inheritance; tables have none. Objects have identity, equality and references, while rows have primary keys and foreign keys. Objects navigate associations by following references; databases use joins. An ORM translates between the two worlds, but it cannot remove the differences. They still influence design decisions, such as choosing an inheritance mapping strategy, and performance, such as lazy loading causing N+1 queries when an object graph is traversed carelessly.

By default, an enum field is stored as its ordinal, its position in the enum declaration. If someone later inserts a new constant in the middle or reorders constants, existing rows silently take on a different meaning: an order stored as 2, meaning SHIPPED, might suddenly read as CANCELLED. @Enumerated(EnumType.STRING) stores the constant's name instead, which is stable when constants are added or reordered, and readable when querying the database directly. Renaming a constant still requires a data migration. For more control, a JPA AttributeConverter can map enums to explicit codes, which also keeps database values independent of Java names.

Make the SQL visible and testable. During development, enable SQL logging with bind parameters and the provider's statistics, so you can see how many statements each use case runs. In integration tests, assert statement counts for important use cases, so an accidental N+1 query fails the build. Compare generated DDL against the migration scripts. In code, choose fetch strategies deliberately: use fetch joins or entity graphs where related data is needed, projections or DTO queries for read-only views, and JDBC batching for bulk inserts and updates. In production, monitor slow queries at the database level.

JPA is designed for loading, changing and saving entities in transactional use cases. It is a poor fit for bulk, set-based operations such as updating a million rows, where loading each entity is wasteful; for reporting queries with heavy aggregation and many joins; and for database-specific features such as window functions, recursive queries or stored procedures. For these, use native SQL, a query library such as jOOQ, or database-side code, often alongside JPA in the same application. The key is to choose per use case and keep the boundary clear, so each part uses the tool that fits.

Treat the database schema as code with its own history. Write versioned migration scripts with Flyway or Liquibase and make them the single source of truth; they run automatically at deployment, in the same order in every environment. Disable the provider's automatic schema generation in all shared environments, because it cannot handle data migrations or renames safely. Use the provider's validation mode or integration tests to check that entity mappings match the migrated schema, so mismatches fail early. For zero-downtime deployments, design migrations in expand-and-contract steps so old and new application versions can run against the same schema.

The first risk is hidden cost: an innocent-looking navigation through an object graph can trigger hundreds of queries, so latency and database load grow unseen until production traffic arrives. The second is coupling: a large entity model shared across many teams or bounded contexts becomes a place where everyone's changes collide, much like a shared database. The third is scalability: a model designed for convenience can force chatty access patterns that are hard to optimise later. Mitigate them with per-use-case queries and DTOs, separate models per bounded context, measured SQL in tests, and clear guidance on when to bypass the ORM.