Add dbName() to MetaQueryPlan - easier to support multi-db query plan capture handling

Metrics - support both CUMULATIVE and DELTA metrics collection concurrently
ebean insight [and StatsD] work off DELTA metrics, where as OTEL and Prometheus want CUMULATIVE. With this change we can have a metrics collection for ebean insight using DELTA mode and have a second collection use CUMULATIVE for reporting to OTEL - for the case of fan-out metrics going to 2 places. This isn't strictly needed when only one collection mode is used.
2026-09-20 19:17:55 +00:00 · 2026-08-14 18:03:02 +12:00 · 2026-08-14 16:31:28 +12:00 · 2026-08-06 21:53:14 +12:00 · 2026-07-28 22:35:46 +12:00 · 2026-07-28 22:29:48 +12:00
668 changed files with 32755 additions and 4129 deletions
@@ -17,7 +17,7 @@ jobs:
    strategy:
      fail-fast: false
      matrix:
-        java_version: [11]
+        java_version: [21]
        os: [ubuntu-latest]

    steps:
@@ -40,5 +40,7 @@ jobs:
 #    - name: Maven single test
 #      run: mvn --batch-mode clean verify -Dtest="io.ebeaninternal.server.core.DefaultServer_getReferenceTest" -DfailIfNoTests=false
    - name: Build with Maven
-      run: mvn -T 8 clean test -Pdefault
+      run: mvn -T 1C clean install -Pdefault
+    - name: Test SequencedSet and SequencedMap (requires installed MR-JAR)
+      run: cd tests/test-java16 && mvn test

@@ -16,7 +16,7 @@ jobs:
    strategy:
      fail-fast: false
      matrix:
-        java_version: [11]
+        java_version: [21]
        os: [ubuntu-latest]

    steps:
@@ -35,4 +35,4 @@ jobs:
          ~/.m2
        key: build-${{ env.cache-name }}
    - name: db2
-      run: mvn -T 8 clean test -Dprops.file=testconfig/ebean-db2.properties
+      run: mvn -T 1C clean test -Dprops.file=testconfig/ebean-db2.properties
@@ -16,7 +16,7 @@ jobs:
    strategy:
      fail-fast: false
      matrix:
-        java_version: [11]
+        java_version: [21]
        os: [ubuntu-latest]

    steps:
@@ -37,5 +37,5 @@ jobs:
    - name: Maven version
      run: mvn --version
    - name: H2Database
-      run: mvn -T 8 clean package
+      run: mvn -T 1C clean package

@@ -16,7 +16,7 @@ jobs:
    strategy:
      fail-fast: false
      matrix:
-        java_version: [11]
+        java_version: [21]
        os: [ubuntu-latest]

    steps:
@@ -35,4 +35,4 @@ jobs:
          ~/.m2
        key: build-${{ env.cache-name }}
    - name: mariadb 10.11
-      run: mvn -T 8 clean test -Dprops.file=testconfig/ebean-mariadb.properties
+      run: mvn -T 1C clean test -Dprops.file=testconfig/ebean-mariadb.properties
@@ -13,7 +13,7 @@ jobs:
    strategy:
      fail-fast: false
      matrix:
-        java_version: [11]
+        java_version: [21]
        os: [ubuntu-latest]

    steps:
@@ -16,7 +16,7 @@ jobs:
    strategy:
      fail-fast: false
      matrix:
-        java_version: [11, 17, 21]
+        java_version: [21]
        os: [ubuntu-latest]

    steps:
@@ -16,7 +16,7 @@ jobs:
    strategy:
      fail-fast: false
      matrix:
-        java_version: [11]
+        java_version: [21]
        os: [ubuntu-latest]

    steps:
@@ -35,4 +35,4 @@ jobs:
          ~/.m2
        key: build-${{ env.cache-name }}
    - name: mysql
-      run: mvn -T 8 clean test -Dprops.file=testconfig/ebean-mysql.properties
+      run: mvn -T 1C clean test -Dprops.file=testconfig/ebean-mysql.properties
@@ -16,7 +16,7 @@ jobs:
    strategy:
      fail-fast: false
      matrix:
-        java_version: [11]
+        java_version: [21]
        os: [ubuntu-latest]

    steps:
@@ -35,4 +35,4 @@ jobs:
          ~/.m2
        key: build-${{ env.cache-name }}
    - name: oracle
-      run: mvn -T 8 clean test -Dprops.file=testconfig/ebean-oracle.properties
+      run: mvn -T 1 clean test -Dprops.file=testconfig/ebean-oracle.properties
@@ -16,7 +16,7 @@ jobs:
    strategy:
      fail-fast: false
      matrix:
-        java_version: [11]
+        java_version: [21]
        os: [ubuntu-latest]

    steps:
@@ -35,4 +35,4 @@ jobs:
          ~/.m2
        key: build-${{ env.cache-name }}
    - name: postgres
-      run: mvn -T 8 clean test -Dprops.file=testconfig/ebean-postgres.properties
+      run: mvn -T 1C clean test -Dprops.file=testconfig/ebean-postgres.properties
@@ -13,7 +13,7 @@ jobs:
    strategy:
      fail-fast: false
      matrix:
-        java_version: [11]
+        java_version: [21]
        os: [ubuntu-latest]

    steps:
@@ -16,7 +16,7 @@ jobs:
    strategy:
      fail-fast: false
      matrix:
-        java_version: [11]
+        java_version: [21]
        os: [ubuntu-latest]

    steps:
@@ -35,4 +35,4 @@ jobs:
          ~/.m2
        key: build-${{ env.cache-name }}
    - name: sqlserver 2022
-      run: mvn -T 8 clean test -Dprops.file=testconfig/ebean-sqlserver.properties
+      run: mvn -T 1C clean test -Dprops.file=testconfig/ebean-sqlserver.properties
@@ -16,7 +16,7 @@ jobs:
    strategy:
      fail-fast: false
      matrix:
-        java_version: [11]
+        java_version: [21]
        os: [ubuntu-latest]

    steps:
@@ -13,6 +13,9 @@ ebean-profiling*.xml
 profiling/
 .DS_Store

+# Local Redis integration test credentials
+ebean-redis/src/test/resources/redis-local.yml
+
 # Intellij project files
 *.iml
 *.ipr
@@ -4,7 +4,7 @@
  <parent>
    <artifactId>ebean-parent</artifactId>
    <groupId>io.ebean</groupId>
-    <version>16.9.0</version>
+    <version>18.4.0</version>
    <relativePath>../..</relativePath>
  </parent>

@@ -17,13 +17,13 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-api</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-core</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
@@ -42,13 +42,13 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-querybean</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-clickhouse</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

  </dependencies>
@@ -4,7 +4,7 @@
  <parent>
    <artifactId>ebean-parent</artifactId>
    <groupId>io.ebean</groupId>
-    <version>16.9.0</version>
+    <version>18.4.0</version>
    <relativePath>../..</relativePath>
  </parent>

@@ -17,13 +17,13 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-api</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-core</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
@@ -42,13 +42,13 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-querybean</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-postgres</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

  </dependencies>
@@ -4,7 +4,7 @@
  <parent>
    <artifactId>ebean-parent</artifactId>
    <groupId>io.ebean</groupId>
-    <version>16.9.0</version>
+    <version>18.4.0</version>
    <relativePath>../..</relativePath>
  </parent>

@@ -17,13 +17,13 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-api</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-core</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
@@ -42,13 +42,13 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-querybean</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-db2</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

  </dependencies>
@@ -4,7 +4,7 @@
  <parent>
    <artifactId>ebean-parent</artifactId>
    <groupId>io.ebean</groupId>
-    <version>16.9.0</version>
+    <version>18.4.0</version>
    <relativePath>../..</relativePath>
  </parent>

@@ -17,13 +17,13 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-api</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-core</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
@@ -42,13 +42,13 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-querybean</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-h2</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

  </dependencies>
@@ -4,7 +4,7 @@
  <parent>
    <artifactId>ebean-parent</artifactId>
    <groupId>io.ebean</groupId>
-    <version>16.9.0</version>
+    <version>18.4.0</version>
    <relativePath>../..</relativePath>
  </parent>

@@ -17,13 +17,13 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-api</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-core</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
@@ -42,13 +42,13 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-querybean</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-hana</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

  </dependencies>
@@ -4,7 +4,7 @@
  <parent>
    <artifactId>ebean-parent</artifactId>
    <groupId>io.ebean</groupId>
-    <version>16.9.0</version>
+    <version>18.4.0</version>
    <relativePath>../..</relativePath>
  </parent>

@@ -17,13 +17,13 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-api</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-core</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
@@ -42,13 +42,13 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-querybean</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-mariadb</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

  </dependencies>
@@ -4,7 +4,7 @@
  <parent>
    <artifactId>ebean-parent</artifactId>
    <groupId>io.ebean</groupId>
-    <version>16.9.0</version>
+    <version>18.4.0</version>
    <relativePath>../..</relativePath>
  </parent>

@@ -17,13 +17,13 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-api</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-core</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
@@ -42,13 +42,13 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-querybean</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-mysql</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

  </dependencies>
@@ -4,7 +4,7 @@
  <parent>
    <artifactId>ebean-parent</artifactId>
    <groupId>io.ebean</groupId>
-    <version>16.9.0</version>
+    <version>18.4.0</version>
    <relativePath>../..</relativePath>
  </parent>

@@ -14,7 +14,7 @@

  <properties>
    <postgis.jdbc.version>2023.1.0</postgis.jdbc.version>
-    <postgres.jdbc.version>42.7.2</postgres.jdbc.version>
+    <postgres.jdbc.version>42.7.11</postgres.jdbc.version>
  </properties>

  <dependencies>
@@ -22,13 +22,13 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-api</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-core</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
@@ -47,19 +47,19 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-querybean</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-postgres</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-net-postgis-types</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
@@ -4,7 +4,7 @@
  <parent>
    <artifactId>ebean-parent</artifactId>
    <groupId>io.ebean</groupId>
-    <version>16.9.0</version>
+    <version>18.4.0</version>
    <relativePath>../..</relativePath>
  </parent>

@@ -17,13 +17,13 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-api</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-core</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
@@ -42,13 +42,13 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-querybean</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-nuodb</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

  </dependencies>
@@ -4,7 +4,7 @@
  <parent>
    <artifactId>ebean-parent</artifactId>
    <groupId>io.ebean</groupId>
-    <version>16.9.0</version>
+    <version>18.4.0</version>
    <relativePath>../..</relativePath>
  </parent>

@@ -17,13 +17,13 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-api</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-core</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
@@ -42,13 +42,13 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-querybean</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-oracle</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

  </dependencies>
@@ -4,7 +4,7 @@
  <parent>
    <artifactId>ebean-parent</artifactId>
    <groupId>io.ebean</groupId>
-    <version>16.9.0</version>
+    <version>18.4.0</version>
    <relativePath>../..</relativePath>
  </parent>

@@ -22,13 +22,13 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-api</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-core</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
@@ -47,19 +47,19 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-querybean</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-postgres</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-pgvector-types</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
@@ -4,7 +4,7 @@
  <parent>
    <artifactId>ebean-parent</artifactId>
    <groupId>io.ebean</groupId>
-    <version>16.9.0</version>
+    <version>18.4.0</version>
    <relativePath>../..</relativePath>
  </parent>

@@ -22,13 +22,13 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-api</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-core</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
@@ -47,19 +47,19 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-querybean</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-postgres</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-postgis-types</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
@@ -4,7 +4,7 @@
  <parent>
    <artifactId>ebean-parent</artifactId>
    <groupId>io.ebean</groupId>
-    <version>16.9.0</version>
+    <version>18.4.0</version>
    <relativePath>../..</relativePath>
  </parent>

@@ -17,13 +17,13 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-api</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-core</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
@@ -42,13 +42,13 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-querybean</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-postgres</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

  </dependencies>
@@ -4,7 +4,7 @@
  <parent>
    <artifactId>ebean-parent</artifactId>
    <groupId>io.ebean</groupId>
-    <version>16.9.0</version>
+    <version>18.4.0</version>
    <relativePath>../..</relativePath>
  </parent>

@@ -17,13 +17,13 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-api</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-core</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
@@ -42,13 +42,13 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-querybean</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-sqlite</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

  </dependencies>
@@ -4,7 +4,7 @@
  <parent>
    <artifactId>ebean-parent</artifactId>
    <groupId>io.ebean</groupId>
-    <version>16.9.0</version>
+    <version>18.4.0</version>
    <relativePath>../..</relativePath>
  </parent>

@@ -17,13 +17,13 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-api</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-core</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
@@ -42,13 +42,13 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-querybean</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-sqlserver</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

  </dependencies>
@@ -4,7 +4,7 @@
  <parent>
    <artifactId>ebean-parent</artifactId>
    <groupId>io.ebean</groupId>
-    <version>16.9.0</version>
+    <version>18.4.0</version>
    <relativePath>../..</relativePath>
  </parent>

@@ -17,13 +17,13 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-api</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-core</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
@@ -42,13 +42,13 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-querybean</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-postgres</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

  </dependencies>
@@ -4,7 +4,7 @@
  <parent>
    <artifactId>ebean-parent</artifactId>
    <groupId>io.ebean</groupId>
-    <version>16.9.0</version>
+    <version>18.4.0</version>
    <relativePath>../..</relativePath>
  </parent>

@@ -17,13 +17,13 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-api</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-core</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
@@ -41,7 +41,7 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-jackson-mapper</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
@@ -60,13 +60,13 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-querybean</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-all</artifactId>
-      <version>16.9.0</version>
+      <version>18.4.0</version>
    </dependency>

  </dependencies>
@@ -4,7 +4,7 @@
  <parent>
    <artifactId>ebean-parent</artifactId>
    <groupId>io.ebean</groupId>
-    <version>16.9.0</version>
+    <version>18.4.0</version>
  </parent>

  <artifactId>composites</artifactId>
@@ -54,7 +54,8 @@ Ebean is an ORM library for Java and Kotlin focused on relational data access, t
 | `exists()` | Efficient existence checks | `new QCustomer().email.equalTo(email).exists();` |
 | `findOne()` | Unique/single-row retrieval | `new QCustomer().id.equalTo(id).findOne();` |
 | `findList()` | List retrieval | `new QCustomer().findList();` |
-| `asDto(...).findList()` | DTO projection reads | `new QOrder().asDto(OrderSummary.class).findList();` |
+| `asDto(...).findList()` | Flat DTO projection reads | `new QOrder().asDto(OrderSummary.class).findList();` |
+| `mapTo(...).findList()` | Nested DTO graph projection reads | `new QCustomer().mapTo(CustomerDto.class).findList();` |

 ### Entity mapping and lifecycle annotations

@@ -183,9 +184,12 @@ database.save(customer);
 | Configure database and `Database` bean | [add-ebean-postgres-database-config.md](guides/add-ebean-postgres-database-config.md) |
 | Add PostgreSQL test container support | [add-ebean-postgres-test-container.md](guides/add-ebean-postgres-test-container.md) |
 | Generate DB migrations | [add-ebean-db-migration-generation.md](guides/add-ebean-db-migration-generation.md) |
+| Migrate JSON APIs from Jackson core to avaje-json-core | [migrating-json-jackson-core-to-avaje-json-core.md](guides/migrating-json-jackson-core-to-avaje-json-core.md) |
+| Know which `@DbJson` types need Jackson vs built-in | [dbjson-mapping-support.md](guides/dbjson-mapping-support.md) |
 | Model entity beans correctly | [entity-bean-creation.md](guides/entity-bean-creation.md) |
 | Use Lombok safely with entities | [lombok-with-ebean-entity-beans.md](guides/lombok-with-ebean-entity-beans.md) |
 | Write type-safe query bean queries | [writing-ebean-query-beans.md](guides/writing-ebean-query-beans.md) |
+| Map nested entity graphs to DTO graphs | [mapping-entity-graphs-to-dtos.md](guides/mapping-entity-graphs-to-dtos.md) |
 | Persist changes and manage transactions | [persisting-and-transactions-with-ebean.md](guides/persisting-and-transactions-with-ebean.md) |
 | Build test entities quickly | [testing-with-testentitybuilder.md](guides/testing-with-testentitybuilder.md) |

@@ -0,0 +1,990 @@
+# Nested DTO Mapping — API Design
+
+Design spike for the accepted requirements in [dto-mapping-requirements.md](./dto-mapping-requirements.md),
+covering issue #2540. This captures the concrete API shape, annotations, and open-question decisions made
+during design review — before implementation begins.
+
+## Two source-vs-target mapping pipelines
+
+Ebean now has (or will have) two distinct DTO pipelines. It's important callers can tell which one they're
+using:
+
+1. **`asDto(Dto.class)`** (existing) — a `DtoQuery`, executed directly against a flat SQL `ResultSet`.
+   One row -> one DTO, via constructor/setter matching. No nested ToOne/ToMany support, no entity graph
+   involved.
+2. **`mapTo(Dto.class)`** (new) — runs the normal ORM entity query (joins/fetches as usual), producing an
+   *unmodifiable entity graph*, then maps that Java object graph into a DTO graph. Supports nested
+   ToOne/ToMany, identity-aware de-duplication, and derives its own fetch spec from the DTO shape.
+
+## Proposed API
+
+```java
+// Existing flat DtoQuery pipeline — unchanged
+new QUser().valid.eq(true)
+    .select(firstName, lastName)
+    .asDto(UserInfo.class)
+    .findList();
+```
+
+```java
+// NEW: nested DTO graph pipeline
+public class CustomerDto {
+  Long id;
+  String name;
+  AddressDto billingAddress;      // ToOne -> nested DTO, matched by property name "billingAddress"
+  List<ContactDto> contacts;      // ToMany -> nested DTO list, matched by property name "contacts"
+
+  @DtoPath("billingAddress.line1")
+  String billingLine1;            // renamed / flattened path
+}
+
+public class ContactDto {
+  Long id;
+  String firstName;
+  String lastName;
+
+  @DtoRef
+  Long customerId;                // id-only back-reference, avoids re-embedding CustomerDto (cycle)
+}
+
+List<CustomerDto> dtos = new QCustomer()
+    .status.eq(Status.ACTIVE)
+    .mapTo(CustomerDto.class)
+    .findList();
+```
+
+Computed values (e.g. `cityOrUnknown` derived from `coalesce(billingAddress.city, 'Unknown')`) are
+**not** modeled with a `@Formula2` annotation directly on the DTO - that was explored and rejected
+(see "Formula2-on-DTO scope" below). Instead they're modeled as a plain matching field on the DTO,
+sourced from an `@Entity @View` entity that itself carries the `@Formula2` - see "Computed/aggregate
+properties" below for the worked example.
+
+`mapTo(CustomerDto.class)`:
+- Introspects `CustomerDto` (recursively, at codegen time) to derive the `select(...)`/`.fetch(...)` spec
+  automatically from the DTO's declared shape.
+- Forces `setUnmodifiable(true)` under the hood — gives fail-fast + a cheap, non-mutable source graph
+  (satisfies the fail-fast requirement without a separate flag).
+- Runs the query, then runs a mapper over the resulting entity graph, de-duplicating DTO instances by id
+  for repeated nested references (identity-aware, mirrors the source entity graph's own de-duplication).
+
+## Decisions made
+
+### Fetch spec: auto-derived from DTO shape
+
+The DTO's declared structure (fields, nested DTO types, `@DtoPath` overrides) is the single source of truth
+for what gets selected/fetched from the database. Callers do not need to separately maintain a `.fetch(...)`
+spec in parallel with the DTO — this directly addresses the original issue's pain point (DTO and query
+projection drifting out of sync).
+
+### Entry point naming: `mapTo(Dto.class)`
+
+Chosen over `asGraph(...)` / `into(...)` / overloading `findList(Class)`. Reads clearly as "map the
+resulting entity graph to this DTO type" and is unambiguous against the existing `asDto(...)` (flat,
+SQL-row-based) mechanism.
+
+### Cycle handling: codegen-time DAG check + `@DtoRef` escape hatch
+
+Because the fetch spec and mapper are both derived from the *static* DTO type graph (not live object
+traversal), cycle detection is a compile-time/codegen-time concern, not a runtime one. This is stronger
+than the common approach in the ecosystem:
+
+- **MapStruct** does not auto-detect cycles. It offers an opt-in `@Context` "cycle guard" pattern (an
+  identity map of already-mapped source -> target objects) that the developer must wire up manually to
+  avoid infinite recursion mapping bidirectional object graphs.
+- **Blaze-Persistence / QueryDSL / JOOQ record mapping** avoid the problem architecturally: view/projection
+  types are required to be a strict tree; a back-reference is modeled as an id or a much shallower type,
+  never the same full view type again.
+
+Ebean's approach: fail the build at annotation-processing time if a DTO's declared type graph is not a DAG,
+with a clear error message. Provide `@DtoRef` as an explicit escape hatch for intentional back-references
+(e.g. `Contact.customer`) — it maps only the id, not the full nested DTO, breaking the cycle by design
+rather than by runtime guard.
+
+### `@DtoPath` / `@DtoRef`: parallels for readers coming from MapStruct or Blaze-Persistence
+
+Neither annotation is a novel concept - both map onto things MapStruct and Blaze-Persistence users will
+already recognise, which is worth spelling out explicitly so it's easy to "grok fast":
+
+- **`@DtoPath("billingAddress.line1")` is Ebean's equivalent of MapStruct's dot-path `source` flattening**
+  — e.g. `@Mapping(target = "line1", source = "billingAddress.line1")`. MapStruct auto-generates a
+  null-safe chain of getter calls for a dotted `source`; `@DtoPath` does exactly the same thing, just
+  declared on the DTO field itself rather than on a mapper method parameter list. It is also close to
+  Blaze-Persistence's `@Mapping("billingAddress.line1")` on an `@EntityView` attribute, which is a JPQL
+  path expression evaluated the same way — Blaze's placement (directly on the target view property) is
+  actually the closer analogue of the two, since Ebean's `@DtoPath` is likewise placed on the DTO field.
+  The difference from Blaze: `@DtoPath` is restricted to plain getter-chain navigation (no arbitrary JPQL/
+  SQL expression) - see "Formula2-on-DTO scope" below for the boundary and why full expression support is
+  deliberately deferred.
+- **`@DtoRef` has no dedicated equivalent in either tool** - both MapStruct and Blaze would express the
+  same "just the id" mapping as a plain dot-path to `.id` (`@Mapping(source = "customer.id")` / Blaze
+  `@Mapping("customer.id")`), with no special marker for it. What `@DtoRef` adds beyond that shorthand is
+  *intent*: it tells the codegen this property is a deliberate cycle-breaking reference, so (a) it adds
+  just the association's own name (not a dotted `.id` path) to the generated fetch spec's root
+  `select(...)` - reading the FK column directly with no join, and skipped entirely if that same
+  association is already fully fetched by a `NESTED_ONE`/`NESTED_MANY` property elsewhere on the same DTO
+  (see `DtoMapperWriter.fetchGroupChainCalls()`'s `case REF` branch) - and (b) it participates in the
+  codegen-time DAG cycle check above as an explicit "this is fine, don't flag it" signal, rather than
+  requiring a suppression escape hatch bolted on afterwards.
+
+  **Bug found and fixed while building the aggregation worked example below:** the original implementation
+  excluded `REF` properties from the fetch spec *entirely*, on the assumption the id is "already available
+  off an unfetched reference without triggering a fetch/lazy load". That assumption is only true when some
+  *other* property on the same DTO happens to also fetch that association (as was always the case in the
+  existing hand-built examples). Tested directly against a bare `@ManyToOne` with no other fetch of it:
+  accessing `.getCustomer().getId()` in that case triggers a full lazy-reload of the owning row (extra SQL,
+  not free) - and for an aggregation query it's worse, since the property being grouped by must be selected
+  or the query can't group correctly at all. Fixed so `REF` always contributes its association name to the
+  root `select(...)` (deduped against any existing `NESTED_ONE`/`NESTED_MANY` fetch of the same path).
+
+**Bug found and fixed (validation phase, testing against `central-access`): primitive-typed field +
+nullable intermediate hop = unboxing `NullPointerException`.** A multi-hop `@DtoPath` (or `@DtoRef`,
+which is always 2-hop) null-guards each intermediate getter with a ternary, e.g.
+`(source.getOrganisation() == null ? null : source.getOrganisation().getId())`. That ternary's static
+type is always the boxed wrapper (`Long`), since one branch is the `null` literal - fine when the DTO
+field is itself a reference type (`Long organisationId`), but when the DTO field is a **primitive**
+(`long organisationId`), passing that boxed expression to the constructor auto-unboxes it, throwing an
+unhelpful `NullPointerException` at runtime whenever the relation really is `null`. This compiled clean
+and only failed at runtime with real (nullable) production data - exactly the kind of gap a hand-written
+mapper would defensively guard against (e.g. `cEbox.getOrganisation() == null ? 0 : ...getId()`) but
+generated code didn't.
+
+Fixed in the generator: when a multi-hop `SCALAR`/`REF` property's DTO field type is primitive, the
+whole null-guarded chain is now wrapped in a small runtime helper (`io.ebean.DtoMapperSupport`) that
+resolves it safely:
+- **Default** (`@DtoPath` with no `failOnNull`, or any `@DtoRef`): silently defaults to the primitive's
+  zero-equivalent value (`0`/`false`/etc.) - matches the old hand-written-mapper convention.
+- **`@DtoPath(failOnNull = true)`**: throws a clear `IllegalStateException` naming the offending property
+  path instead, for callers who'd rather fail fast than silently mask a null they don't expect.
+
+`@DtoRef` has no `failOnNull` attribute (it has no other attributes at all) - it always uses the
+default (silent zero) behaviour. See `PrimitiveNullPathDto`/`PrimitiveNullPathFailOnNullDto` /
+`TestPrimitiveNullPath` for regression coverage.
+
+### Read-only entity memory overhead: `InterceptReadOnly`
+`setUnmodifiable(true)` isn't just a behavioural fail-fast flag - it also swaps the per-bean intercept
+implementation to `InterceptReadOnly`, which is deliberately minimal: just a `boolean[] loaded` (one flag
+per property) and a `boolean frozen`, plus the inherited owner reference and `fullyLoadedBean` flag. Compare
+to `InterceptReadWrite` (the mutable/updatable variant), which additionally carries a `ReentrantLock`, four
+transient collaborator references (`NodeUsageCollector`, `PersistenceContext`, `BeanLoader`,
+`PreGetterCallback`), a `byte[] flags` array (per-property loaded+changed+dirty+orig-value-set state),
+`Object[] origValues`, `Exception[] loadErrors`, `MutableValueInfo[]`/`MutableValueNext[]`, and several more
+scalar bookkeeping fields. None of that is needed for a bean that will only ever be read, so
+`setUnmodifiable(true)` graphs carry meaningfully less per-instance overhead than normal fetched entities -
+relevant here because `mapTo(Dto.class)` forces `setUnmodifiable(true)` on its underlying query, making the
+*source* graph for a DTO mapping cheaper than the equivalent normal (writable) entity graph would be.
+
+### Ad-hoc computed/formula properties: model as `@Entity @View`/`@Sql`, not ad-hoc SQL-on-DTO
+
+The "fully ad-hoc SQL-on-DTO" stretch goal above (closer to Blaze's arbitrary `@Mapping` expressions) doesn't
+need to be built as a bespoke DTO-annotation-processing feature. Ebean already supports modelling read-only,
+computed, or view-backed data as ordinary entities via `@Entity` + `@View` (backed by a SQL view, e.g. one
+with aggregates/computed columns) or `@Entity` + `@Sql` (backed by arbitrary `RawSql`, no base table). Given
+that, the Blaze-Persistence-style "an entity view attribute backed by an arbitrary SQL expression" need can
+usually be satisfied by:
+
+1. Modelling the computed/derived shape as its own `@Entity @View` (or `@Sql`) "read entity" - the SQL
+   expression/aggregation lives in the view definition, not in a new annotation-processed DTO mechanism.
+   `@View`'s `name()` doesn't have to point at a genuinely separate database view - it can just point at
+   an *existing* table (e.g. `@View(name = "contact")` on a second entity class reading the same table as
+   `Contact`) purely to mark the entity as view-like/read-only, in which case Ebean's DDL generator emits
+   **no new table or view at all** for it - it's just a second lens onto the same physical data.
+2. Mapping *that* entity into a plain DTO using the existing, already-implemented `@DtoMapping` machinery -
+   no ad-hoc-SQL-on-DTO support required, since there's no computed expression left to resolve at the DTO
+   layer at all; it's just another entity-to-DTO mapping.
+3. This read entity benefits from the same `setUnmodifiable(true)`/`InterceptReadOnly` memory efficiency
+   above when used purely as `mapTo(...)` input, so there's no meaningful cost to preferring this over a
+   hypothetical native ad-hoc-SQL-on-DTO feature.
+
+This significantly narrows (and may eliminate) the case for a dedicated ad-hoc-SQL-on-DTO mechanism - it
+remains listed as an open stretch goal below primarily for the case where a computed value's SQL is genuinely
+one-off/DTO-specific and not worth promoting to a standalone `@View`/`@Sql` entity.
+
+**Worked example** (`tests/test-dto-mapping`): `ContactSummary` is `@Entity @View(name = "contact")` (no new
+DDL - reads the same table as `Contact`) with `@Formula2("concat(firstName, ' ', lastName)")` computing
+`fullName`; `ContactSummaryDto` is a plain two-field DTO; `@DtoMapping(source = ContactSummary.class, target
+= ContactSummaryDto.class)` generates `ContactSummaryDtoMapper` exactly like any other entity→DTO pair - the
+formula property is just selected like any other field (`select("id,fullName")` in the generated
+`fetchGroup()`). See `TestContactSummaryDtoMapping`.
+
+### Aggregate/group-by computed properties: `@Sum`/`@Aggregation` as `@Entity @View`, same pattern
+
+Ebean's `@Sum` (shorthand for `@Aggregation("sum($1)")`) and `@Aggregation("count(...)"/"sum(...)"/"avg(...)"/
+"min(...)"/"max(...)")` are the group-by parallel to the formula pattern above - the same `@Entity @View`
+approach applies, just with an implicit `GROUP BY` instead of a per-row computed column. Ebean auto-derives
+the `GROUP BY` clause from whichever non-aggregate properties end up in the query's `select()`/`fetch()` - so
+a second `@Entity @View(name = <same base table>)` entity with one or more `@Sum`/`@Aggregation` properties
+plus a `@ManyToOne` grouping key becomes a per-parent rollup, with **no new table/view and no explicit
+`.groupBy()` call required**. This is Ebean's parallel to Blaze-Persistence entity view correlated aggregate
+mappings, e.g. `@Mapping("SIZE(contacts)")` / `@Mapping("SUM(contacts.engagementScore)")` on an `@EntityView`.
+
+**Nuance found while building the worked example, and since fixed: `@DtoRef` originally didn't fit the
+grouping key.** `@DtoRef` was originally excluded from the generated `select()`/`fetch()` spec entirely, on
+the premise that the id is already available off an unfetched reference for an ordinary entity graph. That
+premise doesn't hold for an aggregation query: the `@ManyToOne` *is* the property being grouped by, so if
+it's never selected, the query has nothing to group by. It turned out the premise didn't fully hold for
+ordinary entity graphs either - see the `@DtoRef` bug writeup above. Fixed so `@DtoRef` now adds the
+association's own name to the root `select(...)` (reading the FK column directly, no join) - which both
+supplies the grouping key here and fixes the general-case gap.
+
+**Worked example** (`tests/test-dto-mapping`): `ContactStats` is `@Entity @View(name = "contact")` (no new
+DDL - reads the same table as `Contact`/`ContactSummary`) with `@Aggregation("count(id)") contactCount` and
+`@Sum Integer engagementScore` (a new nullable field added to `Contact` purely to have something to sum),
+grouped by its `@ManyToOne customer`. `ContactStatsDto` is a flat 3-field DTO (`customerId`, `contactCount`,
+`engagementScore`), with `customerId` mapped via plain `@DtoRef`. The generated `ContactStatsDtoMapper`:
+
+```java
+this.fetchGroup = FetchGroup.of(ContactStats.class)
+  .select("customer,contactCount,engagementScore")
+  .build();
+...
+// skip DtoMapContext, only ever a top-level mapping
+return new ContactStatsDto(
+  (source.getCustomer() == null ? null : source.getCustomer().getId()),
+  source.getContactCount(),
+  source.getEngagementScore());
+```
+
+confirmed (via `LoggedSql`) to produce `select t0.customer_id, count(t0.id), sum(t0.engagement_score) from
+contact t0 ... group by t0.customer_id` - **no join**, one row per customer, correctly summed and counted.
+See `TestContactStatsDtoMapping`.
+
+### Formula2-on-DTO scope (v1): existing entity formulas only
+
+`@Formula2` on a DTO property in v1 only pulls in a formula **already declared on the source entity** (or
+a reachable associated entity) — it does not support fully ad-hoc SQL declared directly on the DTO with no
+matching entity property. Fully ad-hoc SQL-on-DTO (closer to Blaze's arbitrary `@Mapping` expressions) is a
+separate, larger stretch goal to revisit once the core graph-mapping mechanism is proven.
+
+**Attempted and rejected for v1.** A narrower version was implemented (`@Formula2(value)` resolved exactly
+like `@DtoPath` - a dot-path getter chain - plus a codegen-time validation that the resolved entity property
+is itself `@Formula2`/`@Formula`-annotated) but was rejected: for the common case (a DTO field with the same
+name as the entity's formula property) it generated **identical code to a plain unannotated field** - the
+only difference was the validation, which wasn't judged enough distinct value to justify a new annotation
+surface. Not implemented. The only way `@Formula2`-on-DTO would add real value is the full ad-hoc-SQL
+capability described above, which remains an open stretch goal.
+
+### Mapper implementation strategy: codegen, not reflection (native-image constraint)
+
+Native-image support is a core Ebean requirement, so the entity-graph -> DTO-graph mapper must not rely on
+runtime reflection or `MethodHandles`. This ruled out an initial reflection-based spike:
+
+- Ebean's existing flat `DtoQuery` (`DtoMetaConstructor`) already uses `MethodHandles` via
+  `Lookups.getLookup()`, but there is no `reflect-config.json` / native-image reachability metadata shipped
+  for it anywhere in the repo. That existing approach is not a clean precedent to copy for a bigger,
+  native-image-first feature.
+- Instead, the approach mirrors `querybean-generator`, which already generates real `.java` source for
+  `Q*` query bean types (not reflection) — consistent with the wider avaje-ecosystem convention
+  (avaje-inject / avaje-jsonb are explicitly reflection-free via compile-time codegen).
+
+**Implementation sequencing:** hand-write the mapper in the exact shape the annotation processor will
+eventually generate (plain Java, direct getter/constructor/setter calls, zero reflection) for one concrete
+example first, to validate the mapping algorithm and API shape quickly without ever introducing throwaway
+reflective code. That hand-written mapper then becomes the target/acceptance-test shape for the
+`querybean-generator` annotation processor that automates producing it.
+
+### Codegen target: Java first
+
+The mapper generation (requirement r2) targets `querybean-generator` (the existing APT module that already
+generates `Q*` query beans, reusing its `PropertyMeta` / `ProcessingContext` machinery). Kotlin parity via
+`kotlin-querybean-generator` is deferred to a later phase — not blocking initial delivery.
+
+### Mapper composition: one mapper per entity/DTO pair, generic `DtoMapper<SOURCE, TARGET>` interface
+
+Rather than one large mapper inlining every nested DTO type, each entity/DTO pair gets its own small
+mapper class - mirroring MapStruct's per-type mapper generation. All mappers implement a shared generic
+interface (prototyped as `org.tests.dtomapping.DtoMapper<SOURCE, TARGET>` in the spike, expected to move to
+`io.ebean` as a public type once solidified):
+
+```java
+public interface DtoMapper<SOURCE, TARGET> {
+  TARGET map(SOURCE source);
+  default List<TARGET> mapList(List<SOURCE> source) { ... }
+}
+```
+
+A parent mapper composes nested mappers via **constructor injection**, not a static singleton:
+
+```java
+public final class CustomerDtoMapper implements DtoMapper<Customer, CustomerDto> {
+  private final DtoMapper<Address, AddressDto> addressMapper;
+
+  public CustomerDtoMapper() {
+    this(new AddressDtoMapper());
+  }
+
+  public CustomerDtoMapper(DtoMapper<Address, AddressDto> addressMapper) {
+    this.addressMapper = addressMapper;
+  }
+
+  @Override
+  public CustomerDto map(Customer source) {
+    if (source == null) return null;
+    return new CustomerDto(source.getId(), source.getName(), addressMapper.map(source.getBillingAddress()));
+  }
+}
+```
+
+Rationale:
+- **Composability & reuse** - the same nested DTO type (e.g. `AddressDto`) used from multiple parent DTOs
+  reuses one generated mapper class rather than duplicating inline mapping logic.
+- **Constructor injection over static state** - avoids a global mutable singleton; a no-arg constructor
+  gives the common case (default nested mapper), while an overload accepting the nested mapper explicitly
+  allows substitution (tests, customization) without touching global state.
+- **Codegen-friendly** - this shape generates naturally: one top-level mapper class per DTO type, each
+  constructor-injecting the mappers for any nested DTO types it references.
+
+## ToMany collections and identity de-duplication (dto-spike-tomany-identity)
+
+Extending the spike (`ebean-test/src/test/java/org/tests/dtomapping/`) to a `Customer` with a
+`List<Contact> contacts` ToMany, where each `Contact` has a `customer` back-reference, surfaced
+two things worth recording.
+
+### The `DtoMapper` interface threads a shared context
+
+`DtoMapper<SOURCE, TARGET>` was extended so that mapping is always done against a `DtoMapContext`:
+
+```java
+public interface DtoMapper<SOURCE, TARGET> {
+  TARGET map(SOURCE source, DtoMapContext context);
+
+  default TARGET map(SOURCE source) {
+    return map(source, new DtoMapContext());
+  }
+
+  default List<TARGET> mapList(List<SOURCE> source, DtoMapContext context) { ... }
+
+  default List<TARGET> mapList(List<SOURCE> source) {
+    return mapList(source, new DtoMapContext());
+  }
+}
+```
+
+`DtoMapContext` is an identity-keyed cache of already-mapped source -> target instances, created
+once per top-level `mapList(...)`/`map(...)` call and threaded through every nested `map(...)`
+call. This lets repeated references to the *same* source entity instance - which Ebean's own
+persistence context already de-duplicates within one query (`contact.getCustomer() == customer`
+for the enclosing `Customer`, confirmed by an existing test) - map to the *same* target DTO
+instance, rather than each producing an equal-but-distinct copy. This is what makes the mapped
+DTO output "graph shaped" rather than "tree of copies shaped", and is required for r1/r3.
+
+### Bug found and fixed: the cache must be partitioned by target type, not just source identity
+
+The first cut of `DtoMapContext` was a single `IdentityHashMap<Object, Object>` keyed only by the
+source instance. This breaks as soon as the *same* source instance legitimately needs to map to
+*two different target types* within one graph - which happens immediately with a back-reference:
+
+- The top-level `CustomerDtoMapper` maps a `Customer` -> full `CustomerDto`.
+- The nested `ContactDtoMapper`, mapping `contact.getCustomer()` (the *same* `Customer` instance,
+  by identity), maps it -> shallow `CustomerRefDto` (the `@DtoRef`-style escape hatch that avoids
+  the `Customer -> Contact -> Customer` cycle).
+
+With a single un-partitioned identity map, whichever mapper runs first "wins" the cache slot for
+that `Customer` instance, and the other mapper incorrectly receives the wrong-typed cached result
+(a `ClassCastException` at best, silently wrong data at worst). This was caught by a failing test
+during the spike and fixed by partitioning the cache per target type:
+
+```java
+public final class DtoMapContext {
+  private final Map<Class<?>, Map<Object, Object>> mappedByType = new HashMap<>();
+
+  public <S, T> T computeIfAbsent(Class<T> targetType, S source, Function<S, T> mappingFunction) {
+    Map<Object, Object> mapped = mappedByType.computeIfAbsent(targetType, t -> new IdentityHashMap<>());
+    // ... existing/create/put ...
+  }
+}
+```
+
+Each generated mapper passes its own target DTO `Class` as the first argument, so `Customer ->
+CustomerDto` and `Customer -> CustomerRefDto` are cached independently even though the key
+(`Customer` instance) is identical. **This is an implementation detail the codegen must get
+right** - worth flagging explicitly when `dto-codegen-mapper` starts, since it's easy to
+regress if the generator is written from scratch without this test coverage in front of it.
+
+### Codegen optimization: skip the `DtoMapContext` cache for types that are never nested elsewhere
+
+`DtoMapContext.computeIfAbsent` only ever produces a cache *hit* when the exact same source
+instance is presented to `map()` more than once within one top-level call - which can only happen
+when the target type is reachable via more than one path in the graph, i.e. it's used as a
+`NESTED_ONE`/`NESTED_MANY` property by some *other* `@DtoMapping` pair (e.g. `CustomerRefDto`
+reached from many `Contact`s via a shared `Customer`, or `AddressDto` shared as `billingAddress`
+across customers). A type that's only ever a top-level `mapTo(...)`/`mapList(...)` entry point can
+never receive the same source instance twice within one call - Ebean's own query engine already
+de-duplicates root entity instances - so the cache lookup/insert there is pure overhead with a
+guaranteed-never-hit `IdentityHashMap`.
+
+Since all `@DtoMapping` pairs are resolved together at codegen time (`DtoMappingReader.
+resolveAndValidate()`), it's straightforward to compute this: after cycle exclusion, walk every
+surviving `DtoBeanMeta`'s properties and mark any `nested()` target as `nestedElsewhere()`. The
+generated `map()` method then branches per mapper:
+
+```java
+// CustomerDto - never nested by another mapper, only a mapTo()/mapList() entry point
+public CustomerDto map(Customer source, DtoMapContext context) {
+  if (source == null) return null;
+  // DtoMapContext for nested mappers only
+  return new CustomerDto(source.getId(), source.getName(),
+    billingAddressMapper.map(source.getBillingAddress(), context),
+    contactsMapper.mapList(source.getContacts(), context));
+}
+
+// AddressDto - nested under CustomerDto.billingAddress, so may be shared across customers
+public AddressDto map(Address source, DtoMapContext context) {
+  if (source == null) return null;
+  // dedup using DtoMapContext, same Address instance can be reached via more than one path in the graph
+  return context.computeIfAbsent(AddressDto.class, source, s -> new AddressDto(
+    s.getId(), s.getLine1(), s.getCity()));
+}
+
+// ContactSummaryDto - flat, top-level only, no nested children at all
+public ContactSummaryDto map(ContactSummary source, DtoMapContext context) {
+  if (source == null) return null;
+  // skip DtoMapContext, only ever a top-level mapping
+  return new ContactSummaryDto(source.getId(), source.getFullName());
+}
+```
+
+Deliberately terse, single-line comments - just enough for a developer skimming generated code (e.g.
+per the earlier `@Formula2`-on-DTO worked example) to know at a glance *why* a given mapper does or
+doesn't use the cache, without spelling out the full reachability argument inline every time (that
+lives here in the design doc instead). Note `CustomerDto`'s own construction skips the cache even
+though it *has* nested children - `context` is still threaded down to `billingAddressMapper`/
+`contactsMapper` since those target types (`AddressDto`, `ContactDto`) *are* nested elsewhere and
+still need the identity cache for themselves - hence the distinct "for nested mappers only" wording
+from the "only ever a top-level mapping" case (`ContactSummaryDto`), which has no children to thread
+a context to at all.
+
+### Fetching a ToOne back-reference used only for its FK/id needs the FK property fetched too
+
+Confirmed (via a first-cut test failure) that if a ToMany's element type has a ToOne back to its
+parent (e.g. `Contact.customer`), that FK property must itself be included in the fetch
+(`.fetch("contacts", "id,firstName,lastName,customer")`) even when the mapper only reads the id
+off the reference. Omitting it throws `LazyInitialisationException: Property not loaded:
+customer` on the `getCustomer()` call itself (not merely on a property access on the returned
+reference) - i.e. the earlier "ToOne reference access alone doesn't lazy load" finding
+(dto-validate-fetch-pagination) only holds once the ToOne/FK property is itself part of the
+fetch/select spec. This reinforces r6 (auto-deriving the fetch spec from DTO shape): the codegen
+must include a ToOne property in the fetch spec whenever a DTO needing it (even just its id) is
+reachable through a ToMany, not just at the top level.
+
+### Test coverage added
+
+- `TestCustomerDtoGraphMapping` extended to cover `contacts` ToMany mapping and to assert that
+  sibling `ContactDto`s under the same customer share the identical `CustomerRefDto` instance.
+- `TestContactDtoGraphMapping` (new) - standalone `ContactDtoMapper` test focused specifically on
+  the identity de-dup guarantee and null-source handling.
+
+## Codegen foundation: avaje-prisms adopted in querybean-generator (dto-codegen-mapper, step 1)
+
+Before writing the DTO-mapper annotation-processing logic itself, adopted `avaje-prisms`
+(`io.avaje:avaje-prisms`) in `querybean-generator` as the mechanism for reading the new
+`@DtoPath`/`@DtoRef` annotations at APT time, replacing what would otherwise be more hand-rolled
+`AnnotationMirror` walking (the existing pattern in `FindDbName.java`/`ReadModuleInfo.java`,
+left as-is/unmigrated - only the *new* annotations use prisms).
+
+This mirrors the proven pattern already used in two sibling projects in the same ecosystem -
+`avaje-inject`'s `inject-generator` and `avaje-jsonb`'s `jsonb-generator` - both declare
+`@GeneratePrism(SomeAnnotation.class)` once and get a generated `SomeAnnotationPrism` with
+`isPresent(element)` / `getInstanceOn(element)` / `getOptionalOn(element)` and typed accessors
+for every annotation member (correctly handling `Class`-valued members, avoiding the classic
+`MirroredTypeException` dance).
+
+Key property preserved: `querybean-generator` has **zero runtime/compile dependencies today**
+(confirmed via `mvn dependency:list` returning "none"), matching annotations by FQN string
+constants (`Constants.java`) rather than importing the actual annotation classes - deliberately
+keeping the processor free of any dependency footprint for consumers. Adding `avaje-prisms` (to
+generate the prism wrapper) and `ebean-annotation` (to reference `@DtoPath`/`@DtoRef` as literal
+`Class` values in `@GeneratePrism(...)`) as `optional` dependencies preserves this: `mvn
+dependency:list -DincludeScope=runtime` confirms every one of these (plus their own transitive
+deps: `avaje-prism-core`, `avaje-spi-service`, `avaje-spi-core`) is marked `(optional)`, so none
+of it propagates to a project that depends on `querybean-generator` (whether as a normal
+dependency or via `annotationProcessorPaths`).
+
+New annotations were added to the separate `ebean-annotation` repo (`io.ebean.annotation`
+package, alongside `@Formula2`), not this repo:
+
+```java
+@DtoPath("billingAddress.line1")
+String billingLine1;   // rename/flatten a DTO property from a nested source path
+
+@DtoRef
+Integer customerId;    // id-only back-reference, breaks what would otherwise be a graph cycle
+```
+
+Both use `@Target({FIELD, METHOD})` and `RetentionPolicy.CLASS` - visible to the annotation
+processor (including across module boundaries, since `CLASS` retention survives in the compiled
+`.class` file) but absent from runtime reflection, consistent with DTOs remaining plain,
+framework-free types with no runtime footprint.
+
+Wiring changes in `querybean-generator`:
+- `pom.xml`: added `avaje-prisms` (`optional`, plus `annotationProcessorPaths` entry) and
+  `ebean-annotation` (`optional`) dependencies; removed the previous `-proc:none` compiler arg
+  (which would have suppressed `avaje-prisms`' own processor from running to generate the prism
+  source) - annotation processing is now scoped to exactly `avaje-prisms` via the explicit
+  `annotationProcessorPaths` list, so no other processor is auto-discovered.
+- `module-info.java`: added `requires static io.avaje.prism;` and `requires static
+  io.ebean.annotation;` (`static` = compile-time only, matching the `optional` Maven scope).
+- New `package-info.java` declaring `@GeneratePrism(DtoPath.class)` and
+  `@GeneratePrism(DtoRef.class)`, generating `DtoPathPrism`/`DtoRefPrism` into
+  `target/generated-sources/annotations`.
+
+Verified: full `querybean-generator` build + existing test suite pass unchanged, and a downstream
+full rebuild (`ebean-test` with `-am`) - which exercises the existing Q-bean codegen - also
+passes with no regressions.
+
+### Trigger mechanism: `@DtoMapping(source, target)` on a neutral package-info.java
+
+Considered and rejected: putting a `source`/entity-referencing annotation directly on the DTO
+class itself (e.g. `@Dto(Customer.class)` on `CustomerDto`). Rejected because DTO types are
+often owned/generated elsewhere (e.g. from an OpenAPI spec) and must not be forced to reference
+an internal persistence/entity type - that would leak internal domain types into a
+public-facing/generated DTO module.
+
+Instead, adopted the same pattern `avaje-jsonb` uses for external/foreign types it doesn't own
+(`@Json.Import`): a repeatable annotation declared on a *neutral* holder - a `package-info.java`
+- naming the `source` entity and `target` DTO as a pair:
+
+```java
+@DtoMapping(source = Customer.class, target = CustomerDto.class)
+@DtoMapping(source = Contact.class, target = ContactDto.class)
+package org.example.dto;
+```
+
+`@DtoMapping` (new, in `ebean-annotation`) is `@Target({PACKAGE, MODULE})`,
+`@Retention(SOURCE)` (pure codegen trigger, never needed at runtime - unlike `@DtoPath`/
+`@DtoRef` which need `CLASS` retention to remain visible to the DTO field itself),
+`@Repeatable(DtoMapping.List.class)` following Java's own repeatable-annotation idiom. Neither
+the entity nor the DTO needs any annotation of its own.
+
+**Generated mapper package placement** - also modeled directly on `avaje-jsonb`'s handling of
+`@Json.Import` for external types (`AdapterName`/`ProcessingContext.isImported`): defaults to the
+target DTO's own package, *unless* the source or target type belongs to a different Java module
+than the one being processed, in which case the generated mapper is placed in a package derived
+from the processing module's own name instead - avoiding a JPMS "split package" violation that
+would occur from generating source into a package owned by another module. An explicit
+`mapperPackage` attribute is available to override this for edge cases. Same-module (or
+non-modular/unnamed-module) projects are unaffected and just get the mapper alongside the DTO.
+
+### mapTo(Class) dispatch: Class-token API + generated compile-time-safe registry
+
+The original API sketch above (`mapTo(CustomerDto.class)`) predates the native-image/no-reflection
+decision. Rather than switching to an instance-based API (`mapTo(new CustomerDtoMapper())`),
+decided to keep the `Class`-token shape and generate a compile-time-safe registry to resolve it -
+no reflection, no `Class.forName`, just literal `Class` comparisons generated at build time, e.g.:
+
+```java
+<S, D> DtoMapper<S, D> mapperFor(Class<S> sourceType, Class<D> targetType) {
+  if (sourceType == Customer.class && targetType == CustomerDto.class) {
+    return (DtoMapper<S, D>) new CustomerDtoMapper();
+  }
+  if (sourceType == Contact.class && targetType == ContactDto.class) {
+    return (DtoMapper<S, D>) new ContactDtoMapper();
+  }
+  return null;
+}
+```
+
+Dispatch is keyed on the **(source, target) pair**, not target alone - this matches how
+`@DtoMapping(source, target)` pairs are declared, allows the same DTO type to be mapped from more
+than one source entity without ambiguity, and lets `query.mapTo(dtoType)` fail fast with a clear
+`PersistenceException` (rather than an incorrect match) when `query.getBeanType()` doesn't pair
+with the requested DTO.
+
+This mirrors the existing, already-proven `EbeanEntityRegister`/`EntityClassRegister` mechanism
+(`SimpleModuleInfoWriter.java`) that `querybean-generator` already generates per module for entity
+classes - a `List<Class<?>>` built from literal `SomeEntity.class` references, registered via
+`META-INF/services` (`ServiceLoader`, itself native-image-friendly with no extra reflection
+config needed for simple no-arg-constructor implementations). The DTO mapper registry follows the
+same per-module aggregation + `META-INF/services` registration shape, giving `mapTo(Class)` a
+concrete generated implementation to dispatch through at runtime without reflection anywhere in
+the chain.
+
+### mapTo(Dto.class) runtime wiring (implemented)
+
+`query.mapTo(dtoType)` returns a `MappedQuery<D>` (`findList()`/`findOne()`/`findOneOrEmpty()`/
+`findStream()`/`findPagedList()`/`usingMaster(boolean)`/`usingTransaction(Transaction)`/`usingConnection(Connection)`).
+On first use it resolves the generated `DtoMapper<S, D>` for the query's `(getBeanType(), dtoType)`
+pair via a `DtoMapperManager` (a `ServiceLoader`-backed aggregator over all generated
+`DtoMapperRegister`s, analogous to `DtoBeanManager`), then:
+
+- applies `mapper.fetchGroup()` to the query via `query.select(fetchGroup)` - the fetch/select spec
+  is entirely derived from the DTO's declared shape, no manual `.select()`/`.fetch()` needed;
+- forces `query.setUnmodifiable(true)` - the resulting entity graph is read-only input to the
+  mapper, and any DTO property whose source wasn't actually fetched fails fast with
+  `LazyInitialisationException` rather than silently lazy loading or returning `null`;
+- executes the query and maps the result(s) via `mapper.map(...)`/`mapper.mapList(...)`.
+
+An unregistered `(source, dtoType)` pair throws a `PersistenceException` with a suggested
+`@DtoMapping` fix, at first use (i.e. `findList()`/`findOne()`), not at `mapTo(dtoType)` call time.
+
+`MappedQuery<D>.usingMaster(boolean)`, `.usingTransaction(Transaction)`, and `.usingConnection(Connection)`
+all delegate directly to the underlying entity query, mirroring `Query`/`QueryBuilder`. This lets a
+caller retry against the master data source after a read-replica failure by calling
+`usingMaster(true)` on the *same* `MappedQuery` instance and re-invoking a find method - there's no
+need to rebuild the query and call `.mapTo(...)` again.
+
+`MappedQuery<D>.findStream()` mirrors `QueryBuilder#findStream()` - the underlying entity query is
+streamed (supporting very large result sets, potentially using multiple persistence contexts
+internally) and each entity is mapped to its target DTO lazily as the stream is consumed. One
+`DtoMapContext` is shared across the whole stream (not per-element), so identity de-duplication of
+nested DTOs (e.g. several `Contact`s sharing the same `Customer`) still holds even when the source
+entities are never materialized into one `List` at all. As with the entity-level `findStream()`,
+callers must consume it via try-with-resources to ensure the underlying resources are closed.
+
+
+## Still open / to revisit during implementation
+
+- Whether `.fetch(...)` calls can still be layered on top of a `mapTo(Dto.class)` query for explicit
+  overrides. Currently the mapper's `fetchGroup()` is the *only* source of the fetch spec - any
+  `.select()`/`.fetch()` calls made before `.mapTo(...)` are overwritten by it.
+- Whether `@DtoPath`/`@DtoRef` need additional attributes beyond a bare path/marker (e.g. an explicit
+  target type on `@DtoRef` for disambiguation) once real DTOs with more complex shapes are codegen'd.
+- Behavior when a DTO property has no matching entity property and no `@DtoPath`/`@Formula2` override
+  (fail at codegen time, most likely, consistent with the "fail fast" philosophy).
+- `@Formula2`-on-DTO mapping to Blaze-Persistence/QueryDSL-style computed properties - not yet
+  implemented (see requirements doc); a narrower validation-only variant was attempted and rejected
+  as not distinct enough from `@DtoPath` (see "Formula2-on-DTO scope" above). The broader ad-hoc-SQL
+  case likely doesn't need a dedicated DTO feature at all - see "Ad-hoc computed/formula properties"
+  above for the `@Entity @View`/`@Sql` alternative.
+- **Fetch-path collision between a `NESTED_ONE`/`NESTED_MANY` property and a `@DtoPath` property -
+  found and fixed**: `DtoMapperWriter.fetchGroupChainCalls()` builds one `.fetch(path, ...)`
+  chain-call per distinct fetch path, but the underlying `OrmQueryDetail.fetch(...)` unconditionally
+  **overwrites** (rather than merges) any existing entry for the same path key. If a DTO declared a
+  `NESTED_ONE`/`NESTED_MANY` property AND a `@DtoPath` property whose fetch-path prefix is the *exact
+  same* path (e.g. a nested `AddressDto billingAddress` alongside `@DtoPath("billingAddress.line1")`
+  on the same DTO - both resolve to fetch path `"billingAddress"`), the generator would emit two
+  `.fetch("billingAddress", ...)` calls and the second would silently discard the first's selected
+  properties. Merging wasn't practical - the nested property's `.fetch(path, mapper.fetchGroup())`
+  call passes another mapper's own pre-built, immutable, shared `FetchGroup`, so there's no clean way
+  to splice an extra scalar property into it at the call site. Fixed instead with a **fail-fast
+  compile-time error**: `DtoMapperWriter` now detects the collision and raises a clear
+  `ctx.logError(...)` (annotation-processor `ERROR` diagnostic, fails the compile) naming the
+  colliding property and fetch path, and suggesting the two ways out - move the property onto the
+  nested DTO type instead, or pick a `@DtoPath` that reaches a different, non-colliding path (as
+  `ContactDto.customerCity` already does deliberately, per its own comment, using a 3-segment path).
+  Verified empirically by compiling a small reproduction with a colliding `@DtoPath` and confirming
+  the expected error fires; a permanent regression test
+  (`DtoMapperFetchPathCollisionTest` in `querybean-generator`) now runs this same repro directly
+  through `javax.tools.JavaCompiler` with the `Processor` registered, asserting the compile fails with
+  the expected diagnostic message.
+- **Compile-time verification of `select(...).asDto(...)` (r6, aspirational) - explored and closed as
+  rejected**: raw SQL is an opaque `String` at compile time, and even the typed query-bean
+  `.select(...)` form only type-checks against the *entity* - the match to the target DTO's constructor
+  still happens at runtime via reflection (`DtoQueryPlanConstructor`), and the `.asDto(...)` call site
+  can be arbitrarily distant from the `.select(...)` call, so there's no fixed AST shape an annotation
+  processor could reliably verify (unlike QueryDSL, whose compile-time safety actually comes from typed
+  `Projections.constructor(...)`/generated Q-type constructor calls, not from checking a select-list
+  against a DTO). `mapTo(Dto.class)` already closes the underlying gap in the tractable direction - it
+  derives the select/fetch spec *from* the DTO's declared shape at APT time, so it is compile-time safe
+  by construction. Recommend `mapTo()` whenever compile-time-checked DTO projection matters, and treat
+  `asDto()`/`findDto()` as the flexible, runtime-checked escape hatch for raw/dynamic SQL. See
+  `dto-mapping-requirements.md` requirement r6.
+- **Custom property conversion (`@DtoConvert`/`@DtoMixin`, r13/r14) - implemented**: motivated by a
+  real hand-written mapper (`DriverMapper`, central-access) needing both a dependency-free scalar
+  coercion (`short` -> `boolean`) and a dependency-backed conversion (AES decryption via an injected
+  cipher). Final design (see `dto-mapping-requirements.md` section E), as built:
+  - `@DtoConvert(value = ConverterType.class, method = "name")` on a DTO property (combinable with
+    `@DtoPath`); the generator dispatches on whether the referenced method is `static` - static means a
+    direct inlined static call (no registration, covers common reusable coercions), instance means
+    dispatch via a new `DtoConverterManager.get(ConverterType.class).method(...)` call, with the
+    resolved instance wired as a real constructor parameter/field on the generated mapper (same shape
+    as existing nested-mapper constructor injection). Multiple properties on the same mapper sharing
+    the same converter type are deduplicated to a single constructor parameter/field
+    (`DtoBeanMeta.converterDeps()`).
+  - `DtoConverterManager` (`ebean-api`, `io.ebean` package) is a small, narrowly-scoped static put/get
+    bridge - the app registers an already-DI-constructed converter singleton (e.g. built by
+    avaje-inject) *before* building the `Database`. This is a deliberate, narrow exception to the
+    general no-static-mutable-state convention: `ServiceLoader`-discovered, no-arg-constructed
+    generated code (`EbeanDtoMapperRegister`) has no other way to reach an already-DI-constructed
+    singleton. `DtoConverterManager.get(type)` throws immediately if nothing was registered for that
+    type, so a missing converter fails fast at Database-startup time (an eager field initializer on
+    `EbeanDtoMapperRegister`, and equally on each mapper's own no-arg constructor, which resolves the
+    same way via `DtoConverterManager.get(...)` for standalone/test construction), not lazily on first
+    use - `DtoMapperRegister`'s `mapperFor(...)` signature and `DtoMapperManager` are otherwise
+    completely unchanged, as originally planned.
+  - Two alternatives were explored and rejected first: (a) a `DtoMapContext.service(Class)` lookup -
+    wrong lifetime, `DtoMapContext` is a short-lived per-call identity-cache only; (b) a
+    `ServiceLoader`-discovered `DtoConverterSource` SPI mirroring `DtoMapperRegister` itself - can't
+    bridge to an *already* DI-constructed dependency without reconstructing/duplicating it.
+  - `@DtoMixin(Target.class)` - a companion type overlaying `@DtoPath`/`@DtoConvert`/`@DtoRef`
+    annotations onto a DTO that can't be annotated directly (e.g. OpenAPI-generated). Discovered via
+    `roundEnv.getElementsAnnotatedWith(...)` (added to `Processor.getSupportedAnnotationTypes()`,
+    since - unlike `@DtoPath`/`@DtoRef`/`@DtoConvert` - a mixin doesn't annotate an already-iterated
+    field of a known `@DtoMapping` target, so it can't be found lazily). `DtoMappingReader` resolves
+    each target property's annotations from the field itself first, falling back to a same-named
+    method on the registered mixin (`DtoMappingReader.prismOn(...)`) - directly mirrors avaje-jsonb's
+    proven `@Json.MixIn` mechanism.
+  - Implemented in `ebean-annotation` (`DtoConvert`, `DtoMixin`), `ebean-api` (`DtoConverterManager`),
+    and `querybean-generator` (`DtoConverterMeta`, `DtoBeanMeta.converterDeps()`,
+    `DtoMappingReader`/`DtoMapperWriter`/`DtoMapperRegisterWriter` changes). Test coverage:
+    `tests/test-dto-mapping` `TestDtoConvert` (static + instance dispatch, fail-fast unregistered-type
+    check) and `TestDtoMixin` (mixin overlay, including instance-dispatch conversion resolved purely
+    from mixin-declared annotations). The instance-dispatch converter is registered via a
+    `DatabaseConfigProvider` (ServiceLoader hook run before the `Database` is built) rather than a test
+    `@BeforeAll`, since `EbeanDtoMapperRegister`'s mapper fields (including any needing
+    `DtoConverterManager`) are all constructed eagerly during `Database` startup, which can be
+    triggered by whichever test class in the module happens to run first.
+
+- **Fixed (validation phase, found via `central-access`): `@DtoPath` through a computed/derived
+  getter now fails at compile time, with an explicit `requires()` escape hatch.** `@DtoPath`
+  assumes every dotted segment names a real, fetchable Ebean bean property - so a path like
+  `@DtoPath("currentMachine.organisationMachine.registrationPlate")`, where `getOrganisationMachine()`
+  is a hand-written derived getter (not a real relation/column), used to **compile cleanly** (the
+  codegen had no way to tell it apart from a real property from source alone) but **fail at
+  runtime** with a `PersistenceException: No property found for [organisationMachine] in
+  expression ...`, because the generated `FetchGroup` builder tried to `fetch`/`select` it as if it
+  were a real Ebean property.
+  - Two genuinely separate sub-problems: (1) *detecting* that a path segment isn't a real,
+    fetchable property - solvable at compile time, since a real persistent property always has a
+    backing field (Ebean requires one to enhance), checked via `javax.lang.model`
+    (`ElementFilter.fieldsIn(...)` over the type + superclass chain, see `DtoMappingReader.hasField(...)`);
+    versus (2) *knowing what the computed getter needs fetched* to execute safely - not solvable at
+    compile time without full static/bytecode analysis of the getter's method body, out of scope.
+  - Resolution: don't attempt to infer (2) automatically. When `DtoMappingReader` detects a `@DtoPath`
+    segment with no backing field, it now fails fast at compile time (`ctx.logError(...)`) unless the
+    developer explicitly declares the real entity paths that must be fetched via
+    `@DtoPath(requires = {...})` (dot-notation, same convention as `@DtoPath`'s own `value()`) - e.g.
+    `@DtoPath(value = "primaryContact.lastName", requires = "contacts")` where `getPrimaryContact()`
+    picks the first entry out of the `contacts` collection. The real prefix before the computed
+    segment (if any) is automatically combined with the declared `requires()` paths, so the developer
+    doesn't need to redundantly repeat it. Declared paths are emitted as bare `.fetch(path)` calls in
+    the generated `FetchGroup` (distinct from the `.fetch(path, "props")` shape used for ordinary
+    scalar `@DtoPath` properties, since there's no specific target property list to narrow to here).
+  - **The zero-extra-fetch case is also supported, via an explicit `requires = {}`** - e.g.
+    `@DtoPath(value = "idBadge", requires = {})` where `getIdBadge()` derives purely from `id`
+    (always fetched regardless). An explicit empty array confirms "nothing extra needed", distinct
+    from omitting `requires()` entirely ("not yet considered", still a compile error) - `requires()`
+    itself can't tell the two cases apart (both read back as an empty `List`), so `DtoMappingReader`
+    checks the avaje-prism-generated `DtoPathPrism.values.requires()` instead, which returns `null`
+    only when the member was left at its default (i.e. omitted from source). `DtoPropertyMeta`
+    correspondingly carries `hasComputedSegment()` as its own boolean flag (set whenever a computed
+    segment was detected at all), independent of whether `requiredFetchPaths()` happens to be empty -
+    an earlier version conflated the two (inferring "has a computed segment" from "has a non-empty
+    requiredFetchPaths list"), which broke exactly this explicit-empty case by falling through to the
+    ordinary scalar `.select(...)` path and failing at runtime with `PersistenceException: Property
+    not found - idBadge` (`idBadge` isn't a real Ebean property, so it can't be selected).
+  - Implemented in `ebean-annotation` (`DtoPath.requires()`), and `querybean-generator`
+    (`DtoMappingReader` computed-segment detection/validation, `DtoPropertyMeta.requiredFetchPaths()`/
+    `hasComputedSegment()`, `DtoMapperWriter.fetchGroupChainCalls()` bare-fetch emission). Test
+    coverage: `tests/test-dto-mapping` `ComputedPathDto`/`TestComputedPath` (happy path, `requires`
+    correctly fetches the dependency and the mapped value is correct), `ComputedPathNoFetchDto`/
+    `TestComputedPathNoFetch` (explicit `requires = {}`, genuinely nothing extra needed), and
+    `querybean-generator`'s `DtoMapperComputedPathTest` (negative case - omitting `requires` on a
+    computed segment is a compile-time `ERROR` diagnostic, verified via direct `javax.tools.JavaCompiler`
+    compilation, mirroring `DtoMapperFetchPathCollisionTest`).
+  - Known gap: the dedup between the computed segment's required fetch paths and existing
+    `pathSelect`/`nestedAssocPaths` keys in `DtoMapperWriter` is a simplified exact-path-string check
+    (skip emitting a duplicate `.fetch(path)`), not full collision detection like the existing
+    NESTED_ONE/MANY vs `@DtoPath` check - a bare `fetch(path)` and an existing `fetch(path,
+    "specific,props")` for the same path string are not merged/reconciled, just left as two separate
+    calls if that edge case arises.
+
+- **Fixed: a single-hop `@DtoPath` rename through a computed/derived getter whose return type is
+  itself a registered nested DTO (`NESTED_ONE`/`NESTED_MANY`, not `SCALAR`) bypassed the
+  computed-segment validation above entirely.** E.g. `@DtoPath("primaryContact")` where the DTO
+  field's declared type is `ContactDto` (a type with its own `@DtoMapping(source = Contact.class,
+  target = ContactDto.class)`) and `getPrimaryContact()` is a computed getter with no backing
+  field on `Customer`. This resolves to a single-segment path, so `DtoMappingReader.resolveProperty()`
+  took its `properties.size() == 1` nested-lookup shortcut and returned early - before the
+  `computedFrom`/`requires()` validation block (added for the `SCALAR` case above) ever ran. The
+  generated `FetchGroup` then emitted a broken `fetch("primaryContact",
+  contactMapper.fetchGroup())` call (`"primaryContact"` isn't a real Ebean fetch path), failing at
+  runtime rather than compile time - the exact class of bug the `SCALAR` fix was meant to close off
+  entirely.
+  - Resolution: restructured `resolveProperty()` so the computed-segment detection/validation block
+    runs *before* the `properties.size() == 1` nested-lookup branch, so both `SCALAR` and
+    `NESTED_ONE`/`NESTED_MANY` paths share the same detection/validation. `DtoPropertyMeta` gained a
+    matching constructor overload for `NESTED_ONE`/`NESTED_MANY` carrying `computedSegment`/
+    `requiredFetchPaths`. In `DtoMapperWriter.fetchGroupChainCalls()`, a `NESTED_ONE`/`NESTED_MANY`
+    property with `hasComputedSegment()` true is routed into `extraFetchPaths` (the same bare
+    `.fetch(path)` mechanism as the `SCALAR` case) instead of emitting `fetch(path,
+    mapper.fetchGroup())` - since the nested mapper's own `FetchGroup` requirements can't be
+    meaningfully attached under a path name that doesn't exist on the source entity.
+  - Note the nested mapper's *own* fetch requirements (e.g. if `ContactDto` itself needed
+    `customer.billingAddress`) are **not** automatically propagated up through a computed segment -
+    only whatever the computed getter itself needs (via `requires()`) is fetched. The nested
+    mapper's `map(...)` call still works via plain Java method invocation regardless (Ebean
+    transparent lazy loading covers any gap), but relying on that silently reintroduces N+1 queries,
+    so the nested DTO used through a computed segment should ideally be a "leaf" shape needing
+    nothing beyond what `requires()` already declares.
+  - Implemented in `querybean-generator` (`DtoMappingReader.resolveProperty()` restructuring,
+    `DtoPropertyMeta`'s new constructor overload, `DtoMapperWriter.fetchGroupChainCalls()`). Test
+    coverage: `tests/test-dto-mapping` `ContactLeafDto`/`ComputedNestedDto`/`TestComputedNestedPath`
+    (happy path - generated `FetchGroup` is `.select("id").fetch("contacts")`, no broken
+    `fetch("primaryContact", ...)` call, and the mapped value is correct end-to-end), and
+    `querybean-generator`'s `DtoMapperComputedPathTest#dtoPathThroughComputedGetter_targetingNestedDto_withoutRequires_expectCompileError`
+    (negative case, mirroring the `SCALAR` one). The `NESTED_MANY` variant (a computed getter
+    returning a `List` of a type with its own registered nested DTO mapping) shares the identical
+    code path but had no dedicated regression test until later confirmed via `Customer
+    .getRecentContacts()` / `ComputedNestedListDto` / `TestComputedNestedListPath` (coverage only,
+    not a bug fix - passed cleanly first try, confirming the shared code path does work end-to-end
+    for both `NESTED_ONE` and `NESTED_MANY`).
+
+- **Fixed: `@DtoRef` never checked for a computed/derived association getter at all.** Unlike
+  `@DtoPath`, `@DtoRef`'s association name (derived by stripping the `Id` suffix off the field
+  name, e.g. `primaryContactId` -> `primaryContact`) was never checked against `hasField(...)` -
+  so `@DtoRef` on a computed getter (e.g. `getPrimaryContact()` picking the first entry out of a
+  `contacts` collection) compiled cleanly and generated a broken `FetchGroup.select("primaryContact")`
+  call (`"primaryContact"` isn't a real Ebean property), failing at runtime rather than compile
+  time - the same class of bug as the original `@DtoPath` fix, just entirely unaddressed for
+  `@DtoRef`'s separate code path.
+  - Resolution: `@DtoRef` gained its own `requires()` attribute (dot-notation, same convention and
+    explicit-empty semantics as `@DtoPath#requires()`, using the same `DtoRefPrism.values.requires()
+    == null` omitted-vs-explicit-empty technique). `DtoMappingReader`'s `@DtoRef` branch now checks
+    `hasField(meta.source(), assocName)` and fails fast at compile time (`ctx.logError(...)`) when
+    the association has no backing field and `requires()` wasn't specified. `DtoPropertyMeta`'s
+    `REF` properties now carry `computedSegment`/`requiredFetchPaths` through the existing fields
+    (no new constructor needed - the full constructor already had the right shape).
+    `DtoMapperWriter.fetchGroupChainCalls()`'s `REF` case now checks `hasComputedSegment()` and
+    routes into `extraFetchPaths` (bare `.fetch(path)`) instead of `rootSelect.add(assoc)` when
+    true - the value expression itself (`source.getPrimaryContact().getId()`, null-guarded) is
+    unaffected, since it's plain Java method invocation regardless of whether the association name
+    is a real Ebean property.
+  - Implemented in `ebean-annotation` (`DtoRef.requires()`), and `querybean-generator`
+    (`DtoMappingReader`'s `@DtoRef` branch, `DtoMapperWriter.fetchGroupChainCalls()`'s `REF` case).
+    Test coverage: `tests/test-dto-mapping` `ComputedRefDto`/`TestComputedRefPath` (happy path -
+    generated `FetchGroup` is `.select("id").fetch("contacts")`, no broken `select("primaryContact")`
+    call, and the mapped id is correct end-to-end), and `querybean-generator`'s
+    `DtoMapperComputedPathTest#dtoRefThroughComputedGetter_withoutRequires_expectCompileError`
+    (negative case, mirroring the `@DtoPath` ones).
+
+- **Fixed: `requires()` path values themselves were never validated against the source type's
+  real property graph.** `@DtoPath(requires = {...})`/`@DtoRef(requires = {...})` values are
+  handed straight through to `FetchGroup.fetch(...)` unmodified - a typo (e.g. `requires =
+  "contactz"` for the real `contacts` property) compiled cleanly, since only the *computed
+  segment itself* was checked against `hasField(...)`, not the developer-declared dependency
+  paths meant to fix it. That silently reintroduced the exact runtime `PersistenceException` the
+  whole `requires()` escape hatch exists to prevent, just one step removed and harder to spot.
+  - Resolution: added `DtoMappingReader.validateRequiresPath(...)`, which walks each dot-notation
+    segment of a declared `requires()` value from the source root (`meta.source()`), checking
+    `hasField(...)` at every hop exactly like `@DtoPath#value()`'s own segments are checked, and
+    unwrapping a `java.util.List`-typed intermediate hop to its element type (via
+    `listElementType(TypeMirror)`) so a collection segment followed by a further hop resolves
+    correctly - needed a new `getterReturnTypeMirror(...)` helper (returning the raw `TypeMirror`
+    rather than converting straight to `TypeElement`, which can't distinguish a `List` from any
+    other declared type) alongside the existing `getterReturnType(...)`. Called for every entry in
+    `pathPrism.requires()`/`refPrism.requires()` right after they're read, for both the `@DtoPath`
+    and `@DtoRef` branches. The already-validated real prefix (segments before the computed one in
+    a `@DtoPath#value()`) is intentionally *not* re-validated, since it was already checked while
+    walking `value()` itself.
+  - Implemented in `querybean-generator` (`DtoMappingReader.validateRequiresPath(...)`,
+    `getterReturnTypeMirror(...)`, called from both the `@DtoPath` and `@DtoRef` branches). Test
+    coverage: `querybean-generator`'s
+    `DtoMapperComputedPathTest#dtoPathRequires_withTypoInPathValue_expectCompileError` (negative
+    case - a typo'd `requires()` segment is a compile-time `ERROR` diagnostic); existing
+    `tests/test-dto-mapping`/`central-access` suites (real multi-segment `requires()` values like
+    `"currentMachine.organisationMachines"`) continue to pass unchanged, confirming the validation
+    doesn't false-positive on legitimate paths.
+
+- **Fixed: a bare, full `requires()` fetch and a sibling property's narrowed `@DtoPath` fetch of
+  the exact same path silently conflicted, with the narrow one always (incorrectly) winning.**
+  `DtoMapperWriter.fetchGroupChainCalls()`'s dedup logic used to skip emitting a computed
+  segment's bare `fetch(path)` call whenever another property's `@DtoPath` already had a narrowed
+  `fetch(path, "specific,props")` entry for that exact path string - on the assumption the two
+  were interchangeable/redundant. They aren't: `FetchGroup`'s builder (`OrmQueryDetail.fetch(...)`)
+  keys fetch calls by path in a plain `Map` and **replaces** rather than merges same-path entries,
+  so whichever call format was emitted meant the *other* was silently discarded. Since the narrow
+  entry was always emitted first and the bare one skipped whenever it existed, the narrow selection
+  always won - meaning a computed getter's `requires()` declaration could be completely ignored
+  whenever an unrelated sibling `@DtoPath` happened to narrow-select the exact same path, leaving
+  whatever extra properties the computed getter actually touches unfetched (a silent lazy load, or
+  a hard `LazyInitialisationException` outside a persistence context).
+  - Resolution: reversed the priority - `fetchGroupChainCalls()` now skips a narrowed `pathSelect`
+    entry when `extraFetchPaths` (the computed segment's `requires()`) declares the exact same
+    path, letting the bare, full `fetch(path)` call win instead. This is always safe since a full
+    fetch is a superset of any narrower property selection - the narrow entry's own properties are
+    included within it regardless. The existing `nestedAssocPaths` priority (a `NESTED_ONE`/
+    `NESTED_MANY` property's full `fetch(path, mapper.fetchGroup())` always wins over a bare
+    `fetch(path)`) was correct already and left unchanged - a nested mapper's own `FetchGroup` is
+    strictly richer than either form and must not be replaced by either.
+  - Implemented in `querybean-generator` (`DtoMapperWriter.fetchGroupChainCalls()`). Test coverage:
+    `tests/test-dto-mapping` `FetchCollisionDto`/`TestFetchCollisionPath`, plus a new computed
+    getter `Customer.getBillingSummary()` (reads `billingAddress.getLine1()`, deliberately a
+    different `Address` property to the `city` narrowly selected by a sibling `@DtoPath` on the
+    same DTO) - confirmed to reproduce `LazyInitialisationException: Property not loaded: line1`
+    when the fix is reverted, and pass cleanly (correct `line1`-derived value, generated
+    `FetchGroup` is `.select("id").fetch("billingAddress")` with no narrowed variant at all) with
+    it in place.
+
+- **Fixed: two `@DtoMixin` companion types targeting the same DTO class silently conflicted, with
+  the second-processed one winning.** `DtoMappingReader.collectMixins()` keyed a single
+  `mixinsByTarget` map by the target DTO's FQN, and `Map.put(...)` unconditionally overwrote any
+  existing entry - so if two mixin interfaces (e.g. a legitimate one plus an accidental duplicate,
+  or two independently-added mixins that both happened to target the same generated/unowned DTO)
+  both declared `@DtoMixin(SameDto.class)`, whichever was visited last by
+  `roundEnv.getElementsAnnotatedWith(...)` silently won, and *all* of the other mixin's
+  `@DtoPath`/`@DtoRef`/`@DtoConvert` overlays were discarded with no diagnostic at all.
+  - Resolution: `collectMixins()` now checks for an existing registration before storing a new one
+    and raises a compile `ERROR` naming both the target and the already-registered mixin's
+    qualified name, rather than silently overwriting it.
+  - Implemented in `querybean-generator` (`DtoMappingReader.collectMixins()`). Test coverage: new
+    negative compile-error test `DtoMapperComputedPathTest#duplicateDtoMixin_forSameTarget_expectCompileError`
+    (two minimal `@DtoMixin(FooDto.class)` interfaces both declaring a `bar()` method, compiled
+    together, asserting the `Duplicate @DtoMixin` diagnostic is raised); existing
+    `tests/test-dto-mapping` `TestDtoMixin` (single, legitimate mixin usage) continues to pass
+    unchanged.
+
+- **Fixed: `@DtoRef` and `@DtoPath` both present on the same field silently conflicted, with
+  `@DtoRef` always (invisibly) winning.** `resolveProperty()` checked `refPrism != null` first and
+  returned immediately whenever present, so a field carrying both annotations at once - whether by
+  copy/paste mistake, a half-finished rename from one style to the other, or simple confusion
+  between the two escape hatches - had its `@DtoPath` completely ignored with no diagnostic at all.
+  - Resolution: `resolveProperty()` now resolves both prisms upfront and raises a compile `ERROR`
+    naming the field when both are present, rather than silently picking `@DtoRef` and discarding
+    `@DtoPath`.
+  - Implemented in `querybean-generator` (`DtoMappingReader.resolveProperty()`). Test coverage: new
+    negative compile-error test `DtoMapperComputedPathTest#dtoRefAndDtoPath_onSameField_expectCompileError`
+    (a field carrying both `@DtoRef` and `@DtoPath("bar.id")` over a real, non-computed association,
+    isolating the conflict diagnostic from the separate computed-getter `requires()` diagnostics).
+
+- **Fixed: `@DtoConvert` on a `NESTED_ONE`/`NESTED_MANY` property was silently ignored.**
+  `resolveProperty()` resolves the property's `DtoConverterMeta` unconditionally up front (before
+  it's known whether the property will resolve to `SCALAR`/`REF`/`NESTED_ONE`/`NESTED_MANY`), but
+  only the `SCALAR`/`REF` `DtoPropertyMeta` constructors actually accept/store a converter - the
+  `NESTED_ONE`/`NESTED_MANY` constructor calls never took one, so a resolved converter was simply
+  dropped on the floor with no diagnostic. A developer adding `@DtoConvert` to a nested-DTO field
+  (e.g. hoping to post-process the nested mapper's result) would see it silently do nothing -
+  `DtoMapperWriter.propertyValueExpression()`'s `NESTED_ONE`/`NESTED_MANY` cases call straight into
+  `mapperFieldName(property) + ".map(...)"`/`".mapList(...)"` with no converter wrapping at all.
+  - Resolution: added `rejectConverterOnNested(...)`, called at each of the four call sites that
+    construct a `NESTED_ONE`/`NESTED_MANY` `DtoPropertyMeta` (the single-hop `@DtoPath`-rename
+    branch's two cases, and the plain non-`@DtoPath` branch's two cases) - raises a compile `ERROR`
+    naming the field whenever a converter was resolved for it, rather than silently discarding it.
+  - Implemented in `querybean-generator` (`DtoMappingReader.resolveProperty()`,
+    `rejectConverterOnNested()`). Test coverage: new negative compile-error test
+    `DtoMapperComputedPathTest#dtoConvertOnNestedOne_expectCompileError` (a `NESTED_ONE` field
+    carrying `@DtoConvert` over a legitimately nested, separately-`@DtoMapping`-registered type);
+    existing `tests/test-dto-mapping` suite (no nested property currently combines `@DtoConvert`
+    with `NESTED_ONE`/`NESTED_MANY`) continues to pass unchanged, confirming no false positives on
+    plain nested properties.
+
+- **Fixed: `@DtoConvert(method = ...)` resolution ignored parameter arity/overloads.** The shared
+  `findMethod(type, name)` helper (also used for the builder's `build()` lookup and `@DtoMixin`
+  companion-method lookup) matches purely by simple name - the first `ExecutableElement` found -
+  with no arity or parameter-type check at all. For `@DtoConvert` specifically this is a real risk:
+  its documented contract is a method "taking the source property value and returning the
+  converted DTO property value" (i.e. exactly one parameter), but a shared/reusable conversion
+  utility class is a very plausible place to have multiple same-named overloads (e.g. `format
+  (Instant)` and `format(LocalDate)`) - `findMethod` would silently bind to whichever one
+  `ElementFilter.methodsIn` happened to return first, independent of which one the developer
+  actually meant, generating either a confusing arity/type-mismatch compile error in the generated
+  mapper or, if both overloads happened to be call-compatible, silently invoking the wrong one.
+  - Resolution: added a dedicated `findConverterMethod(...)` (used only by `resolveConverter()`,
+    leaving the shared `findMethod()` untouched for the builder/mixin call sites which have their
+    own, different arity expectations) that filters same-named candidates down to those taking
+    exactly one parameter. Zero matches raises a clear "not found ... taking exactly one
+    parameter" error; more than one match (multiple 1-arg overloads sharing the name) raises an
+    "ambiguous - N overloads take exactly one parameter" error, since `@DtoConvert` has no
+    parameter-type-based way to disambiguate and the developer must rename one of the overloads.
+  - Implemented in `querybean-generator` (`DtoMappingReader.resolveConverter()`,
+    `findConverterMethod()`). Test coverage: new negative compile-error tests
+    `DtoMapperComputedPathTest#dtoConvertMethod_withAmbiguousOverloads_expectCompileError` (two
+    same-named 1-arg overloads) and `#dtoConvertMethod_withWrongArity_expectCompileError` (a
+    same-named 0-arg method, no 1-arg candidate at all); existing `tests/test-dto-mapping`
+    converter usage (a single, unambiguous 1-arg method per converter type) continues to resolve
+    and pass unchanged.
+
+## References
+
+- Requirements: [dto-mapping-requirements.md](./dto-mapping-requirements.md)
+- Issue: https://github.com/ebean-orm/ebean/issues/2540
+- MapStruct cycle mapping: https://mapstruct.org/documentation/stable/reference/html/#mapping-object-cycles
@@ -0,0 +1,337 @@
+# Nested DTO Mapping — Requirements
+
+Design requirements distilled from [issue #2540 "Support nested DTO mapping"](https://github.com/ebean-orm/ebean/issues/2540),
+reviewed against comparable features in QueryDSL (`@QueryProjection`) and Blaze-Persistence (`@EntityView`).
+
+## Context
+
+Ebean already supports:
+
+- Partial/flat DTO queries via `DB.findDto(...)` and `query.select(...).asDto(Dto.class)`.
+- `@Formula` / `@Formula2` — path-based, auto-joined computed SQL expressions, but only on managed entities.
+- `query.setUnmodifiable(true)` — builds a read-only, non-lazy-loading entity graph (`InterceptReadOnly`,
+  see PR #2626). Accessing an unloaded property throws `LazyInitializationException`; mutating throws
+  `UnmodifiableEntityException`.
+
+Unlike Hibernate, Ebean does dirty-detection on the bean itself (no dynamic proxies), so there is very little
+extra cost to an entity-graph query versus a DTO query. This makes an **unmodifiable entity graph** a cheap,
+natural intermediate representation to map *from* when producing a DTO graph — we don't need Blaze/Hibernate's
+proxy-based `EntityView` mechanism to get the performance benefit they are chasing.
+
+The goal is nested DTO graph support (DTOs containing ToOne/ToMany child DTOs), not just today's flat DTOs,
+while keeping DTOs as plain, framework-unattached classes.
+
+## Accepted Requirements
+
+### A. Nested DTO graphs
+
+- **Support nested DTO graphs (ToOne/ToMany)**
+  Allow mapping a query result into a DTO graph where DTO fields are themselves DTOs (ToOne) or
+  `List`/`Set<Dto>` (ToMany), not just flat DTOs. Use the existing `setUnmodifiable(true)` entity graph as
+  the intermediate, de-duplicated, identity-consistent source to map from.
+  *Inspiration: Blaze `@EntityView` subviews/subview collections; Jimmer fetcher DTOs.*
+
+- **Auto-generated entity → DTO graph mapper**
+  Given an unmodifiable entity graph plus a target nested DTO type, generate (via annotation processing,
+  reflection-free) a mapper that walks the graph and populates the DTO graph, matching properties by
+  name/type with override annotations for renames, computed values, and collection element types.
+  *Inspiration: Blaze `@EntityView` + subview mapping; conceptually similar to MapStruct but Ebean-generated
+  and graph/identity aware.*
+
+- **Identity-aware de-duplication in nested collections**
+  When mapping nested collections referencing the same underlying entity instance multiple times, reuse the
+  same DTO instance (mirrors Blaze/Jimmer identity semantics) rather than producing independent copies.
+  *Inspiration: Blaze/Jimmer identity handling.*
+
+### B. Formula-style DTO annotations
+
+- **`@Formula2`-like annotations on DTO fields**
+  Bring the existing `@Formula` / `@Formula2` concept (auto-joined, path-based computed SQL expressions) to
+  DTO classes so a DTO field can request a computed/aggregated value with the join auto-derived, instead of
+  only being available on managed entities.
+  *Inspiration: User suggestion; Ebean `@Formula2`; Blaze `@Mapping` computed expressions.*
+  *Status: a narrower version (pulling in an existing entity-level `@Formula2` by path) was implemented and
+  then rejected - for the common same-name case it generated code identical to a plain unannotated field, so
+  the annotation added no real value beyond a codegen-time validation. See `docs/dto-mapping-design.md`
+  ("Formula2-on-DTO scope" and "Ad-hoc computed/formula properties" sections). The broader goal - arbitrary
+  ad-hoc computed SQL on a DTO field - is better served by modelling the computed value as its own
+  `@Entity @View`/`@Sql` read entity and mapping *that* into a plain DTO, reusing the existing (already
+  accepted) nested-DTO mapping machinery rather than a new DTO-level annotation.
+
+- **Path-based property mapping annotation on DTO**
+  Allow a DTO field or constructor param to be annotated with a source path expression (e.g. `parent.name`)
+  so Ebean can auto-derive the select clause plus joins for nested/renamed properties, reducing manual
+  constructor wiring for non-trivial mappings.
+  *Inspiration: Blaze `@Mapping`; QueryDSL constructor expressions.*
+
+### C. Compile-time safety
+
+- **Compile-time verification of `select(...).asDto(...)` mapping** *(explored, rejected as impractical -
+  `mapTo()` accepted as the alternative)*
+  Today `select(props).asDto(Dto.class)` is only checked at runtime. Explored an annotation-processor
+  based mechanism to verify at compile time that selected properties match the DTO constructor or setters,
+  mirroring QueryDSL's `@QueryProjection` compile-time Q-type generation. Rejected as impractical: raw SQL
+  is an opaque `String` at compile time, and even the typed query-bean `.select(...)` form only
+  type-checks against the *entity* - the match to the target DTO still happens at runtime via reflection
+  (`DtoQueryPlanConstructor`), and the `.asDto(...)` call site can be arbitrarily distant from the
+  `.select(...)` call, so there's no fixed AST shape an annotation processor could reliably verify.
+  QueryDSL's actual compile-time safety comes from a different mechanism entirely - typed
+  `Projections.constructor(...)`/generated Q-type constructor calls, not from checking an
+  independently-built select-list against a DTO. `mapTo(Dto.class)` (see section A) already closes the
+  underlying gap in the opposite, tractable direction: it derives the select/fetch spec *from* the DTO's
+  declared shape at APT time, so it is compile-time safe by construction, with no separate select-list to
+  drift out of sync. Recommendation: document `mapTo()` as the compile-time-safe answer for DTO
+  projections, and treat `asDto()`/`findDto()` explicitly as the flexible, runtime-checked escape hatch
+  for raw/dynamic SQL.
+  *Inspiration: QueryDSL `@QueryProjection` compile-time Q-type generation.*
+
+- **Fail-fast on unmapped or lazy property access**
+  Ensure a clear, documented, minimal-ceremony way to fail fast if code touches a property not included in
+  the query projection, instead of silently lazy loading or returning null. `query.setUnmodifiable(true)`
+  already satisfies this (throws `LazyInitializationException`) — document/promote it as the answer, and
+  evaluate whether a lighter-weight flag decoupled from full unmodifiable/read-only semantics is needed.
+  *Inspiration: Original issue ask; already solved via `setUnmodifiable()` (PR #2626 `InterceptReadOnly`).*
+
+### D. Fetch strategy and performance
+
+- **Fetch strategy control for DTO graph relationships**
+  Existing entity query fetch hints (join vs. select/subselect secondary query, `+query`/`+lazy`) should
+  transparently carry over when the target of the query is a DTO graph rather than an entity graph.
+  `query.mapTo(Dto.class)` applies the DTO-derived `FetchGroup` only when the query has no
+  `select()`/`fetch()` already set - a manually tuned fetch spec always takes precedence and is never
+  overridden, allowing manual query optimisation when needed (at the cost of falling back to the
+  existing fail-fast-on-unmapped-property behaviour if the manual spec doesn't cover what the DTO needs).
+  *Inspiration: Blaze FETCH/SELECT/SUBSELECT fetch strategies.*
+
+- **Pagination support for DTO graph queries**
+  Confirm existing pagination works unchanged when projecting into nested DTO graphs.
+  *Inspiration: Blaze pagination and keyset pagination support.*
+
+### E. Custom property conversion
+
+- **Per-property custom scalar conversion (`@DtoConvert`)**
+  Motivated by real hand-written mapper code (`DriverMapper`, central-access) doing per-property scalar
+  coercion (`short` -> `boolean`) and dependency-backed conversion (AES decryption via an injected cipher).
+  Introduce a `@DtoConvert(value = ConverterType.class, method = "name")` annotation (combinable with
+  `@DtoPath` for source-getter override) on a DTO property. The generator dispatches based on whether the
+  referenced method is `static`:
+  - **Static method** -> a direct static call is inlined (`ConverterType.method(source.getX())`), zero
+    ceremony, no registration - covers common, reusable, dependency-free scalar coercions (e.g.
+    `short`/`boolean`, enum <-> `String`) that could apply across many unrelated entity/DTO pairs.
+  - **Instance method** -> dispatched via `DtoConverterManager.get(ConverterType.class).method(source.getX())`
+    and wired as a real constructor parameter/field on the generated mapper (same shape as existing
+    nested-mapper constructor injection) - covers conversions needing a real dependency (e.g. a cipher).
+  `DtoConverterManager` is a small, deliberately-scoped static put/get bridge: the app registers an
+  already-DI-constructed converter singleton (e.g. built by avaje-inject) *before* building the `Database`.
+  This is a narrow, accepted exception to the general no-static-mutable-state convention - it exists solely
+  to bridge an already-DI-constructed singleton into `ServiceLoader`-discovered, no-arg-constructed generated
+  code, which cannot otherwise reach a DI container. `DtoConverterManager.get(type)` throws immediately if
+  nothing was registered, so a missing converter fails fast at Database-startup time (an eager field
+  initializer on the generated `EbeanDtoMapperRegister`), not lazily on first use.
+  *Design exploration considered and rejected two alternatives first: (a) a `DtoMapContext.service(Class)`
+  lookup - rejected because `DtoMapContext` is a short-lived per-call identity-cache only, wrong lifetime for
+  a real singleton dependency; (b) a `ServiceLoader`-discovered `DtoConverterSource` SPI mirroring
+  `DtoMapperRegister` itself - rejected because a `ServiceLoader`-instantiated (no-arg) source cannot bridge
+  to an *already* DI-constructed dependency (e.g. a cipher needing config/secrets) without reconstructing it
+  itself, duplicating/bypassing the app's own DI-managed instance.*
+  *Inspiration: `DriverMapper` (central-access) hand-written pattern; MapStruct qualified converter methods.*
+  *Status: implemented - `@DtoConvert` (ebean-annotation), `io.ebean.DtoConverterManager` (ebean-api), and
+  querybean-generator codegen support (static/instance dispatch, constructor wiring deduplicated by converter
+  type). Test coverage: `tests/test-dto-mapping` `TestDtoConvert`.*
+
+- **Type-pair (package-level) custom scalar conversion**
+  Motivated by real hand-written mapper code (`EboxMapper`, central-access): the same conversion repeats
+  across many unrelated properties on one target - `DateUtils.toCalendar(...)` on ~9 fields,
+  `parseEnum(EnumType.class, value)` on ~3 - under today's `@DtoConvert` every one of those properties must
+  carry its own repeated annotation. MapStruct solves this by letting a conversion method be defined once
+  (in the mapper or a `uses = {...}` helper) and auto-applying it to *every* property whose source/target
+  types match that method's signature - no per-field wiring. Proposed: a package-level, repeatable
+  `@DtoConverters({ConverterType.class, ...})` (sibling to `@DtoMapping` in `package-info.java`) - the
+  generator indexes every public static/instance method on the referenced type(s) by `(paramType ->
+  returnType)`, then for any property whose source getter type doesn't already match the target field type
+  and which carries no explicit per-property `@DtoConvert`, looks up that type pair and wires it in
+  automatically (same static-vs-instance/`DtoConverterManager` dispatch rules as `@DtoConvert` today). An
+  explicit per-property `@DtoConvert` always overrides the type-level default. Deliberately no built-in
+  conversions shipped by Ebean itself (no implicit `Enum.valueOf`/`.name()`) - the app still owns
+  exception/null-handling semantics (e.g. `parseEnum`'s catch-and-null-on-bad-value), just declares it once
+  instead of per-field.
+  **Status: implemented.** `@DtoConverters(ConverterType.class, ...)` (a single non-repeatable annotation
+  taking a `Class<?>[]`, `@Target({PACKAGE, MODULE})`) is registered once per package/module alongside
+  `@DtoMapping`. The generator indexes every public, single-arg, non-void method on each referenced type by
+  exact `(paramType -> returnType)`; any SCALAR property (plain or `@DtoPath`-renamed) with no explicit
+  `@DtoConvert` and a source/target type mismatch is auto-wired to the matching method (a duplicate/ambiguous
+  type pair across the registered types is a compile-time processor error). List-element-wise conversion and
+  `@DtoRef` (FK-id) properties are out of scope. Test coverage:
+  `tests/test-dto-mapping/.../TestDtoConverters.java` (`UuidConverters`/`UuidShortCodeConverter`,
+  `ContactTypeConverterDto`) - covers same-name auto-dispatch, `@DtoPath`-renamed auto-dispatch, and explicit
+  `@DtoConvert` overriding the registered default.
+  *Inspiration: `EboxMapper` (central-access) hand-written pattern; MapStruct type-signature-matched
+  conversion methods.*
+
+- **`@DtoMixin` for DTOs that cannot be annotated directly**
+  Some DTOs are generated (e.g. from an OpenAPI spec) and not editable/annotatable, so `@DtoPath`/
+  `@DtoConvert`/`@DtoRef` cannot always be placed directly on the DTO. Introduce a `@DtoMixin(Target.class)`
+  companion interface/type, discovered by scanning the compilation round and overlaying its per-property
+  annotations onto the real target's properties by name-match - directly mirrors avaje-jsonb's
+  `@Json.MixIn` mechanism (`KingfisherMixin`/`CrewMateMixIn` pattern), a proven prior-art solution to the
+  exact same "can't annotate a generated/unowned type" problem.
+  *Inspiration: avaje-jsonb `@Json.MixIn`.*
+  *Status: implemented - `@DtoMixin` (ebean-annotation) and querybean-generator round-scanning/overlay
+  support (matches mixin methods to target properties by name, applying whichever of `@DtoPath`/`@DtoRef`/
+  `@DtoConvert` is present as if declared on the target field itself). Test coverage: `tests/test-dto-mapping`
+  `TestDtoMixin`.*
+
+### F. DI-friendly manual mapper usage
+
+- **Public `DtoMapperManager` with `get(Class<T> mapperType)` for DI**
+  Motivated by `DriverMapper`/`DriverService` (central-access): `DriverMapper` is a hand-written
+  `@Component` constructor-injected into `DriverService`. Moved `DtoMapperManager` from internal
+  (`io.ebeaninternal.server.dto`) to public `io.ebean` - unchanged `mapperFor(source, dto)`, plus a new
+  `get(Class<T> mapperType)` keyed by the generated mapper's own concrete class (e.g.
+  `manager.get(CustomerDtoMapper.class)`), for direct/concrete-typed DI injection. `DtoMapperRegister`
+  gained a default `mapperOfType(Class<T>)` method (non-breaking); the generator emits the real if-chain
+  body (mirrors `mapperFor`'s if-chain). `DtoMapperManager` has zero `Database` dependency (constructor
+  only does `ServiceLoader.load(DtoMapperRegister.class)`), so it can be constructed standalone,
+  independent of/before a `Database` - e.g. as an avaje-inject bean.
+  *Inspiration: `DriverMapper`/`DriverService` (central-access).*
+  *Status: implemented.*
+
+- **`DtoMapperManager` sharing via `DatabaseBuilder.putServiceObject`**
+  So `query.mapTo()` and application-injected mappers share the exact same `DtoMapperManager` instance
+  (and hence the same underlying generated mapper singletons) rather than each independently constructing
+  its own, `InternalConfiguration` checks `config.getServiceObject(DtoMapperManager.class)` first (mirrors
+  the existing `AutoMigrationRunner`/`GeoTypeProvider` `putServiceObject`/`getServiceObject` pattern),
+  falling back to constructing a default `new DtoMapperManager()` if none was supplied.
+  *Inspiration: user proposal following `DriverMapper`/`DriverService` review.*
+  *Status: implemented.*
+
+*Rejected: generator-emitted `builder(source)` method* - `DriverMapper` exposes `builder(cDriver)`
+returning a partially-populated `DriverBuilder` so callers can add extra caller-supplied fields (e.g.
+fleets) before `build()`. Rejected as a generator feature - `Driver`/`DriverSummary` already use
+avaje-recordbuilder's `@RecordBuilder`, which generates `Target.builder(existingInstance)`
+(seed-from-instance). The same effect is already achievable with zero ebean changes:
+`mapper.map(source)` then `Builder.builder(mapped).extraField(x).build()`. Documented as a recipe
+instead (see "Recipe: adding extra caller-supplied fields after mapping" in
+`docs/guides/mapping-entity-graphs-to-dtos.md`).
+
+### G. Large-target construction and shape variants
+
+- **Builder-based target construction for large DTOs**
+  Motivated by `UserService`/`User` (central-access): `User` is a 24-field OpenAPI-generated record with
+  a `@RecordBuilder`-generated `UserBuilder`, hand-mapped via a long fluent builder chain rather than a
+  positional constructor to stay readable/refactor-safe. The generator auto-detects a RecordBuilder-style
+  builder on the target (static `Target.builder()` + fluent per-property setters + `build()`) and uses
+  `Target.builder().prop(x)....build()` instead of `new Target(a, b, c, ...)` whenever (a) a builder is
+  detected and (b) the target has more than a threshold number of properties (default 5), falling back to
+  the positional constructor otherwise. An explicit `@DtoMapping` attribute (`builder = AUTO | ALWAYS |
+  NEVER`) overrides the heuristic in either direction. Applies regardless of whether the target class is
+  hand-authored or foreign/generated (e.g. an OpenAPI record) - `@DtoMapping` is already declared
+  externally via `package-info.java`, not on the target class, so this was already compatible with
+  foreign target types.
+  *Inspiration: `UserService`/`User` (central-access).*
+  *Status: implemented.*
+
+- **Named mapper variants excluding nested paths, sharing one generated class**
+  Motivated by `UserService`/`User` (central-access): `CUser` -> `User` is mapped in two shapes - with
+  nested `fleets` (`findUserByGid`) and without (`findAll`, bulk listing) - to avoid an unnecessary
+  join/fetch on the common bulk-listing path. Keeps the existing "shape always derived from declaration,
+  fetch spec always wins" philosophy (rejected relaxing that rule / rejected a runtime
+  is-property-loaded auto-skip check as less deterministic). The same `(source, target)` pair can be
+  declared more than once in `package-info.java` via a named variant, e.g.
+  `@DtoMapping(source = CUser.class, target = User.class)` (base/full) plus
+  `@DtoMapping(source = CUser.class, target = User.class, name = "noFleets", exclude = "fleets")`
+  (variant). Both variants are generated into the **same** mapper class (one class per target, not one
+  per variant) and share a single private `build(source, context, boolean includeXxx, ...)` method
+  containing the common field population written once; each excluded nested path becomes a `boolean
+  includeXxx` parameter of that shared method rather than a precomputed value, so `build()` still
+  evaluates every property - included or excluded - inline, at its own declared field position (a
+  `includeFleets ? fleetsMapper.mapList(...) : List.of()` ternary in place, not hoisted out as a
+  pre-evaluated call argument). This preserves the DTO's declared property order as the true evaluation
+  order regardless of which properties a variant happens to exclude. The base `map()` passes `true` for
+  every flag; each named variant (exposed as a same-named accessor, e.g. `noFleets()`, returning a single
+  shared/cached instance of its own small `DtoMapper<SOURCE, TARGET>`-implementing inner class - not
+  reconstructed per call) passes `false` for the paths it excludes and omits that path from its own
+  `fetchGroup`. Selected via a new `query.mapTo(Class<D> dtoType, DtoMapper<T, D> mapper)` overload
+  taking an already-resolved mapper instance directly (e.g. `query.mapTo(User.class,
+  userMapper.noFleets())`) - no string-based variant lookup, and no changes needed to
+  `DtoMapperRegister`/`DtoMapperManager`.
+  *Inspiration: `UserService`/`User` (central-access).*
+  *Status: implemented.*
+
+- **Setter-based (mutable JavaBean) target construction**
+  Motivated by `EboxMapper` (central-access): its target types (`Ebox`, `MachineSummaryInfo`, from
+  `nz.co.eroad.schema.eroadtypes`, JAXB/XSD-generated legacy SOAP shapes) are plain mutable JavaBeans - a
+  public no-arg constructor plus a `void setXxx(...)` setter per property - neither a positional constructor
+  match nor a RecordBuilder-style fluent builder (see section G above). The generator currently only
+  recognizes those two construction strategies, so this common third shape (typical of JAXB/XSD-generated
+  and many hand-written mutable POJOs) can't be targeted by `@DtoMapping` at all today. Proposed: detect a
+  no-arg constructor plus a `void setXxx(propertyType)` setter per mapped property as a third construction
+  strategy, generating `Target target = new Target(); target.setX(...); ...; return target;` (mirroring the
+  existing `build = AUTO | ALWAYS | NEVER` override precedent from section G for explicit control over which
+  strategy applies). Would also unblock the `mapToBuilder()`-style "populate ignored/derived properties after
+  the generated mapping, before finishing construction" pattern for these targets (currently only available
+  for builder-shaped targets) - relevant to `EboxMapper`'s `machineSummaryInfo` (a genuinely composite,
+  multi-association derived value, out of reach of `@DtoConvert`/`@DtoPath` regardless of this gap, but a
+  natural fit for the same "map base fields via codegen, then set the derived one by hand" pattern already
+  used for `Fleet.assignedMachines`/`assignedDrivers`).
+  *Inspiration: `EboxMapper` (central-access); JAXB/XSD-generated SOAP DTO shapes generally.*
+  **Status: implemented.** `@DtoMapping(setter = AUTO | ALWAYS | NEVER)` mirrors `builder()`'s override
+  precedent. Detection requires a public no-arg constructor plus a public `setXxx(...)` setter for every
+  mapped property - either `void` or fluent-style (returning the target type itself, e.g. `public Target
+  setXxx(...) { ...; return this; }`); the generated code always calls the setter as a bare statement and
+  discards any return value, so either shape works identically. A builder, when selected, always takes
+  priority over setter-based construction. Under the default `AUTO`, setter-based construction is only
+  attempted when the target has no positional constructor matching the mapped properties (arity-based) and
+  no builder was selected - existing positional-constructor and builder-shaped targets are entirely
+  unaffected. `ALWAYS` requires the shape (codegen-time error otherwise); `NEVER` always uses a positional
+  constructor. Generated shape: `Target target = new Target(); target.setX(...); ...; return target;` (a
+  `computeIfAbsent(...)`-wrapped block-lambda variant when the target is nested elsewhere in the graph).
+  Deliberately **no** `mapToBuilder(...)`-style post-construction accessor is generated for this strategy -
+  the returned target is already the final, fully mutable instance (setters are required to be `public`), so
+  a caller can already call e.g. `dto.setExternalRef(...)` directly on the mapped result, exactly the pattern
+  `EboxMapper` already uses by hand; this is unlike the builder strategy, where the intermediate builder is
+  otherwise unreachable after its one-shot `build()` call. Test coverage:
+  `tests/test-dto-mapping/.../TestDtoSetterConstruction.java` (`ContactSetterDto`) - covers auto-detected
+  setter-chain construction plus post-construction population of two `@DtoIgnore` properties (a plain scalar
+  and a `List`) via their public setters; plus `ContactSetterFluentDto` - covers the fluent-setter-return-shape
+  variant.
+
+### H. Record entity sources
+
+- **Record-style (bare/fluent) accessors on the source (entity) side**
+  Ebean supports entity beans declared as Java `record`s (e.g. `public record CourseRecordEntity(@Id long id,
+  String name, String notes) {}` - see `test-java16`), whose only accessor shape is the bare component name
+  (`active()`, `name()`, `id()`) - never `getXxx()`/`isXxx()`. This bare-accessor convention isn't limited to
+  an actual `record` type though - an ordinary class can just as easily expose bare/fluent-style accessors
+  with no `get`/`is` prefix at all. The generator resolves the real accessor for each source type (the direct
+  source, or an intermediate `@DtoPath`/`@DtoRef` association type) by checking which shape actually exists as
+  a method, in order: (1) `isXxx()` returning `boolean` (JavaBean boolean convention), (2) `getXxx()` (JavaBean
+  convention), (3) the bare `propertyName()` itself - falling back to a guessed `getXxx()` only if none of the
+  three are found. Resolution is entirely name/existence-based (no dependency on whether the type is actually
+  a `record`). The Ebean bean-property name used in generated `FetchGroup.select(...)`/`.fetch(...)` calls is
+  tracked directly from the original property/segment name (not reverse-parsed from the resolved accessor's
+  method name), so it's correct regardless of which of the three accessor shapes was used.
+  *Inspiration: Ebean's own record-entity support (`test-java16`); user-reported gap during review.*
+  *Status: implemented.*
+
+## Rejected Requirements
+
+These were considered and explicitly rejected as out of scope:
+
+- **DTO as interface / dynamic proxy views** — Blaze `@EntityView` defines views as interfaces backed by
+  runtime proxies. This conflicts with Ebean's preference for plain, framework-unattached DTO classes.
+- **Updatable or creatable entity views (persist through DTO)** — Blaze's `@UpdatableEntityView` /
+  `@CreatableEntityView` cascade persist/update through the view. This would duplicate Ebean's existing
+  entity persistence model and introduce a second, ambiguous dirty-checking/cascade model.
+- **New predicate/filter DSL for subview collections** — Blaze allows filter expressions directly in
+  `@Mapping` (e.g. filtering a collection by an attribute value). Ebean already has typed query bean
+  predicates and `.filterMany()` for filtering child collections in queries; no new embedded filter
+  expression language is needed on the DTO itself.
+
+## References
+
+- Issue: https://github.com/ebean-orm/ebean/issues/2540
+- PR #2626: `InterceptReadOnly` / `InterceptReadWrite` split enabling the unmodifiable entity graph fast path
+- Ebean docs: https://ebean.io/docs/query/option#unmodifiable
+- QueryDSL: `@QueryProjection` (constructor-based, compile-time-checked projections)
+- Blaze-Persistence Entity Views: https://persistence.blazebit.com/documentation/1.6/entity-view/manual/en_US/
@@ -12,7 +12,10 @@ Key guides (fetch and follow when performing the relevant task):
 - Maven POM setup: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-postgres-maven-pom.md
 - Database configuration: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-postgres-database-config.md
 - Migrate to `Database.builder()`: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/migrating-to-database-builder.md
+- Migrate JSON APIs from Jackson core to avaje-json-core: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/migrating-json-jackson-core-to-avaje-json-core.md
 - Write queries with query beans: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/writing-ebean-query-beans.md
+- Mapping entity graphs to DTOs (`mapTo`): https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/mapping-entity-graphs-to-dtos.md
+- Derived / formula properties (`@Formula`, `@Formula2`): https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/derived-formula-properties.md
 - Persisting and transactions: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/persisting-and-transactions-with-ebean.md
 - Query metrics and naming: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/ebean-query-metrics.md
 - Query plan capture: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/ebean-query-plan-capture.md
@@ -23,6 +23,7 @@ existing Maven project. Complete the steps in order.
 | Guide | Description |
 |-------|-------------|
 | [Migrate to `Database.builder()`](migrating-to-database-builder.md) | Replace legacy `new DatabaseConfig()` and `DatabaseFactory.create(...)` code with `Database.builder()` and `DatabaseBuilder.build()`. Includes common rewrites, fluent builder equivalents, and manual-review cases for semi-automated upgrades |
+| [Migrate JSON APIs from Jackson core to avaje-json-core](migrating-json-jackson-core-to-avaje-json-core.md) | Cut over `JsonParser`/`JsonGenerator`/`JsonFactory` usage to `JsonReader`/`JsonWriter`/`JsonStream`, including `DatabaseBuilder`/`DatabaseConfig` JSON config changes and validation checklist |

 ## Observability

@@ -38,13 +39,17 @@ existing Maven project. Complete the steps in order.
 |-------|-------------|
 | [Entity Bean Creation](entity-bean-creation.md) | How to generate clean, idiomatic Ebean entity beans for AI agents; patterns and anti-patterns; field visibility and accessor guidance; minimal boilerplate |
 | [Lombok with Ebean entity beans](lombok-with-ebean-entity-beans.md) | Which Lombok annotations to use and avoid on entity beans; why `@Data` is incompatible with Ebean; how to use `@Getter` + `@Setter` + `@Accessors(chain = true)` |
+| [`@DbJson` mapping support (built-in vs Jackson)](dbjson-mapping-support.md) | Which `@DbJson` / `@DbJsonB` property types are handled by the built-in avaje-json-core support versus which require `ebean-jackson-mapper` (Jackson `ObjectMapper`); supported `String`/`List`/`Set`/`Map` matrix; enum-key and `@DbArray` notes |
+| [Derived / formula properties (`@Formula`, `@Formula2`)](derived-formula-properties.md) | Read-only computed properties: physical-SQL `@Formula` (with `${ta}` and hand-written joins) versus logical path-based `@Formula2` (auto-resolved joins); use in `select`/`where`/`orderBy`; default inclusion and the `@Transient` opt-out |

 ## Querying

 | Guide | Description |
 |-------|-------------|
 | [Write Ebean queries with query beans](writing-ebean-query-beans.md) | Step-by-step guidance for AI agents to write type-safe Ebean queries; choose the right terminal method; tune `select()` / `fetch()` / `fetchQuery()`; and project to DTOs when entity beans are not the right output |
+| [Mapping entity graphs to DTOs (`mapTo`)](mapping-entity-graphs-to-dtos.md) | Map a nested entity graph query result to a nested DTO graph via `query.mapTo(Dto.class)`; `@DtoPath`/`@DtoRef` for renamed/flattened/id-only properties; identity-aware de-dup via `DtoMapContext`; computed/aggregate DTO values via `@Entity @View` + `@Formula2`/`@Sum`/`@Aggregation`; comparison with the flat `asDto()` pipeline |
 | [Immutable bean cache for read-only references](immutable-bean-cache.md) | Use `ImmutableBeanCache` and `ImmutableBeanCaches.loading(...)` to resolve assoc-one references in read-only/unmodifiable queries, including secondary `fetchQuery`/`fetchLazy` loads |
+| [Using `RawSql` with Ebean](using-rawsql-with-ebean.md) | Choose between `RawSqlBuilder.parse()`, `unparsed()`, and `withPlaceholders()`; the `${where}`/`${andWhere}`/`${having}`/`${andHaving}` placeholder reference for CTEs, window functions, and subqueries; column mapping; and using `RawSql` with query beans |

 ## Persisting & transactions

@@ -149,6 +154,7 @@ Key guides (fetch and follow these when performing the relevant task):
 - Database configuration: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-postgres-database-config.md
 - Migrate to `Database.builder()`: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/migrating-to-database-builder.md
 - Write queries with query beans: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/writing-ebean-query-beans.md
+- Mapping entity graphs to DTOs (`mapTo`): https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/mapping-entity-graphs-to-dtos.md
 - Immutable bean cache for read-only references: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/immutable-bean-cache.md
 - Ebean OpenTelemetry tracing: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-opentelemetry.md
 - Query metrics and naming: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/ebean-query-metrics.md
@@ -178,6 +184,7 @@ Key guides (fetch and follow these when performing the relevant task):
 - Database configuration: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-postgres-database-config.md
 - Migrate to `Database.builder()`: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/migrating-to-database-builder.md
 - Write queries with query beans: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/writing-ebean-query-beans.md
+- Mapping entity graphs to DTOs (`mapTo`): https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/mapping-entity-graphs-to-dtos.md
 - Persisting and transactions: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/persisting-and-transactions-with-ebean.md
 - Test container setup: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-postgres-test-container.md
 - DB migration generation: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-db-migration-generation.md
@@ -250,6 +250,40 @@ For each future set of entity bean changes:
 4. Review the generated `.sql` to confirm it reflects the intended changes
 5. Commit both files

+### Protecting hand-edited and non-versioned migrations across regeneration
+
+`GenerateDbMigration` regenerates the apply SQL and model XML from the **current
+entity model**. It can therefore overwrite content you did not change in the
+entity beans, including:
+
+- **hand-edited DDL** in a generated versioned `.sql` file, and
+- **repeatable** (`R__*.sql`) scripts that the generator also derives from the
+  model (e.g. view definitions in `extra-ddl.xml`, built-in partitioning helpers).
+
+**Init scripts (`I__*.sql`) are write-once.** If an init script already exists on
+disk the generator **does not** rewrite it, so hand-tuned init DDL (partition
+functions, `UNLOGGED` tables, triggers, seed data) is preserved across
+regeneration. The trade-off: to pick up an upstream change to a built-in init
+script (e.g. the partition helper) you must **delete the file first**, then
+regenerate. Repeatable scripts are always regenerated.
+
+To avoid losing manual work:
+
+- Prefer an **init** (`I__`) script for hand-maintained DDL the entity model
+  cannot express — it is isolated and now protected from regeneration.
+- For **versioned** `.sql` and **repeatable** `R__` scripts that the generator
+  produces, review the diff after **every** regeneration and **restore** any
+  clobbered hand-tuning (e.g. `git checkout dbmigration/...`) before committing.
+- If your build maintains a migration index file (e.g. `idx_*.migrations`),
+  re-check that the new migration is listed and filenames match after renaming a
+  generated file.
+
+> **Run the generator from the module directory.** The output path set via
+> `setPathToResources(...)` is resolved relative to the **working directory**.
+> Run `GenerateDbMigration` with the working directory set to the module that owns
+> `src/main/resources` (e.g. `cd server` first). Note that `mvn exec:java` does
+> **not** honour a configured `workingDirectory`, so set the cwd yourself.
+
 ---

 ## Understanding the output files
@@ -101,7 +101,7 @@ Inside the `<dependencies>` block, add the PostgreSQL JDBC driver:
 <dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
-    <version>42.7.8</version>
+    <version>42.7.11</version>
 </dependency>
 ```

@@ -0,0 +1,186 @@
+# Guide: `@DbJson` / `@DbJsonB` mapping support
+
+## Purpose
+
+Ebean can map `@DbJson` and `@DbJsonB` properties in three ways:
+
+- **Built-in** JSON support, backed by **avaje-json-core** — no extra dependency.
+- **Jackson `ObjectMapper`**, provided by **`ebean-jackson-mapper`**.
+- **Avaje Jsonb**, provided by **`ebean-avajejsonb-mapper`** and its generated adapters.
+
+The built-in mapper handles the common natural JSON types. Add one mapper module for
+typed collections, POJOs, records, and other custom types.
+
+> If a property type is **not** handled built-in and no mapper module is on the classpath,
+> Ebean fails fast at startup:
+>
+> ```text
+> Unsupported @DbJson mapping - missing JSON mapper dependency for <property>
+> ```
+
+---
+
+## Quick reference
+
+| Property type | Built-in (avaje-json-core) | Mapper module |
+|---|:---:|---|
+| `String` | ✅ | |
+| `List<String>`, `List<Long>` | ✅ | |
+| `Set<String>`, `Set<Long>` | ✅ | |
+| `Map<String, Object>`, `Map<String, ?>` | ✅ | |
+| `Map<String, String>` | ✅ | |
+| `Map<Enum, Object>`, `Map<Enum, String>` | ✅ | |
+| `List`/`Set` of any other element type (`Integer`, `Double`, `UUID`, `LocalDate`, an enum, a POJO, …) | | Jackson or Avaje Jsonb |
+| `Map` with a typed value other than `String`/`Object` (`Map<String,Integer>`, `Map<String,UUID>`, …) | | Jackson or Avaje Jsonb |
+| `Map` with a key other than `String` or an enum (`Map<Integer, …>`, `Map<UUID, …>`) | | Jackson or Avaje Jsonb |
+| POJOs, records, or any other type | | Jackson or Avaje Jsonb |
+
+---
+
+## Built-in support (no Jackson required)
+
+The built-in path materialises JSON into the *natural* JSON value types
+(`String`, `Long`, `BigDecimal`, `Boolean`, `Map`, `List`). It is therefore type-safe only
+for the following declared property types:
+
+- **`String`** — stored as raw JSON text.
+- **`List<String>`** and **`List<Long>`**.
+- **`Set<String>`** and **`Set<Long>`**.
+- **`Map<K, V>`** where:
+  - the key `K` is `String` or an **enum**, and
+  - the value `V` is `Object`, `String`, or a wildcard `?`.
+
+  So `Map<String,Object>`, `Map<String,String>`, `Map<Enum,Object>` and `Map<Enum,String>`
+  are all built-in.
+
+These mappings work across all supported storage types — `VARCHAR`, `CLOB`, `BLOB`, and
+Postgres `json` / `jsonb` — without `ebean-jackson-mapper`.
+
+---
+
+## Jackson `ObjectMapper`
+
+`ebean-jackson-mapper` uses a Jackson `ObjectMapper` for the property types not handled
+built-in:
+
+- **Typed collections** — `List`/`Set` whose element type is not `String` or `Long`
+  (for example `List<Integer>`, `List<UUID>`, `List<LocalDate>`, `List<MyEnum>`, `List<MyPojo>`).
+- **Typed-value maps** — a `Map` value type other than `String`/`Object`
+  (for example `Map<String,Integer>`, `Map<String,UUID>`, `Map<String,MyPojo>`).
+- **Non-`String`/non-enum map keys** — for example `Map<Integer,Object>`, `Map<UUID,String>`.
+- **POJOs, records, and any other custom type.**
+
+> **Jackson marker annotation override:** if the **field or getter** carries a Jackson annotation
+> (anything meta-annotated with `com.fasterxml.jackson.annotation.JacksonAnnotation`), Ebean
+> uses the `ObjectMapper` path even when the type would otherwise be handled built-in.
+
+---
+
+### Adding `ebean-jackson-mapper`
+
+```xml
+<dependency>
+  <groupId>io.ebean</groupId>
+  <artifactId>ebean-jackson-mapper</artifactId>
+  <version>${ebean.version}</version>
+</dependency>
+```
+
+A Jackson `ObjectMapper` must be available (via `jackson-databind`). Ebean detects it and
+registers the mapper-based JSON support automatically.
+
+---
+
+## Avaje Jsonb
+
+`ebean-avajejsonb-mapper` uses Avaje Jsonb adapters. Annotate each JSON payload type with
+`@Json`, or use `@Json.Import`, and configure `avaje-jsonb-generator` as an annotation
+processor.
+
+```xml
+<dependency>
+  <groupId>io.ebean</groupId>
+  <artifactId>ebean-avajejsonb-mapper</artifactId>
+  <version>${ebean.version}</version>
+</dependency>
+```
+
+```xml
+<plugin>
+  <groupId>org.apache.maven.plugins</groupId>
+  <artifactId>maven-compiler-plugin</artifactId>
+  <configuration>
+    <annotationProcessorPaths>
+      <path>
+        <groupId>io.avaje</groupId>
+        <artifactId>avaje-jsonb-generator</artifactId>
+        <version>${avaje-jsonb.version}</version>
+      </path>
+    </annotationProcessorPaths>
+  </configuration>
+</plugin>
+```
+
+For example:
+
+```java
+import io.avaje.jsonb.Json;
+
+@Json
+public class Address {
+  public String line1;
+  public String city;
+}
+```
+
+Avaje Jsonb preserves a property's declared generic type, so `List<Address>` and other
+parameterised JSON values use the generated `Address` adapter.
+
+### Avaje JsonNode
+
+`@DbJson` and `@DbJsonB` properties declared as `io.avaje.json.node.JsonNode` are supported
+when the application includes `avaje-json-node`. Its Jsonb component supplies the JSON tree
+adapters; no application-generated adapter is needed for the node hierarchy.
+
+```xml
+<dependency>
+  <groupId>io.avaje</groupId>
+  <artifactId>avaje-json-node</artifactId>
+  <version>${avaje-jsonb.version}</version>
+</dependency>
+```
+
+## Mapper module selection
+
+Use exactly one mapper module in an application: `ebean-jackson-mapper` or
+`ebean-avajejsonb-mapper`. Ebean selects a single `ScalarJsonMapper` service provider, so
+having both modules on the runtime classpath is not supported.
+
+The `ebean` composite dependency includes `ebean-jackson-mapper`. Applications using Avaje
+Jsonb should depend on the individual Ebean modules they need instead of that composite.
+
+To migrate from Jackson to Avaje Jsonb, remove `ebean-jackson-mapper`, add
+`ebean-avajejsonb-mapper`, and generate adapters for each JSON payload type.
+
+---
+
+## Notes
+
+- **Enum map keys** are serialised using the enum `name()` (for example `ACTIVE`), not any
+  `@DbEnumValue` mapping. Round-trips are correct; the DB value mapping is not applied to
+  JSON keys.
+- **`@DbArray` alternative:** for typed *scalar* collections (`List`/`Set` of `Integer`,
+  `Long`, `UUID`, `Double`, an enum, …) consider `@DbArray`, which maps to a native DB array
+  (with a JSON fallback on platforms without array support) and supports more element types
+  than built-in `@DbJson` collections.
+- The reason typed value/element collections need a real mapper is that the built-in path
+  only produces natural JSON types — for example a JSON number always parses to `Long`.
+
+---
+
+## Choosing
+
+- Prefer the **built-in** mappings for the common cases (`String`, string/long lists and sets,
+  object/string maps) to avoid an additional mapper module.
+- Add **`ebean-jackson-mapper`** or **`ebean-avajejsonb-mapper`** when you need rich POJO JSON
+  columns or typed collections / typed-value maps.
@@ -0,0 +1,164 @@
+# Guide: Derived / formula properties — `@Formula` and `@Formula2`
+
+## Purpose
+
+A *formula property* is a read-only entity property whose value is computed by a SQL
+expression at query time rather than stored in its own column. Ebean has two
+annotations for this:
+
+- **`@Formula`** — you write the **physical SQL** for the `select` (and any `join`),
+  using the `${ta}` placeholder for the base table alias. Maximum control; verbose.
+- **`@Formula2`** — you write a **logical expression** using dot-notation property
+  paths (e.g. `parent.familyName`). Ebean translates the paths to the correct table
+  aliases and **adds the required JOINs automatically**.
+
+`@Formula2` is intended as the easier, path-based replacement for `@Formula`. Both
+produce read-only properties and behave the same way with respect to default
+inclusion (see [Default inclusion](#default-inclusion-and-transient)).
+
+---
+
+## Quick comparison
+
+| | `@Formula` | `@Formula2` |
+|---|---|---|
+| Expression | Physical SQL columns + aliases | Logical property paths |
+| Table alias | `${ta}` placeholder you write | Resolved automatically |
+| Joins | You write the `join` clause | Added automatically from the paths |
+| Read only | ✅ | ✅ |
+| Included by default | ✅ (use `@Transient` to opt out) | ✅ (use `@Transient` to opt out) |
+| Usable in `select` / `where` / `orderBy` / `having` | ✅ | ✅ |
+| Creates a DB column (DDL) | ❌ | ❌ |
+
+---
+
+## `@Formula` — physical SQL
+
+You supply the SQL `select` fragment, and an optional `join`. Use `${ta}` wherever you
+need the base table alias of the entity.
+
+```java
+@Entity
+public class ParentPerson {
+
+  // aggregation via a derived join; ${ta} is the base table alias
+  @Formula(select = "coalesce(f2.child_count, 0)",
+           join = "left join (select parent_id, count(*) as child_count"
+                + " from child group by parent_id) f2 on f2.parent_id = ${ta}.id")
+  Integer childCount;
+
+  // coalesce across a joined table using an explicit join alias (j1)
+  @Formula(select = "coalesce(${ta}.family_name, j1.family_name)",
+           join = "join parent_person j1 on j1.id = ${ta}.parent_id")
+  String effectiveFamilyName;
+}
+```
+
+Notes:
+- The `join` string must start with `join` or `left join`.
+- You manage the join aliases (`j1`, `f2`, …) yourself and reference them in `select`.
+- `@Formula` is `@Repeatable` and supports a `platforms()` restriction.
+
+---
+
+## `@Formula2` — logical property paths
+
+Write the expression using property paths. Ebean resolves each path to the right table
+alias and adds the joins it needs.
+
+```java
+@Entity
+public class ParentPerson {
+
+  @ManyToOne
+  GrandParentPerson parent;
+
+  String familyName;
+
+  // Ebean automatically left joins 'parent' and resolves the aliases
+  @Formula2("coalesce(familyName, parent.familyName)")
+  String derivedFamilyName;
+}
+```
+
+A query selecting `derivedFamilyName` produces (roughly):
+
+```sql
+select t0.id, coalesce(t0.family_name, t1.family_name)
+from parent_person t0
+left join grand_parent_person t1 on t1.id = t0.parent_id
+```
+
+Multi-level paths join through each step:
+
+```java
+// joins parent and parent.parent automatically
+@Formula2("coalesce(familyName, parent.familyName, parent.parent.familyName)")
+String deepFamilyName;
+```
+
+`@Formula2` works wherever a normal property does — the required joins are added
+automatically in each case:
+
+```java
+// selected explicitly
+DB.find(ParentPerson.class).select("derivedFamilyName").findList();
+
+// used in where (auto-joins even when not selected)
+DB.find(ParentPerson.class).where().eq("derivedFamilyName", "Smith").findList();
+
+// used in order by
+DB.find(ParentPerson.class).orderBy("derivedFamilyName").findList();
+
+// referenced via a path from another bean
+DB.find(ChildPerson.class).where().eq("parent.derivedFamilyName", "Smith").findList();
+```
+
+It also resolves correctly inside nested `fetch()` joins, so a `@Formula2` on a fetched
+association is computed with its own joins relative to that association.
+
+Notes:
+- The expression supports any SQL function whose arguments are logical property paths.
+- `@Formula2` supports a `platforms()` restriction.
+- No `${ta}` and no hand-written join — that is the point of `@Formula2`.
+
+---
+
+## Default inclusion and `@Transient`
+
+Both annotations are **included in queries by default** (just like a normal mapped
+property). When no explicit `select()`/`fetch()` is given, the formula — and for
+`@Formula2` the joins it requires — are added to the query.
+
+Add `@Transient` to make the formula **opt-in**: it is then **not** selected by default
+and must be requested explicitly via `select()` or `fetch()`. Do this when the formula
+(or the joins it needs) is relatively expensive.
+
+```java
+// not selected by default; must be requested explicitly
+@Transient
+@Formula2("coalesce(familyName, parent.familyName)")
+String lazyDerivedFamilyName;
+```
+
+```java
+DB.find(ParentPerson.class)
+  .select("lazyDerivedFamilyName")   // explicitly included, join auto-added
+  .findList();
+```
+
+This is the same `@Transient` opt-out mechanism used by `@Formula`.
+
+---
+
+## Which should I use?
+
+- Prefer **`@Formula2`** for expressions over property paths (coalesce/case/functions
+  across associations). It is shorter, refactor-friendly, and the joins stay correct as
+  the model changes.
+- Use **`@Formula`** when you need raw SQL that does not map cleanly to property paths —
+  for example a derived aggregate sub-select / dynamic view, or vendor-specific SQL.
+
+For read models that exist only to carry computed values, also consider projecting to a
+DTO instead of mapping the formula onto the entity — see
+[writing-ebean-query-beans.md](writing-ebean-query-beans.md).
@@ -20,7 +20,7 @@ Ebean records timing and counter metrics for the work it does. Every metric has
 | Prefix | What it measures | Example name |
 |---|---|---|
 | `orm.` | Entity (ORM) query | `orm.Customer.findList`, `orm.CustomerFinder.byName` |
-| `dto.` | DTO query | `dto.CustomerDto_byEmail` |
+| `dto.` | DTO query | `dto.CustomerDto.byEmail` |
 | `sql.query.` | Raw SQL query | `sql.query.<label>` |
 | `sql.update.` / `sql.call.` | Raw SQL update / stored procedure call | `sql.update.<label>` |
 | `orm.update.` | ORM update statement | `orm.update.<label>` |
@@ -61,13 +61,17 @@ List<Customer> customers = DB.find(Customer.class)
 // metric name: orm.Customer.custMain
 ```

-DTO queries support `setLabel(..)` too (the label should be unique to the DTO type):
+DTO queries support `setLabel(..)` too, and follow the **same naming convention** as
+ORM queries — an explicit label is prefixed with the DTO type, a profile location is
+used as-is, and an unlabelled DTO query uses just the DTO type:

 ```java
 DB.findDto(CustomerDto.class, sql)
  .setLabel("byEmail")
  .findList();
-// metric name: dto.CustomerDto_byEmail
+// metric name: dto.CustomerDto.byEmail
+//   profile location only ->  dto.<location>      (no type prefix)
+//   unlabelled            ->  dto.CustomerDto
 ```

 ### Step 2 - Use a profile location (preferred for finders / query beans)
@@ -32,7 +32,30 @@ Two ways to trigger phase 2:
 - **On demand** — call the `MetaInfoManager` API to arm and collect plans yourself
  (this is what remote tooling such as ebean-insight uses).

-Only `orm.` SELECT-style queries are plan capable — raw SQL and update/DML metrics are not.
+Plan capable queries are:
+
+- **ORM entity SELECT queries** (`orm.*` metrics) — captured via the per-entity `BeanDescriptor`.
+- **Native-SQL `DtoQuery`** (`dto.*` metrics) — a `DtoQuery` created from a SQL string
+  (`DB.findDto(MyDto.class, "select ...")`) has its own bind capture and is `EXPLAIN`'d directly.
+- **ORM-backed `DtoQuery`** (`Query.asDto(...)`) — captured via the *underlying* ORM query plan
+  (`orm.*`), not the `dto.*` plan. The `dto.*` plan itself is **not** armed in this case, so it
+  does not double-count in `queryPlanInit`.
+- **Native-SQL `SqlQuery`** (`sql.query.*` metrics) — a **labelled** `SqlQuery`
+  (`DB.sqlQuery("select ...").setLabel("myLabel")`) has its own bind capture and is `EXPLAIN`'d
+  directly. A label is required: without `setLabel(...)` the query produces no metric and no plan.
+
+Specifically **excluded** are:
+
+- **Update / DML** — `orm.update.*`, `iud.*`, `sql.update.*`, `sql.call.*`.
+
+Bind capture is wired into the ORM query path (per-entity `BeanDescriptor`), the native-SQL DTO
+path (per-DTO `DtoBeanDescriptor`), and the native-SQL `SqlQuery` path (the relational query
+engine); the init/collect API iterates all three. DML — even though it produces timing metrics —
+never captures bind values and cannot be `EXPLAIN`'d.
+
+> **Cost when disabled:** SqlQuery plan capture is fully gated on the `queryPlan.enable` master
+> switch. When capture is disabled no `SqlQuery` plans are created or cached, so labelled queries
+> incur no extra cost beyond their existing timing metric.

 ---

@@ -40,6 +63,15 @@ Only `orm.` SELECT-style queries are plan capable — raw SQL and update/DML met

 Bind capture is the master switch; nothing is captured until it is on.

+> **Security — bind values may contain PII.** Bind capture records the **actual
+> parameter values** used by slow query executions, and those values are stored
+> and shown verbatim in the captured plan output (alongside the SQL and EXPLAIN
+> plan). They can therefore contain personal or otherwise sensitive data. Capture
+> is opt-in and off by default (`queryPlan.enable=false`): only enable it where
+> that data exposure is acceptable, restrict who can read captured plans, and
+> prefer arming specific query hashes (Step 3) over a low global threshold so you
+> capture the minimum needed.
+
 ```java
 Database database = Database.builder()
  .queryPlanEnable(true)               // turn on bind capture
@@ -200,7 +232,11 @@ logger. Set a listener, or enable `INFO` logging for `io.ebean.QUERYPLAN`.
 `queryPlanCapturePeriodSecs`, tighten `queryPlanCaptureMaxTimeMillis`, or override
 `queryPlanExplain` to a non-ANALYZE form.

-### An update/DML metric never offers plan capture
+### An unlabelled SqlQuery or update metric never offers plan capture

-Only `orm.` SELECT-style queries are plan capable. `orm.update.*`, `iud.*`, `sql.update.*`
-and similar write metrics are intentionally excluded.
+ORM entity SELECT queries (`orm.*`), native-SQL `DtoQuery` (`dto.*`) and native-SQL
+**labelled** `SqlQuery` (`sql.query.*`) are plan capable. ORM-backed DTO queries
+(`Query.asDto(...)`) are captured via their underlying ORM plan (`orm.*`), not the `dto.*` plan.
+An unlabelled `SqlQuery` produces no metric and no plan — add `setLabel(...)` to make it
+capturable. Write metrics (`orm.update.*`, `iud.*`, `sql.update.*`, `sql.call.*`) have no bind
+capture and are intentionally excluded.
@@ -376,7 +376,12 @@ public class Customer {
 **Important:**
 - Use `List<>` not `Set<>` for collections (Set calls equals/hashCode before beans have IDs)
 - `mappedBy` means Order.customer is the owner
- Relationships are lazy-loaded by default
+- Relationships are lazy-loaded by default — **except** `@OneToOne(mappedBy=...)`,
+  which defaults to `FetchType.EAGER` and adds a `left join` to every default
+  select of the owning entity. Explicitly set `fetch = FetchType.LAZY` on
+  `@OneToOne(mappedBy=...)` fields unless the association is needed on
+  (almost) every load. See "`@OneToOne(mappedBy=...)` is EAGER by default" in
+  the query-beans guide for details.

 ---

@@ -0,0 +1,785 @@
+# Guide: Mapping entity graphs to DTOs — `query.mapTo(Dto.class)`
+
+## Purpose
+
+`query.mapTo(SomeDto.class)` maps an entity query result to a **nested DTO graph** —
+DTO fields can themselves be DTOs (`ToOne`) or `List<Dto>`/`Set<Dto>` (`ToMany`), not
+just flat scalar columns. Ebean generates the mapper (reflection-free), automatically
+derives the query's `select()`/`fetch()` spec from the target DTO's declared shape, and
+forces `setUnmodifiable(true)` so any property the mapper needs but wasn't fetched fails
+fast with `LazyInitialisationException` instead of silently lazy loading.
+
+This is distinct from the existing flat `asDto(Dto.class)` — see
+[Quick comparison](#quick-comparison-mapto-vs-asdto-vs-plain-entity-query) below.
+
+```java
+Optional<CustomerDto> dto = new QCustomer()
+  .id.eq(customerId)
+  .mapTo(CustomerDto.class)
+  .findOneOrEmpty();
+```
+
+```java
+List<CustomerDto> dtos = DB.find(Customer.class)
+  .where().eq("status", Status.ACTIVE)
+  .mapTo(CustomerDto.class)   // no .select()/.fetch() needed - derived from CustomerDto's shape
+  .findList();
+```
+
+---
+
+## Quick comparison: `mapTo()` vs `asDto()` vs plain entity query
+
+| | `mapTo(Dto.class)` | `asDto(Dto.class)` | Plain entity query |
+|---|---|---|---|
+| Shape | Nested DTO **graph** (ToOne/ToMany) | Flat, single-row DTO | Entity graph |
+| Fetch spec | Auto-derived from the DTO's declared shape | Whatever `select()`/SQL you write | Whatever `select()`/`fetch()` you write |
+| Mismatch caught | At compile time (unregistered pair fails fast at first use; codegen fails fast on structural problems) | At runtime (reflection-based constructor/setter matching) | N/A (real entity properties) |
+| Identity/de-dup | Yes - repeated source instances map to the same DTO instance (`DtoMapContext`) | N/A (one row in, one DTO out) | Yes (entity/persistence-context identity) |
+| Backing pipeline | Executes the entity ORM query, `setUnmodifiable(true)`, maps the resulting graph | Executes SQL directly against a flat `ResultSet` | Executes the entity ORM query |
+| Best for | API/read-model responses that mirror a **nested** entity shape | Flat summary rows, reports, native/vendor SQL | Data you intend to mutate and save back |
+
+See also [writing-ebean-query-beans.md](writing-ebean-query-beans.md) (Step 8/9) for
+`asDto()` and the general query-shape decision guide.
+
+---
+
+## Basic usage
+
+### 1. Declare a plain DTO
+
+DTOs are plain classes with **no framework attachment** — no annotations required for
+the common case (properties matched to the source entity by name):
+
+```java
+public class CustomerDto {
+  private final Long id;
+  private final String name;
+  private final AddressDto billingAddress;   // nested ToOne
+  private final List<ContactDto> contacts;   // nested ToMany
+
+  public CustomerDto(Long id, String name, AddressDto billingAddress, List<ContactDto> contacts) {
+    this.id = id;
+    this.name = name;
+    this.billingAddress = billingAddress;
+    this.contacts = contacts;
+  }
+
+  public Long getId() { return id; }
+  public String getName() { return name; }
+  public AddressDto getBillingAddress() { return billingAddress; }
+  public List<ContactDto> getContacts() { return contacts; }
+}
+```
+
+A constructor whose parameters match (by name) a source entity/DTO property is used
+for mapping — same shape convention as the existing `DtoQuery`. Getters are used to
+read the source's properties — a bare/fluent accessor like `active()` is resolved
+automatically too, not just `getActive()`/`isActive()` (useful both for Ebean's own
+record entity beans and for ordinary classes that just expose bare-name accessors).
+
+### 2. Register the (source, target) pair
+
+Declare each entity → DTO pair with `@DtoMapping` on a `package-info.java` (a neutral
+holder — see [Why `package-info.java`?](#why-package-infojava)):
+
+```java
+@DtoMapping(source = Customer.class, target = CustomerDto.class)
+@DtoMapping(source = Address.class, target = AddressDto.class)
+@DtoMapping(source = Contact.class, target = ContactDto.class)
+package org.example.dto;
+
+import io.ebean.annotation.DtoMapping;
+```
+
+This triggers `querybean-generator` (the existing annotation processor) to generate a
+`CustomerDtoMapper implements DtoMapper<Customer, CustomerDto>` for each pair — no new
+Maven/Gradle setup beyond what query beans already require.
+
+### 3. Query with `mapTo(...)`
+
+```java
+List<CustomerDto> dtos = DB.find(Customer.class)
+  .where().eq("status", Status.ACTIVE)
+  .mapTo(CustomerDto.class)
+  .findList();
+
+CustomerDto one = new QCustomer().id.eq(id).mapTo(CustomerDto.class).findOne();
+
+Optional<CustomerDto> maybe = new QCustomer().id.eq(id).mapTo(CustomerDto.class).findOneOrEmpty();
+```
+
+`mapTo(...)` works the same from a query bean (`QCustomer`) or a plain `DB.find(...)`/
+`ExpressionList` query.
+
+### Paging - `findPagedList()`
+
+`findPagedList()` mirrors `Query#findPagedList()` — the underlying entity query is paged
+as normal and each page's result is mapped to the target DTO list:
+
+```java
+PagedList<CustomerDto> paged = DB.find(Customer.class)
+  .where().eq("status", Status.ACTIVE)
+  .orderBy().asc("name")
+  .setFirstRow(0)
+  .setMaxRows(50)
+  .mapTo(CustomerDto.class)
+  .findPagedList();
+
+int totalRowCount = paged.getTotalCount();      // page metadata - unaffected by DTO mapping
+List<CustomerDto> page1 = paged.getList();       // mapped DTOs for this page
+```
+
+Page metadata (`getTotalCount()`, `getTotalPageCount()`, `hasNext()`, `hasPrev()`,
+`loadCount()`, ...) reflects the underlying entity query directly; only `getList()`
+is mapped (once, cached) to the DTO type.
+
+### An unregistered pair fails fast
+
+If `(Customer.class, SomeDto.class)` was never declared via `@DtoMapping`, the first
+`mapTo(SomeDto.class)` call throws immediately:
+
+```
+PersistenceException: No DtoMapper registered mapping Customer -> SomeDto
+  - check @DtoMapping(source = Customer.class, target = SomeDto.class) is declared
+    on a package-info.java processed by querybean-generator
+```
+
+---
+
+## Auto-derived fetch spec
+
+You never write `.select()`/`.fetch()` for a `mapTo(...)` query — the generated mapper
+exposes a `fetchGroup()` built directly from the DTO's declared shape, and `mapTo(...)`
+applies it automatically:
+
+```java
+public CustomerDtoMapper() {
+  this(new AddressDtoMapper(), new ContactDtoMapper());
+}
+
+public CustomerDtoMapper(DtoMapper<Address, AddressDto> billingAddressMapper,
+                          DtoMapper<Contact, ContactDto> contactsMapper) {
+  this.fetchGroup = FetchGroup.of(Customer.class)
+    .select("id,name")
+    .fetch("billingAddress", billingAddressMapper.fetchGroup())
+    .fetch("contacts", contactsMapper.fetchGroup())
+    .build();
+}
+```
+
+Each nested DTO gets its own generated mapper (mirroring MapStruct's per-type mapper
+generation), wired together via constructor injection — mappers are stateless and
+substitutable, not static singletons. Mapper instances are constructed once, in
+dependency order, and reused — see [DtoMapperManager](#one-mapper-instance-per-pair)
+below.
+
+---
+
+## Nested collections and identity-aware de-duplication
+
+When the same source entity instance is reachable via more than one path in the graph
+(e.g. two `Contact`s sharing the same `Customer`, or the same `Address` referenced from
+two paths), the mapper reuses the **same** target DTO instance rather than creating
+duplicate-but-equal copies — mirroring the identity semantics the entity graph already
+has:
+
+```java
+List<CustomerDto> dtos = DB.find(Customer.class).mapTo(CustomerDto.class).findList();
+
+CustomerDto customer = dtos.get(0);
+// both contacts share the exact same customer.billingAddress AddressDto instance
+assertThat(customer.getContacts().get(0).getCustomer())
+  .isSameAs(customer.getContacts().get(1).getCustomer());
+```
+
+This is done via a `DtoMapContext` threaded through every nested `map(...)` call within
+one top-level `mapList(...)`/`findList()` invocation. The generated code only pays for
+this when it can actually matter — a DTO that's never nested under another DTO skips
+`DtoMapContext` entirely (there's nothing else in scope to de-duplicate against):
+
+```java
+// AddressDto is nested under CustomerDto (reachable via multiple contacts) - dedup needed
+// dedup using DtoMapContext, same Address instance can be reached via more than one path in the graph
+return context.computeIfAbsent(AddressDto.class, source, s -> new AddressDto(...));
+
+// ContactSummaryDto is only ever mapped as a top-level query result - no dedup possible
+// skip DtoMapContext, only ever a top-level mapping
+return new ContactSummaryDto(source.getId(), source.getFullName());
+
+// CustomerDto has nested mappers (billingAddress, contacts) but is never itself nested
+// DtoMapContext for nested mappers only
+return new CustomerDto(source.getId(), source.getName(), ...);
+```
+
+The generated comment tells you at a glance which of the three cases applies — useful
+when debugging why a `DtoMapContext` is (or isn't) in the generated code for a
+particular mapper.
+
+---
+
+## Using generated mappers directly (outside `query.mapTo()`)
+
+Every generated `XxxDtoMapper` is a plain public class — you don't need `ServiceLoader`,
+a registry, or a `Database` just to construct or call one directly (though
+`DtoMapperManager`, below, is available if you want a shared, DI-friendly lookup). It
+always has a public no-arg constructor (delegating to defaults for any nested mappers/
+`@DtoConvert` converters) plus an explicit constructor taking those dependencies directly,
+and implements `DtoMapper<SOURCE, TARGET>`'s `map(...)`/`mapList(...)`:
+
+```java
+CustomerDtoMapper mapper = new CustomerDtoMapper();
+CustomerDto dto = mapper.map(customer);       // any Customer you already have on hand
+List<CustomerDto> dtos = mapper.mapList(customers);
+```
+
+This works on **any** entity graph, not just one that just came out of a `mapTo(...)`
+query — e.g. entities you loaded with a plain `.fetch(...)` query, entities you just
+`.save()`d, or entities built by hand in a test. The only requirement is that whatever the
+mapper reads (via plain getters) is actually populated — there's no lazy-loading fallback.
+
+### Testing the mapping in isolation
+
+Because mappers are plain, constructor-injected classes, you can unit test the mapping
+logic itself — independent of `query.mapTo()`, the DTO-pair registry, and (for
+`@DtoConvert` instance-dispatch converters) `DtoConverterManager` — by passing a test
+double straight into the explicit constructor:
+
+```java
+SecretCipher upperCasingTestCipher = String::toUpperCase;
+ContactConversionDto dto = new ContactConversionDtoMapper(upperCasingTestCipher).map(contact);
+
+assertThat(dto.getSecretCode()).isEqualTo("SHH");
+```
+
+No `DtoConverterManager.put(...)` registration needed for this kind of test — the real
+production wiring (`DtoConverterManager.get(SecretCipher.class)`) only happens in the
+generated no-arg constructor, which the explicit-constructor call above bypasses entirely.
+See `TestCustomerDtoGraphMapping` (mapper called directly against a manually queried
+graph) and `TestMapperManualUsage` (mapper called directly against hand-built/just-saved
+entities, plus the converter test-double case above) in `tests/test-dto-mapping`.
+
+### `DtoMapperManager` — resolving a generated mapper for dependency injection
+
+`new CustomerDtoMapper()` is enough for a single mapper, but if your application wants a
+single shared instance of *every* generated mapper (mirroring how `query.mapTo()` resolves
+them internally) - e.g. to wire one up for constructor injection into a service, replacing
+a hand-written mapper class - use `io.ebean.DtoMapperManager`:
+
+```java
+DtoMapperManager manager = new DtoMapperManager();   // ServiceLoader discovery only - no Database needed
+CustomerDtoMapper mapper = manager.get(CustomerDtoMapper.class);
+```
+
+`DtoMapperManager` has no dependency on `Database` at all - its constructor only does
+`ServiceLoader.load(DtoMapperRegister.class)` - so it can be constructed independently,
+before (or entirely without) a `Database`, e.g. as a bean in an avaje-inject (or any DI
+framework's) dependency graph:
+
+```java
+@Factory
+class DtoMapperFactory {
+
+  @Bean
+  DtoMapperManager dtoMapperManager() {
+    return new DtoMapperManager();
+  }
+
+  @Bean
+  CustomerDtoMapper customerDtoMapper(DtoMapperManager manager) {
+    return manager.get(CustomerDtoMapper.class);
+  }
+}
+```
+
+If you also want `query.mapTo(...)` to use that *exact same* manager instance (so there's
+only ever one instance of each generated mapper, whichever path resolves it), register it
+via `DatabaseBuilder.putServiceObject` before building the `Database` - this is the same
+`putServiceObject`/`getServiceObject` mechanism already used for things like
+`AutoMigrationRunner`:
+
+```java
+DtoMapperManager sharedManager = new DtoMapperManager();
+
+Database db = Database.builder()
+  .putServiceObject(DtoMapperManager.class, sharedManager)
+  .build();
+
+// query.mapTo(...) against `db` now resolves mappers via `sharedManager`
+```
+
+If nothing is registered via `putServiceObject`, the `Database` builds its own default
+`DtoMapperManager` instance instead - registering one is entirely optional. A standalone
+`DtoMapperManager()` construction bypasses the `DatabaseConfigProvider` hook (that hook is
+specifically about `Database` startup ordering), so if any of your mappers need a
+`@DtoConvert` instance-dispatch converter, register it via `DtoConverterManager.put(...)`
+yourself first, exactly as you would before building a `Database`. See
+`TestDtoMapperManager` and `TestDtoMapperManagerSharing` in `tests/test-dto-mapping`.
+
+### Recipe: adding extra caller-supplied fields after mapping
+
+Sometimes a target DTO needs a field that isn't sourced from the entity graph at all - e.g.
+populated from a separate query or business rule, only when a caller-supplied flag is set.
+Rather than the generator supporting partial/builder-based mapping directly, if your DTO is
+a record with a "seed from instance" builder (e.g. via `avaje-recordbuilder`'s
+`@RecordBuilder`, which generates `Target.builder(existingInstance)`), just map the
+graph-sourced fields as usual and layer the extra field on afterwards:
+
+```java
+Driver base = mapper.map(cDriver);
+Driver full = DriverBuilder.builder(base).fleets(fleets).build();
+```
+
+No generator changes needed - the mapped instance is simply the seed for the builder.
+
+---
+
+## Large targets: builder-based construction and named variants
+
+Two features aimed at large, builder-shaped target DTOs (typically OpenAPI-generated records
+with a generated builder), where a positional constructor call is unwieldy and a single query
+needs to populate the target in more than one shape.
+
+### Builder-based construction (`builder = AUTO | ALWAYS | NEVER`)
+
+If the target has a static no-arg `Target.builder()` factory returning a type with a fluent
+(returns-itself) setter per property plus a `build()` method - the shape
+`avaje-recordbuilder`'s `@RecordBuilder` generates - the generated mapper can construct the
+target via `Target.builder().prop(x)....build()` instead of `new Target(a, b, c, ...)`:
+
+```java
+public record User(Long id, String name, String email, /* ... 21 more fields */) {
+
+  public static UserBuilder builder() {
+    return UserBuilder.builder();
+  }
+}
+```
+
+```java
+@DtoMapping(source = CUser.class, target = User.class)
+package org.example.dto;
+```
+
+By default (`builder = AUTO`), the generator auto-detects a matching builder and uses it only
+once the target has more than 5 properties, falling back to a positional constructor for
+smaller DTOs. Override explicitly either direction:
+
+```java
+@DtoMapping(source = CUser.class, target = User.class, builder = DtoMapping.Builder.ALWAYS)
+```
+
+`builder = ALWAYS` is a codegen-time error if no matching builder shape is found; `builder =
+NEVER` always uses a positional constructor even if a builder is detected. This applies
+regardless of whether the target is hand-authored or foreign/generated - `@DtoMapping` is
+already declared externally via `package-info.java`, so no annotation on the target itself is
+needed either way.
+
+### Named variants excluding nested paths (`name=`, `exclude=`)
+
+The same `(source, target)` pair can be registered more than once - one base mapping (leaving
+`name()` empty) plus any number of named variants, each excluding one or more nested
+ToOne/ToMany properties:
+
+```java
+@DtoMapping(source = CUser.class, target = User.class)
+@DtoMapping(source = CUser.class, target = User.class, name = "noFleets", exclude = "fleets")
+package org.example.dto;
+```
+
+Both variants are generated into the **same** mapper class (one class per target, not one per
+variant) - the generated `noFleets()` accessor returns a single shared/cached `DtoMapper<CUser,
+User>` view (not reconstructed per call), omitting `fleets` from both its mapped output (`null`
+for a ToOne, `List.of()` for a ToMany) and its own `fetchGroup()`. Each excluded property is still
+evaluated inline at its own declared field position internally (guarded by a boolean flag) - a
+variant's exclusions never change the evaluation order of the DTO's other properties. Select it
+with the `query.mapTo(Class, DtoMapper)` overload, which takes an already-resolved mapper instance
+directly - no string-based lookup:
+
+```java
+UserMapper userMapper = new UserMapper();
+
+// full shape, with fleets fetched/mapped
+List<User> withFleets = DB.find(CUser.class)
+  .mapTo(User.class, userMapper) // or plain .mapTo(User.class)
+  .findList();
+
+// bulk listing shape - fleets excluded from both the fetch spec and the output
+List<User> noFleets = DB.find(CUser.class)
+  .mapTo(User.class, userMapper.noFleets())
+  .findList();
+```
+
+Only nested ToOne/ToMany properties can be excluded - a scalar or `@DtoRef` property can't be,
+since there's no type-safe "absent" value for an arbitrary scalar type. Named variants are
+scoped to independent, top-level query results only - unlike the base mapping, they don't
+participate in `DtoMapContext` identity de-duplication when nested elsewhere in a graph, since a
+variant is never intended to be nested inside another DTO's mapping.
+
+---
+
+## `@DtoPath` — renamed or flattened properties
+
+By default a DTO property is matched to the source entity property (or nested DTO
+mapper) of the **same name**. `@DtoPath` overrides that, allowing a DTO property to be
+renamed and/or flattened from a nested path using dot-notation:
+
+```java
+public class ContactDto {
+  private final long id;
+  private final String firstName;
+  private final String lastName;
+
+  @DtoPath("customer.billingAddress.city")
+  private final String customerCity;   // flattened, 2 hops through customer
+
+  // constructor / getters ...
+}
+```
+
+The generated mapper reads the path with a null-guard at each hop and adds the
+necessary joins to the fetch spec automatically:
+
+```java
+(s.getCustomer() == null ? null
+  : (s.getCustomer().getBillingAddress() == null ? null
+      : s.getCustomer().getBillingAddress().getCity()))
+```
+
+`@DtoPath` is purely a compile-time/codegen-time hint — the DTO class itself carries no
+runtime dependency on the annotation.
+
+### Fetch-path collisions are a compile-time error
+
+A `@DtoPath` whose fetch path is identical to a nested `ToOne`/`ToMany` property's own
+fetch path on the *same* DTO (e.g. a nested `customer` field alongside
+`@DtoPath("customer.name")` — both resolve to fetch path `"customer"`) fails the build
+with a clear error, rather than silently discarding one side's fetched properties:
+
+```
+error: @DtoPath property 'customerName' on FooDto resolves to fetch path 'customer',
+  which collides with the nested mapping already using that same fetch path - Ebean's
+  fetch spec can only carry one set of properties per path, so one silently discards
+  the other. Move 'customerName' onto the nested DTO type instead, or choose a
+  @DtoPath that reaches into a different, non-colliding path.
+```
+
+Fix it either way it suggests: move the property onto the nested DTO type, or choose a
+`@DtoPath` that reaches a different path (as `customerCity` above does deliberately,
+using a 3-segment path through `customer.billingAddress` rather than colliding with a
+plain `customer` nested field).
+
+---
+
+## `@DtoRef` — id-only back-references (breaking cycles)
+
+The DTO graph derived from a set of DTO types must form a DAG — codegen fails if it
+doesn't. `@DtoRef` is the explicit escape hatch for an intentional back-reference, e.g.
+a `Contact` DTO referencing its parent `Customer` by id only, rather than re-embedding
+a full `CustomerDto` (which would recreate the `Customer → Contact → Customer` cycle):
+
+```java
+public class ContactDto {
+  private final long id;
+
+  @DtoRef
+  private final Long customerId;   // id-only, no nested CustomerDto re-embedded
+
+  // constructor / getters ...
+}
+```
+
+The generated fetch spec adds the association to the **root** `select(...)` rather
+than a nested `.fetch(...)` — this reads the foreign-key column directly off the base
+table (no SQL join):
+
+```java
+this.fetchGroup = FetchGroup.of(ContactStats.class)
+  .select("customer,contactCount,engagementScore")   // "customer" -> FK column, no join
+  .build();
+```
+
+```java
+(source.getCustomer() == null ? null : source.getCustomer().getId())
+```
+
+If the same association is *also* independently nested-fetched elsewhere on the DTO
+(e.g. `ContactDto` has both a nested `customer` field **and** `@DtoRef Long
+customerId`), the generator recognizes the association is already covered and doesn't
+add a redundant/duplicate select — no join is added twice.
+
+---
+
+## `@DtoConvert` — custom property conversion
+
+Some properties need more than a plain getter copy — a scalar coercion (`short` to
+`boolean`), an enum-to-`String` mapping, or a conversion needing a real dependency (e.g.
+decrypting a value with a cipher). `@DtoConvert(value = ConverterType.class, method =
+"name")` covers both, combinable with `@DtoPath` when the source value also needs a
+path/rename override:
+
+```java
+public class ContactDto {
+  @DtoPath("status")
+  @DtoConvert(value = ContactConversions.class, method = "toActive")
+  private final boolean active;             // Contact.status (Short) -> boolean
+
+  @DtoConvert(value = SecretCipher.class, method = "decode")
+  private final String secretCode;          // decrypted via a registered SecretCipher
+
+  // constructor / getters ...
+}
+```
+
+The generator resolves the referenced method at codegen time and dispatches one of two
+ways, purely based on whether it's `static`:
+
+- **Static method** — inlined as a direct static call
+  (`ContactConversions.toActive(source.getStatus())`). No registration needed at all —
+  use this for common, reusable, dependency-free coercions.
+- **Instance method** — the generated mapper resolves one shared instance via
+  `DtoConverterManager.get(SecretCipher.class)`, wired as a constructor
+  parameter/field (the same shape as nested-mapper constructor injection), then calls
+  `secretCipher.decode(source.getSecretCode())`. Use this when the conversion needs a
+  real dependency.
+
+### Registering an instance-dispatch converter
+
+`DtoConverterManager` is a small, deliberately-scoped static put/get bridge — register
+an already-constructed converter instance (e.g. built by your DI container) **before**
+building the `Database`:
+
+```java
+AES256Cipher cipher = ...;                                    // already DI-constructed
+DtoConverterManager.put(SecretCipher.class, cipher::decrypt); // or a small adapter class
+
+Database db = DatabaseFactory.create(...); // generated mappers resolve converters from here
+```
+
+If nothing is registered for a required type, `DtoConverterManager.get(...)` throws a
+`PersistenceException` immediately — this happens as an eager field initializer on the
+generated `EbeanDtoMapperRegister`, so a missing registration fails fast at `Database`
+build time, not lazily on first `mapTo(...)` call.
+
+> **Testing tip:** since `EbeanDtoMapperRegister`'s mapper fields are all constructed
+> together when the `Database` starts, register converters via a `DatabaseConfigProvider`
+> (a `ServiceLoader` hook that runs before the `Database` is built) rather than a test
+> `@BeforeAll`, so registration always happens before *any* test triggers startup —
+> regardless of which test class runs first.
+
+## `@DtoMixin` — overlaying annotations onto a DTO you can't edit
+
+Some DTOs are generated elsewhere (e.g. from an OpenAPI spec, regenerated on every
+build) and can't be annotated directly. `@DtoMixin(Target.class)` overlays
+`@DtoPath`/`@DtoRef`/`@DtoConvert` from a separate companion type instead — directly
+mirroring avaje-jsonb's `@Json.MixIn` mechanism. Declare a companion interface (or
+class) whose method names match the target DTO's property names:
+
+```java
+// ContactMixinDto itself carries no Ebean annotations at all
+public class ContactMixinDto {
+  public ContactMixinDto(long id, String firstName, boolean active, String secretCode) { ... }
+  // getters ...
+}
+
+@DtoMixin(ContactMixinDto.class)
+interface ContactMixinDtoMixin {
+
+  @DtoPath("status")
+  @DtoConvert(value = ContactConversions.class, method = "toActive")
+  boolean active();
+
+  @DtoConvert(value = SecretCipher.class, method = "decode")
+  String secretCode();
+}
+```
+
+The processor matches each mixin method to the target's property by name and applies
+whichever annotations are present as if they were declared on the target field itself.
+The mixin type is never instantiated and carries no runtime footprint — it's purely a
+compile-time/codegen-time hint.
+
+---
+
+## Computed / aggregate properties via `@Entity @View`
+
+There's no dedicated "formula on DTO" annotation (a narrower `@Formula2`-on-DTO
+variant was explored and rejected — see
+[dto-mapping-design.md](../dto-mapping-design.md) for the reasoning). Instead, model
+the computed value as its own read-only entity using `@View`, then map that entity to a
+plain DTO with the same `@DtoMapping` machinery described above. `@View(name = "...")`
+here just points a second entity at an **existing** table — it does not create a new
+database view or table.
+
+### Worked example — computed column (`@Formula2`)
+
+```java
+@Entity
+@View(name = "contact")   // reads the existing 'contact' table, no new DDL
+public class ContactSummary {
+  @Id
+  private Long id;
+  private String firstName;
+  private String lastName;
+
+  @Formula2("concat(firstName, ' ', lastName)")
+  private String fullName;
+
+  // getters ...
+}
+```
+
+```java
+public class ContactSummaryDto {
+  private final Long id;
+  private final String fullName;
+  // constructor / getters ...
+}
+```
+
+```java
+@DtoMapping(source = ContactSummary.class, target = ContactSummaryDto.class)
+```
+
+```java
+List<ContactSummaryDto> summaries = DB.find(ContactSummary.class)
+  .mapTo(ContactSummaryDto.class)
+  .findList();
+```
+
+### Worked example — group-by aggregation (`@Sum`/`@Aggregation`)
+
+The same `@View`-on-base-table pattern applies to Ebean's `@Sum`/`@Aggregation`
+group-by formulas — the Blaze-Persistence parallel is an `@EntityView` with
+`@Mapping("SIZE(...)")`/`@Mapping("SUM(...)")` correlated mappings:
+
+```java
+@Entity
+@View(name = "contact")
+public class ContactStats {
+  @Id
+  private Long id;              // required so @Aggregation("count(id)") has something to
+                                 // count; deliberately never selected/mapped - selecting it
+                                 // would defeat the aggregation (one row per contact
+                                 // instead of one row per customer)
+  @ManyToOne
+  private Customer customer;
+
+  @Aggregation("count(id)")
+  private Long contactCount;
+
+  @Sum
+  private Integer engagementScore;
+
+  // getters ...
+}
+```
+
+```java
+public class ContactStatsDto {
+  @DtoRef
+  private final Long customerId;   // also the implicit GROUP BY key
+  private final Long contactCount;
+  private final Integer engagementScore;
+  // constructor / getters ...
+}
+```
+
+Because `customerId` uses `@DtoRef`, the generated fetch spec is
+`select("customer,contactCount,engagementScore")` with **no join** — the query groups
+by the FK column directly:
+
+```sql
+select t0.customer_id, count(t0.id), sum(t0.engagement_score)
+from contact t0
+group by t0.customer_id
+```
+
+---
+
+## Performance notes
+
+### Fail-fast, no accidental lazy loading
+
+`mapTo(...)` forces `query.setUnmodifiable(true)` under the hood. If the mapper ever
+needs a property that wasn't fetched, it throws `LazyInitialisationException`
+immediately rather than silently issuing an extra query per row or returning `null`.
+`InterceptReadOnly` (the unmodifiable-graph bean state) is also cheap — a `boolean[]
+loaded` flag array plus a `frozen` flag, not a full second copy of bean state.
+
+### One mapper instance per pair
+
+Generated mappers are constructed once (in dependency order — a mapper with nested
+mappers takes them as constructor params) and reused across every `mapTo(...)` call for
+that pair, resolved and cached by `DtoMapperManager` keyed on `(sourceType, dtoType)`.
+
+### `DtoMapContext` overhead only where it earns its keep
+
+As shown above, the generator only involves `DtoMapContext` for mappers that can
+actually be reached via more than one path in some graph (dedup) or that have nested
+mappers of their own (need to thread the context down); a DTO that's only ever a
+top-level query result skips it entirely.
+
+### Fetch strategy and pagination carry over unchanged
+
+Existing fetch-strategy control (`+query`/`+lazy`, `fetchQuery()`) and pagination
+(including keyset pagination and `findPagedList()`) work the same whether the query
+target is an entity graph or a `mapTo(...)` DTO graph — no special-casing needed.
+
+---
+
+## Which should I use?
+
+- **`mapTo(Dto.class)`** — the target is a **nested** shape (has its own ToOne/ToMany
+  DTO fields) that should mirror part of the entity graph; you want the fetch spec
+  derived automatically and verified to match the DTO's declared shape.
+- **`asDto(Dto.class)`** / `DB.findDto(...)` — the target is a **flat** row (report,
+  summary, native/vendor SQL); you're comfortable with runtime-checked column-to-bean
+  matching, or the SQL doesn't map cleanly to entity property paths at all.
+- **Plain entity query** — the caller needs a real, persistable, mutable entity — not a
+  read-only projection.
+
+---
+
+## Reference
+
+### Why `package-info.java`?
+
+`@DtoMapping` is declared on a package (`ElementType.PACKAGE`), not the DTO or the
+entity, because:
+- the DTO type is often owned/generated elsewhere (e.g. from an OpenAPI spec) and
+  shouldn't need to be annotated with an internal persistence/entity type;
+- one entity may be the source for several different DTOs (e.g. a summary vs. a detail
+  view), and the same entity/DTO pair may need registering from multiple consuming
+  modules.
+
+### Annotations at a glance
+
+| Annotation | Target | Purpose |
+|---|---|---|
+| `@DtoMapping(source=, target=)` | `package-info.java` | Registers an entity → DTO pair, triggers mapper generation |
+| `@DtoMapping(..., builder=)` | `package-info.java` | `AUTO` (default, threshold-based) / `ALWAYS` / `NEVER` - builder-chain vs positional constructor |
+| `@DtoMapping(..., name=, exclude=)` | `package-info.java` | Registers a named variant sharing the base mapping's generated class, excluding nested paths |
+| `@DtoPath("a.b.c")` | DTO field/getter | Renamed and/or flattened multi-hop property mapping |
+| `@DtoRef` | DTO field/getter | Id-only back-reference; breaks a cycle; root-selects the FK (no join) |
+| `@DtoConvert(value=, method=)` | DTO field/getter | Custom scalar conversion - static (no registration) or instance (via `DtoConverterManager`) dispatch |
+| `@DtoMixin(Target.class)` | Companion interface/class | Overlays `@DtoPath`/`@DtoRef`/`@DtoConvert` onto a DTO that can't be annotated directly |
+
+### Parallels with other tools
+
+If you're coming from another mapping library, here's the rough correspondence:
+
+| Ebean | MapStruct | Blaze-Persistence |
+|---|---|---|
+| Generated `DtoMapper` per (source, DTO) pair | Generated `@Mapper` implementation | `@EntityView` (interface + runtime proxy) |
+| `@DtoPath("a.b.c")` | `@Mapping(target = "x", source = "a.b.c")` | `@Mapping("a.b.c")` |
+| `@DtoRef` | `@Context`/manual cycle-breaking (no dedicated annotation) | Sub-view referencing an id-only projection |
+| `@DtoConvert(value=, method=)` | `@Mapping(qualifiedByName = "...")` / custom mapper methods | Custom converter/`@Mapping` expression |
+| `@DtoMixin(Target.class)` | N/A (annotate the `@Mapper` interface's abstract methods instead) | N/A |
+| `DtoMapContext` identity de-dup | Not built in (opt-in `@MappingTarget`/manual caching) | Built in (entity-view identity) |
+| `@Entity @View` + `@Formula2`/`@Sum`/`@Aggregation` for computed DTO values | N/A (MapStruct doesn't touch SQL) | `@Mapping("SIZE(...)")` / `@Mapping("SUM(...)")` correlated mappings |
+
+See [dto-mapping-design.md](../dto-mapping-design.md) for the full design rationale and
+[dto-mapping-requirements.md](../dto-mapping-requirements.md) for the accepted/rejected
+requirements this feature was scoped against (issue
+[#2540](https://github.com/ebean-orm/ebean/issues/2540)).
@@ -0,0 +1,91 @@
+# Guide: Migrate JSON APIs from Jackson core to avaje-json-core
+
+## Purpose
+
+This guide covers the one-step cutover in Ebean from Jackson core JSON APIs to
+avaje-json-core APIs.
+
+Use this when upgrading code that references:
+
+- `com.fasterxml.jackson.core.JsonParser`
+- `com.fasterxml.jackson.core.JsonGenerator`
+- `com.fasterxml.jackson.core.JsonFactory`
+
+The replacement types are:
+
+- `io.avaje.json.JsonReader`
+- `io.avaje.json.JsonWriter`
+- `io.avaje.json.stream.JsonStream`
+
+---
+
+## Breaking API changes
+
+| Previous API | New API |
+|---|---|
+| `JsonParser` | `JsonReader` |
+| `JsonGenerator` | `JsonWriter` |
+| `JsonFactory` | `JsonStream` |
+| `DatabaseBuilder.jsonFactory(...)` | `DatabaseBuilder.jsonStream(...)` |
+| `DatabaseConfig.getJsonFactory()/setJsonFactory(...)` | `DatabaseConfig.getJsonStream()/setJsonStream(...)` |
+
+---
+
+## Typical migration rewrites
+
+### Parser and generator signatures
+
+```java
+// before
+void read(JsonParser parser)
+void write(JsonGenerator generator)
+
+// after
+void read(JsonReader parser)
+void write(JsonWriter generator)
+```
+
+### Database configuration
+
+```java
+// before
+Database.builder().jsonFactory(factory)
+
+// after
+Database.builder().jsonStream(stream)
+```
+
+### JSON utility calls
+
+`EJson` and `JsonContext` APIs now operate on `JsonReader` and `JsonWriter` types.
+If your code was calling those APIs with Jackson core types, switch to avaje types.
+
+---
+
+## Dependency and module notes
+
+- `ebean-core` no longer requires a direct `jackson-core` dependency for JSON
+  parsing/writing.
+- `jackson-databind` remains optional for `ObjectMapper` compatibility paths.
+- `ebean-jackson-mapper` remains the compatibility bridge module for mapper-based
+  integrations.
+
+---
+
+## Behavior notes to verify during upgrade
+
+1. Parser token handling is now based on avaje `JsonReader.Token`.
+2. Scalar JSON reads (for example booleans, date-time, array scalar types) should
+   be validated in your tests if you previously depended on Jackson token quirks.
+3. If your integration uses transient assoc-many JSON mapping with ObjectMapper,
+   keep ObjectMapper wiring enabled.
+
+---
+
+## Validation checklist
+
+1. Compile all modules that implement or consume `io.ebean.text.json` APIs.
+2. Run module tests that cover JSON scalar conversion and bean JSON round-trips.
+3. Confirm no remaining `com.fasterxml.jackson.core.*` imports in migrated code.
+4. Keep `ObjectMapper` compatibility tests if your project depends on mapper paths.
+
@@ -0,0 +1,464 @@
+# Guide: Using `RawSql` with Ebean
+
+## Purpose
+
+`RawSql` lets you back an Ebean bean with a **hand-written SQL query** instead of
+Ebean generating the SQL from the entity mapping. Ebean still handles object
+mapping (result set columns → bean properties), lazy loading of associated beans,
+and - depending on how the `RawSql` is built - dynamic `WHERE`/`HAVING` predicates
+added through the normal query API.
+
+Use this guide when you need to:
+
+- run vendor-specific SQL, complex aggregation, or reporting queries that don't
+  map cleanly to an ORM query
+- reuse a hand-tuned query but still want typed/dynamic predicates, paging, or
+  `ORDER BY` added by the caller
+- back a query bean (`Q*`) or DTO-like bean with SQL containing a CTE, window
+  function, or subquery in the `FROM` clause
+
+Prefer ordinary query bean queries first - see
+[Write Ebean queries with query beans](writing-ebean-query-beans.md), Step 9,
+for the full decision order (query bean → `asDto()` → DTO query → raw SQL).
+This guide covers raw SQL once you've decided it's the right tool.
+
+---
+
+## The bean behind a `RawSql` query
+
+A bean queried with `RawSql` is not necessarily backed by a physical table. Annotate
+it `@Entity @Sql` to tell Ebean it is mapped via `RawSql` rather than table DDL:
+
+```java
+@Entity
+@Sql
+public class OrderAggregate {
+
+  @OneToOne
+  Order order;
+
+  Double totalAmount;
+  Long totalItems;
+
+  // getters/setters
+}
+```
+
+`@Sql` beans still get a generated query bean (`QOrderAggregate`) if the
+querybean-generator annotation processor is configured - see
+[Using `RawSql` with query beans](#using-rawsql-with-query-beans) below.
+
+You can also query an ordinary table-backed `@Entity` with `RawSql` - the column
+mapping just needs to line up with that entity's properties.
+
+---
+
+## Building a `RawSql` - three factory methods
+
+`RawSqlBuilder` has three ways to construct a `RawSql`, depending on how much of
+the SQL Ebean needs to understand:
+
+| Method | SELECT columns parsed? | Dynamic WHERE/HAVING/ORDER BY? | Use for |
+|--------|------------------------|------------------------|---------|
+| `RawSqlBuilder.parse(sql)` | Yes | Yes | Ordinary `SELECT ... FROM ... WHERE ...` statements |
+| `RawSqlBuilder.unparsed(sql)` | No | No | Fixed SQL that never needs additional predicates |
+| `RawSqlBuilder.withPlaceholders(sql)` | No (explicit `columnMapping()` required) | Yes, via `${where}` / `${andWhere}` / `${having}` / `${andHaving}` / `${orderBy}` / `${andOrderBy}` | CTEs, window functions, subqueries - SQL that keyword-based parsing can't handle |
+
+### `parse(sql)` - the common case
+
+`parse(sql)` scans the SQL text for the `select` / `from` / `where` / `group by`
+/ `having` / `order by` keywords to work out the SELECT column list (so it can
+validate your column mappings) and the injection points for dynamic `WHERE`/
+`HAVING` expressions.
+
+```java
+RawSql rawSql = RawSqlBuilder.parse(
+    "select c.id, c.name, c.status from customer c")
+  .columnMapping("c.id", "id")
+  .columnMapping("c.name", "name")
+  .columnMapping("c.status", "status")
+  .create();
+
+List<Customer> customers = DB.find(Customer.class)
+  .setRawSql(rawSql)
+  .where().eq("status", Customer.Status.ACTIVE)
+  .orderBy("name")
+  .findList();
+```
+
+Because the SQL is parsed, mistakes in `columnMapping()` (unknown column, wrong
+order for `unparsed`-style mappings) are caught early. **This fails on SQL the
+keyword parser can't make sense of** - a `WITH` CTE, a window function, a
+subquery in `FROM`, etc. - because the keyword positions found don't correspond
+to the outer query's real structure. Use `withPlaceholders(sql)` for that SQL
+instead (see below).
+
+### `unparsed(sql)` - fixed queries
+
+`unparsed(sql)` skips all parsing. The SQL is used exactly as written, and **no
+further `WHERE`/`HAVING`/`ORDER BY` can be added** by the caller - useful for a
+completely fixed reporting query with no caller-supplied filtering.
+
+```java
+RawSql rawSql = RawSqlBuilder.unparsed(
+    "select id, name, status from customer where status = 'ACTIVE'")
+  .columnMapping("id", "id")
+  .columnMapping("name", "name")
+  .columnMapping("status", "status")
+  .create();
+
+List<Customer> customers = DB.find(Customer.class)
+  .setRawSql(rawSql)
+  .findList();
+```
+
+Column mappings for `unparsed(sql)` must be supplied **in the same order** as
+the columns appear in the SQL, since there's no parsing to match them by name.
+
+### `withPlaceholders(sql)` - complex SQL (CTEs, window functions, subqueries)
+
+`withPlaceholders(sql)` avoids keyword scanning entirely. You mark exactly where
+a dynamic `WHERE`/`HAVING`/`ORDER BY` expression should be injected using
+placeholder tokens, and column mappings are always explicit (as with `unparsed`).
+
+#### Placeholder reference
+
+| Placeholder | Meaning | Use when |
+|-------------|---------|----------|
+| `${where}` | Insert a new `WHERE <expr>` clause here | No static `WHERE` clause exists yet at this point in the SQL |
+| `${andWhere}` | Insert `AND <expr>` here | A static `WHERE ...` clause already exists in the SQL and you want to append to it |
+| `${having}` | Insert a new `HAVING <expr>` clause here | No static `HAVING` clause exists yet at this point in the SQL |
+| `${andHaving}` | Insert `AND <expr>` here | A static `HAVING ...` clause already exists in the SQL and you want to append to it |
+| `${orderBy}` | Insert a new `ORDER BY <expr>` clause here | No static `ORDER BY` clause exists yet at this point in the SQL, and callers may supply `.orderBy(...)` |
+| `${andOrderBy}` | Insert `, <expr>` here | A static `ORDER BY ...` clause already exists in the SQL and you want callers to be able to append extra sort columns to it |
+
+Rules:
+
+- At least one placeholder is required - `withPlaceholders(sql)` throws
+  `IllegalArgumentException` if none of the six tokens are present.
+- Use only the placeholders you need. Omit `${where}`/`${andWhere}` entirely if
+  the query never needs a dynamic `WHERE` (e.g. only a dynamic `HAVING` on an
+  aggregate). Omit `${having}`/`${andHaving}` if there's no dynamic `HAVING`.
+  Omit `${orderBy}`/`${andOrderBy}` if the ordering is always fixed.
+- Explicit `columnMapping()` is required for every returned column - there is no
+  column-list parsing to infer names from.
+- **A caller-supplied `.orderBy(...)`/`.order(...)` is only applied if the SQL
+  contains an `${orderBy}` or `${andOrderBy}` placeholder.** Without one of
+  those placeholders there is no defined injection point for dynamic ordering,
+  so any `.orderBy(...)` call on the query is safely ignored rather than risk
+  producing invalid SQL - even if the template has a static trailing
+  `ORDER BY ...` of its own. If you need callers to be able to influence
+  ordering, add `${orderBy}` (no existing static order by) or `${andOrderBy}`
+  (append after an existing static order by).
+- Any other static SQL that follows a `${where}`/`${having}` placeholder (e.g.
+  a trailing `GROUP BY`) is preserved and correctly positioned **after**
+  whatever dynamic expression gets injected at that placeholder.
+
+#### Example - CTE with `${where}`
+
+```java
+String sql = """
+  with order_totals as (
+    select o.id as order_id, sum(d.qty * d.unit_price) as total_amount
+    from o_order o
+    join o_order_detail d on d.order_id = o.id
+    group by o.id
+  )
+  select order_id, total_amount
+  from order_totals
+  ${where}
+  order by order_id
+  """;
+
+RawSql rawSql = RawSqlBuilder.withPlaceholders(sql)
+  .columnMapping("order_id", "order.id")
+  .columnMapping("total_amount", "totalAmount")
+  .create();
+
+List<OrderAggregate> list = DB.find(OrderAggregate.class)
+  .setRawSql(rawSql)
+  .where().gt("totalAmount", 100)
+  .findList();
+```
+
+`total_amount` is a genuine column of the `order_totals` CTE here, so it's valid
+to filter on it in the outer `WHERE` - this only works because the aggregate is
+computed inside the CTE rather than as a same-level `SELECT` alias.
+
+#### Example - static `WHERE` already present, append with `${andWhere}`
+
+```java
+String sql = "... from order_totals where total_amount > 0 ${andWhere} order by order_id";
+
+RawSql rawSql = RawSqlBuilder.withPlaceholders(sql)
+  .columnMapping("order_id", "order.id")
+  .columnMapping("total_amount", "totalAmount")
+  .create();
+
+// executed SQL: ... where total_amount > 0 and total_amount > ? order by order_id
+DB.find(OrderAggregate.class)
+  .setRawSql(rawSql)
+  .where().gt("totalAmount", 100)
+  .findList();
+```
+
+#### Example - `${having}` only, filtering on an aggregate directly
+
+No `WHERE` placeholder is needed if you only ever filter on the aggregate value:
+
+```java
+String sql =
+  "select o.id as order_id, sum(d.qty * d.unit_price) as total_amount" +
+  " from o_order o join o_order_detail d on d.order_id = o.id" +
+  " group by o.id" +
+  " ${having}" +
+  " order by order_id";
+
+RawSql rawSql = RawSqlBuilder.withPlaceholders(sql)
+  .columnMapping("order_id", "order.id")
+  .columnMapping("total_amount", "totalAmount")
+  .create();
+
+List<OrderAggregate> list = DB.find(OrderAggregate.class)
+  .setRawSql(rawSql)
+  .having().gt("totalAmount", 100)
+  .findList();
+```
+
+The dynamic `HAVING` clause is injected before the static trailing `ORDER BY`,
+even though `${having}` is the only placeholder present. Because there's no
+`${orderBy}`/`${andOrderBy}` placeholder here, a caller-supplied `.orderBy(...)`
+would be ignored - the ordering stays fixed as `order by order_id`.
+
+#### Example - both `${where}` and `${having}`
+
+```java
+String sql =
+  "select o.id as order_id, sum(d.qty * d.unit_price) as total_amount" +
+  " from o_order o join o_order_detail d on d.order_id = o.id" +
+  " ${where}" +
+  " group by o.id" +
+  " ${having}" +
+  " order by order_id";
+
+RawSql rawSql = RawSqlBuilder.withPlaceholders(sql)
+  .columnMapping("order_id", "order.id")
+  .columnMapping("total_amount", "totalAmount")
+  .create();
+
+List<OrderAggregate> list = DB.find(OrderAggregate.class)
+  .setRawSql(rawSql)
+  .where().gt("order.id", 0)
+  .having().gt("totalAmount", 50)
+  .findList();
+```
+
+Both the dynamic `WHERE` and dynamic `HAVING` are injected at their respective
+placeholders, and the trailing `order by order_id` is preserved after the
+`HAVING` clause.
+
+#### Example - `${orderBy}`, fully dynamic ordering
+
+Use `${orderBy}` when there's no static default ordering and you want the
+caller's `.orderBy(...)` to control it entirely:
+
+```java
+String sql =
+  "with order_totals as (" +
+  "  select o.id as order_id, sum(d.qty * d.unit_price) as total_amount" +
+  "  from o_order o join o_order_detail d on d.order_id = o.id" +
+  "  group by o.id" +
+  ")" +
+  " select order_id, total_amount from order_totals" +
+  " ${where}" +
+  " ${orderBy}";
+
+RawSql rawSql = RawSqlBuilder.withPlaceholders(sql)
+  .columnMapping("order_id", "order.id")
+  .columnMapping("total_amount", "totalAmount")
+  .create();
+
+// executed SQL: ... where total_amount > ? order by total_amount desc
+List<OrderAggregate> list = DB.find(OrderAggregate.class)
+  .setRawSql(rawSql)
+  .where().gt("totalAmount", 0)
+  .orderBy("totalAmount desc")
+  .findList();
+```
+
+If the caller doesn't call `.orderBy(...)`, nothing is injected at `${orderBy}`
+and no `ORDER BY` clause is emitted at all.
+
+#### Example - `${andOrderBy}`, appending to a static default ordering
+
+Use `${andOrderBy}` when there's a sensible static default ordering but you
+want callers to be able to add extra tie-breaker sort columns:
+
+```java
+String sql =
+  "... from order_totals" +
+  " ${where}" +
+  " order by total_amount desc ${andOrderBy}";
+
+RawSql rawSql = RawSqlBuilder.withPlaceholders(sql)
+  .columnMapping("order_id", "order.id")
+  .columnMapping("total_amount", "totalAmount")
+  .create();
+
+// executed SQL: ... order by total_amount desc , order_id
+List<OrderAggregate> list = DB.find(OrderAggregate.class)
+  .setRawSql(rawSql)
+  .where().gt("totalAmount", 0)
+  .orderBy("order.id")
+  .findList();
+```
+
+---
+
+## Using `fetchQuery()` to build out more of the graph
+
+A `RawSql` query can be the **root query** and still use `fetchQuery(path)` the
+same way an ordinary ORM query does - Ebean runs the raw SQL for the root rows,
+then runs additional secondary ORM queries to populate the requested paths. This
+lets you hand-write only the part of the query that needs raw SQL (e.g. an
+aggregate/CTE) and let the ORM build out the rest of the object graph normally.
+
+```java
+List<OrderAggregate> list = DB.find(OrderAggregate.class)
+  .setRawSql(rawSql)           // root query - runs the CTE/aggregate SQL
+  .fetchQuery("order")         // secondary query - loads the full Order
+  .fetchQuery("order.details") // secondary query - loads Order.details
+  .where().gt("totalAmount", 50)
+  .findList();
+```
+
+This executes **three** queries: the raw SQL root query, then one secondary
+query per `fetchQuery(path)` call.
+
+**Important**: if the raw SQL's column mapping only populates part of an
+association (e.g. only `order.id`, as in the examples above), that association
+is a *partial reference*. To load a nested to-many under it (e.g.
+`order.details`), you must add an explicit `fetchQuery(...)` (or `fetch(...)`)
+for the **intermediate path** (`order`) as well as the nested path
+(`order.details`) - `fetchQuery("order.details")` alone will leave `details` as
+a deferred/lazy collection, because Ebean doesn't otherwise have a fetch node
+for `order` to hang the secondary query off. If the raw SQL already selects the
+full set of columns for an association directly (no partial reference), this
+extra step isn't needed.
+
+This is the same `fetchQuery()` mechanism used for ordinary query bean queries -
+see [Use `fetchQuery()` for to-many paths](writing-ebean-query-beans.md#step-7---use-fetchquery-for-to-many-paths-and-fetchgroup-for-reusable-query-shapes)
+for background on why to-many paths are loaded via secondary queries rather than
+a single joined query.
+
+---
+
+## Column mapping
+
+Every `RawSqlBuilder` (except a bare `unparsed(sql)` with implicit positional
+mapping) uses `columnMapping(dbColumn, propertyName)` to map SQL result columns
+to bean properties:
+
+```java
+.columnMapping("order_id", "order.id")   // maps to the "order" association's "id" property
+.columnMapping("total_amount", "totalAmount")
+```
+
+- Dotted property paths (e.g. `"order.id"`) map a column into a nested/associated
+  bean property.
+- `columnMappingIgnore(dbColumn)` marks a selected column as intentionally unmapped
+  (present in the SQL but not needed on the bean).
+- `tableAliasMapping(tableAlias, path)` bulk-renames every mapping using a given
+  SQL table alias to be prefixed with a bean property path - handy when a `parse()`
+  query selects many columns from a joined table (e.g. alias `c` → path `customer`)
+  and you don't want to repeat the prefix in every `columnMapping()` call.
+
+---
+
+## Using `RawSql` with query beans
+
+`RawSql` is not limited to the plain `Query<T>` API - it also works with a
+generated query bean, giving type-safe `where()`/`having()`-equivalent
+expressions (as bean properties) over hand-written SQL. Every generated query
+bean exposes `setRawSql(...)`:
+
+```java
+RawSql rawSql = RawSqlBuilder.parse("select id, name, status from customer")
+  .columnMapping("id", "id")
+  .columnMapping("name", "name")
+  .columnMapping("status", "status")
+  .create();
+
+List<Customer> customers = new QCustomer()
+  .setRawSql(rawSql)
+  .status.equalTo(Customer.Status.ACTIVE) // typed expression, injected into the parsed WHERE clause
+  .findList();
+```
+
+This also works with `withPlaceholders(sql)` and an `@Sql` query bean:
+
+```java
+List<OrderAggregate> list = new QOrderAggregate()
+  .setRawSql(rawSql) // built with withPlaceholders() as shown above
+  .totalAmount.gt(100)
+  .findList();
+```
+
+The typed property expression (`.totalAmount.gt(100)`) is translated to a bound
+predicate and injected at the `${where}`/`${having}` placeholder position, exactly
+as `.where().gt("totalAmount", 100)` would be on the plain `Query<T>` API.
+
+---
+
+## Common anti-patterns
+
+### Anti-pattern 1 - reaching for raw SQL before trying a query bean
+
+Complex-looking joins are often just ordinary association traversal in a query
+bean. Don't use raw SQL just because a query touches several tables - see
+[Write Ebean queries with query beans](writing-ebean-query-beans.md).
+
+### Anti-pattern 2 - using `parse(sql)` on a CTE or window-function query
+
+`parse(sql)` will throw a parsing exception (or silently mis-locate the WHERE
+injection point) on SQL it can't understand structurally. If your SQL starts
+with `WITH ...` or has a subquery in `FROM`, use `withPlaceholders(sql)` instead.
+
+### Anti-pattern 3 - filtering on a same-level SELECT alias
+
+You cannot add a dynamic `WHERE` predicate on a `SELECT`-clause alias in the
+same query level (e.g. `select sum(x) as total ... ${where}` - `total` isn't a
+real column yet at the `WHERE` stage of that query level). Either:
+
+- move the aggregation into a CTE and filter on the CTE's output column in the
+  outer query (`WHERE` case), or
+- use `${having}`/`${andHaving}` to filter on the aggregate at the `HAVING` stage
+  of the same query level, where the aggregate expression is valid.
+
+### Anti-pattern 4 - forgetting `columnMapping()` with `unparsed()`/`withPlaceholders()`
+
+Both `unparsed(sql)` and `withPlaceholders(sql)` require **every** returned
+column to be explicitly mapped (or explicitly ignored via
+`columnMappingIgnore(...)`) - there's no column-list parsing to infer them.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---------|--------------|-----|
+| `RuntimeException: Error parsing sql, can not find ... keyword` | `parse(sql)` used on SQL with a CTE, window function, or subquery in `FROM` | Use `RawSqlBuilder.withPlaceholders(sql)` instead |
+| `IllegalArgumentException: withPlaceholders() requires at least one of ${where}, ${andWhere}, ${having}, ${andHaving}, ${orderBy}, ${andOrderBy}...` | None of the six placeholder tokens were found in the SQL | Add the appropriate placeholder token at the injection point |
+| Dynamic `WHERE`/`HAVING` predicate silently has no effect, or query throws | Used `unparsed(sql)` and then tried to add a predicate | `unparsed(sql)` queries cannot be modified - switch to `parse(sql)` or `withPlaceholders(sql)` |
+| Generated SQL is invalid / clauses appear in the wrong order | Predicates added via `.where()`/`.having()` don't match the placeholders actually present in the SQL | Make sure `${where}`/`${having}` (or the `and` variants) exist at the point you expect predicates to be injected |
+| `.orderBy(...)`/`.order(...)` on the query silently has no effect | The SQL has no `${orderBy}`/`${andOrderBy}` placeholder | This is by design - without one of those placeholders there's no defined injection point, so the ordering is ignored rather than corrupting the SQL. Add `${orderBy}` or `${andOrderBy}` if you need caller-controlled ordering |
+| `Unknown column` / unmapped property error | Missing `columnMapping()` for a selected column | Add a `columnMapping(...)` or `columnMappingIgnore(...)` for every SQL column |
+| `fetchQuery("a.b")` collection stays deferred/lazy | `a` is a partial reference from the raw SQL column mapping (e.g. only `a.id` mapped), and there's no fetch node for `a` itself | Add `fetchQuery("a")` (or `fetch("a")`) alongside `fetchQuery("a.b")` |
+
+---
+
+## Related documentation
+
+- [Write Ebean queries with query beans](writing-ebean-query-beans.md)
+- [Derived / formula properties (`@Formula`, `@Formula2`)](derived-formula-properties.md)
+- [Ebean query docs](https://ebean.io/docs/query/)
@@ -77,6 +77,7 @@ often the right query shape.
 | Check if at least one row exists | `exists()` | Cheapest choice for boolean existence checks |
 | Load exactly one row by ID or unique key | `findOne()` | Only use when the predicate is truly unique |
 | Load a list of entity beans | `findList()` | Default for list screens and domain logic |
+| Stream rows, usually to map into another type | `findStream()` | For large/unbounded results streamed from the JDBC cursor; close via try-with-resources. For small/bounded results prefer `findList().stream()` |
 | Count matching rows | `findCount()` | Prefer over loading entities just to count |
 | Load a page plus optional total row count | `findPagedList()` | Use when the caller needs pagination metadata |
 | Return DTO/read-model rows | `asDto(...).findList()` | Prefer this over partially loaded entities for API/view models |
@@ -99,6 +100,43 @@ Customer customer = new QCustomer()

 Do **not** use `findOne()` for predicates that can match multiple rows.

+### Example - stream and map to another type
+
+Choose based on result size and how you consume it:
+
+- **`findList().stream()`** — executes the query, materialises the rows,
+  **releases the connection**, then streams over an in-memory list. No open
+  database resources and no try-with-resources needed. Prefer this for small or
+  bounded results (e.g. when you apply `setMaxRows`) that you collect anyway.
+- **`findStream()`** — streams rows directly from the JDBC cursor, holding a
+  connection (and an implicit transaction) open for the **whole lifetime of the
+  stream pipeline**. It must be closed with try-with-resources. Prefer it when
+  the result may be large, when you want constant memory, or when you want to
+  short-circuit (`limit`, `findFirst`, `takeWhile`) without loading everything.
+
+```java
+// small, bounded result fully collected -> findList().stream()
+List<PendingPlan> pending = new QCaptureRequest()
+  .collectedAt.isNull()
+  .orderBy().requestedAt.asc()
+  .findList()
+  .stream()
+  .map(r -> new PendingPlan(r.app().getName(), r.hash()))
+  .toList();
+
+// large/unbounded result streamed from the cursor -> findStream() + try-with-resources
+try (Stream<Customer> stream = new QCustomer()
+  .status.equalTo(Status.NEW)
+  .findStream()) {
+  stream
+    .map(...)
+    .forEach(...);
+}
+```
+
+For processing large results one bean at a time, `findEach()` is often the
+simplest choice because it closes the underlying resources automatically.
+
 ---

 ## Step 3 - Build predicates by traversing properties and associations
@@ -131,6 +169,49 @@ List<Customer> customers = new QCustomer()
  .findList();
 ```

+### Optional predicates - prefer conditional helpers over `if` blocks
+
+When a filter is driven by a nullable/optional parameter, use the built-in
+conditional helpers instead of wrapping predicates in `if` blocks. The query
+stays fluent and reads top-to-bottom, and no predicate is added when the value
+is absent.
+
+| Helper | Adds predicate when | Resulting SQL |
+|--------|---------------------|---------------|
+| `eqIfPresent(v)` | `v != null` | `prop = ?` |
+| `eqIfNotBlank(v)` (String) | `v` non-null and not blank (value is trimmed) | `prop = ?` |
+| `eqOrNull(v)` | always | `(prop = ? or prop is null)` |
+| `inOrEmpty(coll)` | `coll` non-empty | `prop in (...)` (no predicate when empty) |
+| `likeIfPresent` / `ilikeIfPresent` / `startsWithIfPresent` / `istartsWithIfPresent` / `containsIfPresent` / `icontainsIfPresent` (String) | `v != null` | the match expression |
+
+```java
+// Instead of building the query with if blocks:
+QCustomer q = new QCustomer();
+if (name != null && !name.isBlank()) {
+  q.name.eq(name.trim());
+}
+if (status != null) {
+  q.status.eq(status);
+}
+List<Customer> customers = q.findList();
+
+// Prefer the conditional helpers:
+List<Customer> customers = new QCustomer()
+  .name.eqIfNotBlank(name)
+  .status.eqIfPresent(status)
+  .findList();
+```
+
+Use `eqOrNull(v)` when a null column value should also match - for example an
+"any environment" row stored with `env_id is null` should surface under any env
+filter - instead of a hand-rolled `or()/eq()/isNull()/endOr()` block:
+
+```java
+List<CaptureRequest> rows = new QCaptureRequest()
+  .env.name.eqOrNull(envFilter)   // env_name = ? or env_name is null
+  .findList();
+```
+
 ### Agent rule

 When adding a new query:
@@ -140,6 +221,10 @@ When adding a new query:
 3. Traverse relationships instead of writing manual join SQL
 4. Keep property references type-safe; avoid string property names unless the API
   specifically requires them
+5. For optional filters, reach for `eqIfPresent` / `eqIfNotBlank` / `inOrEmpty`
+   before writing an `if (param != null)` block, and use `eqOrNull` instead of a
+   manual `or()/eq()/isNull()/endOr()` when the intent is "match this value or a
+   null column"

 ---

@@ -346,6 +431,48 @@ List<Customer> customers = new QCustomer()
 If the caller needs multiple to-many paths or a paged query, be suspicious of a
 plain `fetch(...)` on those paths. `fetchQuery()` is often the safer default.

+### `@OneToOne(mappedBy=...)` is EAGER by default — mark it LAZY
+
+The non-owning side of a `@OneToOne` (the side with `mappedBy`) defaults to
+`FetchType.EAGER` per JPA, same as `@ManyToOne`. Unlike a `@ManyToOne`
+reference (which is FK-only until `.fetch()`'d), Ebean's default select for an
+EAGER `@OneToOne(mappedBy=...)` still adds a `left join` to the target table
+on **every** query for the owning entity — even a plain `findById()` — because
+there is no local FK column to use as a lazy reference; the only way to know
+the associated row exists is to join to it.
+
+If that association is rarely needed (e.g. a rarely-read child/detail table),
+this join executes on every load of the parent, including in hot-path list
+queries, and can dominate query cost as more such associations accumulate.
+
+**Always set `fetch = FetchType.LAZY` on `@OneToOne(mappedBy=...)`
+associations unless the association is genuinely needed on (almost) every
+load:**
+
+```java
+@OneToOne(mappedBy = "device", fetch = FetchType.LAZY)
+private SensorBoard sensorBoard;
+```
+
+This correctly excludes the join from Ebean's default select clause (verified
+for FK-based, non-shared-primary-key `@OneToOne` relationships — the common
+case). Callers that do need the association can still `.fetch("sensorBoard")`
+explicitly on the query bean.
+
+**Caveat:** the exclusion is driven by Ebean's default-select-clause
+mechanism. It is bypassed if the query has already been switched into an
+"all properties" mode by something other than the deploy-time
+`FetchType.LAZY`/`EAGER` metadata (for example, an active AutoTune profile
+that supplies its own tuned property set). Confirm the join is actually gone
+by checking generated SQL (`LoggedSql` in tests, or query logging) after
+making this change — don't assume it's excluded from the annotation alone.
+
+### Agent rule
+
+Default new `@OneToOne(mappedBy=...)` fields to `fetch = FetchType.LAZY`
+unless there's a clear reason the association is needed on every load. This
+is a one-line, low-risk change that avoids an always-on join.
+
 ---

 ## Step 8 - Use DTO projection when the caller does not need entity beans
@@ -377,6 +504,11 @@ List<CustomerSummary> summaries = new QCustomer()
 - the result is not going to be updated and saved back as an entity
 - the query contains formulas or aggregation intended for a read model

+`asDto(...)` maps a **flat**, single-row result. If the target DTO itself needs nested
+DTO fields (ToOne/ToMany) mirroring part of the entity graph, use
+`mapTo(Dto.class)` instead — see
+[Mapping entity graphs to DTOs](mapping-entity-graphs-to-dtos.md).
+
 ---

 ## Step 9 - Only fall back to raw SQL when the ORM query is not a good fit
@@ -398,6 +530,30 @@ Prefer the following order:
 Do **not** jump to raw SQL just because the query joins multiple tables. Query
 beans already handle ordinary relationship traversal well.

+### Using `RawSql` with query beans
+
+`RawSql` is not limited to the plain `Query<T>` API - it also works with a
+generated query bean, giving type-safe `where()`/`having()` expressions over
+hand-written SQL. Every generated query bean exposes `setRawSql(...)`:
+
+```java
+RawSql rawSql = RawSqlBuilder.parse("select id, name, status from customer")
+  .columnMapping("id", "id")
+  .columnMapping("name", "name")
+  .columnMapping("status", "status")
+  .create();
+
+List<Customer> customers = new QCustomer()
+  .setRawSql(rawSql)
+  .status.equalTo(Customer.Status.ACTIVE) // typed expression, injected into the parsed WHERE clause
+  .findList();
+```
+
+For the full guide to building `RawSql` - including `unparsed()`,
+`withPlaceholders()` for CTEs/window functions, the `${where}` / `${andWhere}`
+/ `${having}` / `${andHaving}` placeholder reference, and column mapping - see
+[Using `RawSql` with Ebean](using-rawsql-with-ebean.md).
+
 ---

 ## Common anti-patterns
@@ -485,4 +641,5 @@ When asked to add or modify an Ebean query:
 - [Add Ebean Postgres Maven POM](add-ebean-postgres-maven-pom.md)
 - [Entity Bean Creation](entity-bean-creation.md)
 - [Immutable bean cache for read-only references](immutable-bean-cache.md)
+- [Using `RawSql` with Ebean](using-rawsql-with-ebean.md)
 - [Ebean query docs](https://ebean.io/docs/query/)
@@ -4,7 +4,7 @@
  <parent>
    <artifactId>ebean-parent</artifactId>
    <groupId>io.ebean</groupId>
-    <version>16.9.0</version>
+    <version>18.4.0</version>
  </parent>

  <name>ebean api</name>
@@ -70,15 +70,13 @@
      <optional>true</optional>
    </dependency>

-    <!-- Jackson core used internally by Ebean -->
    <dependency>
-      <groupId>com.fasterxml.jackson.core</groupId>
-      <artifactId>jackson-core</artifactId>
-      <version>${jackson.version}</version>
-      <optional>true</optional>
+      <groupId>io.avaje</groupId>
+      <artifactId>avaje-json-core</artifactId>
+      <version>${avaje-json-core.version}</version>
    </dependency>

-    <!-- provided scope for JsonNode support -->
+    <!-- Jackson databind remains for ObjectMapper compatibility paths -->
    <dependency>
      <groupId>com.fasterxml.jackson.core</groupId>
      <artifactId>jackson-databind</artifactId>
@@ -105,6 +103,53 @@
        </excludes>
      </resource>
    </resources>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-compiler-plugin</artifactId>
+        <executions>
+          <execution>
+            <id>compile</id>
+            <goals>
+              <goal>compile</goal>
+            </goals>
+            <configuration>
+              <release>11</release>
+            </configuration>
+          </execution>
+          <execution>
+            <id>compile-21</id>
+            <phase>compile</phase>
+            <goals>
+              <goal>compile</goal>
+            </goals>
+            <configuration>
+              <release>21</release>
+              <compileSourceRoots>
+                <compileSourceRoot>${project.basedir}/src/main/java21</compileSourceRoot>
+              </compileSourceRoots>
+              <multiReleaseOutput>true</multiReleaseOutput>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-jar-plugin</artifactId>
+        <configuration>
+          <archive>
+            <addMavenDescriptor>false</addMavenDescriptor>
+            <manifestEntries>
+              <Multi-Release>true</Multi-Release>
+            </manifestEntries>
+          </archive>
+        </configuration>
+<!--          <manifest>-->
+<!--            <addDefaultImplementationEntries>true</addDefaultImplementationEntries>-->
+<!--          </manifest>-->
+
+      </plugin>
+    </plugins>
  </build>

 </project>
@@ -457,6 +457,10 @@ public final class DB {

  /**
   * Same as {@link #checkUniqueness(Object)} but with given transaction.
+   * <p>
+   * For control over query cache use and whether to skip the check when the bean's unique
+   * properties are unchanged, use {@link Database#checkUniqueness(Object, Transaction, boolean, boolean)}
+   * via {@link #getDefault()} instead.
   */
  public static Set<Property> checkUniqueness(Object bean, Transaction transaction) {
    return getDefault().checkUniqueness(bean, transaction);
@@ -1078,12 +1078,21 @@ public interface Database {
   * @param bean The entity bean to check uniqueness on
   * @return a set of Properties if constraint validation was detected or empty list.
   */
-  Set<Property> checkUniqueness(Object bean);
+  default Set<Property> checkUniqueness(Object bean) {
+    return checkUniqueness(bean, null, false, true);
+  }

  /**
   * Same as {@link #checkUniqueness(Object)}. but with given transaction.
   */
-  Set<Property> checkUniqueness(Object bean, Transaction transaction);
+  default Set<Property> checkUniqueness(Object bean, Transaction transaction) {
+    return checkUniqueness(bean, transaction, false, true);
+  }
+
+  /**
+   * Same as {@link #checkUniqueness(Object)}. but with given transaction and extended search options.
+   */
+  Set<Property> checkUniqueness(Object bean, Transaction transaction, boolean useQueryCache, boolean skipClean);

  /**
   * Marks the entity bean as dirty.
@@ -1,6 +1,6 @@
 package io.ebean;

-import com.fasterxml.jackson.core.JsonFactory;
+import io.avaje.json.stream.JsonStream;
 import io.ebean.annotation.*;
 import io.ebean.cache.ServerCachePlugin;
 import io.ebean.config.*;
@@ -61,6 +61,11 @@ public interface DatabaseBuilder {

  /**
   * Build and return the Database instance.
+   * <p>
+   * When {@link #setRegister(boolean)} is set to true (the default), and a database
+   * with the same name is already registered, this throws an {@link IllegalStateException}.
+   * Use a unique name, or use {@link #setRegister(boolean)} with {@code false} if the
+   * Database instance is not intended to be registered/looked up by name.
   */
  Database build();

@@ -360,18 +365,18 @@ public interface DatabaseBuilder {
  DatabaseBuilder putServiceObject(Object configObject);

  /**
-   * Set the Jackson JsonFactory to use.
+   * Set the JsonStream to use.
   * <p>
   * If not set a default implementation will be used.
   */
-  default DatabaseBuilder jsonFactory(JsonFactory jsonFactory) {
-    return setJsonFactory(jsonFactory);
+  default DatabaseBuilder jsonStream(JsonStream jsonStream) {
+    return setJsonStream(jsonStream);
  }

  /**
-   * @deprecated migrate to {@link #jsonFactory(JsonFactory)}.
+   * @deprecated migrate to {@link #jsonStream(JsonStream)}.
   */
-  DatabaseBuilder setJsonFactory(JsonFactory jsonFactory);
+  DatabaseBuilder setJsonStream(JsonStream jsonStream);

  /**
   * Set the JSON format to use for DateTime types.
@@ -883,6 +888,13 @@ public interface DatabaseBuilder {
  @Deprecated
  DatabaseBuilder setBackgroundExecutorWrapper(BackgroundExecutorWrapper backgroundExecutorWrapper);

+  /**
+   * Enable tenant-partitioned caches. When enabled each tenant gets its own cache namespace,
+   * improving cache-hit ratio by preventing cross-tenant key collisions.
+   * Use {@link SpiCacheManager#clearTenant(Object)} when a tenant is deactivated.
+   */
+  DatabaseBuilder tenantPartitionedCache(boolean tenantPartitionedCache);
+
  /**
   * Set the L2 cache default max size.
   */
@@ -2254,11 +2266,11 @@ public interface DatabaseBuilder {
    boolean isAutoLoadModuleInfo();

    /**
-     * Return the Jackson JsonFactory to use.
+     * Return the JsonStream to use.
     * <p>
     * If not set a default implementation will be used.
     */
-    JsonFactory getJsonFactory();
+    JsonStream getJsonStream();

    /**
     * Get the clock used for setting the timestamps (e.g. @UpdatedTimestamp) on objects.
@@ -2563,6 +2575,11 @@ public interface DatabaseBuilder {
     */
    boolean isAutoPersistUpdates();

+    /**
+     * Return true if caches are partitioned by tenant.
+     */
+    boolean isTenantPartitionedCache();
+
    /**
     * Return the L2 cache default max size.
     */
@@ -71,18 +71,28 @@ public final class DatabaseFactory {
    lock.lock();
    try {
      var config = builder.settings();
-      if (config.getName() == null) {
+      var name = config.getName();
+      if (name == null) {
        throw new PersistenceException("The name is null (it is required)");
      }
+      if (config.isRegister()) {
+        // We're explicitly creating a database to be registered, so avoid
+        // triggering DbContext static initialisation to auto-create a default one.
+        DbPrimary.setSkip(true);
+        if (DbContext.getInstance().contains(name)) {
+          throw new IllegalStateException("A Database with name [" + name + "] is already registered."
+            + " Use a unique DatabaseConfig name, or set DatabaseConfig.setRegister(false)"
+            + " if this Database instance is not intended to be registered/looked up by name.");
+        }
+      }
      Database server = createInternal(config);
      if (config.isRegister()) {
        if (config.isDefaultServer()) {
-          if (defaultServerName != null && !defaultServerName.equals(config.getName())) {
-            throw new IllegalStateException("Registering [" + config.getName() + "] as the default server but [" + defaultServerName + "] is already registered as the default");
+          if (defaultServerName != null && !defaultServerName.equals(name)) {
+            throw new IllegalStateException("Registering [" + name + "] as the default server but [" + defaultServerName + "] is already registered as the default");
          }
-          defaultServerName = config.getName();
+          defaultServerName = name;
        }
-        DbPrimary.setSkip(true);
        DbContext.getInstance().register(server, config.isDefaultServer());
      }
      return server;
@@ -111,6 +121,24 @@ public final class DatabaseFactory {
    }
  }

+  /**
+   * Remove the registration of this Database.
+   * <p>
+   * This is invoked when a Database is shutdown so that its registered name
+   * becomes available again for a subsequently created Database with the same name.
+   */
+  public static void unregister(Database server) {
+    lock.lock();
+    try {
+      DbContext.getInstance().deregister(server);
+      if (server.name().equals(defaultServerName)) {
+        defaultServerName = null;
+      }
+    } finally {
+      lock.unlock();
+    }
+  }
+
  /**
   * Shutdown gracefully all Database instances cleaning up any resources as required.
   * <p>
@@ -4,6 +4,7 @@ import io.ebean.config.BeanNotEnhancedException;
 import io.ebean.datasource.DataSourceConfigurationException;

 import jakarta.persistence.PersistenceException;
+
 import java.util.HashMap;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.locks.ReentrantLock;
@@ -75,6 +76,10 @@ final class DbContext {
    return defaultDatabase;
  }

+  boolean contains(String name) {
+    return concMap.containsKey(name);
+  }
+
  /**
   * Return the database by name.
   */
@@ -115,6 +120,27 @@ final class DbContext {
    registerWithName(server.name(), server, isDefault);
  }

+  /**
+   * Remove the registration for this Database (typically on shutdown) so that
+   * its name becomes available again for a subsequently created Database.
+   * <p>
+   * Only removes the registration if it currently maps to this exact instance
+   * (avoids removing a different Database subsequently registered with the same name).
+   */
+  void deregister(Database server) {
+    lock.lock();
+    try {
+      String name = server.name();
+      concMap.remove(name, server);
+      syncMap.remove(name, server);
+      if (defaultDatabase == server) {
+        defaultDatabase = null;
+      }
+    } finally {
+      lock.unlock();
+    }
+  }
+
  private void registerWithName(String name, Database server, boolean isDefault) {
    lock.lock();
    try {
@@ -0,0 +1,65 @@
+package io.ebean;
+
+import jakarta.persistence.PersistenceException;
+
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * Static bridge registering custom {@code @DtoConvert} converter instances so generated DTO
+ * mappers can reach them.
+ * <p>
+ * Generated mappers (see {@code query.mapTo(SomeDto.class)}) are wired via {@code ServiceLoader}
+ * as plain, no-arg-constructed, compile-time singletons (mirroring how entity/query-bean
+ * registration already works) - they have no way to reach a dependency-injection container, or
+ * any particular {@code Database} instance, at construction time. When a
+ * {@code @DtoConvert(value = ConverterType.class, method = "...")} property's converter is an
+ * <b>instance</b> method (as opposed to a {@code static} one, which is called directly with no
+ * registration needed at all), the generated mapper resolves it via {@link #get(Class)} - so the
+ * application must register an instance here, typically one already built by its own DI
+ * container, <b>before</b> building the {@code Database}:
+ * <pre>{@code
+ * AES256Cipher cipher = ...; // already DI-constructed
+ * DtoConverterManager.put(DriverConversions.class, new DriverConversionsImpl(cipher));
+ *
+ * Database db = DatabaseFactory.create(...); // generated mappers resolve converters from here
+ * }</pre>
+ * <p>
+ * This is a deliberate, narrowly-scoped exception to preferring dependency injection over static
+ * mutable state - it exists solely to bridge an already-DI-constructed singleton into
+ * {@code ServiceLoader}-discovered, no-arg-constructed generated code, which cannot otherwise
+ * reach a DI container or a specific {@code Database} instance. {@link #get(Class)} throws
+ * immediately if nothing was registered for the given type, so a missing/late registration fails
+ * fast at {@code Database} build time (a generated mapper's eager field initializer) rather than
+ * lazily on first use.
+ */
+public final class DtoConverterManager {
+
+  private static final Map<Class<?>, Object> converters = new ConcurrentHashMap<>();
+
+  private DtoConverterManager() {
+  }
+
+  /**
+   * Register a converter instance for the given type - must be called before the
+   * {@code Database} using it is built.
+   */
+  public static <T> void put(Class<T> type, T instance) {
+    converters.put(type, instance);
+  }
+
+  /**
+   * Return the registered converter instance for the given type.
+   *
+   * @throws PersistenceException if no instance was registered for {@code type}.
+   */
+  @SuppressWarnings("unchecked")
+  public static <T> T get(Class<T> type) {
+    T instance = (T) converters.get(type);
+    if (instance == null) {
+      throw new PersistenceException("No " + type.getName() + " registered - call "
+        + "DtoConverterManager.put(" + type.getSimpleName() + ".class, ...) before starting the Database");
+    }
+    return instance;
+  }
+}
@@ -0,0 +1,51 @@
+package io.ebean;
+
+import java.util.HashMap;
+import java.util.IdentityHashMap;
+import java.util.Map;
+import java.util.function.Function;
+
+/**
+ * Identity-keyed cache of already-mapped source -&gt; target instances, shared across one
+ * top-level {@link DtoMapper#mapList(java.util.List)} call (or an explicitly shared context).
+ * <p>
+ * Keyed by source object <b>identity</b> (an {@link IdentityHashMap}, not {@code equals()}/
+ * {@code hashCode()}) because the source is an Ebean entity graph, where repeated references to
+ * the same row within one query already resolve to the same Java object instance.
+ * <p>
+ * The identity map is partitioned <b>per target DTO type</b>. This matters because the same
+ * source instance can legitimately need to be mapped to more than one target type within a
+ * single graph - e.g. a top-level {@code CustomerDtoMapper} maps a {@code Customer} to a full
+ * {@code CustomerDto}, while a nested {@code ContactDtoMapper} maps the very same {@code Customer}
+ * instance (accessed via {@code contact.getCustomer()}) to a shallow {@code CustomerRefDto} to
+ * avoid a cycle. A single un-partitioned {@code IdentityHashMap<Object,Object>} would have the
+ * two mappers collide on the same source key and incorrectly hand back the other mapper's
+ * (wrong-typed) cached result. Partitioning by target type keeps each mapper's cache isolated
+ * while still sharing one context/instance per top-level mapping call.
+ * <p>
+ * Not thread-safe - a context is expected to be created per top-level mapping call and not
+ * shared across threads.
+ */
+public final class DtoMapContext {
+
+  private final Map<Class<?>, Map<Object, Object>> mappedByType = new HashMap<>();
+
+  /**
+   * Return the already-mapped target for the given source instance if present, otherwise map it
+   * via {@code mappingFunction}, register it, and return it.
+   *
+   * @param targetType the DTO type being produced - used to partition the identity cache so that
+   *     mapping the same source to different target types never collides.
+   */
+  @SuppressWarnings("unchecked")
+  public <S, T> T computeIfAbsent(Class<T> targetType, S source, Function<S, T> mappingFunction) {
+    Map<Object, Object> mapped = mappedByType.computeIfAbsent(targetType, t -> new IdentityHashMap<>());
+    T existing = (T) mapped.get(source);
+    if (existing != null) {
+      return existing;
+    }
+    T created = mappingFunction.apply(source);
+    mapped.put(source, created);
+    return created;
+  }
+}
@@ -0,0 +1,76 @@
+package io.ebean;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Mapper interface implemented by generated (or hand-written) entity -&gt; DTO graph mappers.
+ * <p>
+ * Used with nested entity-to-DTO graph mapping (see {@code query.mapTo(SomeDto.class)}) as
+ * distinct from the existing flat, single-row {@link DtoQuery} pipeline. Each entity/DTO type
+ * pair gets its own small, composable mapper implementation (mirroring MapStruct's per-type
+ * mapper generation) rather than one large mapper inlining every nested type. Nested mappers are
+ * wired together via constructor injection, not static singletons - this keeps mappers stateless,
+ * substitutable (e.g. for tests) and avoids global mutable state.
+ * <p>
+ * A {@link DtoMapContext} is threaded through every nested {@code map(...)} call within one
+ * top-level {@link #mapList(List)} invocation, so that repeated references to the same source
+ * entity instance (e.g. several {@code Contact}s sharing the same {@code Customer}) map to the
+ * <b>same</b> target DTO instance rather than creating duplicate-but-equal copies. This mirrors
+ * the identity semantics Ebean's own entity graph already has, and is what makes the resulting
+ * DTO graph "graph shaped" rather than "tree of copies shaped".
+ * <p>
+ * Implementations contain no reflection or {@code MethodHandles} - only direct getter calls and
+ * constructor invocation - so generated mappers are safe under GraalVM native-image with zero
+ * additional reachability metadata.
+ *
+ * @param <SOURCE> the source entity (or embeddable) type
+ * @param <TARGET> the target DTO type
+ */
+public interface DtoMapper<SOURCE, TARGET> {
+
+  /**
+   * Return the {@link FetchGroup} of exactly the source properties (and nested paths) needed to
+   * populate the target DTO graph - the select()/fetch() spec is derived from the DTO's declared
+   * shape rather than maintained separately by hand. Used by {@code query.mapTo(TARGET.class)}
+   * to automatically apply the correct fetch spec before the query is executed.
+   */
+  FetchGroup<SOURCE> fetchGroup();
+
+  /**
+   * Map a single source instance to its target DTO, reusing/registering the mapping in the
+   * given context so that repeated references to the same source instance de-duplicate to the
+   * same target instance. Must return {@code null} when given {@code null}.
+   */
+  TARGET map(SOURCE source, DtoMapContext context);
+
+  /**
+   * Map a single source instance using a fresh, one-off context. Convenience for mapping a
+   * single object in isolation (no de-duplication opportunity since there's nothing else in
+   * scope to de-duplicate against).
+   */
+  default TARGET map(SOURCE source) {
+    return map(source, new DtoMapContext());
+  }
+
+  /**
+   * Map a list of source instances to a list of target DTOs sharing the given context,
+   * preserving order.
+   */
+  default List<TARGET> mapList(List<SOURCE> source, DtoMapContext context) {
+    List<TARGET> result = new ArrayList<>(source.size());
+    for (SOURCE s : source) {
+      result.add(map(s, context));
+    }
+    return result;
+  }
+
+  /**
+   * Map a list of source instances to a list of target DTOs using a fresh context shared across
+   * the whole list - this is the usual top-level entry point, e.g. mapping the result of a
+   * {@code query.findList()} call.
+   */
+  default List<TARGET> mapList(List<SOURCE> source) {
+    return mapList(source, new DtoMapContext());
+  }
+}
@@ -0,0 +1,125 @@
+package io.ebean;
+
+import io.ebean.config.DtoMapperRegister;
+import jakarta.persistence.PersistenceException;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.ServiceLoader;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * Loads all generated {@link DtoMapperRegister} implementations (via {@code ServiceLoader},
+ * mirroring how {@code EntityClassRegister} is discovered) once, and resolves the {@link
+ * DtoMapper} for a given (source, dto) pair, or by the generated mapper's own concrete type, on
+ * request.
+ * <p>
+ * Has no dependency on {@link Database} - it can be constructed independently, before (or
+ * without) a {@code Database} existing at all, e.g. as a DI-managed singleton constructed
+ * alongside the rest of an application's dependency graph. If you want the exact same instance
+ * (and hence the exact same underlying mapper instances) shared between {@code query.mapTo(...)}
+ * and your own application code, construct it yourself and register it via {@code
+ * DatabaseBuilder.putServiceObject(DtoMapperManager.class, myManager)} before building the {@code
+ * Database} - it is then used instead of a Database-internal default instance.
+ * <p>
+ * Resolved mappers are cached so that repeated lookups only ever pay the cost of iterating the
+ * generated registers and constructing the mapper (and its nested mapper/{@code FetchGroup}
+ * graph) once - after that, every lookup is a single hash-map hit regardless of how many entity/
+ * DTO pairs are registered.
+ */
+public final class DtoMapperManager {
+
+  private final List<DtoMapperRegister> registers;
+  private final ConcurrentHashMap<MapperKey, DtoMapper<?, ?>> pairCache = new ConcurrentHashMap<>();
+  private final ConcurrentHashMap<Class<?>, Object> typeCache = new ConcurrentHashMap<>();
+
+  public DtoMapperManager() {
+    this.registers = load();
+  }
+
+  private static List<DtoMapperRegister> load() {
+    List<DtoMapperRegister> result = new ArrayList<>();
+    for (DtoMapperRegister register : ServiceLoader.load(DtoMapperRegister.class)) {
+      result.add(register);
+    }
+    return result;
+  }
+
+  /**
+   * Return the {@link DtoMapper} for the given (source, dto) pair.
+   *
+   * @throws PersistenceException if no generated mapper is registered for that pair.
+   */
+  @SuppressWarnings("unchecked")
+  public <S, D> DtoMapper<S, D> mapperFor(Class<S> sourceType, Class<D> dtoType) {
+    return (DtoMapper<S, D>) pairCache.computeIfAbsent(new MapperKey(sourceType, dtoType), this::resolve);
+  }
+
+  /**
+   * Return the generated mapper instance of the given concrete mapper type - e.g. {@code
+   * manager.get(CustomerDtoMapper.class)} - typically used to resolve a mapper instance for
+   * dependency injection into application code (e.g. an avaje-inject {@code @Factory} bean
+   * method).
+   *
+   * @throws PersistenceException if no generated mapper of that type is registered.
+   */
+  @SuppressWarnings("unchecked")
+  public <T> T get(Class<T> mapperType) {
+    return (T) typeCache.computeIfAbsent(mapperType, this::resolveByType);
+  }
+
+  private DtoMapper<?, ?> resolve(MapperKey key) {
+    for (DtoMapperRegister register : registers) {
+      DtoMapper<?, ?> mapper = register.mapperFor(key.sourceType, key.dtoType);
+      if (mapper != null) {
+        return mapper;
+      }
+    }
+    throw new PersistenceException("No DtoMapper registered mapping " + key.sourceType + " -> " + key.dtoType
+      + " - check @DtoMapping(source = " + key.sourceType.getSimpleName() + ".class, target = "
+      + key.dtoType.getSimpleName() + ".class) is declared on a package-info.java processed by querybean-generator");
+  }
+
+  private Object resolveByType(Class<?> mapperType) {
+    for (DtoMapperRegister register : registers) {
+      Object mapper = register.mapperOfType(mapperType);
+      if (mapper != null) {
+        return mapper;
+      }
+    }
+    throw new PersistenceException("No DtoMapper of type " + mapperType.getName() + " registered"
+      + " - check a @DtoMapping(...) pair generating " + mapperType.getSimpleName()
+      + " is declared on a package-info.java processed by querybean-generator");
+  }
+
+  /**
+   * Cache key pairing the source entity type and target DTO type.
+   */
+  private static final class MapperKey {
+
+    private final Class<?> sourceType;
+    private final Class<?> dtoType;
+
+    MapperKey(Class<?> sourceType, Class<?> dtoType) {
+      this.sourceType = sourceType;
+      this.dtoType = dtoType;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+      if (this == o) {
+        return true;
+      }
+      if (!(o instanceof MapperKey)) {
+        return false;
+      }
+      MapperKey other = (MapperKey) o;
+      return sourceType == other.sourceType && dtoType == other.dtoType;
+    }
+
+    @Override
+    public int hashCode() {
+      return 31 * sourceType.hashCode() + dtoType.hashCode();
+    }
+  }
+}
@@ -0,0 +1,137 @@
+package io.ebean;
+
+/**
+ * Runtime helpers used by generated {@link DtoMapper} implementations to safely resolve a
+ * primitive-typed DTO field whose value is derived from a multi-hop {@code @DtoPath} that
+ * traverses a nullable intermediate relation.
+ * <p>
+ * A {@code null}-guarded getter-chain (e.g. {@code source.getOrganisation() == null ? null :
+ * source.getOrganisation().getId()}) always types as the boxed wrapper (since one branch is the
+ * {@code null} literal). When the DTO's target field is a primitive (e.g. {@code long
+ * organisationId}), passing that boxed expression to the constructor auto-unboxes it - which
+ * throws a raw, unhelpful {@link NullPointerException} if the relation really is {@code null}.
+ * <p>
+ * These methods give the generated mapper a choice, controlled by {@code @DtoPath#failOnNull()}:
+ * default to the primitive's zero-equivalent value ({@code orZero} methods, the default), or
+ * throw a clear, descriptive exception naming the offending property path ({@code require}
+ * methods, opted into via {@code failOnNull = true}).
+ *
+ * @see io.ebean.annotation.DtoPath
+ */
+public final class DtoMapperSupport {
+
+  private DtoMapperSupport() {
+  }
+
+  /** Return {@code 0} if {@code value} is {@code null}, otherwise its unboxed value. */
+  public static long orZero(Long value) {
+    return value == null ? 0L : value;
+  }
+
+  /** Return {@code 0} if {@code value} is {@code null}, otherwise its unboxed value. */
+  public static int orZero(Integer value) {
+    return value == null ? 0 : value;
+  }
+
+  /** Return {@code 0} if {@code value} is {@code null}, otherwise its unboxed value. */
+  public static short orZero(Short value) {
+    return value == null ? 0 : value;
+  }
+
+  /** Return {@code 0} if {@code value} is {@code null}, otherwise its unboxed value. */
+  public static byte orZero(Byte value) {
+    return value == null ? 0 : value;
+  }
+
+  /** Return {@code 0.0} if {@code value} is {@code null}, otherwise its unboxed value. */
+  public static double orZero(Double value) {
+    return value == null ? 0.0 : value;
+  }
+
+  /** Return {@code 0.0f} if {@code value} is {@code null}, otherwise its unboxed value. */
+  public static float orZero(Float value) {
+    return value == null ? 0.0f : value;
+  }
+
+  /** Return {@code false} if {@code value} is {@code null}, otherwise its unboxed value. */
+  public static boolean orZero(Boolean value) {
+    return value != null && value;
+  }
+
+  /** Return {@code '\u0000'} if {@code value} is {@code null}, otherwise its unboxed value. */
+  public static char orZero(Character value) {
+    return value == null ? '\u0000' : value;
+  }
+
+  /** Return the unboxed value, or throw if {@code value} is {@code null}. */
+  public static long require(Long value, String path) {
+    if (value == null) {
+      throw failure(path);
+    }
+    return value;
+  }
+
+  /** Return the unboxed value, or throw if {@code value} is {@code null}. */
+  public static int require(Integer value, String path) {
+    if (value == null) {
+      throw failure(path);
+    }
+    return value;
+  }
+
+  /** Return the unboxed value, or throw if {@code value} is {@code null}. */
+  public static short require(Short value, String path) {
+    if (value == null) {
+      throw failure(path);
+    }
+    return value;
+  }
+
+  /** Return the unboxed value, or throw if {@code value} is {@code null}. */
+  public static byte require(Byte value, String path) {
+    if (value == null) {
+      throw failure(path);
+    }
+    return value;
+  }
+
+  /** Return the unboxed value, or throw if {@code value} is {@code null}. */
+  public static double require(Double value, String path) {
+    if (value == null) {
+      throw failure(path);
+    }
+    return value;
+  }
+
+  /** Return the unboxed value, or throw if {@code value} is {@code null}. */
+  public static float require(Float value, String path) {
+    if (value == null) {
+      throw failure(path);
+    }
+    return value;
+  }
+
+  /** Return the unboxed value, or throw if {@code value} is {@code null}. */
+  public static boolean require(Boolean value, String path) {
+    if (value == null) {
+      throw failure(path);
+    }
+    return value;
+  }
+
+  /** Return the unboxed value, or throw if {@code value} is {@code null}. */
+  public static char require(Character value, String path) {
+    if (value == null) {
+      throw failure(path);
+    }
+    return value;
+  }
+
+  private static IllegalStateException failure(String path) {
+    return new IllegalStateException(
+      "@DtoPath(\"" + path + "\") resolved to null via a nullable intermediate relation, but the"
+        + " target DTO field is primitive and failOnNull=true - either handle the null case in"
+        + " source data, use a boxed wrapper type for the DTO field, or remove failOnNull to"
+        + " default to the primitive's zero-equivalent value instead.");
+  }
+}
@@ -1,16 +1,9 @@
 package io.ebean;

 import org.jspecify.annotations.NullMarked;
-import org.jspecify.annotations.Nullable;

-import javax.sql.DataSource;
-import java.sql.Connection;
 import java.util.Collection;
 import java.util.List;
-import java.util.Optional;
-import java.util.function.Consumer;
-import java.util.function.Predicate;
-import java.util.stream.Stream;

 /**
 * Query for performing native SQL queries that return DTO Bean's.
@@ -43,12 +36,7 @@ import java.util.stream.Stream;
 * }</pre>
 */
@NullMarked
-public interface DtoQuery<T> extends CancelableQuery {
-
-  /**
-   * Execute the query returning a list.
-   */
-  List<T> findList();
+public interface DtoQuery<T> extends StreamableQuery<DtoQuery<T>, T> {

  /**
   * Execute the query iterating a row at a time.
@@ -59,56 +47,6 @@ public interface DtoQuery<T> extends CancelableQuery {
   */
  QueryIterator<T> findIterate();

-  /**
-   * Execute the query returning a Stream.
-   * <p>
-   * Note that the Stream holds resources related to the underlying
-   * resultSet and potentially connection and MUST be closed. We should use
-   * the Stream in a <em>try with resource block</em>.
-   */
-  Stream<T> findStream();
-
-  /**
-   * Execute the query iterating a row at a time.
-   * <p>
-   * This streaming type query is useful for large query execution as only 1 row needs to be held in memory.
-   * </p>
-   */
-  void findEach(Consumer<T> consumer);
-
-  /**
-   * Execute the query iterating the results and batching them for the consumer.
-   * <p>
-   * This runs like findEach streaming results from the database but just collects the results
-   * into batches to pass to the consumer.
-   *
-   * @param batch    The number of dto beans to collect before given them to the consumer
-   * @param consumer The consumer to process the batch of DTO beans
-   */
-  void findEach(int batch, Consumer<List<T>> consumer);
-
-  /**
-   * Execute the query iterating a row at a time with the ability to stop consuming part way through.
-   * <p>
-   * Returning false after processing a row stops the iteration through the query results.
-   * </p>
-   * <p>
-   * This streaming type query is useful for large query execution as only 1 row needs to be held in memory.
-   * </p>
-   */
-  void findEachWhile(Predicate<T> consumer);
-
-  /**
-   * Execute the query returning a single bean.
-   */
-  @Nullable
-  T findOne();
-
-  /**
-   * Execute the query returning an optional bean.
-   */
-  Optional<T> findOneOrEmpty();
-
  /**
   * Bind all the parameters using index positions.
   * <p>
@@ -215,35 +153,41 @@ public interface DtoQuery<T> extends CancelableQuery {
  DtoQuery<T> setBufferFetchSizeHint(int bufferFetchSizeHint);

  /**
-   * Use the explicit transaction to execute the query.
-   */
-  DtoQuery<T> usingTransaction(Transaction transaction);
-
-  /**
-   * Execute the query using the given connection.
-   */
-  DtoQuery<T> usingConnection(Connection connection);
-
-  /**
-   * Ensure that the master DataSource is used if there is a read only data source
-   * being used (that is using a read replica database potentially with replication lag).
+   * Return a PagedList for this query using firstRow and maxRows.
   * <p>
-   * When the database is configured with a read-only DataSource via
-   * say {@link io.ebean.DatabaseBuilder#readOnlyDataSource(DataSource)} then
-   * by default when a query is run without an active transaction, it uses the read-only data
-   * source. We use {@code usingMaster()} to instead ensure that the query is executed
-   * against the master data source.
-   */
-  default DtoQuery<T> usingMaster() {
-    return usingMaster(true);
-  }
-
-  /**
-   * Ensure the master DataSource is used when useMaster is true. Otherwise, the read only
-   * data source can be used if defined.
+   * The benefit of using this over findList() is that it provides functionality to get the
+   * total row count etc.
+   * <p>
+   * If maxRows is not set on the query prior to calling findPagedList() then a
+   * PersistenceException is thrown.
+   * <p>
+   * This is only supported for a DtoQuery that is derived from an ORM query via
+   * {@link Query#asDto(Class)} / {@link ExpressionList#asDto(Class)}. It is not supported
+   * for a DtoQuery based on raw SQL (e.g. via {@link Database#findDto(Class, String)}) as
+   * there is no query structure available from which to derive a matching row count query -
+   * a PersistenceException is thrown in that case.
+   * <pre>{@code
   *
-   * @see #usingMaster()
+   *  PagedList<OrderDto> pagedList =
+   *    DB.find(Order.class)
+   *       .where().eq("status", Order.Status.NEW)
+   *       .orderBy().asc("id")
+   *       .setFirstRow(50)
+   *       .setMaxRows(20)
+   *       .asDto(OrderDto.class)
+   *       .findPagedList();
+   *
+   *       // fetch the total row count in the background
+   *       pagedList.loadCount();
+   *
+   *       List<OrderDto> orders = pagedList.getList();
+   *       int totalRowCount = pagedList.getTotalCount();
+   *
+   * }</pre>
+   *
+   * @return The PagedList
   */
-  DtoQuery<T> usingMaster(boolean useMaster);
+  @Override
+  PagedList<T> findPagedList();

 }
@@ -10,6 +10,7 @@ import java.sql.Timestamp;
 import java.util.*;
 import java.util.function.Consumer;
 import java.util.function.Predicate;
+import java.util.function.Supplier;

 /**
 * List of Expressions that make up a where or having clause.
@@ -103,6 +104,29 @@ public interface ExpressionList<T> {
   */
  <D> DtoQuery<D> asDto(Class<D> dtoClass);

+  /**
+   * Map the query result to a nested DTO graph, automatically deriving the select()/fetch() spec
+   * from the target DTO's declared shape and forcing {@code setUnmodifiable(true)}.
+   * <p>
+   * Distinct from {@link #asDto(Class)} (the flat, single-row SQL pipeline) - this supports
+   * nested ToOne/ToMany DTO graphs, mapped from the normal ORM entity query result.
+   *
+   * @throws jakarta.persistence.PersistenceException if no generated {@link DtoMapper} is
+   *     registered for this (entity, dto) pair.
+   */
+  <D> MappedQuery<D> mapTo(Class<D> dtoType);
+
+  /**
+   * Map the query result to a nested DTO graph using an already-resolved {@link DtoMapper}
+   * instance, rather than looking one up by (entity, dtoType) - e.g. to select a named variant
+   * mapper (see {@code @DtoMapping(name = "...", exclude = "...")}), such as
+   * {@code query.mapTo(User.class, userMapper.noFleets())}.
+   *
+   * @param dtoType the DTO type mapped to (must match {@code mapper}'s target type)
+   * @param mapper the mapper instance to use, e.g. a named variant accessor on a generated mapper
+   */
+  <D> MappedQuery<D> mapTo(Class<D> dtoType, DtoMapper<T, D> mapper);
+
  /**
   * Return the underlying query as an UpdateQuery.
   * <p>
@@ -205,6 +229,22 @@ public interface ExpressionList<T> {
   */
  int delete();

+  /**
+   * Execute as a delete query permanently deleting the 'root level' beans that match the
+   * predicates in the query without soft delete.
+   * <p>
+   * This is the same as {@link #delete()} except that when the bean type uses soft delete
+   * (e.g. {@code @SoftDelete}) the matching rows are permanently (hard) deleted rather than
+   * being marked as deleted.
+   * <p>
+   * Note that if the query includes joins then the generated delete statement may not be
+   * optimal depending on the database platform.
+   * </p>
+   *
+   * @return the number of rows that were permanently deleted.
+   */
+  int deletePermanent();
+
  /**
   * Execute as a update query.
   *
@@ -382,6 +422,26 @@ public interface ExpressionList<T> {
   */
  Optional<T> findOneOrEmpty();

+  /**
+   * Execute the query returning a single bean or throwing a {@link jakarta.persistence.EntityNotFoundException}
+   * if there is no matching bean.
+   *
+   * @see Query#findOneOrThrow()
+   */
+  default T findOneOrThrow() {
+    return query().findOneOrThrow();
+  }
+
+  /**
+   * Execute the query returning a single bean or throwing the exception produced by the
+   * given supplier if there is no matching bean.
+   *
+   * @see Query#findOneOrThrow(Supplier)
+   */
+  default T findOneOrThrow(Supplier<? extends RuntimeException> exceptionSupplier) {
+    return query().findOneOrThrow(exceptionSupplier);
+  }
+
  /**
   * Execute find row count query in a background thread.
   * <p>
@@ -0,0 +1,89 @@
+package io.ebean;
+
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
+
+import jakarta.persistence.EntityNotFoundException;
+import javax.sql.DataSource;
+import java.sql.Connection;
+import java.util.List;
+import java.util.Optional;
+import java.util.function.Supplier;
+
+/**
+ * Common find operations shared by the query types that can execute and return
+ * results - {@link SqlQuery}, {@link DtoQuery}, {@link MappedQuery} and {@link QueryBuilder}.
+ *
+ * @param <SELF> The query type (used for method chaining)
+ * @param <T>    The type of the result
+ */
+@NullMarked
+public interface FindableQuery<SELF extends FindableQuery<SELF, T>, T> extends CancelableQuery {
+
+  /**
+   * Execute the query returning the list of results.
+   */
+  List<T> findList();
+
+  /**
+   * Execute the query returning a single result, or {@code null} if there is no matching row.
+   * <p>
+   * If more than 1 row is found for this query then a PersistenceException is thrown.
+   */
+  @Nullable
+  T findOne();
+
+  /**
+   * Execute the query returning an optional result.
+   */
+  Optional<T> findOneOrEmpty();
+
+  /**
+   * Execute the query returning a single result or throwing a
+   * {@link jakarta.persistence.EntityNotFoundException} if there is no matching row.
+   */
+  default T findOneOrThrow() {
+    return findOneOrEmpty().orElseThrow(() -> new EntityNotFoundException("Not found"));
+  }
+
+  /**
+   * Execute the query returning a single result or throwing the exception produced
+   * by the given supplier if there is no matching row.
+   */
+  default T findOneOrThrow(Supplier<? extends RuntimeException> exceptionSupplier) {
+    return findOneOrEmpty().orElseThrow(exceptionSupplier);
+  }
+
+  /**
+   * Execute the query using the given transaction.
+   */
+  SELF usingTransaction(Transaction transaction);
+
+  /**
+   * Execute the query using the given connection.
+   */
+  SELF usingConnection(Connection connection);
+
+  /**
+   * Ensure that the master DataSource is used if there is a read only data source
+   * being used (that is using a read replica database potentially with replication lag).
+   * <p>
+   * When the database is configured with a read-only DataSource via
+   * say {@link DatabaseBuilder#readOnlyDataSource(DataSource)} then
+   * by default when a query is run without an active transaction, it uses the read-only data
+   * source. We use {@code usingMaster()} to instead ensure that the query is executed
+   * against the master data source.
+   */
+  default SELF usingMaster() {
+    return usingMaster(true);
+  }
+
+  /**
+   * Ensure the master DataSource is used when useMaster is true. Otherwise, the read only
+   * data source can be used if defined.
+   *
+   * @see #usingMaster()
+   */
+  SELF usingMaster(boolean useMaster);
+
+}
@@ -0,0 +1,111 @@
+package io.ebean;
+
+import org.jspecify.annotations.NullMarked;
+
+import java.util.List;
+import java.util.function.Consumer;
+import java.util.function.Predicate;
+import java.util.stream.Stream;
+
+/**
+ * Query that maps an entity graph query result to a nested DTO graph, produced by
+ * {@code query.mapTo(SomeDto.class)}.
+ * <p>
+ * Distinct from the existing flat, single-row {@link DtoQuery} pipeline (see {@link
+ * QueryBuilder#asDto(Class)}) - this executes the underlying entity ORM query (with the
+ * select()/fetch() spec automatically derived from the target DTO's declared shape, see
+ * {@link DtoMapper#fetchGroup()}), forces {@code setUnmodifiable(true)}, and then maps the
+ * resulting (unmodifiable) entity graph into a DTO graph via the generated {@link DtoMapper},
+ * supporting nested ToOne/ToMany and identity-aware de-duplication.
+ *
+ * @param <D> the target DTO type
+ */
+@NullMarked
+public interface MappedQuery<D> extends StreamableQuery<MappedQuery<D>, D> {
+
+  /**
+   * Execute the query returning the mapped DTO list.
+   */
+  @Override
+  List<D> findList();
+
+  /**
+   * Execute the query returning a paged list of mapped DTOs.
+   * <p>
+   * Mirrors {@code Query#findPagedList()} - the underlying entity graph query is paged (via
+   * {@code setFirstRow(int)}/{@code setMaxRows(int)}) and executed as normal, then each page's
+   * result is mapped to the target DTO graph. Row-count/page-index metadata
+   * ({@link PagedList#getTotalCount()}, {@link PagedList#hasNext()}, etc.) reflects the
+   * underlying entity query and is unaffected by the DTO mapping.
+   */
+  @Override
+  PagedList<D> findPagedList();
+
+  /**
+   * Execute the query returning the result as a Stream of mapped DTOs.
+   * <p>
+   * Mirrors {@link QueryBuilder#findStream()} - the underlying entity graph query is streamed
+   * (supporting very large queries iterating any number of results, potentially using multiple
+   * persistence contexts internally) and each entity is mapped to its target DTO lazily as the
+   * stream is consumed, sharing one {@link DtoMapContext} across the whole stream so that
+   * repeated references to the same source entity still de-duplicate to the same DTO instance.
+   * <pre>{@code
+   *
+   *  // use try with resources to ensure Stream is closed
+   *
+   *  try (Stream<CustomerDto> stream = query.mapTo(CustomerDto.class).findStream()) {
+   *    stream
+   *    .map(...)
+   *    .collect(...);
+   *  }
+   *
+   * }</pre>
+   */
+  @Override
+  Stream<D> findStream();
+
+  /**
+   * Execute the query processing the mapped DTOs one at a time.
+   * <p>
+   * Mirrors {@link QueryBuilder#findEach(Consumer)} - the underlying entity graph query is
+   * streamed one entity at a time and each entity is mapped to its target DTO lazily as it is
+   * consumed, sharing one {@link DtoMapContext} across the whole callback so that repeated
+   * references to the same source entity still de-duplicate to the same DTO instance.
+   * <p>
+   * This method is appropriate to process very large query results as the mapped DTOs are
+   * consumed one at a time and do not need to be held in memory (unlike {@link #findList()}).
+   *
+   * @param consumer the consumer used to process the mapped DTOs.
+   */
+  @Override
+  void findEach(Consumer<D> consumer);
+  /**
+   * Execute findEach streaming query batching the mapped DTOs for consuming.
+   * <p>
+   * Mirrors {@link QueryBuilder#findEach(int, Consumer)} - typically used when we want to do
+   * further processing on the mapped DTOs in batch form, for example 100 at a time. Each batch
+   * shares one {@link DtoMapContext} with the rest of the query so that repeated references to
+   * the same source entity still de-duplicate to the same DTO instance.
+   *
+   * @param batch    The number of mapped DTOs processed in the batch
+   * @param consumer Process the batch of mapped DTOs
+   */
+  @Override
+  void findEach(int batch, Consumer<List<D>> consumer);
+
+  /**
+   * Execute the query using callbacks to process the resulting mapped DTOs one at a time,
+   * with the ability to stop processing part way through.
+   * <p>
+   * Mirrors {@link QueryBuilder#findEachWhile(Predicate)} - returning {@code false} after
+   * processing a DTO stops the iteration through the query results. Sharing one
+   * {@link DtoMapContext} across the whole callback so that repeated references to the same
+   * source entity still de-duplicate to the same DTO instance.
+   *
+   * @param consumer the consumer used to process the mapped DTOs, returning {@code false} to
+   *                 stop processing.
+   */
+  @Override
+  void findEachWhile(Predicate<D> consumer);
+
+}
@@ -151,7 +151,7 @@ import org.jspecify.annotations.Nullable;
 * @param <T> the type of Entity bean this query will fetch.
 */
@NullMarked
-public interface Query<T> extends CancelableQuery, QueryBuilder<Query<T>, T> {
+public interface Query<T> extends QueryBuilder<Query<T>, T> {

  /**
   * The lock type (strength) to use with query FOR UPDATE row locking.
@@ -2,8 +2,7 @@ package io.ebean;

 import org.jspecify.annotations.Nullable;

-import javax.sql.DataSource;
-import java.sql.Connection;
+import jakarta.persistence.EntityNotFoundException;
 import java.sql.Timestamp;
 import java.util.List;
 import java.util.Map;
@@ -11,8 +10,6 @@ import java.util.Optional;
 import java.util.Set;
 import java.util.function.BooleanSupplier;
 import java.util.function.Consumer;
-import java.util.function.Predicate;
-import java.util.stream.Stream;

 /**
 * Build and execute an ORM query.
@@ -20,7 +17,7 @@ import java.util.stream.Stream;
 * @param <SELF> The type of the builder
 * @param <T>    The entity bean type
 */
-public interface QueryBuilder<SELF extends QueryBuilder<SELF, T>, T> extends QueryBuilderProjection<SELF, T> {
+public interface QueryBuilder<SELF extends QueryBuilder<SELF, T>, T> extends QueryBuilderProjection<SELF, T>, StreamableQuery<SELF, T> {

  /**
   * Set root table alias.
@@ -77,6 +74,32 @@ public interface QueryBuilder<SELF extends QueryBuilder<SELF, T>, T> extends Que
   */
  <D> DtoQuery<D> asDto(Class<D> dtoClass);

+  /**
+   * Map the query result to a nested DTO graph, automatically deriving the select()/fetch() spec
+   * from the target DTO's declared shape and forcing {@code setUnmodifiable(true)}.
+   * <p>
+   * Distinct from {@link #asDto(Class)} (the flat, single-row SQL pipeline) - this supports
+   * nested ToOne/ToMany DTO graphs, mapped from the normal ORM entity query result.
+   *
+   * @throws jakarta.persistence.PersistenceException if no generated {@link DtoMapper} is
+   *     registered for this (entity, dto) pair.
+   */
+  <D> MappedQuery<D> mapTo(Class<D> dtoType);
+
+  /**
+   * Map the query result to a nested DTO graph using an already-resolved {@link DtoMapper}
+   * instance, rather than looking one up by (entity, dtoType). Bypasses {@link DtoMapperManager}
+   * entirely, so it's the way to select a named variant mapper (see {@code @DtoMapping(name =
+   * "...", exclude = "...")}) - e.g. {@code query.mapTo(User.class, userMapper.noFleets())}.
+   * <p>
+   * Also forces {@code setUnmodifiable(true)} and derives the select()/fetch() spec from
+   * {@code mapper.fetchGroup()}, same as {@link #mapTo(Class)}.
+   *
+   * @param dtoType the DTO type mapped to (must match {@code mapper}'s target type)
+   * @param mapper the mapper instance to use, e.g. a named variant accessor on a generated mapper
+   */
+  <D> MappedQuery<D> mapTo(Class<D> dtoType, DtoMapper<T, D> mapper);
+
  /**
   * Convert the query to a UpdateQuery.
   * <p>
@@ -120,48 +143,16 @@ public interface QueryBuilder<SELF extends QueryBuilder<SELF, T>, T> extends Que
   */
  SELF copy();

-  /**
-   * Execute the query using the given transaction.
-   */
-  SELF usingTransaction(Transaction transaction);
-
  /**
   * Execute this query using immutable bean cache values for matching bean types.
   */
  SELF using(ImmutableBeanCache<?> beanCache);

-  /**
-   * Execute the query using the given connection.
-   */
-  SELF usingConnection(Connection connection);
-
  /**
   * Execute the query using the given database.
   */
  SELF usingDatabase(Database database);

-  /**
-   * Ensure that the master DataSource is used if there is a read only data source
-   * being used (that is using a read replica database potentially with replication lag).
-   * <p>
-   * When the database is configured with a read-only DataSource via
-   * say {@link io.ebean.config.DatabaseConfig#setReadOnlyDataSource(DataSource)} then
-   * by default when a query is run without an active transaction, it uses the read-only data
-   * source. We we use {@code usingMaster()} to instead ensure that the query is executed
-   * against the master data source.
-   */
-  default SELF usingMaster() {
-    return usingMaster(true);
-  }
-
-  /**
-   * Ensure the master DataSource is used when useMaster is true. Otherwise, the read only
-   * data source can be used if defined.
-   *
-   * @see #usingMaster()
-   */
-  SELF usingMaster(boolean useMaster);
-
  /**
   * Set the base table to use for this query.
   * <p>
@@ -607,6 +598,21 @@ public interface QueryBuilder<SELF extends QueryBuilder<SELF, T>, T> extends Que
   */
  int delete();

+  /**
+   * Execute as a delete query permanently deleting the 'root level' beans that match the
+   * predicates in the query without soft delete.
+   * <p>
+   * This is the same as {@link #delete()} except that when the bean type uses soft delete
+   * (e.g. {@code @SoftDelete}) the matching rows are permanently (hard) deleted rather than
+   * being marked as deleted.
+   * <p>
+   * Note that if the query includes joins then the generated delete statement may not be
+   * optimal depending on the database platform.
+   *
+   * @return the number of beans/rows that were permanently deleted.
+   */
+  int deletePermanent();
+
  /**
   * Execute the query returning true if a row is found.
   * <p>
@@ -638,88 +644,24 @@ public interface QueryBuilder<SELF extends QueryBuilder<SELF, T>, T> extends Que
  boolean exists();

  /**
-   * Execute the query returning either a single bean or null (if no matching
-   * bean is found).
-   * <p>
-   * If more than 1 row is found for this query then a PersistenceException is
-   * thrown.
-   * <p>
-   * This is useful when your predicates dictate that your query should only
-   * return 0 or 1 results.
+   * Execute the query returning a single bean or throwing a {@link jakarta.persistence.EntityNotFoundException}
+   * if there is no matching bean.
   * <p>
+   * This is a convenience alternative to:
   * <pre>{@code
-   *
-   * // assuming the sku of products is unique...
-   * Product product =
-   *     new QProduct()
-   *         .sku.equalTo("aa113")
-   *         .findOne();
-   * ...
+   *   query.findOneOrEmpty()
+   *     .orElseThrow(() -> new EntityNotFoundException(...));
   * }</pre>
   * <p>
-   * It is also useful with finding objects by their id when you want to specify
-   * further join information to optimise the query.
-   * <p>
-   * <pre>{@code
-   *
-   * // Fetch order 42 and additionally fetch join its order details...
-   * Order order =
-   *     new QOrder()
-   *         .fetch("details") // eagerly load the order details
-   *         .id.equalTo(42)
-   *         .findOne();
-   *
-   * // the order details were eagerly loaded
-   * List<OrderDetail> details = order.getDetails();
-   * ...
-   * }</pre>
+   * The exception message is a best effort - it uses the id when this is effectively a
+   * find-by-id query, or the single equality predicate when the query is filtered by what
+   * looks like a natural/unique key, otherwise a generic "not found" message.
   */
-  @Nullable
-  T findOne();
-
-  /**
-   * Execute the query returning an optional bean.
-   */
-  Optional<T> findOneOrEmpty();
-
-  /**
-   * Execute the query returning the list of objects.
-   * <p>
-   * This query will execute against the EbeanServer that was used to create it.
-   * <p>
-   * <pre>{@code
-   *
-   * List<Customer> customers =
-   *     new QCustomer()
-   *       .name.ilike("rob%")
-   *       .findList();
-   *
-   * }</pre>
-   *
-   * @see Query#findList()
-   */
-  List<T> findList();
-
-  /**
-   * Execute the query returning the result as a Stream.
-   * <p>
-   * Note that this can support very large queries iterating
-   * any number of results. To do so internally it can use
-   * multiple persistence contexts.
-   * </p>
-   * <pre>{@code
-   *
-   *  // use try with resources to ensure Stream is closed
-   *
-   *  try (Stream<Customer> stream = query.findStream()) {
-   *    stream
-   *    .map(...)
-   *    .collect(...);
-   *  }
-   *
-   * }</pre>
-   */
-  Stream<T> findStream();
+  @Override
+  default T findOneOrThrow() {
+    return findOneOrEmpty().orElseThrow(() ->
+      new EntityNotFoundException(getBeanType().getSimpleName() + " not found"));
+  }

  /**
   * Execute the query returning the set of objects.
@@ -864,84 +806,6 @@ public interface QueryBuilder<SELF extends QueryBuilder<SELF, T>, T> extends Que
   */
  <A> Set<A> findSingleAttributeSet();

-  /**
-   * Execute the query processing the beans one at a time.
-   * <p>
-   * This method is appropriate to process very large query results as the
-   * beans are consumed one at a time and do not need to be held in memory
-   * (unlike #findList #findSet etc)
-   * <p>
-   * Note that internally Ebean can inform the JDBC driver that it is expecting larger
-   * resultSet and specifically for MySQL this hint is required to stop it's JDBC driver
-   * from buffering the entire resultSet. As such, for smaller resultSets findList() is
-   * generally preferable.
-   * <p>
-   * Compared with #findEachWhile this will always process all the beans where as
-   * #findEachWhile provides a way to stop processing the query result early before
-   * all the beans have been read.
-   * <p>
-   * This method is functionally equivalent to findIterate() but instead of using an
-   * iterator uses the Consumer interface which is better suited to use with closures.
-   *
-   * <pre>{@code
-   *
-   *  new QCustomer()
-   *     .status.equalTo(Status.NEW)
-   *     .orderBy().id.asc()
-   *     .findEach((Customer customer) -> {
-   *
-   *       // do something with customer
-   *       System.out.println("-- visit " + customer);
-   *     });
-   *
-   * }</pre>
-   *
-   * @param consumer the consumer used to process the queried beans.
-   */
-  void findEach(Consumer<T> consumer);
-
-  /**
-   * Execute findEach streaming query batching the results for consuming.
-   * <p>
-   * This query execution will stream the results and is suited to consuming
-   * large numbers of results from the database.
-   * <p>
-   * Typically, we use this batch consumer when we want to do further processing on
-   * the beans and want to do that processing in batch form, for example - 100 at
-   * a time.
-   *
-   * @param batch    The number of beans processed in the batch
-   * @param consumer Process the batch of beans
-   */
-  void findEach(int batch, Consumer<List<T>> consumer);
-
-  /**
-   * Execute the query using callbacks to a visitor to process the resulting
-   * beans one at a time.
-   * <p>
-   * This method is functionally equivalent to findIterate() but instead of using an
-   * iterator uses the Predicate interface which is better suited to use with closures.
-   *
-   * <pre>{@code
-   *
-   *  new QCustomer()
-   *     .status.equalTo(Status.NEW)
-   *     .orderBy().id.asc()
-   *     .findEachWhile((Customer customer) -> {
-   *
-   *       // do something with customer
-   *       System.out.println("-- visit " + customer);
-   *
-   *       // return true to continue processing or false to stop
-   *       return (customer.getId() < 40);
-   *     });
-   *
-   * }</pre>
-   *
-   * @param consumer the consumer used to process the queried beans.
-   */
-  void findEachWhile(Predicate<T> consumer);
-
  /**
   * Return versions of a @History entity bean.
   * <p>
@@ -1007,33 +871,4 @@ public interface QueryBuilder<SELF extends QueryBuilder<SELF, T>, T> extends Que
   */
  <K> FutureMap<K,T> findFutureMap();

-  /**
-   * Return a PagedList for this query using firstRow and maxRows.
-   * <p>
-   * The benefit of using this over findList() is that it provides functionality to get the
-   * total row count etc.
-   * <p>
-   * If maxRows is not set on the query prior to calling findPagedList() then a
-   * PersistenceException is thrown.
-   * <p>
-   * <pre>{@code
-   *
-   *  PagedList<Order> pagedList =
-   *    new QOrder()
-   *       .setFirstRow(50)
-   *       .setMaxRows(20)
-   *       .findPagedList();
-   *
-   *       // fetch the total row count in the background
-   *       pagedList.loadRowCount();
-   *
-   *       List<Order> orders = pagedList.getList();
-   *       int totalRowCount = pagedList.getTotalRowCount();
-   *
-   * }</pre>
-   *
-   * @return The PagedList
-   */
-  PagedList<T> findPagedList();
-
 }
@@ -41,6 +41,49 @@ public interface RawSqlBuilder {
    return XBootstrapService.rawSql().unparsed(sql);
  }

+  /**
+   * Return a RawSqlBuilder for SQL containing {@code ${where}}, {@code ${having}} and/or
+   * {@code ${orderBy}} placeholder(s). Unlike {@link #parse(String)} this does NOT attempt to parse
+   * the SELECT columns, so it supports complex SQL such as CTEs, subqueries, and window functions.
+   * <p>
+   * Explicit column mappings must be provided (as with {@link #unparsed(String)}), but
+   * WHERE, HAVING and ORDER BY expressions can be added dynamically via the query API - provided
+   * the corresponding placeholder is present in the SQL. If a query calls {@code .orderBy(...)}
+   * on a template with no {@code ${orderBy}}/{@code ${andOrderBy}} placeholder, that ordering is
+   * ignored (there is no injection point for it) rather than producing invalid SQL.
+   * </p>
+   * <p>
+   * Available placeholders:
+   * </p>
+   * <ul>
+   *   <li>{@code ${where}} / {@code ${andWhere}} - inject "where &lt;expr&gt;" / "and &lt;expr&gt;"</li>
+   *   <li>{@code ${having}} / {@code ${andHaving}} - inject "having &lt;expr&gt;" / "and &lt;expr&gt;"</li>
+   *   <li>{@code ${orderBy}} / {@code ${andOrderBy}} - inject "order by &lt;expr&gt;" / ", &lt;expr&gt;"</li>
+   * </ul>
+   * <h3>Example:</h3>
+   * <pre>{@code
+   *
+   *   String sql = """
+   *     with agg as (
+   *       select company_id, sum(amount) as total
+   *       from orders
+   *       ${where}
+   *       group by company_id
+   *     )
+   *     select company_id, total from agg ${orderBy}
+   *     """;
+   *
+   *   RawSql rawSql = RawSqlBuilder.withPlaceholders(sql)
+   *     .columnMapping("company_id", "companyId")
+   *     .columnMapping("total", "total")
+   *     .create();
+   *
+   * }</pre>
+   */
+  static RawSqlBuilder withPlaceholders(String sql) {
+    return XBootstrapService.rawSql().withPlaceholders(sql);
+  }
+
  /**
   * Return a RawSqlBuilder parsing the sql.
   * <p>
@@ -3,7 +3,6 @@ package io.ebean;
 import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;

-import javax.sql.DataSource;
 import java.io.Serializable;
 import java.sql.Connection;
 import java.util.Collection;
@@ -41,44 +40,7 @@ import java.util.function.Predicate;
 * }</pre>
 */
@NullMarked
-public interface SqlQuery extends Serializable, CancelableQuery {
-
-  /**
-   * Execute the query using the given transaction.
-   */
-  SqlQuery usingTransaction(Transaction transaction);
-
-  /**
-   * Execute the query using the given connection.
-   */
-  SqlQuery usingConnection(Connection connection);
-
-  /**
-   * Ensure that the master DataSource is used if there is a read only data source
-   * being used (that is using a read replica database potentially with replication lag).
-   * <p>
-   * When the database is configured with a read-only DataSource via
-   * say {@link io.ebean.DatabaseBuilder#readOnlyDataSource(DataSource)}then
-   * by default when a query is run without an active transaction, it uses the read-only data
-   * source. We use {@code usingMaster()} to instead ensure that the query is executed
-   * against the master data source.
-   */
-  default SqlQuery usingMaster() {
-    return usingMaster(true);
-  }
-
-  /**
-   * Ensure the master DataSource is used when useMaster is true. Otherwise, the read only
-   * data source can be used if defined.
-   *
-   * @see #usingMaster()
-   */
-  SqlQuery usingMaster(boolean useMaster);
-
-  /**
-   * Execute the query returning a list.
-   */
-  List<SqlRow> findList();
+public interface SqlQuery extends Serializable, FindableQuery<SqlQuery, SqlRow> {

  /**
   * Execute the SqlQuery iterating a row at a time.
@@ -99,16 +61,6 @@ public interface SqlQuery extends Serializable, CancelableQuery {
   */
  void findEachWhile(Predicate<SqlRow> consumer);

-  /**
-   * Execute the query returning a single row or null.
-   * <p>
-   * If this query finds 2 or more rows then it will throw a
-   * PersistenceException.
-   * </p>
-   */
-  @Nullable
-  SqlRow findOne();
-
  /**
   * Execute the query reading each row from ResultSet using the RowConsumer.
   * <p>
@@ -139,11 +91,6 @@ public interface SqlQuery extends Serializable, CancelableQuery {
   */
  void findEachRow(RowConsumer consumer);

-  /**
-   * Execute the query returning an optional row.
-   */
-  Optional<SqlRow> findOneOrEmpty();
-
  /**
   * Set one of more positioned parameters.
   * <p>
@@ -365,7 +312,7 @@ public interface SqlQuery extends Serializable, CancelableQuery {
   *
   * @param <T> The type of the scalar values
   */
-  interface TypeQuery<T> {
+  interface TypeQuery<T> extends FindableQuery<TypeQuery<T>, T> {

    /**
     * Ensure the master DataSource is used when useMaster is true. Otherwise, the read only
@@ -373,27 +320,38 @@ public interface SqlQuery extends Serializable, CancelableQuery {
     *
     * @see SqlQuery#usingMaster(boolean)
     */
+    @Override
    TypeQuery<T> usingMaster(boolean useMaster);

    /**
     * Execute the query using the given transaction.
     */
+    @Override
    TypeQuery<T> usingTransaction(Transaction transaction);

+    /**
+     * Execute the query using the given connection.
+     */
+    @Override
+    TypeQuery<T> usingConnection(Connection connection);
+
    /**
     * Return the single value.
     */
    @Nullable
+    @Override
    T findOne();

    /**
     * Return the single value that is optional.
     */
+    @Override
    Optional<T> findOneOrEmpty();

    /**
     * Return the list of values.
     */
+    @Override
    List<T> findList();

    /**
@@ -158,6 +158,15 @@ public interface SqlUpdate {
   */
  int executeNow();

+  /**
+   * Set an explicit transaction to use to execute this statement.
+   * <p>
+   * When not set, {@link #execute()} and {@link #executeNow()} use whatever transaction
+   * is currently active on the thread (or auto-commit if none is active) - consistent
+   * with {@link Database#execute(SqlUpdate, Transaction)}.
+   */
+  SqlUpdate usingTransaction(Transaction transaction);
+
  /**
   * Execute when addBatch() has been used to batch multiple bind executions.
   *
@@ -0,0 +1,101 @@
+package io.ebean;
+
+import org.jspecify.annotations.NullMarked;
+
+import java.util.List;
+import java.util.function.Consumer;
+import java.util.function.Predicate;
+import java.util.stream.Stream;
+
+/**
+ * A {@link FindableQuery} that additionally supports streaming results and paging.
+ *
+ * @param <SELF> The query type (used for method chaining)
+ * @param <T>    The type of the result
+ */
+@NullMarked
+public interface StreamableQuery<SELF extends StreamableQuery<SELF, T>, T> extends FindableQuery<SELF, T> {
+
+  /**
+   * Execute the query returning the result as a Stream.
+   * <p>
+   * Note that this can support very large queries iterating any number of results.
+   * To do so internally it can use multiple persistence contexts.
+   * <p>
+   * Note that the Stream holds resources related to the underlying resultSet and
+   * potentially connection and MUST be closed. We should use the Stream in a
+   * <em>try with resource block</em>.
+   * <pre>{@code
+   *
+   *  // use try with resources to ensure Stream is closed
+   *
+   *  try (Stream<T> stream = query.findStream()) {
+   *    stream
+   *    .map(...)
+   *    .collect(...);
+   *  }
+   *
+   * }</pre>
+   */
+  Stream<T> findStream();
+
+  /**
+   * Return a PagedList for this query using firstRow and maxRows.
+   * <p>
+   * The benefit of using this over findList() is that it provides functionality to get the
+   * total row count etc.
+   * <p>
+   * If maxRows is not set on the query prior to calling findPagedList() then a
+   * PersistenceException is thrown.
+   *
+   * @return The PagedList
+   */
+  PagedList<T> findPagedList();
+
+  /**
+   * Execute the query processing the results one at a time.
+   * <p>
+   * This method is appropriate to process very large query results as the results are
+   * consumed one at a time and do not need to be held in memory (unlike {@link #findList()}).
+   * <p>
+   * Note that internally Ebean can inform the JDBC driver that it is expecting a larger
+   * resultSet and specifically for MySQL this hint is required to stop its JDBC driver
+   * from buffering the entire resultSet. As such, for smaller resultSets findList() is
+   * generally preferable.
+   * <p>
+   * Compared with {@link #findEachWhile(Predicate)} this will always process all the results
+   * whereas findEachWhile() provides a way to stop processing the query result early before
+   * all the results have been read.
+   *
+   * @param consumer the consumer used to process the queried results.
+   */
+  void findEach(Consumer<T> consumer);
+
+  /**
+   * Execute findEach streaming query batching the results for consuming.
+   * <p>
+   * This query execution will stream the results and is suited to consuming
+   * large numbers of results from the database.
+   * <p>
+   * Typically, we use this batch consumer when we want to do further processing on
+   * the results and want to do that processing in batch form, for example - 100 at
+   * a time.
+   *
+   * @param batch    The number of results processed in the batch
+   * @param consumer Process the batch of results
+   */
+  void findEach(int batch, Consumer<List<T>> consumer);
+
+  /**
+   * Execute the query using callbacks to process the resulting results one at a time,
+   * with the ability to stop processing part way through.
+   * <p>
+   * Returning {@code false} after processing a result stops the iteration through the
+   * query results.
+   *
+   * @param consumer the consumer used to process the queried results, returning
+   *                 {@code false} to stop processing.
+   */
+  void findEachWhile(Predicate<T> consumer);
+
+}
@@ -260,6 +260,27 @@ public interface Transaction extends AutoCloseable {
   */
  void setUpdateAllLoadedProperties(boolean updateAllLoadedProperties);

+  /**
+   * Set to false to disable auto-generation of {@code @WhenCreated}, {@code @WhenModified},
+   * {@code @WhoCreated} and {@code @WhoModified} values for this transaction.
+   * <p>
+   * When disabled, Ebean will only set a generated property value if the property currently
+   * has a null value (for inserts) or is a {@code @Version} property. Any value already set
+   * on the bean is preserved.
+   * <p>
+   * This is useful in backup and restore scenarios where you need to retain the original
+   * audit timestamps and user values rather than have them overwritten.
+   * <pre>{@code
+   *   try (Transaction txn = DB.beginTransaction()) {
+   *     txn.setGeneratedPropertiesEnabled(false);
+   *     bean.setWhenCreated(originalTimestamp);
+   *     DB.save(bean);
+   *     txn.commit();
+   *   }
+   * }</pre>
+   */
+  void setGeneratedPropertiesEnabled(boolean enable);
+
  /**
   * Set if the L2 cache should be skipped for "find by id" and "find by natural key" queries.
   * <p>
@@ -84,6 +84,15 @@ public interface Update<T> {
   */
  int execute();

+  /**
+   * Set an explicit transaction to use to execute this statement.
+   * <p>
+   * When not set, {@link #execute()} uses whatever transaction is currently active on
+   * the thread (or auto-commit if none is active) - consistent with
+   * {@link Database#execute(Update, Transaction)}.
+   */
+  Update<T> usingTransaction(Transaction transaction);
+
  /**
   * Set an ordered bind parameter.
   * <p>
@@ -175,7 +175,7 @@ public final class InterceptReadOnly extends InterceptBase {

  @Override
  public boolean isUpdate() {
-    return false;
+    return true;
  }

  @Override
@@ -151,14 +151,16 @@ public final class BeanList<E> extends AbstractBeanCollection<E> implements List
    }
  }

-  /**
-   * Set the actual underlying list.
-   * <p>
-   * This is primarily for the deferred fetching function.
-   */
-  @SuppressWarnings("unchecked")
-  public void setActualList(List<?> list) {
-    this.list = (List<E>) list;
+  public BeanCollectionAdd collectionAdd() {
+    if (list == null) {
+      list = new ArrayList<>();
+    }
+    return this;
+  }
+
+  public void refresh(ModifyListenMode modifyListenMode, BeanList<E> newList) {
+    setModifyListening(modifyListenMode);
+    this.list = newList.actualList();
  }

  /**
@@ -1,9 +1,6 @@
 package io.ebean.common;

-import io.ebean.bean.BeanCollection;
-import io.ebean.bean.BeanCollectionLoader;
-import io.ebean.bean.EntityBean;
-import io.ebean.bean.ToStringBuilder;
+import io.ebean.bean.*;

 import java.util.*;

@@ -17,12 +14,12 @@ public final class BeanMap<K, E> extends AbstractBeanCollection<E> implements Ma
  /**
   * The underlying map implementation.
   */
-  private Map<K, E> map;
+  private LinkedHashMap<K, E> map;

  /**
   * Create with a given Map.
   */
-  public BeanMap(Map<K, E> map) {
+  public BeanMap(LinkedHashMap<K, E> map) {
    this.map = map;
  }

@@ -165,18 +162,23 @@ public final class BeanMap<K, E> extends AbstractBeanCollection<E> implements Ma
    }
  }

-  /**
-   * Set the actual underlying map. Used for performing lazy fetch.
-   */
+  public LinkedHashMap<K, E> collectionAdd() {
+    if (map == null) {
+      map = new LinkedHashMap<>();
+    }
+    return map;
+  }
+
  @SuppressWarnings("unchecked")
-  public void setActualMap(Map<?, ?> map) {
-    this.map = (Map<K, E>) map;
+  public void refresh(ModifyListenMode modifyListenMode, BeanMap<?, ?> newMap) {
+    setModifyListening(modifyListenMode);
+    this.map = (LinkedHashMap<K, E>) newMap.actualMap();
  }

  /**
   * Return the actual underlying map.
   */
-  public Map<K, E> actualMap() {
+  public LinkedHashMap<K, E> actualMap() {
    return map;
  }

@@ -15,12 +15,12 @@ public final class BeanSet<E> extends AbstractBeanCollection<E> implements Set<E
  /**
   * The underlying Set implementation.
   */
-  private Set<E> set;
+  private LinkedHashSet<E> set;

  /**
   * Create with a specific Set implementation.
   */
-  public BeanSet(Set<E> set) {
+  public BeanSet(LinkedHashSet<E> set) {
    this.set = set;
  }

@@ -146,18 +146,22 @@ public final class BeanSet<E> extends AbstractBeanCollection<E> implements Set<E
    }
  }

-  /**
-   * Set the underlying set (used for lazy fetch).
-   */
-  @SuppressWarnings("unchecked")
-  public void setActualSet(Set<?> set) {
-    this.set = (Set<E>) set;
+  public BeanCollectionAdd collectionAdd() {
+    if (set == null) {
+      set = new LinkedHashSet<>();
+    }
+    return this;
+  }
+
+  public void refresh(ModifyListenMode modifyListenMode, BeanSet<E> newSet) {
+    setModifyListening(modifyListenMode);
+    this.set = newSet.actualSet();
  }

  /**
   * Return the actual underlying set.
   */
-  public Set<E> actualSet() {
+  public LinkedHashSet<E> actualSet() {
    return set;
  }

@@ -60,7 +60,8 @@ public class ClassLoadConfig {
  }

  public boolean isJacksonCorePresent() {
-    return isPresent("com.fasterxml.jackson.core.JsonParser");
+    // Legacy method name retained for compatibility; now checks avaje JSON core.
+    return isPresent("io.avaje.json.JsonReader");
  }

  /**
@@ -158,4 +159,3 @@ public class ClassLoadConfig {
    }
  }
 }
-
@@ -1,7 +1,7 @@
 package io.ebean.config;

-import com.fasterxml.jackson.core.JsonFactory;
 import io.avaje.config.Config;
+import io.avaje.json.stream.JsonStream;
 import io.ebean.*;
 import io.ebean.annotation.MutationDetection;
 import io.ebean.annotation.PersistBatch;
@@ -420,7 +420,7 @@ public class DatabaseConfig implements DatabaseBuilder.Settings {
   * The default PersistenceContextScope used if one is not explicitly set on a query.
   */
  private PersistenceContextScope persistenceContextScope = PersistenceContextScope.TRANSACTION;
-  private JsonFactory jsonFactory;
+  private JsonStream jsonStream;
  private boolean localTimeWithNanos;
  private boolean durationWithNanos;
  private int maxCallStack = 5;
@@ -432,6 +432,8 @@ public class DatabaseConfig implements DatabaseBuilder.Settings {
  private int backgroundExecutorShutdownSecs = 30;
  private BackgroundExecutorWrapper backgroundExecutorWrapper = new MdcBackgroundExecutorWrapper();

+  private boolean tenantPartitionedCache;
+
  // defaults for the L2 bean caching

  private int cacheMaxSize = 10000;
@@ -631,13 +633,13 @@ public class DatabaseConfig implements DatabaseBuilder.Settings {
  }

  @Override
-  public JsonFactory getJsonFactory() {
-    return jsonFactory;
+  public JsonStream getJsonStream() {
+    return jsonStream;
  }

  @Override
-  public DatabaseConfig setJsonFactory(JsonFactory jsonFactory) {
-    this.jsonFactory = jsonFactory;
+  public DatabaseConfig setJsonStream(JsonStream jsonStream) {
+    this.jsonStream = jsonStream;
    return this;
  }

@@ -1175,6 +1177,17 @@ public class DatabaseConfig implements DatabaseBuilder.Settings {
    return cacheMaxSize;
  }

+  @Override
+  public boolean isTenantPartitionedCache() {
+    return tenantPartitionedCache;
+  }
+
+  @Override
+  public DatabaseConfig tenantPartitionedCache(boolean tenantPartitionedCache) {
+    this.tenantPartitionedCache = tenantPartitionedCache;
+    return this;
+  }
+
  @Override
  public DatabaseConfig setCacheMaxSize(int cacheMaxSize) {
    this.cacheMaxSize = cacheMaxSize;
@@ -2228,6 +2241,15 @@ public class DatabaseConfig implements DatabaseBuilder.Settings {
    ddlPlaceholders = p.get("ddl.placeholders", ddlPlaceholders);
    ddlHeader = p.get("ddl.header", ddlHeader);

+    tenantPartitionedCache = p.getBoolean("tenantPartitionedCache", tenantPartitionedCache);
+
+    cacheMaxSize = p.getInt("cacheMaxSize", cacheMaxSize);
+    cacheMaxIdleTime = p.getInt("cacheMaxIdleTime", cacheMaxIdleTime);
+    cacheMaxTimeToLive = p.getInt("cacheMaxTimeToLive", cacheMaxTimeToLive);
+    queryCacheMaxSize = p.getInt("queryCacheMaxSize", queryCacheMaxSize);
+    queryCacheMaxIdleTime = p.getInt("queryCacheMaxIdleTime", queryCacheMaxIdleTime);
+    queryCacheMaxTimeToLive = p.getInt("queryCacheMaxTimeToLive", queryCacheMaxTimeToLive);
+
    // read tenant-configuration from config:
    // tenant.mode = NONE | DB | SCHEMA | CATALOG | PARTITION
    String mode = p.get("tenant.mode");
@@ -0,0 +1,31 @@
+package io.ebean.config;
+
+import io.ebean.DtoMapper;
+
+/**
+ * Loads and returns the {@link DtoMapper} to use for a given DTO type, generated per-module by
+ * the querybean-generator annotation processor for each {@code io.ebean.annotation.DtoMapping}
+ * registered pair.
+ * <p>
+ * Implementations resolve purely via literal {@code Class} comparisons (no reflection,
+ * {@code Class.forName}, or {@code MethodHandles}) - safe under GraalVM native-image with zero
+ * additional reachability metadata - mirroring {@link EntityClassRegister}.
+ */
+public interface DtoMapperRegister {
+
+  /**
+   * Return the mapper for the given DTO type, or {@code null} if this register has no mapper for
+   * that type.
+   */
+  <SOURCE,TARGET> DtoMapper<SOURCE, TARGET> mapperFor(Class<SOURCE> sourceType, Class<TARGET> targetType);
+
+  /**
+   * Return the mapper instance of the given concrete generated mapper type, or {@code null} if
+   * this register has no mapper of that type.
+   * <p>
+   * An alternative to {@link #mapperFor(Class, Class)} for looking up a mapper by its own class
+   * (e.g. {@code CustomerDtoMapper.class}) rather than by its (source, target) pair - typically
+   * used to resolve a mapper instance for dependency injection into application code.
+   */
+  <T> T mapperOfType(Class<T> mapperType);
+}
@@ -162,6 +162,18 @@ public class DatabasePlatform {
  protected boolean selectCountWithAlias;
  protected boolean selectCountWithColumnAlias;

+  /**
+   * Set true for platforms where {@code exists(...)} can only be used as a predicate
+   * and not as a directly selectable scalar boolean expression (e.g. SQL Server, Oracle).
+   */
+  protected boolean existsWithCaseWhen;
+
+  /**
+   * Clause appended after the {@code case when exists(...) then 1 else 0 end} exists query
+   * for platforms that require a FROM clause on every select (e.g. {@code from dual} on Oracle).
+   */
+  protected String existsFromClause = "";
+
  /**
   * If set then use the FORWARD ONLY hint when creating ResultSets for
   * findIterate() and findVisit().
@@ -660,6 +672,21 @@ public class DatabasePlatform {
    return selectCountWithColumnAlias;
  }

+  /**
+   * Return true if a scalar boolean {@code exists(...)} expression is not supported
+   * as a select expression and needs to be wrapped as {@code case when exists(...) then 1 else 0 end}.
+   */
+  public boolean existsWithCaseWhen() {
+    return existsWithCaseWhen;
+  }
+
+  /**
+   * Return the clause to append after the exists case-when wrapping (e.g. {@code from dual} on Oracle).
+   */
+  public String existsFromClause() {
+    return existsFromClause;
+  }
+

  public String completeSql(String sql, Query<?> query) {
    if (query.isForUpdate()) {
@@ -11,10 +11,12 @@ import java.sql.Connection;
 import java.sql.PreparedStatement;
 import java.sql.ResultSet;
 import java.sql.SQLException;
+import java.util.ArrayDeque;
 import java.util.Collections;
+import java.util.Deque;
 import java.util.List;
-import java.util.NavigableSet;
-import java.util.TreeSet;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ConcurrentMap;
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.locks.ReentrantLock;

@@ -23,18 +25,36 @@ import static java.lang.System.Logger.Level.ERROR;

 /**
 * Database sequence based IdGenerator.
+ * <p>
+ * Maintains a separate buffer of pre-fetched id values per tenant when the supplied
+ * DataSource implements {@link TenantConnectionSource}. For the common single-tenant
+ * case a single buffer is used (keyed by {@link #SINGLE}).
 */
 public abstract class SequenceIdGenerator implements PlatformIdGenerator {

  protected static final System.Logger log = AppLog.getLogger("io.ebean.SEQ");

-  private final ReentrantLock lock = new ReentrantLock();
+  /**
+   * Buffer key used when there is no current tenant (single-tenant or no tenant in scope).
+   */
+  private static final Object SINGLE = new Object();
+
  protected final String seqName;
  protected final DataSource dataSource;
  protected final BackgroundExecutor backgroundExecutor;
-  protected final NavigableSet<Long> idList = new TreeSet<>();
  protected final int allocationSize;
-  protected AtomicBoolean currentlyBackgroundLoading = new AtomicBoolean(false);
+  private final TenantConnectionSource tenantSource;
+  private final TenantBuffer single = new TenantBuffer();
+  private final ConcurrentMap<Object, TenantBuffer> buffers = new ConcurrentHashMap<>();
+
+  /**
+   * Per-tenant pre-fetched id buffer with its own lock and background-loading flag.
+   */
+  private static final class TenantBuffer {
+    final ReentrantLock lock = new ReentrantLock();
+    final Deque<Long> idList = new ArrayDeque<>();
+    final AtomicBoolean currentlyBackgroundLoading = new AtomicBoolean(false);
+  }

  /**
   * Construct given a dataSource and sql to return the next sequence value.
@@ -44,6 +64,7 @@ public abstract class SequenceIdGenerator implements PlatformIdGenerator {
    this.dataSource = ds;
    this.seqName = seqName;
    this.allocationSize = allocationSize;
+    this.tenantSource = (ds instanceof TenantConnectionSource) ? (TenantConnectionSource) ds : null;
  }

  public abstract String getSql(int batchSize);
@@ -64,6 +85,24 @@ public abstract class SequenceIdGenerator implements PlatformIdGenerator {
    return true;
  }

+  private Object currentTenantKey() {
+    if (tenantSource != null) {
+      Object tenantId = tenantSource.currentTenantId();
+      if (tenantId != null) {
+        return tenantId;
+      }
+    }
+    return SINGLE;
+  }
+
+  private TenantBuffer buffer(Object tenantKey) {
+    if (tenantKey == SINGLE) {
+      // common single-tenant path - avoid the concurrent map lookup
+      return single;
+    }
+    return buffers.computeIfAbsent(tenantKey, k -> new TenantBuffer());
+  }
+
  /**
   * If allocateSize is large load some sequences in a background thread.
   * <p>
@@ -78,23 +117,22 @@ public abstract class SequenceIdGenerator implements PlatformIdGenerator {

  /**
   * Return the next Id.
-   * <p>
-   * If a Transaction has been passed in use the Connection from it.
-   * </p>
   */
  @Override
  public Object nextId(Transaction t) {
-    lock.lock();
+    Object tenantKey = currentTenantKey();
+    TenantBuffer buffer = buffer(tenantKey);
+    buffer.lock.lock();
    try {
-      int size = idList.size();
+      int size = buffer.idList.size();
      if (size > 0) {
        maybeLoadMoreInBackground(size);
      } else {
-        loadMore(allocationSize);
+        loadMore(tenantKey, buffer, allocationSize);
      }
-      return idList.pollFirst();
+      return buffer.idList.poll();
    } finally {
-      lock.unlock();
+      buffer.lock.unlock();
    }
  }

@@ -106,29 +144,36 @@ public abstract class SequenceIdGenerator implements PlatformIdGenerator {
    }
  }

-  private void loadMore(int requestSize) {
-    List<Long> newIds = getMoreIds(requestSize);
-    lock.lock();
+  private void loadMore(Object tenantKey, TenantBuffer buffer, int requestSize) {
+    List<Long> newIds = getMoreIds(tenantKey, requestSize);
+    buffer.lock.lock();
    try {
-      idList.addAll(newIds);
+      buffer.idList.addAll(newIds);
    } finally {
-      lock.unlock();
+      buffer.lock.unlock();
    }
  }

  /**
   * Load another batch of Id's using a background thread.
+   * <p>
+   * The tenant is captured here (submit time) as the current tenant is not in scope
+   * on the background executor thread.
   */
  protected void loadInBackground(final int requestSize) {
-    if (currentlyBackgroundLoading.get()) {
+    final Object tenantKey = currentTenantKey();
+    final TenantBuffer buffer = buffer(tenantKey);
+    if (!buffer.currentlyBackgroundLoading.compareAndSet(false, true)) {
      // skip as already background loading
      log.log(DEBUG, "... skip background sequence load (another load in progress)");
      return;
    }
-    currentlyBackgroundLoading.set(true);
    backgroundExecutor.execute(() -> {
-      loadMore(requestSize);
-      currentlyBackgroundLoading.set(false);
+      try {
+        loadMore(tenantKey, buffer, requestSize);
+      } finally {
+        buffer.currentlyBackgroundLoading.set(false);
+      }
    });
  }

@@ -140,7 +185,7 @@ public abstract class SequenceIdGenerator implements PlatformIdGenerator {
  /**
   * Get more Id's by executing a query and reading the Id's returned.
   */
-  protected List<Long> getMoreIds(int requestSize) {
+  protected List<Long> getMoreIds(Object tenantKey, int requestSize) {

    String sql = getSql(requestSize);

@@ -148,7 +193,7 @@ public abstract class SequenceIdGenerator implements PlatformIdGenerator {
    PreparedStatement statement = null;
    ResultSet resultSet = null;
    try {
-      connection = dataSource.getConnection();
+      connection = connectionFor(tenantKey);

      statement = connection.prepareStatement(sql);
      resultSet = statement.executeQuery();
@@ -174,6 +219,17 @@ public abstract class SequenceIdGenerator implements PlatformIdGenerator {
    }
  }

+  /**
+   * Return a connection for the given tenant. For multi-tenant this is routed to the
+   * tenant database/schema/catalog; otherwise the plain DataSource connection is used.
+   */
+  private Connection connectionFor(Object tenantKey) throws SQLException {
+    if (tenantSource != null && tenantKey != SINGLE) {
+      return tenantSource.connectionForTenant(tenantKey);
+    }
+    return dataSource.getConnection();
+  }
+
  /**
   * Close the JDBC resources.
   */
@@ -0,0 +1,29 @@
+package io.ebean.config.dbplatform;
+
+import java.sql.Connection;
+import java.sql.SQLException;
+
+/**
+ * Optionally implemented by the DataSource passed to a {@link SequenceIdGenerator}
+ * to make sequence id allocation multi-tenant aware.
+ * <p>
+ * When the DataSource implements this interface the sequence generator maintains
+ * a separate id buffer per tenant and obtains connections that are routed to the
+ * correct tenant database (TenantMode.DB) or schema/catalog (TenantMode.SCHEMA / CATALOG).
+ * <p>
+ * The {@link #connectionForTenant(Object)} method takes an explicit tenantId so that
+ * background pre-fetch (which runs on a separate thread without the current tenant
+ * in scope) can fetch sequence values for the tenant captured at submit time.
+ */
+public interface TenantConnectionSource {
+
+  /**
+   * Return the current tenant id, or null when there is no current tenant scope.
+   */
+  Object currentTenantId();
+
+  /**
+   * Return a connection routed to the given tenant (its database, schema or catalog).
+   */
+  Connection connectionForTenant(Object tenantId) throws SQLException;
+}
@@ -1,6 +1,7 @@
 package io.ebean.event;

 import io.ebean.Database;
+import io.ebean.DatabaseFactory;
 import io.ebean.EbeanVersion;
 import io.ebean.service.SpiContainer;

@@ -188,6 +189,7 @@ public final class ShutdownManager {
   */
  public static void unregisterDatabase(Database server) {
    databases.remove(server);
+    DatabaseFactory.unregister(server);
  }

  private static class ShutdownHook extends Thread {
@@ -9,6 +9,11 @@ import java.time.Instant;
 */
 public interface MetaQueryPlan {

+  /**
+   * Return the name of the database for the query.
+   */
+  String dbName();
+
  /**
   * Return the bean type for the query.
   */
@@ -44,6 +49,11 @@ public interface MetaQueryPlan {
   */
  String plan();

+  /**
+   * The tenant ID of the plan.
+   */
+  Object tenantId();
+
  /**
   * Return the query execution time associated with the bind values capture.
   */
@@ -0,0 +1,135 @@
+package io.ebean.meta;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * Canonical "v2" mapping of Ebean's internal flat metric names (e.g.
+ * {@code orm.Customer.findList}, {@code iud.User.save}, {@code txn.named.X},
+ * {@code l2.<region>.<op>}) into a metric family name plus a tag string following
+ * the label-tag convention.
+ *
+ * <p>This is the source-of-truth mapping for the v2 metrics JSON form
+ * ({@link ServerMetricsAsJson#writeV2(Appendable)}). The tag string is a canonical,
+ * sorted, comma separated list of {@code key:value} pairs, e.g.
+ * {@code "kind:orm,label:Customer.findList,type:Customer"}.
+ *
+ * <table>
+ *   <caption>Ebean prefix → family name + tags</caption>
+ *   <tr><th>Ebean prefix</th><th>name</th><th>tags</th></tr>
+ *   <tr><td>{@code iud.X}</td><td>{@code ebean.dml}</td><td>{@code label=X}</td></tr>
+ *   <tr><td>{@code orm.X}</td><td>{@code ebean.query}</td><td>{@code kind=orm, type=<bean>, label=X}</td></tr>
+ *   <tr><td>{@code dto.X}</td><td>{@code ebean.query}</td><td>{@code kind=dto, type=<bean>, label=X}</td></tr>
+ *   <tr><td>{@code sql.X}</td><td>{@code ebean.query}</td><td>{@code kind=sql, type=<bean>, label=X}</td></tr>
+ *   <tr><td>{@code txn.named.X} / {@code txn.X}</td><td>{@code ebean.txn}</td><td>{@code label=X}</td></tr>
+ *   <tr><td>{@code l2.<region>.<op>}</td><td>{@code ebean.l2}</td><td>{@code op=<op>, region=<region>}</td></tr>
+ *   <tr><td>(unrecognised)</td><td>{@code ebean.other}</td><td>{@code label=<original name>}</td></tr>
+ * </table>
+ *
+ * <p>The {@code kind} tag is the query category (orm/dto/sql) while the {@code type}
+ * tag is the queried bean/entity simple name. The {@code type} tag is omitted when
+ * the bean type is unknown.
+ */
+final class MetricNamingV2 {
+
+  /** Result of a name mapping: family name plus canonical tag string. */
+  static final class Mapped {
+    private final String name;
+    private final String tags;
+
+    Mapped(String name, String tags) {
+      this.name = name;
+      this.tags = tags;
+    }
+
+    String name() {
+      return name;
+    }
+
+    String tags() {
+      return tags;
+    }
+  }
+
+  private MetricNamingV2() {
+  }
+
+  /**
+   * Map an Ebean flat metric name (and optional bean type for query metrics) into
+   * the canonical family name plus tag string.
+   */
+  static Mapped map(String ebeanName, String beanType) {
+    if (ebeanName == null || ebeanName.isEmpty()) {
+      return new Mapped("ebean.other", "");
+    }
+    int firstDot = ebeanName.indexOf('.');
+    if (firstDot <= 0) {
+      return new Mapped("ebean.other", tags("label", ebeanName));
+    }
+    String prefix = ebeanName.substring(0, firstDot);
+    String rest = ebeanName.substring(firstDot + 1);
+    switch (prefix) {
+      case "iud":
+        return new Mapped("ebean.dml", tags("label", rest));
+      case "orm":
+        return query("orm", rest, beanType);
+      case "dto":
+        return query("dto", rest, beanType);
+      case "sql":
+        return query("sql", rest, beanType);
+      case "txn":
+        String txnLabel = rest.startsWith("named.") ? rest.substring("named.".length()) : rest;
+        return new Mapped("ebean.txn", tags("label", txnLabel));
+      case "l2":
+        return l2(rest);
+      default:
+        return new Mapped("ebean.other", tags("label", ebeanName));
+    }
+  }
+
+  private static Mapped query(String kind, String label, String beanType) {
+    if (beanType == null || beanType.isEmpty()) {
+      return new Mapped("ebean.query", tags("kind", kind, "label", label));
+    }
+    return new Mapped("ebean.query", tags("kind", kind, "type", beanType, "label", label));
+  }
+
+  private static Mapped l2(String rest) {
+    int dot = rest.indexOf('.');
+    if (dot <= 0) {
+      return new Mapped("ebean.l2", tags("op", rest));
+    }
+    String region = rest.substring(0, dot);
+    String op = rest.substring(dot + 1);
+    return new Mapped("ebean.l2", tags("op", op, "region", region));
+  }
+
+  /**
+   * Build a canonical (sorted) {@code key:value,key2:value2} tag string from the given
+   * key/value pairs, skipping null/empty values and sanitising the reserved
+   * delimiter characters from values.
+   */
+  private static String tags(String... keyValues) {
+    List<String> pairs = new ArrayList<>(keyValues.length / 2);
+    for (int i = 0; i + 1 < keyValues.length; i += 2) {
+      String value = keyValues[i + 1];
+      if (value != null && !value.isEmpty()) {
+        pairs.add(keyValues[i] + ':' + sanitize(value));
+      }
+    }
+    Collections.sort(pairs);
+    return String.join(",", pairs);
+  }
+
+  /**
+   * Replace the reserved tag delimiter characters ({@code ,} and {@code :}) so they
+   * cannot break the {@code key:value,key2:value2} encoding.
+   */
+  private static String sanitize(String value) {
+    if (value.indexOf(',') < 0 && value.indexOf(':') < 0) {
+      return value;
+    }
+    return value.replace(',', '_').replace(':', '_');
+  }
+}
@@ -19,6 +19,7 @@ final class MetricsAsJson implements ServerMetricsAsJson {
  private Comparator<MetaTimedMetric> sortBy = SortMetric.NAME;
  private int listCounter;
  private int objKeyCounter;
+  private boolean v2;

  MetricsAsJson(ServerMetrics metrics) {
    this.metrics = metrics;
@@ -67,6 +68,13 @@ final class MetricsAsJson implements ServerMetricsAsJson {
    collect();
  }

+  @Override
+  public void writeV2(Appendable buffer) {
+    this.v2 = true;
+    this.writer = buffer;
+    collect();
+  }
+
  private void collect() {
    try {
      start();
@@ -151,12 +159,26 @@ final class MetricsAsJson implements ServerMetricsAsJson {
  }

  private void metricStart(MetaMetric metric) throws IOException {
+    metricStart(metric, null);
+  }
+
+  private void metricStart(MetaMetric metric, String beanType) throws IOException {
    if (listCounter++ > 0) {
      writer.append(',').append(newLine);
    }
    objStart();
-    key("name");
-    val(metric.name());
+    if (v2) {
+      MetricNamingV2.Mapped mapped = MetricNamingV2.map(metric.name(), beanType);
+      key("name");
+      val(mapped.name());
+      if (!mapped.tags().isEmpty()) {
+        key("tags");
+        val(mapped.tags());
+      }
+    } else {
+      key("name");
+      val(metric.name());
+    }
  }

  private void metricEnd() throws IOException {
@@ -180,7 +202,8 @@ final class MetricsAsJson implements ServerMetricsAsJson {
  }

  private void logQuery(MetaQueryMetric metric) throws IOException {
-    metricStart(metric);
+    Class<?> beanType = metric.type();
+    metricStart(metric, beanType == null ? null : beanType.getSimpleName());
    appendTiming(metric);
    if (withHash) {
      append("hash", metric.hash());
@@ -41,6 +41,17 @@ public interface ServerMetricsAsJson {
   */
  void write(Appendable buffer);

+  /**
+   * Collect and write metrics as "v2" JSON to the given buffer.
+   * <p>
+   * The v2 form uses the canonical label-tag convention: each metric is written with
+   * a family {@code name} (e.g. {@code ebean.query}, {@code ebean.dml}) plus a
+   * {@code tags} string of sorted {@code key:value} pairs (e.g.
+   * {@code "kind:orm,label:Customer.findList,type:Customer"}) rather than the flat
+   * prefixed name. Timing, hash, location and sql attributes are unchanged.
+   */
+  void writeV2(Appendable buffer);
+
  /**
   * Return the metrics in raw JSON.
   */
@@ -34,6 +34,6 @@ public interface MetricFactory extends BootstrapService {
  /**
   * Create a Timed metric.
   */
-  QueryPlanMetric createQueryPlanMetric(Class<?> type, String label, ProfileLocation profileLocation, String sql);
+  QueryPlanMetric createQueryPlanMetric(Class<?> type, String name, String label, ProfileLocation profileLocation, String sql, String hash);

 }
@@ -1,8 +1,8 @@
 package io.ebean.service;

-import com.fasterxml.jackson.core.JsonGenerator;
-import com.fasterxml.jackson.core.JsonParser;
-import com.fasterxml.jackson.core.JsonToken;
+import io.avaje.json.JsonReader;
+import io.avaje.json.JsonReader.Token;
+import io.avaje.json.JsonWriter;

 import java.io.IOException;
 import java.io.Reader;
@@ -32,12 +32,12 @@ public interface SpiJsonService extends BootstrapService {
  /**
   * Write the nested Map/List as json to the jsonGenerator.
   */
-  void write(Object object, JsonGenerator jsonGenerator) throws IOException;
+  void write(Object object, JsonWriter jsonGenerator) throws IOException;

  /**
   * Write the collection as json array to the jsonGenerator.
   */
-  void writeCollection(Collection<Object> collection, JsonGenerator jsonGenerator) throws IOException;
+  void writeCollection(Collection<Object> collection, JsonWriter jsonGenerator) throws IOException;

  /**
   * Parse the json and return as a Map additionally specifying if the returned map should
@@ -61,17 +61,17 @@ public interface SpiJsonService extends BootstrapService {
  Map<String, Object> parseObject(Reader reader) throws IOException;

  /**
-   * Parse the json and return as a Map taking a JsonParser.
+   * Parse the json and return as a Map taking a JsonReader.
   */
-  Map<String, Object> parseObject(JsonParser parser) throws IOException;
+  Map<String, Object> parseObject(JsonReader parser) throws IOException;

  /**
-   * Parse the json and return as a Map taking a JsonParser and a starting token.
+   * Parse the json and return as a Map taking a JsonReader and a starting token.
   * <p>
   * Used when the first token is checked to see if the value is null prior to calling this.
   * </p>
   */
-  Map<String, Object> parseObject(JsonParser parser, JsonToken token) throws IOException;
+  Map<String, Object> parseObject(JsonReader parser, Token token) throws IOException;

  /**
   * Parse the json and return as a modify aware List.
@@ -89,14 +89,14 @@ public interface SpiJsonService extends BootstrapService {
  List<Object> parseList(Reader reader) throws IOException;

  /**
-   * Parse the json and return as a List taking a JsonParser.
+   * Parse the json and return as a List taking a JsonReader.
   */
-  List<Object> parseList(JsonParser parser) throws IOException;
+  List<Object> parseList(JsonReader parser) throws IOException;

  /**
   * Parse the json returning as a List taking into account the current token.
   */
-  <T> List<T> parseList(JsonParser parser, JsonToken currentToken) throws IOException;
+  <T> List<T> parseList(JsonReader parser, Token currentToken) throws IOException;

  /**
   * Parse the json and return as a List or Map.
@@ -111,7 +111,7 @@ public interface SpiJsonService extends BootstrapService {
  /**
   * Parse the json and return as a List or Map.
   */
-  Object parse(JsonParser parser) throws IOException;
+  Object parse(JsonReader parser) throws IOException;

  /**
   * Parse the json returning a Set that might be modify aware.
@@ -121,5 +121,5 @@ public interface SpiJsonService extends BootstrapService {
  /**
   * Parse the json returning as a Set taking into account the current token.
   */
-  <T> Set<T> parseSet(JsonParser parser, JsonToken currentToken) throws IOException;
+  <T> Set<T> parseSet(JsonReader parser, Token currentToken) throws IOException;
 }
@@ -27,6 +27,13 @@ public interface SpiRawSqlService extends BootstrapService {
   */
  RawSqlBuilder unparsed(String sql);

+  /**
+   * SQL with ${where}/${having} placeholder(s) but no SELECT column parsing.
+   * Supports complex SQL (CTEs, window functions) where keyword parsing would fail.
+   * Explicit column mapping is required (as with unparsed).
+   */
+  RawSqlBuilder withPlaceholders(String sql);
+
  /**
   * Create based on a JDBC ResultSet.
   *
@@ -1,8 +1,7 @@
 package io.ebean.text.json;

-import com.fasterxml.jackson.core.JsonGenerator;
-import com.fasterxml.jackson.core.JsonParser;
-import com.fasterxml.jackson.core.JsonToken;
+import io.avaje.json.JsonReader;
+import io.avaje.json.JsonReader.Token;
 import io.ebean.XBootstrapService;
 import io.ebean.service.SpiJsonService;

@@ -38,14 +37,14 @@ public class EJson {
  /**
   * Write the nested Map/List as json to the jsonGenerator.
   */
-  public static void write(Object object, JsonGenerator jsonGenerator) throws IOException {
+  public static void write(Object object, io.avaje.json.JsonWriter jsonGenerator) throws IOException {
    plugin.write(object, jsonGenerator);
  }

  /**
   * Write the collection as json array to the jsonGenerator.
   */
-  public static void writeCollection(Collection<Object> collection, JsonGenerator jsonGenerator) throws IOException {
+  public static void writeCollection(Collection<Object> collection, io.avaje.json.JsonWriter jsonGenerator) throws IOException {
    plugin.writeCollection(collection, jsonGenerator);
  }

@@ -79,19 +78,19 @@ public class EJson {
  }

  /**
-   * Parse the json and return as a Map taking a JsonParser.
+   * Parse the json and return as a Map taking a JsonReader.
   */
-  public static Map<String, Object> parseObject(JsonParser parser) throws IOException {
+  public static Map<String, Object> parseObject(JsonReader parser) throws IOException {
    return plugin.parseObject(parser);
  }

  /**
-   * Parse the json and return as a Map taking a JsonParser and a starting token.
+   * Parse the json and return as a Map taking a JsonReader and a starting token.
   * <p>
   * Used when the first token is checked to see if the value is null prior to calling this.
   * </p>
   */
-  public static Map<String, Object> parseObject(JsonParser parser, JsonToken token) throws IOException {
+  public static Map<String, Object> parseObject(JsonReader parser, Token token) throws IOException {
    return plugin.parseObject(parser, token);
  }

@@ -117,16 +116,16 @@ public class EJson {
  }

  /**
-   * Parse the json and return as a List taking a JsonParser.
+   * Parse the json and return as a List taking a JsonReader.
   */
-  public static List<Object> parseList(JsonParser parser) throws IOException {
+  public static List<Object> parseList(JsonReader parser) throws IOException {
    return plugin.parseList(parser);
  }

  /**
   * Parse the json returning as a List taking into account the current token.
   */
-  public static <T> List<T> parseList(JsonParser parser, JsonToken currentToken) throws IOException {
+  public static <T> List<T> parseList(JsonReader parser, Token currentToken) throws IOException {
    return plugin.parseList(parser, currentToken);
  }

@@ -147,7 +146,7 @@ public class EJson {
  /**
   * Parse the json and return as a List or Map.
   */
-  public static Object parse(JsonParser parser) throws IOException {
+  public static Object parse(JsonReader parser) throws IOException {
    return plugin.parse(parser);
  }

@@ -161,7 +160,7 @@ public class EJson {
  /**
   * Parse the json returning as a Set taking into account the current token.
   */
-  public static <T> Set<T> parseSet(JsonParser parser, JsonToken currentToken) throws IOException {
+  public static <T> Set<T> parseSet(JsonReader parser, Token currentToken) throws IOException {
    return plugin.parseSet(parser, currentToken);
  }
 }
@@ -1,6 +1,6 @@
 package io.ebean.text.json;

-import com.fasterxml.jackson.core.JsonParser;
+import io.avaje.json.JsonReader;
 import io.ebean.bean.PersistenceContext;

 /**
@@ -25,9 +25,9 @@ public interface JsonBeanReader<T> {
  }
  
  /**
-   * Create a new reader taking the context from the existing one but using a new JsonParser.
+   * Create a new reader taking the context from the existing one but using a new JsonReader.
   */
-  JsonBeanReader<T> forJson(JsonParser moreJson);
+  JsonBeanReader<T> forJson(JsonReader moreJson);

  /**
   * Add a bean explicitly to the persistence context.
@@ -1,7 +1,6 @@
 package io.ebean.text.json;

-import com.fasterxml.jackson.core.JsonGenerator;
-import com.fasterxml.jackson.core.JsonParser;
+import io.avaje.json.JsonReader;
 import io.ebean.FetchPath;
 import io.ebean.plugin.BeanType;

@@ -49,14 +48,14 @@ public interface JsonContext {
   *
   * @throws JsonIOException When IOException occurs
   */
-  <T> T toBean(Class<T> cls, JsonParser parser) throws JsonIOException;
+  <T> T toBean(Class<T> cls, JsonReader parser) throws JsonIOException;

  /**
   * Convert json parser input into a Bean of a specific type additionally using JsonReadOptions..
   *
   * @throws JsonIOException When IOException occurs
   */
-  <T> T toBean(Class<T> cls, JsonParser parser, JsonReadOptions options) throws JsonIOException;
+  <T> T toBean(Class<T> cls, JsonReader parser, JsonReadOptions options) throws JsonIOException;

  /**
   * Read json parser input into a given Bean. <br>
@@ -65,19 +64,19 @@ public interface JsonContext {
   *
   * @throws JsonIOException When IOException occurs
   */
-  <T> void toBean(T target, JsonParser parser) throws JsonIOException;
+  <T> void toBean(T target, JsonReader parser) throws JsonIOException;

  /**
   * Read json parser input into a given Bean additionally using JsonReadOptions.<br>
-   * See {@link #toBean(Class, JsonParser)} for details modified.
+   * See {@link #toBean(Class, JsonReader)} for details modified.
   *
   * @throws JsonIOException When IOException occurs
   */
-  <T> void toBean(T target, JsonParser parser, JsonReadOptions options) throws JsonIOException;
+  <T> void toBean(T target, JsonReader parser, JsonReadOptions options) throws JsonIOException;

  /**
   * Read json reader input into a given Bean.<br>
-   * See {@link #toBean(Class, JsonParser)} for details
+   * See {@link #toBean(Class, JsonReader)} for details
   *
   * @throws JsonIOException When IOException occurs
   */
@@ -85,7 +84,7 @@ public interface JsonContext {

  /**
   * Read json reader input into a given Bean additionally using JsonReadOptions.<br>
-   * See {@link #toBean(Class, JsonParser)} for details modified.
+   * See {@link #toBean(Class, JsonReader)} for details modified.
   *
   * @throws JsonIOException When IOException occurs
   */
@@ -93,7 +92,7 @@ public interface JsonContext {

  /**
   * Read json string input into a given Bean.<br>
-   * See {@link #toBean(Class, JsonParser)} for details
+   * See {@link #toBean(Class, JsonReader)} for details
   *
   * @throws JsonIOException When IOException occurs
   */
@@ -101,7 +100,7 @@ public interface JsonContext {

  /**
   * Read json string input into a given Bean additionally using JsonReadOptions.<br>
-   * See {@link #toBean(Class, JsonParser)} for details
+   * See {@link #toBean(Class, JsonReader)} for details
   *
   * @throws JsonIOException When IOException occurs
   */
@@ -113,7 +112,7 @@ public interface JsonContext {
   * Note that JsonOption provides an option for setting a persistence context and also enabling further lazy loading. Further lazy
   * loading requires a persistence context so if that is set on then a persistence context is created if there is not one set.
   */
-  <T> JsonBeanReader<T> createBeanReader(Class<T> cls, JsonParser parser, JsonReadOptions options) throws JsonIOException;
+  <T> JsonBeanReader<T> createBeanReader(Class<T> cls, JsonReader parser, JsonReadOptions options) throws JsonIOException;

  /**
   * Create and return a new bean reading for the bean type given the JSON options and source.
@@ -122,7 +121,7 @@ public interface JsonContext {
   * further lazy loading. Further lazy loading requires a persistence context so if that is set
   * on then a persistence context is created if there is not one set.
   */
-  <T> JsonBeanReader<T> createBeanReader(BeanType<T> beanType, JsonParser parser, JsonReadOptions options) throws JsonIOException;
+  <T> JsonBeanReader<T> createBeanReader(BeanType<T> beanType, JsonReader parser, JsonReadOptions options) throws JsonIOException;

  /**
   * Convert json string input into a list of beans of a specific type.
@@ -157,14 +156,14 @@ public interface JsonContext {
   *
   * @throws JsonIOException When IOException occurs
   */
-  <T> List<T> toList(Class<T> cls, JsonParser json) throws JsonIOException;
+  <T> List<T> toList(Class<T> cls, JsonReader json) throws JsonIOException;

  /**
   * Convert json parser input into a list of beans of a specific type additionally using JsonReadOptions.
   *
   * @throws JsonIOException When IOException occurs
   */
-  <T> List<T> toList(Class<T> cls, JsonParser json, JsonReadOptions options) throws JsonIOException;
+  <T> List<T> toList(Class<T> cls, JsonReader json, JsonReadOptions options) throws JsonIOException;

  /**
   * Use the genericType to determine if this should be converted into a List or
@@ -188,7 +187,7 @@ public interface JsonContext {
   *
   * @throws JsonIOException When IOException occurs
   */
-  Object toObject(Type genericType, JsonParser jsonParser) throws JsonIOException;
+  Object toObject(Type genericType, JsonReader jsonParser) throws JsonIOException;

  /**
   * Return the bean or collection as JSON string.
@@ -212,11 +211,11 @@ public interface JsonContext {
  void toJson(Object value, Writer writer) throws JsonIOException;

  /**
-   * Write the bean or collection to the JsonGenerator.
+   * Write the bean or collection to the JsonWriter.
   *
   * @throws JsonIOException When IOException occurs
   */
-  void toJson(Object value, JsonGenerator generator) throws JsonIOException;
+  void toJson(Object value, io.avaje.json.JsonWriter generator) throws JsonIOException;

  /**
   * Return the bean or collection as JSON string using FetchPath.
@@ -231,15 +230,15 @@ public interface JsonContext {
  void toJson(Object value, Writer writer, FetchPath fetchPath) throws JsonIOException;

  /**
-   * Write the bean or collection to the JsonGenerator using the FetchPath.
+   * Write the bean or collection to the JsonWriter using the FetchPath.
   */
-  void toJson(Object value, JsonGenerator generator, FetchPath fetchPath) throws JsonIOException;
+  void toJson(Object value, io.avaje.json.JsonWriter generator, FetchPath fetchPath) throws JsonIOException;

  /**
   * Deprecated in favour of using PathProperties by itself.
-   * Write json to the JsonGenerator using the JsonWriteOptions.
+   * Write json to the JsonWriter using the JsonWriteOptions.
   */
-  void toJson(Object value, JsonGenerator generator, JsonWriteOptions options) throws JsonIOException;
+  void toJson(Object value, io.avaje.json.JsonWriter generator, JsonWriteOptions options) throws JsonIOException;

  /**
   * Deprecated in favour of using PathProperties by itself.
@@ -264,27 +263,27 @@ public interface JsonContext {
  boolean isSupportedType(Type genericType);

  /**
-   * Create and return a new JsonGenerator for the given writer.
+   * Create and return a new JsonWriter for the given writer.
   *
   * @throws JsonIOException When IOException occurs
   */
-  JsonGenerator createGenerator(Writer writer) throws JsonIOException;
+  io.avaje.json.JsonWriter createGenerator(Writer writer) throws JsonIOException;

  /**
-   * Create and return a new JsonParser for the given reader.
+   * Create and return a new JsonReader for the given reader.
   *
   * @throws JsonIOException When IOException occurs
   */
-  JsonParser createParser(Reader reader) throws JsonIOException;
+  JsonReader createParser(Reader reader) throws JsonIOException;

  /**
-   * Write a scalar types known to Ebean to Jackson.
+   * Write scalar types known to Ebean to JsonWriter.
   * <p>
   * Ebean has built in support for java8 and Joda types as well as the other
   * standard JDK types like URI, URL, UUID etc. This is a fast simple way to
-   * write any of those types to Jackson.
+   * write any of those types.
   * </p>
   */
-  void writeScalar(JsonGenerator generator, Object scalarValue) throws IOException;
+  void writeScalar(io.avaje.json.JsonWriter generator, Object scalarValue) throws IOException;

 }
@@ -1,19 +1,17 @@
 package io.ebean.text.json;

-import com.fasterxml.jackson.core.JsonGenerator;
-
 import java.io.InputStream;
 import java.math.BigDecimal;

 /**
- * Wraps an underlying JsonGenerator taking into account null suppression and exposing isIncludeEmpty() etc.
+ * Wraps an underlying JsonWriter taking into account null suppression and exposing isIncludeEmpty() etc.
 */
 public interface JsonWriter {

  /**
-   * Return the Jackson core JsonGenerator.
+   * Return the underlying JsonWriter.
   */
-  JsonGenerator gen();
+  io.avaje.json.JsonWriter gen();

  /**
   * Return true if null values should be included in JSON output.
@@ -8,6 +8,7 @@ module io.ebean.api {

  requires transitive java.sql;
  requires transitive io.avaje.config;
+  requires transitive io.avaje.json;
  requires transitive org.jspecify;
  requires transitive jakarta.persistence.api;
  requires transitive io.ebean.annotation;
@@ -16,7 +17,6 @@ module io.ebean.api {

  requires static org.slf4j;
  requires static io.ebean.types;
-  requires static com.fasterxml.jackson.core;
  requires static com.fasterxml.jackson.databind;

  exports io.ebean;
@@ -0,0 +1,432 @@
+package io.ebean.common;
+
+import io.ebean.bean.*;
+
+import java.util.*;
+
+/**
+ * Map capable of lazy loading and modification aware.
+ */
+public final class BeanMap<K, E> extends AbstractBeanCollection<E> implements SequencedMap<K, E> {
+
+  private static final long serialVersionUID = 1L;
+
+  /**
+   * The underlying map implementation.
+   */
+  private LinkedHashMap<K, E> map;
+
+  /**
+   * Create with a given Map.
+   */
+  public BeanMap(LinkedHashMap<K, E> map) {
+    this.map = map;
+  }
+
+  /**
+   * Create using a underlying LinkedHashMap.
+   */
+  public BeanMap() {
+    this(new LinkedHashMap<>());
+  }
+
+  public BeanMap(BeanCollectionLoader ebeanServer, EntityBean ownerBean, String propertyName) {
+    super(ebeanServer, ownerBean, propertyName);
+  }
+
+  @Override
+  public Map<K, E> freeze() {
+    return map == null ? null : Collections.unmodifiableMap(map);
+  }
+
+  @Override
+  public void toString(ToStringBuilder builder) {
+    if (map == null || map.isEmpty()) {
+      builder.addRaw("{}");
+    } else {
+      builder.addRaw("{");
+      for (Entry<K, E> entry : map.entrySet()) {
+        builder.add(String.valueOf(entry.getKey()), entry.getValue());
+      }
+      builder.addRaw("}");
+    }
+  }
+
+  @Override
+  public void reset(EntityBean ownerBean, String propertyName) {
+    this.ownerBean = ownerBean;
+    this.propertyName = propertyName;
+    this.map = null;
+  }
+
+  @Override
+  public boolean isSkipSave() {
+    return map == null || (map.isEmpty() && !holdsModifications());
+  }
+
+  @Override
+  @SuppressWarnings("unchecked")
+  public void loadFrom(BeanCollection<?> other) {
+    BeanMap<K, E> otherMap = (BeanMap<K, E>) other;
+    internalPutNull();
+    map.putAll(otherMap.actualMap());
+  }
+
+  public void internalPutNull() {
+    if (map == null) {
+      map = new LinkedHashMap<>();
+    }
+  }
+
+  @SuppressWarnings("unchecked")
+  public void internalPut(Object key, Object bean) {
+    if (map == null) {
+      map = new LinkedHashMap<>();
+    }
+    if (key != null) {
+      map.put((K) key, (E) bean);
+    }
+  }
+
+  public void internalPutWithCheck(Object key, Object bean) {
+    if (map == null || key == null || !map.containsKey(key)) {
+      internalPut(key, bean);
+    }
+  }
+
+  @Override
+  public void internalAddWithCheck(Object bean) {
+    throw new RuntimeException("Not allowed for map");
+  }
+
+  @Override
+  public void internalAdd(Object bean) {
+    throw new RuntimeException("Not allowed for map");
+  }
+
+  /**
+   * Return true if the underlying map has been populated. Returns false if it
+   * has a deferred fetch pending.
+   */
+  @Override
+  public boolean isPopulated() {
+    return map != null;
+  }
+
+  /**
+   * Return true if this is a reference (lazy loading) bean collection. This is
+   * the same as !isPopulated();
+   */
+  @Override
+  public boolean isReference() {
+    return map == null;
+  }
+
+  @Override
+  public boolean checkEmptyLazyLoad() {
+    if (map == null) {
+      map = new LinkedHashMap<>();
+      return true;
+    } else {
+      return false;
+    }
+  }
+
+  private void initClear() {
+    lock.lock();
+    try {
+      if (map == null) {
+        if (!disableLazyLoad && modifyListening) {
+          lazyLoadCollection(true);
+        } else {
+          map = new LinkedHashMap<>();
+        }
+      }
+    } finally {
+      lock.unlock();
+    }
+  }
+
+  private void init() {
+    lock.lock();
+    try {
+      if (map == null) {
+        if (disableLazyLoad) {
+          map = new LinkedHashMap<>();
+        } else {
+          lazyLoadCollection(false);
+        }
+      }
+    } finally {
+      lock.unlock();
+    }
+  }
+
+  public LinkedHashMap<K, E> collectionAdd() {
+    if (map == null) {
+      map = new LinkedHashMap<>();
+    }
+    return map;
+  }
+
+  @SuppressWarnings("unchecked")
+  public void refresh(ModifyListenMode modifyListenMode, BeanMap<?, ?> newMap) {
+    setModifyListening(modifyListenMode);
+    this.map = (LinkedHashMap<K, E>) newMap.actualMap();
+  }
+
+  /**
+   * Return the actual underlying map.
+   */
+  public LinkedHashMap<K, E> actualMap() {
+    return map;
+  }
+
+  /**
+   * Returns the collection of beans (map values).
+   */
+  @Override
+  public Collection<E> actualDetails() {
+    return map.values();
+  }
+
+  /**
+   * Returns the map entrySet.
+   */
+  @Override
+  public Collection<?> actualEntries() {
+    return map.entrySet();
+  }
+
+  @Override
+  public String toString() {
+    if (map == null) {
+      return "BeanMap<deferred>";
+    } else {
+      return map.toString();
+    }
+  }
+
+  /**
+   * Equal if object is a Map and equal in a Map sense.
+   */
+  @Override
+  public boolean equals(Object object) {
+    init();
+    return map.equals(object);
+  }
+
+  @Override
+  public int hashCode() {
+    init();
+    return map.hashCode();
+  }
+
+  @Override
+  public void clear() {
+    initClear();
+    if (modifyListening) {
+      // add all beans to the removal list
+      for (E bean : map.values()) {
+        modifyRemoval(bean);
+      }
+    }
+    map.clear();
+  }
+
+  @Override
+  public boolean containsKey(Object key) {
+    init();
+    return map.containsKey(key);
+  }
+
+  @Override
+  public boolean containsValue(Object value) {
+    init();
+    return map.containsValue(value);
+  }
+
+  @Override
+  public Set<Entry<K, E>> entrySet() {
+    init();
+    return modifyListening ? new ModifyEntrySet<>(this, map.entrySet()) : map.entrySet();
+  }
+
+  @Override
+  public E get(Object key) {
+    init();
+    return map.get(key);
+  }
+
+  @Override
+  public boolean isEmpty() {
+    init();
+    return map.isEmpty();
+  }
+
+  @Override
+  public Set<K> keySet() {
+    init();
+    return modifyListening ? new ModifyKeySet<>(this, map.keySet()) : map.keySet();
+  }
+
+  @Override
+  public E put(K key, E value) {
+    init();
+    if (modifyListening) {
+      E oldBean = map.put(key, value);
+      if (value != oldBean) {
+        // register the add of the new and the removal of the old
+        modifyAddition(value);
+        modifyRemoval(oldBean);
+      }
+      return oldBean;
+    } else {
+      return map.put(key, value);
+    }
+  }
+
+  @Override
+  public void putAll(Map<? extends K, ? extends E> puts) {
+    init();
+    if (modifyListening) {
+      for (Entry<? extends K, ? extends E> entry : puts.entrySet()) {
+        Object oldBean = map.put(entry.getKey(), entry.getValue());
+        if (entry.getValue() != oldBean) {
+          modifyAddition(entry.getValue());
+          modifyRemoval(oldBean);
+        }
+      }
+    } else {
+      map.putAll(puts);
+    }
+  }
+
+  @Override
+  public void addBean(E bean) {
+    throw new UnsupportedOperationException("Method not allowed on Map. Please use List instead.");
+  }
+
+  @Override
+  public void removeBean(E bean) {
+    throw new UnsupportedOperationException("Method not allowed on Map. Please use List instead.");
+  }
+
+  @Override
+  public E remove(Object key) {
+    init();
+    if (modifyListening) {
+      E o = map.remove(key);
+      modifyRemoval(o);
+      return o;
+    }
+    return map.remove(key);
+  }
+
+  @Override
+  public int size() {
+    init();
+    return map.size();
+  }
+
+  @Override
+  public Collection<E> values() {
+    init();
+    return modifyListening ? new ModifyCollection<>(this, map.values()) : map.values();
+  }
+
+  // -----------------------------------------------------//
+  // SequencedMap (Java 21+)
+  // -----------------------------------------------------//
+
+  @Override
+  public SequencedMap<K, E> reversed() {
+    init();
+    if (modifyListening) {
+      throw new UnsupportedOperationException("Not supported on modify listening map");
+    }
+    return map.reversed();
+  }
+
+  @Override
+  public Entry<K, E> firstEntry() {
+    init();
+    return map.firstEntry();
+  }
+
+  @Override
+  public Entry<K, E> lastEntry() {
+    init();
+    return map.lastEntry();
+  }
+
+  @Override
+  public Entry<K, E> pollFirstEntry() {
+    init();
+    Entry<K, E> entry = map.pollFirstEntry();
+    if (modifyListening && entry != null) {
+      modifyRemoval(entry.getValue());
+    }
+    return entry;
+  }
+
+  @Override
+  public Entry<K, E> pollLastEntry() {
+    init();
+    Entry<K, E> entry = map.pollLastEntry();
+    if (modifyListening && entry != null) {
+      modifyRemoval(entry.getValue());
+    }
+    return entry;
+  }
+
+  @Override
+  public E putFirst(K key, E value) {
+    init();
+    if (modifyListening) {
+      E oldBean = map.putFirst(key, value);
+      if (value != oldBean) {
+        // register the add of the new and the removal of the old
+        modifyAddition(value);
+        modifyRemoval(oldBean);
+      }
+      return oldBean;
+    } else {
+      return map.putFirst(key, value);
+    }
+  }
+
+  @Override
+  public E putLast(K key, E value) {
+    init();
+    if (modifyListening) {
+      E oldBean = map.putLast(key, value);
+      if (value != oldBean) {
+        // register the add of the new and the removal of the old
+        modifyAddition(value);
+        modifyRemoval(oldBean);
+      }
+      return oldBean;
+    } else {
+      return map.putLast(key, value);
+    }
+  }
+
+  @Override
+  public SequencedSet<K> sequencedKeySet() {
+    init();
+    return map.sequencedKeySet();
+  }
+
+  @Override
+  public SequencedCollection<E> sequencedValues() {
+    init();
+    return map.sequencedValues();
+  }
+
+  @Override
+  public SequencedSet<Entry<K, E>> sequencedEntrySet() {
+    init();
+    return map.sequencedEntrySet();
+  }
+}
@@ -0,0 +1,419 @@
+package io.ebean.common;
+
+import io.ebean.bean.*;
+
+import java.util.*;
+
+/**
+ * Set capable of lazy loading and modification aware.
+ */
+public final class BeanSet<E> extends AbstractBeanCollection<E> implements SequencedSet<E>, BeanCollectionAdd {
+
+  private static final long serialVersionUID = 1L;
+
+  /**
+   * The underlying Set implementation.
+   */
+  private LinkedHashSet<E> set;
+
+  /**
+   * Create with a specific Set implementation.
+   */
+  public BeanSet(LinkedHashSet<E> set) {
+    this.set = set;
+  }
+
+  /**
+   * Create using an underlying LinkedHashSet.
+   */
+  public BeanSet() {
+    this(new LinkedHashSet<>());
+  }
+
+  public BeanSet(BeanCollectionLoader loader, EntityBean ownerBean, String propertyName) {
+    super(loader, ownerBean, propertyName);
+  }
+
+  @Override
+  public Set<E> freeze() {
+    return set == null ? null : Collections.unmodifiableSet(set);
+  }
+
+  @Override
+  public void toString(ToStringBuilder builder) {
+    builder.addCollection(set);
+  }
+
+  @Override
+  public void reset(EntityBean ownerBean, String propertyName) {
+    this.ownerBean = ownerBean;
+    this.propertyName = propertyName;
+    this.set = null;
+  }
+
+  @Override
+  public boolean isSkipSave() {
+    return set == null || (set.isEmpty() && !holdsModifications());
+  }
+
+  @Override
+  @SuppressWarnings("unchecked")
+  public void addEntityBean(EntityBean bean) {
+    set.add((E) bean);
+  }
+
+  @Override
+  @SuppressWarnings("unchecked")
+  public void loadFrom(BeanCollection<?> other) {
+    if (set == null) {
+      set = new LinkedHashSet<>();
+    }
+    set.addAll((Collection<? extends E>) other.actualDetails());
+  }
+
+  @Override
+  public void internalAddWithCheck(Object bean) {
+    // set add() already de-dups so just add it
+    internalAdd(bean);
+  }
+
+  @Override
+  @SuppressWarnings("unchecked")
+  public void internalAdd(Object bean) {
+    if (set == null) {
+      set = new LinkedHashSet<>();
+    }
+    if (bean != null) {
+      set.add((E) bean);
+    }
+  }
+
+  /**
+   * Returns true if the underlying set has its data.
+   */
+  @Override
+  public boolean isPopulated() {
+    return set != null;
+  }
+
+  /**
+   * Return true if this is a reference (lazy loading) bean collection. This is
+   * the same as !isPopulated();
+   */
+  @Override
+  public boolean isReference() {
+    return set == null;
+  }
+
+  @Override
+  public boolean checkEmptyLazyLoad() {
+    if (set == null) {
+      set = new LinkedHashSet<>();
+      return true;
+    } else {
+      return false;
+    }
+  }
+
+  private void initClear() {
+    lock.lock();
+    try {
+      if (set == null) {
+        if (!disableLazyLoad && modifyListening) {
+          lazyLoadCollection(false);
+        } else {
+          set = new LinkedHashSet<>();
+        }
+      }
+    } finally {
+      lock.unlock();
+    }
+  }
+
+  private void init() {
+    lock.lock();
+    try {
+      if (set == null) {
+        if (disableLazyLoad) {
+          set = new LinkedHashSet<>();
+        } else {
+          lazyLoadCollection(false);
+        }
+      }
+    } finally {
+      lock.unlock();
+    }
+  }
+
+  public BeanCollectionAdd collectionAdd() {
+    if (set == null) {
+      set = new LinkedHashSet<>();
+    }
+    return this;
+  }
+
+  public void refresh(ModifyListenMode modifyListenMode, BeanSet<E> newSet) {
+    setModifyListening(modifyListenMode);
+    this.set = newSet.actualSet();
+  }
+
+  /**
+   * Return the actual underlying set.
+   */
+  public LinkedHashSet<E> actualSet() {
+    return set;
+  }
+
+  @Override
+  public Collection<E> actualDetails() {
+    return set;
+  }
+
+  @Override
+  public Collection<?> actualEntries() {
+    return set;
+  }
+
+  @Override
+  public String toString() {
+    if (set == null) {
+      return "BeanSet<deferred>";
+    } else {
+      return set.toString();
+    }
+  }
+
+  /**
+   * Equal if obj is a Set and equal in a Set sense.
+   */
+  @Override
+  public boolean equals(Object obj) {
+    init();
+    return set.equals(obj);
+  }
+
+  @Override
+  public int hashCode() {
+    init();
+    return set.hashCode();
+  }
+
+  @Override
+  public void addBean(E bean) {
+    add(bean);
+  }
+
+  @Override
+  public void removeBean(E bean) {
+    if (set.remove(bean)) {
+      getModifyHolder().modifyRemoval(bean);
+    }
+  }
+
+  // -----------------------------------------------------//
+  // proxy method for map
+  // -----------------------------------------------------//
+
+  @Override
+  public boolean add(E bean) {
+    init();
+    if (modifyListening) {
+      if (set.add(bean)) {
+        modifyAddition(bean);
+        return true;
+      } else {
+        return false;
+      }
+    }
+    return set.add(bean);
+  }
+
+  @Override
+  public boolean addAll(Collection<? extends E> beans) {
+    init();
+    if (modifyListening) {
+      boolean changed = false;
+      for (E bean : beans) {
+        if (set.add(bean)) {
+          // register the addition of the bean
+          modifyAddition(bean);
+          changed = true;
+        }
+      }
+      return changed;
+    }
+    return set.addAll(beans);
+  }
+
+  @Override
+  public void clear() {
+    initClear();
+    if (modifyListening) {
+      for (E bean : set) {
+        modifyRemoval(bean);
+      }
+    }
+    set.clear();
+  }
+
+  @Override
+  public boolean contains(Object bean) {
+    init();
+    return set.contains(bean);
+  }
+
+  @Override
+  public boolean containsAll(Collection<?> beans) {
+    init();
+    return set.containsAll(beans);
+  }
+
+  @Override
+  public boolean isEmpty() {
+    init();
+    return set.isEmpty();
+  }
+
+  @Override
+  public Iterator<E> iterator() {
+    init();
+    if (modifyListening) {
+      return new ModifyIterator<>(this, set.iterator());
+    }
+    return set.iterator();
+  }
+
+  @Override
+  public boolean remove(Object bean) {
+    init();
+    if (modifyListening) {
+      if (set.remove(bean)) {
+        modifyRemoval(bean);
+        return true;
+      }
+      return false;
+    }
+    return set.remove(bean);
+  }
+
+  @Override
+  public boolean removeAll(Collection<?> beans) {
+    init();
+    if (modifyListening) {
+      boolean changed = false;
+      for (Object bean : beans) {
+        if (set.remove(bean)) {
+          modifyRemoval(bean);
+          changed = true;
+        }
+      }
+      return changed;
+    }
+    return set.removeAll(beans);
+  }
+
+  @Override
+  public boolean retainAll(Collection<?> beans) {
+    init();
+    if (modifyListening) {
+      boolean changed = false;
+      Iterator<?> it = set.iterator();
+      while (it.hasNext()) {
+        Object bean = it.next();
+        if (!beans.contains(bean)) {
+          // not retaining this bean so add it to the removal list
+          it.remove();
+          modifyRemoval(bean);
+          changed = true;
+        }
+      }
+      return changed;
+    }
+    return set.retainAll(beans);
+  }
+
+  @Override
+  public int size() {
+    init();
+    return set.size();
+  }
+
+  @Override
+  public Object[] toArray() {
+    init();
+    return set.toArray();
+  }
+
+  @Override
+  public <T> T[] toArray(T[] array) {
+    init();
+    //noinspection SuspiciousToArrayCall
+    return set.toArray(array);
+  }
+
+  // -----------------------------------------------------//
+  // SequencedSet (Java 21+)
+  // -----------------------------------------------------//
+
+  @Override
+  public SequencedSet<E> reversed() {
+    init();
+    if (modifyListening) {
+      throw new UnsupportedOperationException("Not supported on modify listening set");
+    }
+    return set.reversed();
+  }
+
+  @Override
+  public void addFirst(E bean) {
+    init();
+    if (modifyListening) {
+      modifyAddition(bean);
+    }
+    set.addFirst(bean);
+  }
+
+  @Override
+  public void addLast(E bean) {
+    init();
+    if (modifyListening) {
+      modifyAddition(bean);
+    }
+    set.addLast(bean);
+  }
+
+  @Override
+  public E getFirst() {
+    init();
+    return set.getFirst();
+  }
+
+  @Override
+  public E getLast() {
+    init();
+    return set.getLast();
+  }
+
+  @Override
+  public E removeFirst() {
+    init();
+    if (modifyListening) {
+      E bean = set.removeFirst();
+      modifyRemoval(bean);
+      return bean;
+    }
+    return set.removeFirst();
+  }
+
+  @Override
+  public E removeLast() {
+    init();
+    if (modifyListening) {
+      E bean = set.removeLast();
+      modifyRemoval(bean);
+      return bean;
+    }
+    return set.removeLast();
+  }
+
+}
@@ -136,13 +136,13 @@ class ToStringBuilderTest {
  @Test
  void beanSet_null_empty() {
    assertThat(toStringFor(new BeanSet<String>(null))).isEqualTo("[]");
-    assertThat(toStringFor(new BeanSet<String>(Collections.emptySet()))).isEqualTo("[]");
+    assertThat(toStringFor(new BeanSet<String>(new LinkedHashSet<>()))).isEqualTo("[]");
  }

  @Test
  void beanMap_null_empty() {
    assertThat(toStringFor(new BeanMap<String, String>(null))).isEqualTo("{}");
-    assertThat(toStringFor(new BeanMap<String, String>(Collections.emptyMap()))).isEqualTo("{}");
+    assertThat(toStringFor(new BeanMap<String, String>(new LinkedHashMap<>()))).isEqualTo("{}");
  }

  @Test
@@ -159,7 +159,7 @@ class ToStringBuilderTest {

  @Test
  void beanMap_some() {
-    Map<String, Recurse> under = new LinkedHashMap<>();
+    var under = new LinkedHashMap<String, Recurse>();
    under.put("a", new Recurse(1, "a"));
    under.put("b", new Recurse(2, "b"));
    BeanMap<String, Recurse> list = new BeanMap<>(under);
@@ -0,0 +1,93 @@
+package io.ebean.meta;
+
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class MetricNamingV2Test {
+
+  private MetricNamingV2.Mapped map(String name, String beanType) {
+    return MetricNamingV2.map(name, beanType);
+  }
+
+  @Test
+  void orm_withBeanType() {
+    MetricNamingV2.Mapped m = map("orm.Customer.findList", "Customer");
+    assertThat(m.name()).isEqualTo("ebean.query");
+    assertThat(m.tags()).isEqualTo("kind:orm,label:Customer.findList,type:Customer");
+  }
+
+  @Test
+  void orm_withoutBeanType() {
+    MetricNamingV2.Mapped m = map("orm.Customer.findList", null);
+    assertThat(m.name()).isEqualTo("ebean.query");
+    assertThat(m.tags()).isEqualTo("kind:orm,label:Customer.findList");
+  }
+
+  @Test
+  void dto_andSql() {
+    assertThat(map("dto.CustomerDto.findRecent", "CustomerDto").tags())
+      .isEqualTo("kind:dto,label:CustomerDto.findRecent,type:CustomerDto");
+    assertThat(map("sql.query.fooBar", "Customer").tags())
+      .isEqualTo("kind:sql,label:query.fooBar,type:Customer");
+  }
+
+  @Test
+  void iud() {
+    MetricNamingV2.Mapped m = map("iud.User.save", null);
+    assertThat(m.name()).isEqualTo("ebean.dml");
+    assertThat(m.tags()).isEqualTo("label:User.save");
+  }
+
+  @Test
+  void txn_named_and_plain() {
+    assertThat(map("txn.named.ProcessJob", null).name()).isEqualTo("ebean.txn");
+    assertThat(map("txn.named.ProcessJob", null).tags()).isEqualTo("label:ProcessJob");
+    assertThat(map("txn.main", null).tags()).isEqualTo("label:main");
+  }
+
+  @Test
+  void l2_regionAndOp() {
+    MetricNamingV2.Mapped m = map("l2.customer.hit", null);
+    assertThat(m.name()).isEqualTo("ebean.l2");
+    assertThat(m.tags()).isEqualTo("op:hit,region:customer");
+  }
+
+  @Test
+  void l2_opOnly() {
+    assertThat(map("l2.hit", null).tags()).isEqualTo("op:hit");
+  }
+
+  @Test
+  void unrecognisedPrefix_isOther() {
+    MetricNamingV2.Mapped m = map("l2n.Customer.hit", null);
+    assertThat(m.name()).isEqualTo("ebean.other");
+    assertThat(m.tags()).isEqualTo("label:l2n.Customer.hit");
+  }
+
+  @Test
+  void noDot_isOther() {
+    assertThat(map("jvm", null).name()).isEqualTo("ebean.other");
+    assertThat(map("jvm", null).tags()).isEqualTo("label:jvm");
+  }
+
+  @Test
+  void nullOrEmpty() {
+    assertThat(map(null, null).name()).isEqualTo("ebean.other");
+    assertThat(map(null, null).tags()).isEmpty();
+    assertThat(map("", null).tags()).isEmpty();
+  }
+
+  @Test
+  void sanitisesReservedChars() {
+    MetricNamingV2.Mapped m = map("orm.Customer.weird", "Cust:om,er");
+    assertThat(m.tags()).isEqualTo("kind:orm,label:Customer.weird,type:Cust_om_er");
+  }
+
+  @Test
+  void tagsAreSortedByKey() {
+    // kind < label < type alphabetically regardless of build order
+    assertThat(map("orm.X.find", "Bean").tags())
+      .isEqualTo("kind:orm,label:X.find,type:Bean");
+  }
+}
@@ -0,0 +1,166 @@
+package io.ebean.meta;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class MetricsAsJsonV2Test {
+
+  @Test
+  void writeV2_usesFamilyNamesAndTags() {
+    ServerMetrics metrics = new FakeServerMetrics();
+    StringBuilder sb = new StringBuilder();
+    new MetricsAsJson(metrics).writeV2(sb);
+    String json = sb.toString();
+
+    assertThat(json).contains("\"db\":\"db1\"");
+    // query metric -> ebean.query with kind/type/label tags
+    assertThat(json).contains("\"name\":\"ebean.query\"");
+    assertThat(json).contains("\"tags\":\"kind:orm,label:Customer.findList,type:Customer\"");
+    // timed iud metric -> ebean.dml
+    assertThat(json).contains("\"name\":\"ebean.dml\"");
+    assertThat(json).contains("\"tags\":\"label:User.save\"");
+    // count metric (l2n not specially mapped) -> ebean.other
+    assertThat(json).contains("\"name\":\"ebean.other\"");
+    assertThat(json).contains("\"tags\":\"label:l2n.Customer.hit\"");
+  }
+
+  @Test
+  void write_v1_unchanged_usesFlatNames() {
+    ServerMetrics metrics = new FakeServerMetrics();
+    StringBuilder sb = new StringBuilder();
+    new MetricsAsJson(metrics).write(sb);
+    String json = sb.toString();
+
+    assertThat(json).contains("\"name\":\"orm.Customer.findList\"");
+    assertThat(json).contains("\"name\":\"iud.User.save\"");
+    assertThat(json).doesNotContain("\"tags\"");
+  }
+
+  static final class FakeServerMetrics implements ServerMetrics {
+    @Override
+    public String name() {
+      return "db1";
+    }
+
+    @Override
+    public ServerMetricsAsJson asJson() {
+      return new MetricsAsJson(this);
+    }
+
+    @Override
+    public List<MetricData> asData() {
+      return new java.util.ArrayList<>();
+    }
+
+    @Override
+    public List<MetaTimedMetric> timedMetrics() {
+      return new java.util.ArrayList<>(List.of(new FakeTimed("iud.User.save")));
+    }
+
+    @Override
+    public List<MetaQueryMetric> queryMetrics() {
+      return new java.util.ArrayList<>(List.of(new FakeQuery("orm.Customer.findList", Customer.class)));
+    }
+
+    @Override
+    public List<MetaCountMetric> countMetrics() {
+      return new java.util.ArrayList<>(List.of(new FakeCount("l2n.Customer.hit")));
+    }
+  }
+
+  static class Customer {
+  }
+
+  static class FakeTimed implements MetaTimedMetric {
+    private final String name;
+
+    FakeTimed(String name) {
+      this.name = name;
+    }
+
+    @Override
+    public String name() {
+      return name;
+    }
+
+    @Override
+    public String location() {
+      return null;
+    }
+
+    @Override
+    public long count() {
+      return 3;
+    }
+
+    @Override
+    public long total() {
+      return 30;
+    }
+
+    @Override
+    public long max() {
+      return 20;
+    }
+
+    @Override
+    public long mean() {
+      return 10;
+    }
+
+    @Override
+    public boolean initialCollection() {
+      return false;
+    }
+  }
+
+  static final class FakeQuery extends FakeTimed implements MetaQueryMetric {
+    private final Class<?> type;
+
+    FakeQuery(String name, Class<?> type) {
+      super(name);
+      this.type = type;
+    }
+
+    @Override
+    public Class<?> type() {
+      return type;
+    }
+
+    @Override
+    public String label() {
+      return null;
+    }
+
+    @Override
+    public String sql() {
+      return null;
+    }
+
+    @Override
+    public String hash() {
+      return "h1";
+    }
+  }
+
+  static final class FakeCount implements MetaCountMetric {
+    private final String name;
+
+    FakeCount(String name) {
+      this.name = name;
+    }
+
+    @Override
+    public String name() {
+      return name;
+    }
+
+    @Override
+    public long count() {
+      return 5;
+    }
+  }
+}
@@ -0,0 +1,113 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <parent>
+    <artifactId>ebean-parent</artifactId>
+    <groupId>io.ebean</groupId>
+    <version>18.4.0</version>
+  </parent>
+  <modelVersion>4.0.0</modelVersion>
+
+  <artifactId>ebean-avajejsonb-mapper</artifactId>
+  <name>ebean-avajejsonb-mapper</name>
+
+  <dependencies>
+    <dependency>
+      <groupId>io.ebean</groupId>
+      <artifactId>ebean-core-type</artifactId>
+      <version>18.4.0</version>
+      <scope>provided</scope>
+    </dependency>
+
+    <dependency>
+      <groupId>io.avaje</groupId>
+      <artifactId>avaje-json-core</artifactId>
+      <version>${avaje-json-core.version}</version>
+      <scope>provided</scope>
+    </dependency>
+
+    <dependency>
+      <groupId>io.avaje</groupId>
+      <artifactId>avaje-jsonb</artifactId>
+      <version>${avaje-jsonb.version}</version>
+    </dependency>
+
+    <dependency>
+      <groupId>io.avaje</groupId>
+      <artifactId>avaje-json-node</artifactId>
+      <version>${avaje-jsonb.version}</version>
+      <scope>test</scope>
+    </dependency>
+
+    <dependency>
+      <groupId>io.ebean</groupId>
+      <artifactId>ebean-core</artifactId>
+      <version>18.4.0</version>
+      <scope>test</scope>
+    </dependency>
+
+    <dependency>
+      <groupId>io.ebean</groupId>
+      <artifactId>ebean-platform-h2</artifactId>
+      <version>18.4.0</version>
+      <scope>test</scope>
+    </dependency>
+
+    <dependency>
+      <groupId>io.ebean</groupId>
+      <artifactId>ebean-datasource</artifactId>
+      <version>${ebean-datasource.version}</version>
+      <scope>test</scope>
+    </dependency>
+
+    <dependency>
+      <groupId>com.h2database</groupId>
+      <artifactId>h2</artifactId>
+      <version>${h2database.version}</version>
+      <scope>test</scope>
+    </dependency>
+
+    <dependency>
+      <groupId>io.ebean</groupId>
+      <artifactId>ebean-ddl-generator</artifactId>
+      <version>18.4.0</version>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
+
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-compiler-plugin</artifactId>
+        <configuration>
+          <annotationProcessorPaths>
+            <path>
+              <groupId>io.avaje</groupId>
+              <artifactId>avaje-jsonb-generator</artifactId>
+              <version>${avaje-jsonb.version}</version>
+            </path>
+          </annotationProcessorPaths>
+        </configuration>
+      </plugin>
+
+      <plugin>
+        <groupId>io.ebean</groupId>
+        <artifactId>ebean-maven-plugin</artifactId>
+        <version>${ebean-maven-plugin.version}</version>
+        <executions>
+          <execution>
+            <id>test</id>
+            <phase>process-test-classes</phase>
+            <configuration>
+              <packages>org/example/avajejsonb/**</packages>
+              <transformArgs>debug=0</transformArgs>
+            </configuration>
+            <goals>
+              <goal>testEnhance</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
+</project>
@@ -0,0 +1,223 @@
+package io.ebean.avajejsonb.mapper;
+
+import io.avaje.json.JsonReader;
+import io.avaje.json.JsonWriter;
+import io.avaje.jsonb.JsonType;
+import io.avaje.jsonb.Jsonb;
+import io.ebean.annotation.MutationDetection;
+import io.ebean.core.type.DataBinder;
+import io.ebean.core.type.DataReader;
+import io.ebean.core.type.DocPropertyType;
+import io.ebean.core.type.JsonTrim;
+import io.ebean.core.type.PostgresHelper;
+import io.ebean.core.type.ScalarJsonManager;
+import io.ebean.core.type.ScalarJsonMapper;
+import io.ebean.core.type.ScalarJsonRequest;
+import io.ebean.core.type.ScalarType;
+import io.ebean.core.type.ScalarTypeBase;
+import io.ebean.text.TextException;
+import jakarta.persistence.PersistenceException;
+
+import java.io.DataInput;
+import java.io.DataOutput;
+import java.io.IOException;
+import java.lang.annotation.Annotation;
+import java.lang.reflect.Field;
+import java.lang.reflect.Type;
+import java.sql.SQLException;
+import java.sql.Types;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * Supports {@code @DbJson} properties using Avaje Jsonb.
+ */
+public final class ScalarJsonAvajeJsonbMapper implements ScalarJsonMapper {
+
+  private final ConcurrentHashMap<Type, JsonType<Object>> jsonTypes = new ConcurrentHashMap<>();
+
+  @Override
+  public <A extends Annotation> Class<A> markerAnnotation() {
+    return null;
+  }
+
+  @Override
+  public ScalarType<?> createType(ScalarJsonRequest request) {
+    Type genericType = genericType(request);
+    JsonType<Object> jsonType = jsonTypes.computeIfAbsent(genericType, type -> jsonb(request.manager()).type(type));
+    if (request.mode() == MutationDetection.NONE) {
+      return new NoMutationDetection(request.manager(), jsonType, request.dbType(), request.docType());
+    }
+    return new GenericObject(request.manager(), jsonType, request.dbType(), request.docType());
+  }
+
+  private Jsonb jsonb(ScalarJsonManager manager) {
+    Object mapper = manager.mapper();
+    return mapper instanceof Jsonb ? (Jsonb) mapper : Jsonb.instance();
+  }
+
+  private Type genericType(ScalarJsonRequest request) {
+    Class<?> type = request.beanType();
+    while (type != null) {
+      try {
+        Field field = type.getDeclaredField(request.name());
+        return field.getGenericType();
+      } catch (NoSuchFieldException e) {
+        type = type.getSuperclass();
+      }
+    }
+    throw new IllegalStateException("Field not found to match " + request.name());
+  }
+
+  private static final class NoMutationDetection extends Base<Object> {
+
+    NoMutationDetection(ScalarJsonManager jsonManager, JsonType<Object> jsonType, int dbType, DocPropertyType docType) {
+      super(Object.class, jsonManager, jsonType, dbType, docType);
+    }
+  }
+
+  private static final class GenericObject extends Base<Object> {
+
+    private final boolean jsonb;
+
+    GenericObject(ScalarJsonManager jsonManager, JsonType<Object> jsonType, int dbType, DocPropertyType docType) {
+      super(Object.class, jsonManager, jsonType, dbType, docType);
+      this.jsonb = "jsonb".equals(pgType);
+    }
+
+    @Override
+    public boolean mutable() {
+      return true;
+    }
+
+    @Override
+    public boolean jsonMapper() {
+      return true;
+    }
+
+    @Override
+    public Object read(DataReader reader) throws SQLException {
+      String json = reader.getString();
+      if (jsonb) {
+        json = JsonTrim.trim(json);
+      }
+      reader.pushJson(json);
+      return parseJson(json);
+    }
+
+    @Override
+    public void bind(DataBinder binder, Object value) throws SQLException {
+      String rawJson = binder.popJson();
+      if (rawJson == null && value != null) {
+        rawJson = formatValue(value);
+      }
+      bindJson(binder, value, rawJson);
+    }
+  }
+
+  private static abstract class Base<T> extends ScalarTypeBase<T> {
+
+    private final JsonType<T> jsonType;
+    protected final String pgType;
+    private final DocPropertyType docType;
+
+    Base(Class<T> cls, ScalarJsonManager jsonManager, JsonType<T> jsonType, int dbType, DocPropertyType docType) {
+      super(cls, false, dbType);
+      this.jsonType = jsonType;
+      this.pgType = jsonManager.postgresType(dbType);
+      this.docType = docType;
+    }
+
+    @Override
+    public T read(DataReader reader) throws SQLException {
+      return parseJson(reader.getString());
+    }
+
+    @Override
+    public void bind(DataBinder binder, T value) throws SQLException {
+      bindJson(binder, value, value == null ? null : formatValue(value));
+    }
+
+    final T parseJson(String json) {
+      if (json == null || json.isEmpty()) {
+        return null;
+      }
+      try {
+        return jsonType.fromJson(json);
+      } catch (RuntimeException e) {
+        throw new TextException("Failed to parse JSON [{}] as " + jsonType, json, e);
+      }
+    }
+
+    final void bindJson(DataBinder binder, Object value, String rawJson) throws SQLException {
+      if (pgType != null) {
+        binder.setObject(PostgresHelper.asObject(pgType, rawJson));
+      } else if (value == null) {
+        binder.setNull(Types.VARCHAR);
+      } else {
+        binder.setString(rawJson);
+      }
+    }
+
+    @Override
+    public final Object toJdbcType(Object value) {
+      return value;
+    }
+
+    @Override
+    @SuppressWarnings("unchecked")
+    public final T toBeanType(Object value) {
+      return (T) value;
+    }
+
+    @Override
+    public final String formatValue(T value) {
+      try {
+        return jsonType.toJson(value);
+      } catch (RuntimeException e) {
+        throw new PersistenceException("Unable to create JSON", e);
+      }
+    }
+
+    @Override
+    public final T parse(String value) {
+      return parseJson(value);
+    }
+
+    @Override
+    public final DocPropertyType docType() {
+      return docType;
+    }
+
+    @Override
+    public final T jsonRead(JsonReader parser) {
+      if (parser.isNullValue()) {
+        return null;
+      }
+      return parseJson(parser.readRaw());
+    }
+
+    @Override
+    public final void jsonWrite(JsonWriter writer, T value) throws IOException {
+      if (value == null) {
+        writer.nullValue();
+      } else {
+        writer.rawValue(formatValue(value));
+      }
+    }
+
+    @Override
+    public final T readData(DataInput dataInput) throws IOException {
+      return dataInput.readBoolean() ? parse(dataInput.readUTF()) : null;
+    }
+
+    @Override
+    public final void writeData(DataOutput dataOutput, T value) throws IOException {
+      if (value == null) {
+        dataOutput.writeBoolean(false);
+      } else {
+        dataOutput.writeBoolean(true);
+        dataOutput.writeUTF(format(value));
+      }
+    }
+  }
+}
--- a/Show More
+++ b/Show More