Jimmer ORM Documentation

Jimmer provides a comprehensive suite of features for JVM developers (Java & Kotlin):

Querying Capabilities

• Flexible APIs: Provides a robust Java DSL and an elegant Kotlin DSL.
• Advanced SQL Support: Supports Derived Tables, CTE (Common Table Expressions), and Recursive-CTE. You can mix native SQL expressions into the DSL to use database-specific features.
• SQL Optimization: Automatically removes unused table joins, merges logically equivalent joins, and merges logically equivalent implicit subqueries. It also optimizes count queries for pagination.

DTO Management

Jimmer uses a compile-time code generator to make DTOs extremely efficient. It supports three main types:

• Output DTO: Used for the return values of complex queries.
• Input DTO: Used as parameters for complex save operations.
• Specification DTO: Used as parameters for complex queries.

Graph Operations

• Reading: Supports querying any graph structure without the N + 1 problem. Objects at any level can be partial, and self-referential properties can be queried recursively.
• Writing: Supports saving any graph structure using database upsert (merge) capabilities. Multiple objects at any level are handled via batch DML operations. It also automatically translates constraint violation exceptions.

Performance and Caching

• Multi-level Caching: Supports multiple cache levels where each level can use different technologies. It caches not just objects, but also associations, computed values, and multiple views.
• Consistency: Automatically maintains cache consistency.

Integration

• Fast support for GraphQL.
• Client contract generation based on doc comments (OpenAPI, TypeScript).

Jimmer's fundamental philosophy is treating arbitrary data structures as a single unit for read and write operations, rather than just managing individual entity objects.

• Jimmer entities are NOT POJOs: They are designed to express arbitrary shapes of data structures.
• Reading: Jimmer creates and provides you with an infinitely flexible data structure (the shape you requested).
• Writing: You create an infinitely flexible data structure and pass it to Jimmer to be saved.

This approach differs from other technologies:

• vs GraphQL: While GraphQL focuses on querying arbitrary shapes, Jimmer also focuses on how to write them. Jimmer also supports recursive queries on self-referential properties, which GraphQL does not.
• vs JPA: In JPA, the shape of saved data is fixed by configurations like insertable, updatable, or cascade. In Jimmer, you can construct and save partial or complex data structures without prior planning. Jimmer is also the only ORM that supports nested projections based on DTOs.
• vs MongoDB: Unlike MongoDB where document structures are often fixed by design, Jimmer allows you to plan and use any data structure shape for any business scenario on the fly.

Jimmer's fundamental design philosophy is to read and write data structures of arbitrary shapes as a whole, rather than processing individual entity objects.

Key distinctions include:

• Jimmer entities are not POJOs: They are designed to express complex, infinitely flexible data structures.
• Reading: Jimmer creates flexible data structures (including nested associations and computed values) and passes them to you.
• Writing: You can construct a data structure of any shape and pass it to Jimmer to save. This allows for saving incomplete objects (only the fields you provide are updated) and handling complex hierarchical relationships without prior design of fixed DTOs.
• Comparison with JPA: Unlike JPA, where saving requires configuring insertable, updatable, or cascade properties, Jimmer allows the data structure shape to be ever-changing. Jimmer also supports recursive queries on self-referencing properties and nested projections based on DTOs, which JPA's EntityGraph does not support easily.

The DDL compiler uses a snapshot model to maintain a durable schema baseline. This baseline is stored as a directory of per-table lockfiles under .jimmer-ddl/entity-table-snapshot/.

Key Characteristics

• Per-table lockfiles: Each file records one table schema hash, its encoded structural model, and the Jimmer entities mapped to that table. This allows multiple developers to work on different entities without causing Git merge conflicts in a single aggregate file.
• Staging process: The compiler stages the next baseline under build/generated/jimmer-ddl/main/resources/.jimmer-ddl/entity-table-snapshot/.
• Applying changes: After accepting a generated migration, you must manually mirror the contents of the staged directory to your durable .jimmer-ddl/entity-table-snapshot/ directory. This includes deleting lockfiles for tables that have been removed.

Source Fingerprints

If jimmerDdl.sourceFingerprint is provided, it is written to build/jimmer-ddl/source-fingerprint.properties. This is disposable build state and must not be committed to Git or copied into the structural snapshot.

Jimmer DDL Compiler is a compile-time DDL generator that converts Jimmer entity metadata into dialect-specific schema SQL. It can be used as a Kotlin KSP processor or a Java APT processor.

Kotlin/KSP Setup

Add the jimmer-ddl-compiler dependency using the ksp configuration and configure the required arguments in the ksp block.

Java/APT Setup

Add the jimmer-ddl-compiler dependency using the annotationProcessor configuration and pass the configuration via compilerArgs in the JavaCompile task.

### Kotlin/KSP
```kotlin
dependencies {
    ksp("org.babyfish.jimmer:jimmer-ddl-compiler:<jimmer-version>")
}

ksp {
    arg("jimmerDdl.enabled", "true")
    arg("jimmerDdl.databaseType", "postgresql")
    arg("jimmerDdl.outputFormat", "flyway")
    arg("jimmerDdl.outputDir", "$projectDir/build/generated/jimmer-ddl/main/resources/db/migration")
    arg("jimmerDdl.version", "1001")
    arg("jimmerDdl.description", "jimmer_auto_ddl_generated")
}

Java/APT

dependencies {
    annotationProcessor("org.babyfish.jimmer:jimmer-ddl-compiler:<jimmer-version>")
}

tasks.withType<JavaCompile>().configureEach {
    options.compilerArgs.add("-AjimmerDdl.enabled=true")
    options.compilerArgs.add("-AjimmerDdl.databaseType=postgresql")
}

Jimmer's internal benchmarks measure runtime hot paths (SQL rendering, parameter binding, DefaultExecutor, and entity materialization) using a fixed-row JDBC stub to exclude database/driver costs.

To run the standard 20-thread benchmark in a forked JVM, use the following command:

gradle run --args="20 5 5 1 one-shot"

Argument Format

The arguments passed to --args follow this order:

1. Thread count: Number of threads to use.
2. Warmup iterations: Number of warmup cycles.
3. Measurement iterations: Number of measurement cycles.
4. Fork count: Number of JVM forks.
5. Benchmark mode (optional): The specific path to measure.

Benchmark Modes

• one-shot (default): Covers the full production path from query construction through result materialization.
• retained: Measures the narrower retained-query path.
• materialization: Compares entity materialization against equivalent handwritten JDBC mapping, independent of query preparation. This mode reads batches of 1, 100, 1000, and 10000 rows. Results are normalized per row using @OperationsPerInvocation.

Jimmer is a compile-time framework that relies on Apt (for Java) or Ksp (for Kotlin). While Java IDEs support these technologies, you should be aware of how to trigger code generation in different scenarios:

Standard Scenario

Most changes involve modifying Java or Kotlin code (e.g., changing an entity type or a Web Controller). In these cases, simply clicking the Run or Debug button in your IDE will trigger the necessary pre-compilation, and the generated source files/resources will update automatically.

DTO-only Changes

If you modify only a DTO file without changing any other Java or Kotlin source code in the same project, the IDE might not trigger generation automatically. You have three options:

1. Use the dedicated DTO plugin.
2. Perform a full compilation using Maven or Gradle commands, or use the IDE's Rebuild button.
3. Delete the build output directory of the affected project and then click the IDE's Run or Debug button.

The DDL compiler is configured using jimmerDdl.* arguments. Below are the available configuration options: