Why

So, "there are quite a few ORM tools out there, why develop another one?" you say. Well, because EzQu was first released in 2008, long before most mature ORMs existed. It's intentionally lightweight and straightforward. Back then J2EE was complex and Hibernate was still evolving annotations and required a custom query language with weak typing. Since then, Centimia Ltd. had been using EzQu and employed it across several large projects that use Oracle, MySQL, MariaDB, H2, and Microsoft SQL Server. For no good reason we never released it until now.

EzQu lets Java developers who already understand SQL start working quickly without learning a new language. It handles simple POJO mapping as well as complex annotated entities, supports on-the-fly join mappings, and offers strong typing even in aggregate queries.

EzQu keeps it simple, excelling at converting relational ResultSets into objects. Developers can use it at any level, from basic mapping to fluent, type-safe APIs that control CRUD operations and all O2O, O2M, M2M, M2O relationships.

See some examples

What

EzQu wraps around JDBC and functions as a bridge between a Java application's data-domain layer and a relational database. The application uses EzQu's APIs to load, persist, query, and otherwise manipulate domain data. It is not a Jakarta-JPA provider and has no plans to become one.

EzQu is an Object Relational Mapping (ORM) tool that enables pure Java grammar. With EzQu, you can persist objects into the database with One2One, One2Many, Many2One, and Many2Many relationships. You can also control the loading of your relationships, whether it be lazy or eager, and manage primary key relations.

Two core building blocks are the EzQuSessionFactory and the Db objects.

When

Object-Relational Mapping (ORM) should not always be the goto choice for an application. EzQu, while a powerful ORM framework for Java, is not without its criticisms. Many of these criticisms stem from the fundamental challenge of bridging the gap between object-oriented programming and relational databases, known as the Object-Relational Impedance Mismatch.

Here are some of the main criticisms leveled against ORM tools and how they are mitigated by EzQu's approach:

• Performance: Slower than Pure JDBC/Native SQL: Because EzQu, like other ORMs, adds a layer of abstraction and generates SQL at runtime, it is inherently slower than writing highly-optimized, hand-tuned native JDBC or SQL queries.
  EzQu still allows the developer to write the queries, like in jdbc and just deal with the mapping to objects. The performance penalty payed in this mapping, which is done via reflection, is negligent.
• The N+1 Problem: Most ORM's suffer from Over-Fetching Data, Poor configuration of fetching strategies (e.g., using default eager fetching for collection-based associations) can lead to the "N+1 select problem," where one query retrieves the main entities, and then N additional queries are executed to fetch the associated collections or entities.
  EzQu offers a depth feature and specialised update annotations that let you control how deeply an object graph is persisted. By leveraging inheritance you can create different "views" of the graph; saving or loading a lightweight view will retrieve/ modify only the specified parts and leave the rest of the database unchanged.
• Complex Query Generation: For complex joins and reports, the SQL generated by EzQu, although usually straight forward, can be inefficient or overly complicated, making performance tuning difficult.
• Caching Complexity: EzQu provides two caching mechanisms: a query cache to reduce duplicate object loading and a per session "multi-call" cache for objects fetched within a single session. Misusing this multi-call cache can lead to data inconsistencies. Unlike many ORMs, EzQu does not support second-level caching, so you avoid that extra complexity.
• You Must Still Know SQL: To diagnose performance issues, understand the generated queries, and handle complex scenarios, a thorough knowledge of SQL and the underlying relational data model is essential. Moreover, there are still some queries you just can not do with fluent api and you may still want to call database functions and procedures.
• Object-Relational Impedance Mismatch: Trying to perfectly map features like object inheritance and deep object graphs onto a relational schema can be challenging and sometimes results in complex, non-performant table structures and mappings.
  EzQu handles two common inheritance approaches:
  • Table per class - each subclass gets its own table that copies all parent columns and adds its own
  • Discriminator - all subclasses share one table that contains the common columns plus subclass-specific columns, with a discriminator column distinguishing them.
  Both strategies are enabled with simple annotations, and EzQu performs the necessary mapping automatically.
• Relationships are Difficult to Manage: Managing complex entity associations (One-to-Many, Many-to-Many) is often cited as a source of frustration, leading to tricky mapping rules and unexpected behaviour, especially when dealing with bi-directional relationships. I hope developers find this easy when using EzQu.
• Proprietary Query Language: Many ORMs introduce their own query language (e.g., Hibernate's JPQL/HQL). While adequate for basic CRUD, it adds a learning curve and still requires the developer to understand SQL. For advanced reporting, data-warehousing, or using vendor-specific features such as LATERAL JOINs, custom window functions, or specialized indexes, these proprietary query languages often prove insufficient.
  EzQU eschews a proprietary query language. Instead it offers an SQL-style fluent API that provides strong typing and compile-time checks, letting developers who already know SQL work seamlessly. It also supports writing raw SQL directly.
• Default Eager Loading: By default, the JPA specification sets FetchType.EAGER for single-valued associations (@ManyToOne and @OneToOne). See the "The N+1 Problem" above to understand why this is a problem.
  EzQu, in contrast, does Eager loading for O2O, M2O relationships but defaults to lazy loading in O2M and M2M relationships.
• Dirty Checking: Certain ORMs perform dirty-checking to skip persisting unchanged objects, cutting needless database updates while potentially hurting performance.
  EzQu EzQu omits dirty-checking. Persisting a single field or an entire row has almost no performance cost. We find that EzQUs depth-control strategies is usually sufficient, easy for developers to manage, and imposes no performance penalty.

Like most ORMs, EzQu follows a Java-first ("code-first") mindset, yet it is permissive and lets the database dictate many details. You can configure indexes, constraints, column names and primary-key types during schema generation, but all constraint enforcement, except 'not null', is left to the database and JDBC driver. For example, a field marked unique is enforced by the DB, not by EzQu.

In a "Java-first" approach, the ORM (Object-Relational Mapping, EzQu) framework treats your Java classes (entities/POJOs) as the single source of truth for your application's data structure.

"Java-First" Advantages

• Schema Generation (DB from Code): You write your Java entity classes first, defining fields, relationships, and constraints using standard Java syntax and ORM-specific annotations (e.g., @Entity, @PrimaryKey, @OneToMany ...).
  EzQu framework reads these annotations and uses them to automatically generate the corresponding database schema (tables, columns, foreign keys). Note that EzQu lacks the capability to update changes into an existing schema.
• Reduced Context Switching: Developers spend more time writing Java code and less time switching to writing and debugging DDL (Data Definition Language) SQL scripts.
• Annotation Simplicity: Complex database features like inheritance mapping (e.g., Joined or Single Table), custom data types, and complex relationships are often easier to define using ORM annotations than raw SQL.
• Portability: Since the schema is generated from a platform-agnostic Java standard, it is much easier to switch between different SQL databases (e.g., MySQL to PostgreSQL) with minimal code changes, if any.

"Java-First" Disadvantages

While convenient, relinquishing control to the ORM can introduce complexity and performance challenges.

• Suboptimal Schema: The schema generated by the ORM may not be the most performant or idiomatic for a specific database system. Database administrators (DBAs) often prefer hand-tuned schemas for efficiency, indexing, and partitioning, which can be hard to achieve purely through ORM annotations. To make it clear, EzQu does not prevent that and can usually map it self to an existing schema. But there are constraints such as 'non-null' constraints are not allowed and using FK defined in the ddl are not recommended.
• Migration Challenges: In a scenario where the database is already running (a "legacy" or "brownfield" project) or is shared by multiple non-Java applications, the Java-first approach is difficult or sometimes impossible. The Java application cannot be allowed to dictate schema changes. EzQu entity paradigms might break, using pojo and fluent api should still work.
• Destructive Operations: Using automatic table generation features (like createTable=true) can be risky in production, as an ORM might drop or modify tables in a destructive way based on a Java entity.
• Tight Coupling: The Java code becomes tightly coupled to the EzQu's specific annotations and configuration, making it harder to switch ORM frameworks later.
• Abstraction Leaks: While the goal is to hide SQL, developers still need a deep understanding of SQL and relational database concepts to ensure that the generated SQL queries and schema are efficient.