Version 12.16.3

#3393 Fix for 12.x to support "NoTimeZone" to bypass MySQL JDBC use of Timezone Calendar

.github/workflows/build.yml

@@ -1,11 +1,7 @@
 
 name: Build
 
-on:
-  workflow_dispatch:
-  pull_request:
-  push:
-    branches: master
+on: [push, pull_request]
 
 jobs:
   build:
@@ -17,18 +13,18 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        java_version: [11]
+        java_version: [8]
         os: [ubuntu-latest]
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v2
     - name: Set up Java
-      uses: actions/setup-java@v4
+      uses: actions/setup-java@v2
       with:
         java-version: ${{ matrix.java_version }}
         distribution: 'zulu'
     - name: Maven cache
-      uses: actions/cache@v4
+      uses: actions/cache@v2
       env:
         cache-name: maven-cache
       with:
@@ -40,5 +36,5 @@ 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 clean package
 

.github/workflows/db2luw.yml

@@ -20,14 +20,14 @@ jobs:
         os: [ubuntu-latest]
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v2
     - name: Set up Java
-      uses: actions/setup-java@v4
+      uses: actions/setup-java@v2
       with:
         java-version: ${{ matrix.java_version }}
         distribution: 'adopt'
     - name: Maven cache
-      uses: actions/cache@v4
+      uses: actions/cache@v2
       env:
         cache-name: maven-cache
       with:
@@ -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 clean test -Dprops.file=testconfig/ebean-db2.properties

.github/workflows/h2database.yml

@@ -20,14 +20,14 @@ jobs:
         os: [ubuntu-latest]
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v2
     - name: Set up Java
-      uses: actions/setup-java@v4
+      uses: actions/setup-java@v2
       with:
         java-version: ${{ matrix.java_version }}
         distribution: 'zulu'
     - name: Maven cache
-      uses: actions/cache@v4
+      uses: actions/cache@v2
       env:
         cache-name: maven-cache
       with:
@@ -37,5 +37,5 @@ jobs:
     - name: Maven version
       run: mvn --version
     - name: H2Database
-      run: mvn -T 8 clean package
+      run: mvn clean package
 

.github/workflows/jdk-18-ea.yml

@@ -0,0 +1,39 @@
+
+name: JDK 18-ea
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '30 6 * * 1,3,5'
+
+jobs:
+  build:
+
+    runs-on: ${{ matrix.os }}
+    permissions:
+      contents: read
+      packages: write
+    strategy:
+      fail-fast: false
+      matrix:
+        java_version: [18-ea]
+        os: [ubuntu-latest]
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Java
+      uses: actions/setup-java@v2
+      with:
+        java-version: ${{ matrix.java_version }}
+        distribution: 'zulu'
+    - name: Maven cache
+      uses: actions/cache@v2
+      env:
+        cache-name: maven-cache
+      with:
+        path:
+          ~/.m2
+        key: build-${{ env.cache-name }}
+    - name: Build with Maven
+      run: mvn package
+

.github/workflows/jdk-ea.yml

@@ -16,26 +16,24 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        java_version: [GA,EA]
+        java_version: [17,18,19,loom,valhalla,metropolis,panama]
         os: [ubuntu-latest]
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v2
     - name: Set up Java
       uses: oracle-actions/setup-java@v1
       with:
         website: jdk.java.net
         release: ${{ matrix.java_version }}
     - name: Maven cache
-      uses: actions/cache@v4
+      uses: actions/cache@v2
       env:
         cache-name: maven-cache
       with:
         path:
           ~/.m2
         key: build-${{ env.cache-name }}
-    - name: Maven version
-      run: mvn --version
     - name: Build with Maven
-      run: mvn test -Pea
+      run: mvn package
 

.github/workflows/mariadb.yml

@@ -20,19 +20,19 @@ jobs:
         os: [ubuntu-latest]
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v2
     - name: Set up Java
-      uses: actions/setup-java@v4
+      uses: actions/setup-java@v2
       with:
         java-version: ${{ matrix.java_version }}
         distribution: 'adopt'
     - name: Maven cache
-      uses: actions/cache@v4
+      uses: actions/cache@v2
       env:
         cache-name: maven-cache
       with:
         path:
           ~/.m2
         key: build-${{ env.cache-name }}
-    - name: mariadb 10.11
-      run: mvn -T 8 clean test -Dprops.file=testconfig/ebean-mariadb.properties
+    - name: mariadb 10.6
+      run: mvn clean test -Dprops.file=testconfig/ebean-mariadb.properties

.github/workflows/multi-db-platform.yml

@@ -17,14 +17,14 @@ jobs:
         os: [ubuntu-latest]
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v2
     - name: Set up Java
-      uses: actions/setup-java@v4
+      uses: actions/setup-java@v2
       with:
         java-version: ${{ matrix.java_version }}
         distribution: 'adopt'
     - name: Maven cache
-      uses: actions/cache@v4
+      uses: actions/cache@v2
       env:
         cache-name: maven-cache
       with:

.github/workflows/multi-jdk-build.yml

@@ -16,26 +16,24 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        java_version: [11, 17, 21]
+        java_version: [8.0.192, 8, 11.0.3, 11, 17]
         os: [ubuntu-latest]
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v2
     - name: Set up Java
-      uses: actions/setup-java@v4
+      uses: actions/setup-java@v2
       with:
         java-version: ${{ matrix.java_version }}
         distribution: 'zulu'
     - name: Maven cache
-      uses: actions/cache@v4
+      uses: actions/cache@v2
       env:
         cache-name: maven-cache
       with:
         path:
           ~/.m2
         key: build-${{ env.cache-name }}
-    - name: Maven version
-      run: mvn --version
     - name: Build with Maven
       run: mvn package
 

.github/workflows/mysql.yml

@@ -20,14 +20,14 @@ jobs:
         os: [ubuntu-latest]
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v2
     - name: Set up Java
-      uses: actions/setup-java@v4
+      uses: actions/setup-java@v2
       with:
         java-version: ${{ matrix.java_version }}
         distribution: 'adopt'
     - name: Maven cache
-      uses: actions/cache@v4
+      uses: actions/cache@v2
       env:
         cache-name: maven-cache
       with:
@@ -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 clean test -Dprops.file=testconfig/ebean-mysql.properties

.github/workflows/oracle18.yml

@@ -1,5 +1,5 @@
 
-name: Oracle
+name: Oracle18
 
 on:
   workflow_dispatch:
@@ -20,14 +20,14 @@ jobs:
         os: [ubuntu-latest]
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v2
     - name: Set up Java
-      uses: actions/setup-java@v4
+      uses: actions/setup-java@v2
       with:
         java-version: ${{ matrix.java_version }}
         distribution: 'zulu'
     - name: Maven cache
-      uses: actions/cache@v4
+      uses: actions/cache@v2
       env:
         cache-name: maven-cache
       with:
@@ -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 clean test -Dprops.file=testconfig/ebean-oracle.properties

.github/workflows/postgres.yml

@@ -20,14 +20,14 @@ jobs:
         os: [ubuntu-latest]
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v2
     - name: Set up Java
-      uses: actions/setup-java@v4
+      uses: actions/setup-java@v2
       with:
         java-version: ${{ matrix.java_version }}
         distribution: 'adopt'
     - name: Maven cache
-      uses: actions/cache@v4
+      uses: actions/cache@v2
       env:
         cache-name: maven-cache
       with:
@@ -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 clean test -Dprops.file=testconfig/ebean-postgres.properties

.github/workflows/sqlserver-2019.yml

@@ -17,14 +17,14 @@ jobs:
         os: [ubuntu-latest]
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v2
     - name: Set up Java
-      uses: actions/setup-java@v4
+      uses: actions/setup-java@v2
       with:
         java-version: ${{ matrix.java_version }}
         distribution: 'adopt'
     - name: Maven cache
-      uses: actions/cache@v4
+      uses: actions/cache@v2
       env:
         cache-name: maven-cache
       with:

.github/workflows/sqlserver.yml

@@ -20,19 +20,19 @@ jobs:
         os: [ubuntu-latest]
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v2
     - name: Set up Java
-      uses: actions/setup-java@v4
+      uses: actions/setup-java@v2
       with:
         java-version: ${{ matrix.java_version }}
         distribution: 'adopt'
     - name: Maven cache
-      uses: actions/cache@v4
+      uses: actions/cache@v2
       env:
         cache-name: maven-cache
       with:
         path:
           ~/.m2
         key: build-${{ env.cache-name }}
-    - name: sqlserver 2022
-      run: mvn -T 8 clean test -Dprops.file=testconfig/ebean-sqlserver.properties
+    - name: sqlserver 2017
+      run: mvn clean test -Dprops.file=testconfig/ebean-sqlserver17.properties

.github/workflows/valhalla.yml

@@ -1,41 +0,0 @@
-name: Valhalla EA
-
-on:
-  workflow_dispatch:
-  schedule:
-    - cron: '39 2 * * 3'
-
-jobs:
-  build:
-
-    runs-on: ${{ matrix.os }}
-    permissions:
-      contents: read
-      packages: write
-    strategy:
-      fail-fast: false
-      matrix:
-        java_version: [valhalla]
-        os: [ubuntu-latest]
-
-    steps:
-      - uses: actions/checkout@v4
-      - name: Set up Java
-        uses: oracle-actions/setup-java@v1
-        with:
-          website: jdk.java.net
-          release: ${{ matrix.java_version }}
-      - name: Maven cache
-        uses: actions/cache@v4
-        env:
-          cache-name: maven-cache
-        with:
-          path:
-            ~/.m2
-          key: build-${{ env.cache-name }}
-      - name: Maven version
-        run: mvn --version
-#      - name: Prepare
-#        run: ./jakarta-to-valhalla.sh
-      - name: Build with Maven
-        run: mvn package

.github/workflows/yugabyte.yml

@@ -4,7 +4,7 @@ name: Yugabyte
 on:
   workflow_dispatch:
   schedule:
-    - cron: '10 3 * * 3'
+    - cron: '10 3 * * *'
 
 jobs:
   build:
@@ -20,14 +20,14 @@ jobs:
         os: [ubuntu-latest]
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v2
     - name: Set up Java
-      uses: actions/setup-java@v4
+      uses: actions/setup-java@v2
       with:
         java-version: ${{ matrix.java_version }}
         distribution: 'adopt'
     - name: Maven cache
-      uses: actions/cache@v4
+      uses: actions/cache@v2
       env:
         cache-name: maven-cache
       with:

.gitignore

@@ -11,7 +11,6 @@ ebean-profiling*.xml
 /db
 /mydb.db
 profiling/
-.DS_Store
 
 # Intellij project files
 *.iml

CONFIGURATION.md

@@ -4,13 +4,13 @@ Overview of ebean.properties file
 
 ### DbMigration options
 
-You can set individual values for different platforms when generating migrations.
+You can set individual values for different platforms when generating migrations
 
 `dbmigration.platform.<PLATFORM>.databaseSequenceBatchSize`
 For DB's using sequences this is the number of sequence values prefetched.
  
 `dbmigration.platform.<PLATFORM>.dbuuid`
-Control, how UUID generation should work - it affects which column type is generated in DDL. Possible values:
+Control, how UUID generation should work - it affects DDL which column type is generated. Possible values:
 - BINARY enforces binary UUID 
 - VARCHAR enforces varchar UUID
 - BINARY_OPTIMIZED enforces binary-optimized UUID (makes sense only with Type1 ID)
@@ -19,7 +19,7 @@ Control, how UUID generation should work - it affects which column type is gener
 - AUTO_VARCHAR (default) use varchar when platform does not support UUID 
 
 `dbmigration.platform.<PLATFORM>.uuidStoreAsBinary`
-Same as setting dbuuid to BINARY.
+Same as setting dbuuid to BINARY
 
 `dbmigration.platform.<PLATFORM>.geometrySRID`
 The Geometry SRID value (default 4326).
@@ -30,6 +30,7 @@ The ID type (IDENTITY, SEQUENCE, GENERATOR, EXTERNAL)
 `dbmigration.platform.<PLATFORM>.mapping`
 Adjust the mapping. For example `BOOLEAN=integer(32);BIT=tinyint(3)`
 
+
 `ebean.migration.applyPrefix`
 Set this to "V" to be compatible with FlywayDB.
 
@@ -49,7 +50,7 @@ Set to true if the DB migration should be generated on server start.
 The version of a pending drop that should be generated as the next migration.
 
 `ebean.migration.includeGeneratedFileComment`
-Adds the header about the migration files being generated when true. Reading 'THIS IS A GENERATED FILE - DO NOT MODIFY'
+TODO
 
 `ebean.migration.metaTable`
 For running migration the DB table that holds migration execution status. Default 'db_migration'
@@ -64,17 +65,17 @@ Subdirectory the model xml files go into. Default 'model'
 Suffix. Default '.model.xml' 
 
 `ebean.migration.name`
-Description text that can be appended to the version to become the ddl script file name.
+Description text that can be appended to the version to become the ddl script file name
  
 `ebean.migration.patchInsertOn`
-Migration versions that should be added to history without running.
+migration versions that should be added to history without running.
 
 `ebean.migration.patchResetChecksumOn`
 migration versions that should have their checksum reset and not run.
 Use this if you get a 'Checksum mismatch' error.
 
 `ebean.migration.placeholders`
-A comma and equals delimited map of placeholders that are substituted in SQL scripts when running migration (used by DB Migration runner only).
+A comma and equals delimited placeholders that are substituted in SQL scripts when running migration (used by DB Migration runner only).
 
 `ebean.migration.platform`
 The database platform to generate migration DDL for.
@@ -89,7 +90,7 @@ The migration version name (typically FlywayDb compatible). Example: 1.1.1_2
 ### Ebean UUID options
 
 `ebean.uuidVersion`
-Controls how the UUIDs are generated. Possible values:
+Controls, how the UUIDs are generated. Possible values
 - VERSION4 (default) generate random V4 UUIDs,
 - VERSION1 generate rfc4122 compliant Type 1 UUIDs (requires a state file)
 - VERSION1RND generate fake Type 1 UUIDs
@@ -97,7 +98,7 @@ Controls how the UUIDs are generated. Possible values:
 Note, that V1 UUIDs in conjunction with AUTO_BINARY_OPTIMIZED will give you the best index performance, but you MUST understand how this works to avoid collisions.
 
 `ebean.uuidStateFile`
-The state file that is required to generate V1 UUIDs.
+The state file that is Required to generate V1 UUIDs
 
 
 ### DocStoreConfig
@@ -106,7 +107,7 @@ The state file that is required to generate V1 UUIDs.
 True when the Document store integration is active/on.
 
 `ebean.docstore.allowAllCertificates`
-Set to true such that the client allows connections to invalid/self-signed SSL certificates.
+Set to true such that the client allows connections to invalid/self signed SSL certificates.
 
 `ebean.docstore.bulkBatchSize`
 The default batch size to use for the Bulk API calls.
@@ -191,7 +192,7 @@ Suffix appended to the base table to derive the view that contains the union of
 Set to true if the DataSource uses autoCommit. Indicates that Ebean should use autoCommit friendly Transactions and TransactionManager.
 
 `ebean.autoReadOnlyDataSource`
-When true create a read only DataSource using readOnlyDataSourceConfig defaulting values from dataSourceConfig.
+When true create a read only DataSource using readOnlyDataSourceConfig defaulting values from dataSourceConfig
 
 `ebean.autostart`
 Should the server start all

README.md

@@ -1,63 +1,37 @@
-
 [![Build](https://github.com/ebean-orm/ebean/actions/workflows/build.yml/badge.svg)](https://github.com/ebean-orm/ebean/actions/workflows/build.yml)
 [![Maven Central : ebean](https://maven-badges.herokuapp.com/maven-central/io.ebean/ebean/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.ebean/ebean)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/ebean-orm/ebean/blob/master/LICENSE)
 [![Multi-JDK Build](https://github.com/ebean-orm/ebean/actions/workflows/multi-jdk-build.yml/badge.svg)](https://github.com/ebean-orm/ebean/actions/workflows/multi-jdk-build.yml)
-[![GraalVM Native Image](https://img.shields.io/badge/GraalVM-Native%20Image%20Ready-darkgreen?logo=graalvm)](https://www.graalvm.org/)
+[![JDK 18-ea](https://github.com/ebean-orm/ebean/actions/workflows/jdk-18-ea.yml/badge.svg)](https://github.com/ebean-orm/ebean/actions/workflows/jdk-18-ea.yml)
 
-##### Build with database platforms
 [![H2Database](https://github.com/ebean-orm/ebean/actions/workflows/h2database.yml/badge.svg)](https://github.com/ebean-orm/ebean/actions/workflows/h2database.yml)
 [![Postgres](https://github.com/ebean-orm/ebean/actions/workflows/postgres.yml/badge.svg)](https://github.com/ebean-orm/ebean/actions/workflows/postgres.yml)
 [![MySql](https://github.com/ebean-orm/ebean/actions/workflows/mysql.yml/badge.svg)](https://github.com/ebean-orm/ebean/actions/workflows/mysql.yml)
 [![MariaDB](https://github.com/ebean-orm/ebean/actions/workflows/mariadb.yml/badge.svg)](https://github.com/ebean-orm/ebean/actions/workflows/mariadb.yml)
-[![Oracle](https://github.com/ebean-orm/ebean/actions/workflows/oracle.yml/badge.svg)](https://github.com/ebean-orm/ebean/actions/workflows/oracle.yml)
 [![SqlServer](https://github.com/ebean-orm/ebean/actions/workflows/sqlserver.yml/badge.svg)](https://github.com/ebean-orm/ebean/actions/workflows/sqlserver.yml)
-[![DB2 LUW](https://github.com/ebean-orm/ebean/actions/workflows/db2luw.yml/badge.svg)](https://github.com/ebean-orm/ebean/actions/workflows/db2luw.yml)
 [![Yugabyte](https://github.com/ebean-orm/ebean/actions/workflows/yugabyte.yml/badge.svg)](https://github.com/ebean-orm/ebean/actions/workflows/yugabyte.yml)
 
-##### Build with Java Early Access versions
+
+#### Builds against EA (Early Access) versions of Java (19, Loom, panama etc)
+
 [![ebean EA](https://github.com/ebean-orm/ebean/actions/workflows/jdk-ea.yml/badge.svg)](https://github.com/ebean-orm/ebean/actions/workflows/jdk-ea.yml)
 [![datasource EA](https://github.com/ebean-orm/ebean-datasource/actions/workflows/jdk-ea.yml/badge.svg)](https://github.com/ebean-orm/ebean-datasource/actions/workflows/jdk-ea.yml)
 [![migration EA](https://github.com/ebean-orm/ebean-migration/actions/workflows/jdk-ea.yml/badge.svg)](https://github.com/ebean-orm/ebean-migration/actions/workflows/jdk-ea.yml)
 [![test-docker EA](https://github.com/ebean-orm/ebean-test-docker/actions/workflows/jdk-ea.yml/badge.svg)](https://github.com/ebean-orm/ebean-test-docker/actions/workflows/jdk-ea.yml)
-[![ebean-agent EA](https://github.com/ebean-orm/ebean-agent/actions/workflows/jdk-ea.yml/badge.svg)](https://github.com/ebean-orm/ebean-agent/actions/workflows/jdk-ea.yml)
-
-----------------------
-
-# Ebean ORM for Java & Kotlin
-
-**Multiple abstraction levels**: Ebean provides multiple levels of query abstraction [ORM Queries, mixed with SQL](https://ebean.io/docs/intro/queries/orm-query), [DTO Queries](https://ebean.io/docs/intro/queries/dto-query), [SqlQuery and JDBC](https://ebean.io/docs/intro/queries/sql-query).
-Work at the highest level of abstraction and drop down levels as needed.
-
-**Database migrations**: Built in [DB migration](https://ebean.io/docs/db-migrations/) generation and running. Support for "rebase" migrations as well as repeatable, init and 'normal' migrations.
-
-**Awesome SQL**: Ebean produces SQL that you would hand craft yourself. Use great SQL, never generate SQL cartesian product, always honor relational limit/offset.
-
-**Automated query tuning**: For ORM queries Ebean can profile the object graph being used and either [automatically tune the query](https://ebean.io/docs/query/background/autotune).
-
-**Docker test containers**: [Docker test containers](https://ebean.io/docs/testing/) for all the supported databases. Get 100% test coverage on all the features of the database we use.
-
-**Type safe queries**: We can build queries using type safe [query beans](https://ebean.io/docs/query/query-beans). IDE auto-complete when writing queries, compile time checking and it's FUN.
-
-**Performance isn't optional**: Optimise queries to only fetch what we need (partial objects). Automatically avoid N+1 via a smart load context.
-
-#### Benefits of ORM
-
-* Automatically avoid N+1
-* L2 caching to reduce database load
-* Queries mixing database and L2 cache
-* Automatically tune ORM queries
-* Elasticsearch for search or L3 cache
 
 
-----------------------
 # Sponsors
 <table>
   <tbody>
     <tr>
       <td align="center" valign="middle">
         <a href="https://www.foconis.de/" target="_blank">
-          <img width="222px" src="https://group.foconis.com/download/ci/logo/png-72dpi/logo-quer/foconis-analytics-quer.png">
+          <img width="222px" src="https://www.foconis.de/templates/yootheme/cache/foconis_logo_322-709da1de.png">
+        </a>
+      </td>
+      <td align="center" valign="middle">
+        <a href="https://www.payintech.com/" target="_blank">
+          <img width="222px" src="https://ebean.io/images/sponsor_PayinTech-logo-noir.png">
         </a>
       </td>
       <td align="center" valign="middle">
@@ -75,57 +49,14 @@ Work at the highest level of abstraction and drop down levels as needed.
 </table>
 
 ## Need help?
-Post questions or issues to the [Ebean google group](https://groups.google.com/forum/#!forum/ebean)
-or [github discussions](https://github.com/ebean-orm/ebean/discussions)
+Post questions or issues to the Ebean google group - https://groups.google.com/forum/#!forum/ebean
 
 ## Documentation
 Goto [https://ebean.io/docs/](https://ebean.io/docs/)
 
-## Guides
-Library reference (capabilities, scope, and AI guidance): [docs/LIBRARY.md](docs/LIBRARY.md)
-
-Step-by-step guides for common tasks: [docs/guides/](docs/guides/README.md)
-
-Available guides:
-- [Maven POM setup](docs/guides/add-ebean-postgres-maven-pom.md)
-- [Database configuration](docs/guides/add-ebean-postgres-database-config.md)
-- [Test container setup](docs/guides/add-ebean-postgres-test-container.md)
-- [DB migration generation](docs/guides/add-ebean-db-migration-generation.md)
-- [Lombok with Ebean entity beans](docs/guides/lombok-with-ebean-entity-beans.md)
 
 ## Maven central
-[Maven central - g:io.ebean](http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22io.ebean%22%20)
-
-## Building Ebean from source
-
-- JDK 11 or higher installed
-- Maven installed
-- `git clone git@github.com:ebean-orm/ebean.git`
-- `mvn clean install`
-
-Ebean 13 uses Java modules with module-info. This means that there are stricter compilation
-rules in place now than when building with classpath pre version 13.
-
-For Maven Surefire testing we use `<surefire.useModulePath>false</surefire.useModulePath>` such
-that tests run using classpath and not module-path. We are doing this until all the tooling
-(Maven, IDE) improves in the area of testing with module-info.
-
-#### Eclipse IDE
-
-Right now we can't use Eclipse IDE to build Ebean and run its tests due to its poor support
-for java modules. See [ebean/issues/2653](https://github.com/ebean-orm/ebean/issues/2653)
-
-The current recommendation is to use IntelliJ IDEA as the IDE to build and hack Ebean.
+[Maven central - io.ebean](http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22io.ebean%22%20)
 
 
-#### IntelliJ IDEA
 
-We want to get IntelliJ to run tests using classpath similar to Maven Surefire. To do this set:
-`JUnit -> modify options -> Do not use module-path option`
-
-To set this option as the global default for IntelliJ use:
-
-`Run - Edit Configurations -> Edit configuration templates -> JUnit -> modify options - Do not use module-path option`
-
-
-end

composites/ebean-clickhouse/pom.xml

@@ -1,55 +0,0 @@
-<?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">
-  <modelVersion>4.0.0</modelVersion>
-  <parent>
-    <artifactId>ebean-parent</artifactId>
-    <groupId>io.ebean</groupId>
-    <version>16.6.0</version>
-    <relativePath>../..</relativePath>
-  </parent>
-
-  <name>ebean-clickhouse</name>
-  <description>ebean-clickhouse composite</description>
-  <artifactId>ebean-clickhouse</artifactId>
-
-  <dependencies>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-api</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-core</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-datasource</artifactId>
-      <version>${ebean-datasource.version}</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-migration</artifactId>
-      <version>${ebean-migration.version}</version>
-    </dependency>
-
-    <!-- Technically optional but most expected to use query beans -->
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-querybean</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-platform-clickhouse</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-  </dependencies>
-</project>

composites/ebean-clickhouse/src/main/java/io/ebean/clickhouse/assembly/Assembly.java

@@ -1,7 +0,0 @@
-package io.ebean.clickhouse.assembly;
-
-/**
- * Nothing interesting here - required placeholder for javadoc.
- */
-public class Assembly {
-}

composites/ebean-clickhouse/src/main/java/module-info.java

@@ -1,9 +0,0 @@
-module io.ebean.clickhouse {
-
-  requires transitive io.ebean.api;
-  requires transitive io.ebean.core;
-  requires transitive io.ebean.datasource;
-  requires transitive io.ebean.querybean;
-  requires transitive io.ebean.platform.clickhouse;
-
-}

composites/ebean-cockroach/src/main/java/io/ebean/cockroach/assembly/Assembly.java

@@ -1,7 +0,0 @@
-package io.ebean.cockroach.assembly;
-
-/**
- * Nothing interesting here - required placeholder for javadoc.
- */
-public class Assembly {
-}

composites/ebean-cockroach/src/main/java/module-info.java

@@ -1,9 +0,0 @@
-module io.ebean.cockroach {
-
-  requires transitive io.ebean.api;
-  requires transitive io.ebean.core;
-  requires transitive io.ebean.datasource;
-  requires transitive io.ebean.querybean;
-  requires transitive io.ebean.platform.postgres;
-
-}

composites/ebean-db2/pom.xml

@@ -1,55 +0,0 @@
-<?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">
-  <modelVersion>4.0.0</modelVersion>
-  <parent>
-    <artifactId>ebean-parent</artifactId>
-    <groupId>io.ebean</groupId>
-    <version>16.6.0</version>
-    <relativePath>../..</relativePath>
-  </parent>
-
-  <name>ebean-db2</name>
-  <description>ebean-db2 composite</description>
-  <artifactId>ebean-db2</artifactId>
-
-  <dependencies>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-api</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-core</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-datasource</artifactId>
-      <version>${ebean-datasource.version}</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-migration</artifactId>
-      <version>${ebean-migration.version}</version>
-    </dependency>
-
-    <!-- Technically optional but most expected to use query beans -->
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-querybean</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-platform-db2</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-  </dependencies>
-</project>

composites/ebean-db2/src/main/java/io/ebean/db2/assembly/Assembly.java

@@ -1,7 +0,0 @@
-package io.ebean.db2.assembly;
-
-/**
- * Nothing interesting here - required placeholder for javadoc.
- */
-public class Assembly {
-}

composites/ebean-db2/src/main/java/module-info.java

@@ -1,9 +0,0 @@
-module io.ebean.db2 {
-
-  requires transitive io.ebean.api;
-  requires transitive io.ebean.core;
-  requires transitive io.ebean.datasource;
-  requires transitive io.ebean.querybean;
-  requires transitive io.ebean.platform.db2;
-
-}

composites/ebean-h2/pom.xml

@@ -1,55 +0,0 @@
-<?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">
-  <modelVersion>4.0.0</modelVersion>
-  <parent>
-    <artifactId>ebean-parent</artifactId>
-    <groupId>io.ebean</groupId>
-    <version>16.6.0</version>
-    <relativePath>../..</relativePath>
-  </parent>
-
-  <name>ebean-h2</name>
-  <description>ebean-h2 composite</description>
-  <artifactId>ebean-h2</artifactId>
-
-  <dependencies>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-api</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-core</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-datasource</artifactId>
-      <version>${ebean-datasource.version}</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-migration</artifactId>
-      <version>${ebean-migration.version}</version>
-    </dependency>
-
-    <!-- Technically optional but most expected to use query beans -->
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-querybean</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-platform-h2</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-  </dependencies>
-</project>

composites/ebean-h2/src/main/java/io/ebean/h2/assembly/Assembly.java

@@ -1,7 +0,0 @@
-package io.ebean.h2.assembly;
-
-/**
- * Nothing interesting here - required placeholder for javadoc.
- */
-public class Assembly {
-}

composites/ebean-h2/src/main/java/module-info.java

@@ -1,9 +0,0 @@
-module io.ebean.h2 {
-
-  requires transitive io.ebean.api;
-  requires transitive io.ebean.core;
-  requires transitive io.ebean.datasource;
-  requires transitive io.ebean.querybean;
-  requires transitive io.ebean.platform.h2;
-
-}

composites/ebean-hana/pom.xml

@@ -1,55 +0,0 @@
-<?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">
-  <modelVersion>4.0.0</modelVersion>
-  <parent>
-    <artifactId>ebean-parent</artifactId>
-    <groupId>io.ebean</groupId>
-    <version>16.6.0</version>
-    <relativePath>../..</relativePath>
-  </parent>
-
-  <name>ebean-hana</name>
-  <description>ebean-hana composite</description>
-  <artifactId>ebean-hana</artifactId>
-
-  <dependencies>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-api</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-core</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-datasource</artifactId>
-      <version>${ebean-datasource.version}</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-migration</artifactId>
-      <version>${ebean-migration.version}</version>
-    </dependency>
-
-    <!-- Technically optional but most expected to use query beans -->
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-querybean</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-platform-hana</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-  </dependencies>
-</project>

composites/ebean-hana/src/main/java/io/ebean/hana/assembly/Assembly.java

@@ -1,7 +0,0 @@
-package io.ebean.hana.assembly;
-
-/**
- * Nothing interesting here - required placeholder for javadoc.
- */
-public class Assembly {
-}

composites/ebean-hana/src/main/java/module-info.java

@@ -1,9 +0,0 @@
-module io.ebean.hana {
-
-  requires transitive io.ebean.api;
-  requires transitive io.ebean.core;
-  requires transitive io.ebean.datasource;
-  requires transitive io.ebean.querybean;
-  requires transitive io.ebean.platform.hana;
-
-}

composites/ebean-mariadb/pom.xml

@@ -1,55 +0,0 @@
-<?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">
-  <modelVersion>4.0.0</modelVersion>
-  <parent>
-    <artifactId>ebean-parent</artifactId>
-    <groupId>io.ebean</groupId>
-    <version>16.6.0</version>
-    <relativePath>../..</relativePath>
-  </parent>
-
-  <name>ebean-mariadb</name>
-  <description>ebean-mariadb composite</description>
-  <artifactId>ebean-mariadb</artifactId>
-
-  <dependencies>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-api</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-core</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-datasource</artifactId>
-      <version>${ebean-datasource.version}</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-migration</artifactId>
-      <version>${ebean-migration.version}</version>
-    </dependency>
-
-    <!-- Technically optional but most expected to use query beans -->
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-querybean</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-platform-mariadb</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-  </dependencies>
-</project>

composites/ebean-mariadb/src/main/java/io/ebean/mariadb/assembly/Assembly.java

@@ -1,7 +0,0 @@
-package io.ebean.mariadb.assembly;
-
-/**
- * Nothing interesting here - required placeholder for javadoc.
- */
-public class Assembly {
-}

composites/ebean-mariadb/src/main/java/module-info.java

@@ -1,9 +0,0 @@
-module io.ebean.mariadb {
-
-  requires transitive io.ebean.api;
-  requires transitive io.ebean.core;
-  requires transitive io.ebean.datasource;
-  requires transitive io.ebean.querybean;
-  requires transitive io.ebean.platform.mariadb;
-
-}

composites/ebean-mysql/pom.xml

@@ -1,55 +0,0 @@
-<?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">
-  <modelVersion>4.0.0</modelVersion>
-  <parent>
-    <artifactId>ebean-parent</artifactId>
-    <groupId>io.ebean</groupId>
-    <version>16.6.0</version>
-    <relativePath>../..</relativePath>
-  </parent>
-
-  <name>ebean-mysql</name>
-  <description>ebean-mysql composite</description>
-  <artifactId>ebean-mysql</artifactId>
-
-  <dependencies>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-api</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-core</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-datasource</artifactId>
-      <version>${ebean-datasource.version}</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-migration</artifactId>
-      <version>${ebean-migration.version}</version>
-    </dependency>
-
-    <!-- Technically optional but most expected to use query beans -->
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-querybean</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-platform-mysql</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-  </dependencies>
-</project>

composites/ebean-mysql/src/main/java/io/ebean/mysql/assembly/Assembly.java

@@ -1,7 +0,0 @@
-package io.ebean.mysql.assembly;
-
-/**
- * Nothing interesting here - required placeholder for javadoc.
- */
-public class Assembly {
-}

composites/ebean-mysql/src/main/java/module-info.java

@@ -1,9 +0,0 @@
-module io.ebean.mysql {
-
-  requires transitive io.ebean.api;
-  requires transitive io.ebean.core;
-  requires transitive io.ebean.datasource;
-  requires transitive io.ebean.querybean;
-  requires transitive io.ebean.platform.mysql;
-
-}

composites/ebean-net-postgis/pom.xml

@@ -1,85 +0,0 @@
-<?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">
-  <modelVersion>4.0.0</modelVersion>
-  <parent>
-    <artifactId>ebean-parent</artifactId>
-    <groupId>io.ebean</groupId>
-    <version>16.6.0</version>
-    <relativePath>../..</relativePath>
-  </parent>
-
-  <name>ebean-net-postgis</name>
-  <description>ebean-net-postgis composite</description>
-  <artifactId>ebean-net-postgis</artifactId>
-
-  <properties>
-    <postgis.jdbc.version>2023.1.0</postgis.jdbc.version>
-    <postgres.jdbc.version>42.7.2</postgres.jdbc.version>
-  </properties>
-
-  <dependencies>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-api</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-core</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-datasource</artifactId>
-      <version>${ebean-datasource.version}</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-migration</artifactId>
-      <version>${ebean-migration.version}</version>
-    </dependency>
-
-    <!-- Technically optional but most expected to use query beans -->
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-querybean</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-platform-postgres</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-net-postgis-types</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>org.postgresql</groupId>
-      <artifactId>postgresql</artifactId>
-      <version>${postgres.jdbc.version}</version>
-      <exclusions>
-        <!-- exclude unnecessary checker framework -->
-        <exclusion>
-          <groupId>*</groupId>
-          <artifactId>*</artifactId>
-        </exclusion>
-      </exclusions>
-    </dependency>
-
-    <dependency>
-      <groupId>net.postgis</groupId>
-      <artifactId>postgis-jdbc</artifactId>
-      <version>${postgis.jdbc.version}</version>
-    </dependency>
-
-  </dependencies>
-</project>

composites/ebean-net-postgis/src/main/java/io/ebean/postgis/assembly/Assembly.java

@@ -1,7 +0,0 @@
-package io.ebean.postgis.assembly;
-
-/**
- * Nothing interesting here - required placeholder for javadoc.
- */
-public class Assembly {
-}

composites/ebean-net-postgis/src/main/java/module-info.java

@@ -1,10 +0,0 @@
-module io.ebean.postgis {
-
-  requires transitive io.ebean.api;
-  requires transitive io.ebean.core;
-  requires transitive io.ebean.datasource;
-  requires transitive io.ebean.querybean;
-  requires transitive io.ebean.platform.postgres;
-  // requires transitive io.ebean.postgis.types;
-
-}

composites/ebean-nuodb/pom.xml

@@ -1,55 +0,0 @@
-<?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">
-  <modelVersion>4.0.0</modelVersion>
-  <parent>
-    <artifactId>ebean-parent</artifactId>
-    <groupId>io.ebean</groupId>
-    <version>16.6.0</version>
-    <relativePath>../..</relativePath>
-  </parent>
-
-  <name>ebean-nuodb</name>
-  <description>ebean-nuodb composite</description>
-  <artifactId>ebean-nuodb</artifactId>
-
-  <dependencies>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-api</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-core</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-datasource</artifactId>
-      <version>${ebean-datasource.version}</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-migration</artifactId>
-      <version>${ebean-migration.version}</version>
-    </dependency>
-
-    <!-- Technically optional but most expected to use query beans -->
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-querybean</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-platform-nuodb</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-  </dependencies>
-</project>

composites/ebean-nuodb/src/main/java/io/ebean/nuodb/assembly/Assembly.java

@@ -1,7 +0,0 @@
-package io.ebean.nuodb.assembly;
-
-/**
- * Nothing interesting here - required placeholder for javadoc.
- */
-public class Assembly {
-}

composites/ebean-nuodb/src/main/java/module-info.java

@@ -1,9 +0,0 @@
-module io.ebean.nuodb {
-
-  requires transitive io.ebean.api;
-  requires transitive io.ebean.core;
-  requires transitive io.ebean.datasource;
-  requires transitive io.ebean.querybean;
-  requires transitive io.ebean.platform.nuodb;
-
-}

composites/ebean-oracle/pom.xml

@@ -1,55 +0,0 @@
-<?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">
-  <modelVersion>4.0.0</modelVersion>
-  <parent>
-    <artifactId>ebean-parent</artifactId>
-    <groupId>io.ebean</groupId>
-    <version>16.6.0</version>
-    <relativePath>../..</relativePath>
-  </parent>
-
-  <name>ebean-oracle</name>
-  <description>ebean-oracle composite</description>
-  <artifactId>ebean-oracle</artifactId>
-
-  <dependencies>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-api</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-core</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-datasource</artifactId>
-      <version>${ebean-datasource.version}</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-migration</artifactId>
-      <version>${ebean-migration.version}</version>
-    </dependency>
-
-    <!-- Technically optional but most expected to use query beans -->
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-querybean</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-platform-oracle</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-  </dependencies>
-</project>

composites/ebean-oracle/src/main/java/io/ebean/oracle/assembly/Assembly.java

@@ -1,7 +0,0 @@
-package io.ebean.oracle.assembly;
-
-/**
- * Nothing interesting here - required placeholder for javadoc.
- */
-public class Assembly {
-}

composites/ebean-oracle/src/main/java/module-info.java

@@ -1,9 +0,0 @@
-module io.ebean.oracle {
-
-  requires transitive io.ebean.api;
-  requires transitive io.ebean.core;
-  requires transitive io.ebean.datasource;
-  requires transitive io.ebean.querybean;
-  requires transitive io.ebean.platform.oracle;
-
-}

composites/ebean-pgvector/pom.xml

@@ -1,85 +0,0 @@
-<?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">
-  <modelVersion>4.0.0</modelVersion>
-  <parent>
-    <artifactId>ebean-parent</artifactId>
-    <groupId>io.ebean</groupId>
-    <version>16.6.0</version>
-    <relativePath>../..</relativePath>
-  </parent>
-
-  <name>ebean-pgvector</name>
-  <description>ebean-pgvector composite</description>
-  <artifactId>ebean-pgvector</artifactId>
-
-  <properties>
-    <pgvector.version>0.1.6</pgvector.version>
-    <postgres.jdbc.version>42.7.2</postgres.jdbc.version>
-  </properties>
-
-  <dependencies>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-api</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-core</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-datasource</artifactId>
-      <version>${ebean-datasource.version}</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-migration</artifactId>
-      <version>${ebean-migration.version}</version>
-    </dependency>
-
-    <!-- Technically optional but most expected to use query beans -->
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-querybean</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-platform-postgres</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-pgvector-types</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>org.postgresql</groupId>
-      <artifactId>postgresql</artifactId>
-      <version>${postgres.jdbc.version}</version>
-      <exclusions>
-        <!-- exclude unnecessary checker framework -->
-        <exclusion>
-          <groupId>*</groupId>
-          <artifactId>*</artifactId>
-        </exclusion>
-      </exclusions>
-    </dependency>
-
-    <dependency>
-      <groupId>com.pgvector</groupId>
-      <artifactId>pgvector</artifactId>
-      <version>${pgvector.version}</version>
-    </dependency>
-
-  </dependencies>
-</project>

composites/ebean-pgvector/src/main/java/io/ebean/pgvector/assembly/Assembly.java

@@ -1,7 +0,0 @@
-package io.ebean.pgvector.assembly;
-
-/**
- * Nothing interesting here - required placeholder for javadoc.
- */
-public class Assembly {
-}

composites/ebean-pgvector/src/main/java/module-info.java

@@ -1,9 +0,0 @@
-module io.ebean.pgvector {
-
-  requires transitive io.ebean.api;
-  requires transitive io.ebean.core;
-  requires transitive io.ebean.datasource;
-  requires transitive io.ebean.querybean;
-  requires transitive io.ebean.platform.postgres;
-
-}

composites/ebean-postgis/pom.xml

@@ -1,85 +0,0 @@
-<?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">
-  <modelVersion>4.0.0</modelVersion>
-  <parent>
-    <artifactId>ebean-parent</artifactId>
-    <groupId>io.ebean</groupId>
-    <version>16.6.0</version>
-    <relativePath>../..</relativePath>
-  </parent>
-
-  <name>ebean-postgis</name>
-  <description>ebean-postgis composite</description>
-  <artifactId>ebean-postgis</artifactId>
-
-  <properties>
-    <postgis.jdbc.version>2.5.1</postgis.jdbc.version>
-    <postgres.jdbc.version>42.7.2</postgres.jdbc.version>
-  </properties>
-
-  <dependencies>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-api</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-core</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-datasource</artifactId>
-      <version>${ebean-datasource.version}</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-migration</artifactId>
-      <version>${ebean-migration.version}</version>
-    </dependency>
-
-    <!-- Technically optional but most expected to use query beans -->
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-querybean</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-platform-postgres</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-postgis-types</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>org.postgresql</groupId>
-      <artifactId>postgresql</artifactId>
-      <version>${postgres.jdbc.version}</version>
-      <exclusions>
-        <!-- exclude unnecessary checker framework -->
-        <exclusion>
-          <groupId>*</groupId>
-          <artifactId>*</artifactId>
-        </exclusion>
-      </exclusions>
-    </dependency>
-
-    <dependency>
-      <groupId>net.postgis</groupId>
-      <artifactId>postgis-jdbc</artifactId>
-      <version>${postgis.jdbc.version}</version>
-    </dependency>
-
-  </dependencies>
-</project>

composites/ebean-postgis/src/main/java/io/ebean/postgis/assembly/Assembly.java

@@ -1,7 +0,0 @@
-package io.ebean.postgis.assembly;
-
-/**
- * Nothing interesting here - required placeholder for javadoc.
- */
-public class Assembly {
-}

composites/ebean-postgis/src/main/java/module-info.java

@@ -1,10 +0,0 @@
-module io.ebean.postgis {
-
-  requires transitive io.ebean.api;
-  requires transitive io.ebean.core;
-  requires transitive io.ebean.datasource;
-  requires transitive io.ebean.querybean;
-  requires transitive io.ebean.platform.postgres;
-  // requires transitive io.ebean.postgis.types;
-
-}

composites/ebean-postgres/pom.xml

@@ -1,55 +0,0 @@
-<?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">
-  <modelVersion>4.0.0</modelVersion>
-  <parent>
-    <artifactId>ebean-parent</artifactId>
-    <groupId>io.ebean</groupId>
-    <version>16.6.0</version>
-    <relativePath>../..</relativePath>
-  </parent>
-
-  <name>ebean-postgres</name>
-  <description>ebean-postgres composite</description>
-  <artifactId>ebean-postgres</artifactId>
-
-  <dependencies>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-api</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-core</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-datasource</artifactId>
-      <version>${ebean-datasource.version}</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-migration</artifactId>
-      <version>${ebean-migration.version}</version>
-    </dependency>
-
-    <!-- Technically optional but most expected to use query beans -->
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-querybean</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-platform-postgres</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-  </dependencies>
-</project>

composites/ebean-postgres/src/main/java/io/ebean/postgres/assembly/Assembly.java

@@ -1,7 +0,0 @@
-package io.ebean.postgres.assembly;
-
-/**
- * Nothing interesting here - required placeholder for javadoc.
- */
-public class Assembly {
-}

composites/ebean-postgres/src/main/java/module-info.java

@@ -1,9 +0,0 @@
-module io.ebean.postgres {
-
-  requires transitive io.ebean.api;
-  requires transitive io.ebean.core;
-  requires transitive io.ebean.datasource;
-  requires transitive io.ebean.querybean;
-  requires transitive io.ebean.platform.postgres;
-
-}

composites/ebean-sqlite/pom.xml

@@ -1,55 +0,0 @@
-<?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">
-  <modelVersion>4.0.0</modelVersion>
-  <parent>
-    <artifactId>ebean-parent</artifactId>
-    <groupId>io.ebean</groupId>
-    <version>16.6.0</version>
-    <relativePath>../..</relativePath>
-  </parent>
-
-  <name>ebean-sqlite</name>
-  <description>ebean-sqlite composite</description>
-  <artifactId>ebean-sqlite</artifactId>
-
-  <dependencies>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-api</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-core</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-datasource</artifactId>
-      <version>${ebean-datasource.version}</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-migration</artifactId>
-      <version>${ebean-migration.version}</version>
-    </dependency>
-
-    <!-- Technically optional but most expected to use query beans -->
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-querybean</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-platform-sqlite</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-  </dependencies>
-</project>

composites/ebean-sqlite/src/main/java/io/ebean/sqlite/assembly/Assembly.java

@@ -1,7 +0,0 @@
-package io.ebean.sqlite.assembly;
-
-/**
- * Nothing interesting here - required placeholder for javadoc.
- */
-public class Assembly {
-}

composites/ebean-sqlite/src/main/java/module-info.java

@@ -1,9 +0,0 @@
-module io.ebean.sqlite {
-
-  requires transitive io.ebean.api;
-  requires transitive io.ebean.core;
-  requires transitive io.ebean.datasource;
-  requires transitive io.ebean.querybean;
-  requires transitive io.ebean.platform.sqlite;
-
-}

composites/ebean-sqlserver/pom.xml

@@ -1,55 +0,0 @@
-<?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">
-  <modelVersion>4.0.0</modelVersion>
-  <parent>
-    <artifactId>ebean-parent</artifactId>
-    <groupId>io.ebean</groupId>
-    <version>16.6.0</version>
-    <relativePath>../..</relativePath>
-  </parent>
-
-  <name>ebean-sqlserver</name>
-  <description>ebean-sqlserver composite</description>
-  <artifactId>ebean-sqlserver</artifactId>
-
-  <dependencies>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-api</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-core</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-datasource</artifactId>
-      <version>${ebean-datasource.version}</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-migration</artifactId>
-      <version>${ebean-migration.version}</version>
-    </dependency>
-
-    <!-- Technically optional but most expected to use query beans -->
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-querybean</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-platform-sqlserver</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-  </dependencies>
-</project>

composites/ebean-sqlserver/src/main/java/io/ebean/sqlserver/assembly/Assembly.java

@@ -1,7 +0,0 @@
-package io.ebean.sqlserver.assembly;
-
-/**
- * Nothing interesting here - required placeholder for javadoc.
- */
-public class Assembly {
-}

composites/ebean-sqlserver/src/main/java/module-info.java

@@ -1,9 +0,0 @@
-module io.ebean.sqlserver {
-
-  requires transitive io.ebean.api;
-  requires transitive io.ebean.core;
-  requires transitive io.ebean.datasource;
-  requires transitive io.ebean.querybean;
-  requires transitive io.ebean.platform.sqlserver;
-
-}

composites/ebean-yugabyte/pom.xml

@@ -1,55 +0,0 @@
-<?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">
-  <modelVersion>4.0.0</modelVersion>
-  <parent>
-    <artifactId>ebean-parent</artifactId>
-    <groupId>io.ebean</groupId>
-    <version>16.6.0</version>
-    <relativePath>../..</relativePath>
-  </parent>
-
-  <name>ebean-yugabyte</name>
-  <description>ebean-yugabyte composite</description>
-  <artifactId>ebean-yugabyte</artifactId>
-
-  <dependencies>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-api</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-core</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-datasource</artifactId>
-      <version>${ebean-datasource.version}</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-migration</artifactId>
-      <version>${ebean-migration.version}</version>
-    </dependency>
-
-    <!-- Technically optional but most expected to use query beans -->
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-querybean</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-platform-postgres</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-  </dependencies>
-</project>

composites/ebean-yugabyte/src/main/java/io/ebean/yugabyte/assembly/Assembly.java

@@ -1,7 +0,0 @@
-package io.ebean.yugabyte.assembly;
-
-/**
- * Nothing interesting here - required placeholder for javadoc.
- */
-public class Assembly {
-}

composites/ebean-yugabyte/src/main/java/module-info.java

@@ -1,9 +0,0 @@
-module io.ebean.yugabyte {
-
-  requires transitive io.ebean.api;
-  requires transitive io.ebean.core;
-  requires transitive io.ebean.datasource;
-  requires transitive io.ebean.querybean;
-  requires transitive io.ebean.platform.postgres;
-
-}

composites/ebean/pom.xml

@@ -1,73 +0,0 @@
-<?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">
-  <modelVersion>4.0.0</modelVersion>
-  <parent>
-    <artifactId>ebean-parent</artifactId>
-    <groupId>io.ebean</groupId>
-    <version>16.6.0</version>
-    <relativePath>../..</relativePath>
-  </parent>
-
-  <name>ebean (all platforms)</name>
-  <description>composite of common runtime dependencies for all platforms</description>
-  <artifactId>ebean</artifactId>
-
-  <dependencies>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-api</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-core</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-joda-time</artifactId>
-      <version>14.0.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-jackson-jsonnode</artifactId>
-      <version>14.0.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-jackson-mapper</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-datasource</artifactId>
-      <version>${ebean-datasource.version}</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-migration</artifactId>
-      <version>${ebean-migration.version}</version>
-    </dependency>
-
-    <!-- Technically optional but most expected to use query beans -->
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-querybean</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-platform-all</artifactId>
-      <version>16.6.0</version>
-    </dependency>
-
-  </dependencies>
-</project>

composites/pom.xml

@@ -1,35 +0,0 @@
-<?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">
-  <modelVersion>4.0.0</modelVersion>
-  <parent>
-    <artifactId>ebean-parent</artifactId>
-    <groupId>io.ebean</groupId>
-    <version>16.6.0</version>
-  </parent>
-
-  <artifactId>composites</artifactId>
-  <packaging>pom</packaging>
-
-  <modules>
-    <module>ebean</module>
-    <module>ebean-clickhouse</module>
-    <module>ebean-cockroach</module>
-    <module>ebean-db2</module>
-    <module>ebean-h2</module>
-    <module>ebean-hana</module>
-<!--    <module>hsqldb</module>-->
-    <module>ebean-mariadb</module>
-    <module>ebean-mysql</module>
-    <module>ebean-nuodb</module>
-    <module>ebean-oracle</module>
-    <module>ebean-postgres</module>
-    <module>ebean-postgis</module>
-    <module>ebean-net-postgis</module>
-    <module>ebean-pgvector</module>
-<!--    <module>sqlanywhere</module>-->
-    <module>ebean-sqlite</module>
-    <module>ebean-sqlserver</module>
-    <module>ebean-yugabyte</module>
-  </modules>
-
-</project>

docs/LIBRARY.md

@@ -1,248 +0,0 @@
-# Ebean ORM Library Definition
-
-Ebean is an ORM library for Java and Kotlin focused on relational data access, type-safe query construction, and production-friendly SQL behavior.
-
-## Identity
-
-- **Name**: Ebean ORM
-- **Package**: `io.ebean`
-- **Primary Maven Group**: `io.ebean`
-- **Category**: ORM / Data Access
-- **Repository**: https://github.com/ebean-orm/ebean
-- **Issues**: https://github.com/ebean-orm/ebean/issues
-- **Discussions**: https://github.com/ebean-orm/ebean/discussions
-- **Website**: https://ebean.io/
-- **Documentation**: https://ebean.io/docs/
-- **License**: Apache 2.0
-
-## Version & Requirements
-
-- **Repository Version (this checkout)**: `16.5.0` (from repository `pom.xml`)
-- **Minimum Java Version**: 11+
-- **Languages**: Java, Kotlin
-- **Build Tooling in this docs set**: Maven-focused examples
-
-## Core Artifacts
-
-| Artifact | Purpose |
-|------|------|
-| `io.ebean:ebean` | Core ORM runtime and API |
-| `io.ebean:ebean-postgres` | PostgreSQL platform bundle used in setup guides |
-| `io.ebean:ebean-test` | Test support, including Docker-backed database testing |
-| `io.ebean:querybean-generator` | Generates `Q*` type-safe query beans |
-| `io.ebean:ebean-maven-plugin` | Bytecode enhancement for entities at build time |
-| `io.ebean:ebean-migration` | Runtime migration runner (often transitive via platform artifact) |
-
-## Core APIs & Annotations
-
-### Database and transaction APIs
-
-| API | Purpose | Example |
-|------|------|------|
-| `DB.getDefault()` | Access default `Database` | `Database db = DB.getDefault();` |
-| `DB.byName("...")` | Access named `Database` | `Database reporting = DB.byName("reporting");` |
-| `database.find(...)` | Query entities | `Customer c = database.find(Customer.class, id);` |
-| `database.insert/save/update/delete` | Persist entity changes | `database.save(customer);` |
-| `database.beginTransaction()` | Manual transaction boundary | `try (Transaction txn = database.beginTransaction()) { ... }` |
-| `Database.builder()` | Programmatic `Database` setup | `Database.builder().loadFromProperties().build();` |
-
-### Query APIs
-
-| API | Purpose | Example |
-|------|------|------|
-| `Q*` query beans | Type-safe query construction | `new QCustomer().status.equalTo(ACTIVE).findList();` |
-| `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();` |
-
-### Entity mapping and lifecycle annotations
-
-| Annotation | Purpose |
-|------|------|
-| `@Entity` | Marks class as persistent entity |
-| `@Id` | Primary key mapping |
-| `@Version` | Optimistic locking |
-| `@WhenCreated` | Creation timestamp management |
-| `@WhenModified` | Modification timestamp management |
-| `@Transactional` | Declarative transaction boundary |
-
-## Capabilities
-
-### ✅ Included
-
-- Relational ORM with automatic dirty checking and lazy loading (via enhancement)
-- Multiple query abstraction levels (ORM query, DTO query, SQL/JDBC)
-- Type-safe query beans (`Q*`) with IDE autocomplete
-- Built-in migration generation and migration running support
-- Transaction APIs for implicit, declarative, and explicit transaction control
-- Support for test-time Docker database workflows
-- Query tuning and caching features for performance-sensitive workloads
-
-### ❌ Not in scope
-
-- HTTP routing, REST controllers, or web server runtime
-- Dependency injection container functionality
-- JSON serialization framework responsibilities
-- Front-end/UI rendering concerns
-
-Ebean is intentionally focused on persistence and data access. Pair it with a web framework and DI library as needed.
-
-## Use Cases
-
-### ✅ Strong fit
-
-- SQL-backed business applications with rich domain models
-- Services that need both ORM productivity and SQL-level control
-- Projects requiring type-safe query authoring via generated query beans
-- Teams that want migration generation integrated with entity model changes
-- Integration test suites that need real database behavior (not only in-memory mocks)
-
-### ⚠️ Consider alternatives if
-
-- You need a full web framework (routing/controllers) rather than a persistence layer
-- Your project does not use relational databases as a core storage model
-- You want a single library to cover persistence, DI, and HTTP all at once
-
-## Quick Start (Maven)
-
-```xml
-<properties>
-  <ebean.version><!-- use latest stable from Maven Central --></ebean.version>
-</properties>
-
-<dependencies>
-  <dependency>
-    <groupId>io.ebean</groupId>
-    <artifactId>ebean-postgres</artifactId>
-    <version>${ebean.version}</version>
-  </dependency>
-  <dependency>
-    <groupId>io.ebean</groupId>
-    <artifactId>ebean-test</artifactId>
-    <version>${ebean.version}</version>
-    <scope>test</scope>
-  </dependency>
-</dependencies>
-
-<build>
-  <plugins>
-    <plugin>
-      <groupId>io.ebean</groupId>
-      <artifactId>ebean-maven-plugin</artifactId>
-      <version>${ebean.version}</version>
-      <extensions>true</extensions>
-    </plugin>
-    <plugin>
-      <groupId>org.apache.maven.plugins</groupId>
-      <artifactId>maven-compiler-plugin</artifactId>
-      <configuration>
-        <annotationProcessorPaths>
-          <path>
-            <groupId>io.ebean</groupId>
-            <artifactId>querybean-generator</artifactId>
-            <version>${ebean.version}</version>
-          </path>
-        </annotationProcessorPaths>
-      </configuration>
-    </plugin>
-  </plugins>
-</build>
-```
-
-## Minimal Example
-
-```java
-import io.ebean.DB;
-import jakarta.persistence.Entity;
-import jakarta.persistence.Id;
-
-@Entity
-class Customer {
-  @Id
-  private long id;
-  private String name;
-
-  public void setName(String name) {
-    this.name = name;
-  }
-}
-
-Database database = DB.getDefault(); // or injected
-
-Customer customer = database.find(Customer.class, 42);
-customer.setName("Updated");
-database.save(customer);
-```
-
-## Common Tasks & Guides
-
-| Task | Guide |
-|------|------|
-| Add Ebean to an existing Maven project | [add-ebean-postgres-maven-pom.md](guides/add-ebean-postgres-maven-pom.md) |
-| 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) |
-| 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) |
-| 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) |
-
-**Guides index**: [guides/README.md](guides/README.md)
-
-## Related Ecosystem Docs
-
-- [Creating DataSource Pools](https://github.com/ebean-orm/ebean-datasource/blob/master/docs/guides/create-datasource-pool.md)
-- [AWS Aurora Read-Write Split](https://github.com/ebean-orm/ebean-datasource/blob/master/docs/guides/aws-aurora-read-write-split.md)
-- [Connection Validation Best Practices](https://github.com/ebean-orm/ebean-datasource/blob/master/docs/guides/connection-validation-best-practices.md)
-
-## AI Agent Instructions
-
-### For Claude, GPT, and web-based agents
-
-Use this file as the top-level reference when answering Ebean questions.
-
-1. Check this file first for scope and capability fit.
-2. Route implementation tasks to the relevant guide in **Common Tasks & Guides**.
-3. Treat Ebean as the persistence layer only; avoid implying it provides HTTP/DI features.
-4. Prefer type-safe query bean examples when showing query code.
-5. For setup and migration changes, follow the Maven-focused guide steps exactly.
-
-### For IDE-based agents (Copilot, Cursor, etc.)
-
-If `docs/LIBRARY.md` is not in context automatically:
-
-1. Read `README.md` for docs entry points.
-2. Open `docs/guides/README.md` for task-specific guides.
-3. Follow linked guide files directly for concrete implementation steps.
-
----
-
-## Notes for Maintainers
-
-### When to update this file
-
-- New release that changes requirements or key APIs
-- New guide added to `docs/guides/`
-- Capability/scope changes that affect "Included" or "Not in scope"
-- Significant migration or setup workflow changes
-
-### Maintenance checklist
-
-- [ ] Keep requirements and version references accurate
-- [ ] Keep Common Tasks table aligned with `docs/guides/README.md`
-- [ ] Keep artifact names/snippets aligned with setup guides
-- [ ] Keep AI instructions aligned with current docs structure
-
-### Link from repository README
-
-In `README.md`, include:
-
-```markdown
-## Documentation
-
-- [Ebean docs](https://ebean.io/docs/)
-- [Library reference](docs/LIBRARY.md)
-- [Step-by-step guides](docs/guides/README.md)
-```

docs/guides/AGENTS.md

@@ -1,20 +0,0 @@
-# AGENTS.md — Ebean ORM
-
-This project uses [Ebean ORM](https://ebean.io).
-
-## AI Agent Instructions
-
-Step-by-step guides for common Ebean tasks (Maven setup, database config, query writing, transactions, test containers, DB migrations, Lombok) are at:
-
-**https://github.com/ebean-orm/ebean/tree/HEAD/docs/guides/**
-
-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
-- Write queries with query beans: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/writing-ebean-query-beans.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
-- Lombok with entity beans: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/lombok-with-ebean-entity-beans.md
-
-Agents: Before performing any Ebean-related task, fetch and follow the relevant guide above.

docs/guides/README.md

@@ -1,182 +0,0 @@
-# Guides
-
-See also: [AGENTS.md](AGENTS.md) — a minimal template for AI agent onboarding and automation in Ebean ORM projects.
-
-Step-by-step guides written as instructions for AI agents and developers.
-
-For a high-level capability reference (scope, core APIs, and AI guidance), see
-[../LIBRARY.md](../LIBRARY.md).
-
-## Adding Ebean ORM with PostgreSQL to an existing Maven project
-
-A three-part guide covering everything needed to wire Ebean + PostgreSQL into an
-existing Maven project. Complete the steps in order.
-
-| Step | Guide | Description |
-|------|-------|-------------|
-| 1 | [Maven POM setup](add-ebean-postgres-maven-pom.md) | Add Ebean dependencies, the enhancement plugin, and the querybean-generator annotation processor to `pom.xml` |
-| 2 | [Test container setup](add-ebean-postgres-test-container.md) | Start a PostgreSQL (or PostGIS) Docker container for tests using `@TestScope @Factory` with Avaje Inject; verify the test database works with `mvn verify` before adding production configuration |
-| 3 | [Database configuration](add-ebean-postgres-database-config.md) | Configure the production Ebean `Database` bean using `DataSourceBuilder` and `DatabaseBuilder` with Avaje Inject |
-
-## Entity beans
-
-| Guide | Description |
-|-------|-------------|
-| [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)` |
-
-## 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 |
-| [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 |
-
-## Persisting & transactions
-
-| Guide | Description |
-|-------|-------------|
-| [Persisting and transactions with Ebean](persisting-and-transactions-with-ebean.md) | Step-by-step guidance for AI agents to choose `insert` / `save` / `update` / `delete`; inspect cascades; select the right transaction boundary; and use batch or bulk update for large write sets |
-
-## Testing
-
-| Guide | Description |
-|-------|-------------|
-| [Testing with TestEntityBuilder](testing-with-testentitybuilder.md) | Rapidly create test entity instances with auto-populated random values; manage relationships and cascades; customize value generation for domain-specific testing needs |
-
-## Database migrations
-
-| Guide | Description |
-|-------|-------------|
-| [DB migration generation](add-ebean-db-migration-generation.md) | Add `GenerateDbMigration.java` to generate schema diff migrations offline; configure the migration runner; understand `.sql` and `.model.xml` output files; workflow for pending drops |
-
-## Connection Pooling & DataSource Configuration
-
-The [ebean-datasource](https://github.com/ebean-orm/ebean-datasource) project provides
-comprehensive guides on connection pool configuration and best practices. These are particularly
-useful for production deployments, especially in Kubernetes or AWS environments:
-
-| Guide | Description |
-|-------|-------------|
-| [Creating DataSource Pools](https://github.com/ebean-orm/ebean-datasource/blob/master/docs/guides/create-datasource-pool.md) | Step-by-step guide for basic, read-only, Kubernetes, and AWS Lambda datasource configurations |
-| [AWS Aurora Read-Write Split](https://github.com/ebean-orm/ebean-datasource/blob/master/docs/guides/aws-aurora-read-write-split.md) | Setting up dual DataSources with Aurora read and write endpoints for Ebean integration |
-| [Connection Validation Best Practices](https://github.com/ebean-orm/ebean-datasource/blob/master/docs/guides/connection-validation-best-practices.md) | Understanding connection heartbeat strategies and why `Connection.isValid()` is the recommended approach |
-
----
-
-## Helping AI agents find these guides
-
-### Agent Skills (recommended)
-
-The **ebean-orm skill** packages these guides into a structured format that AI agents
-load on-demand. See the [ebean-orm/skills](https://github.com/ebean-orm/skills) repo
-for installation instructions. Quick start:
-
-```bash
-git clone git@github.com:ebean-orm/skills.git ~/.agents/ebean-skills
-mkdir -p ~/.agents/skills
-ln -sf ~/.agents/ebean-skills/ebean-orm ~/.agents/skills/ebean-orm
-```
-
-This works with [pi](https://github.com/mariozechner/pi-coding-agent),
-[Claude Code](https://docs.anthropic.com/en/docs/claude-code), and any harness
-that supports the [Agent Skills standard](https://agentskills.io/specification).
-
-### Other approaches
-
-AI coding agents can only follow these guides if they know they exist. Below are
-copy-paste snippets for the most common AI tooling configurations. Add whichever
-applies to your project.
-
-### llms.txt (fastest bootstrap for any agent)
-
-`https://ebean.io/llms.txt` provides a concise Ebean capability reference and links
-to all guides in a format optimised for LLMs. Agents that check `llms.txt` before
-starting work will find everything they need without requiring project-level
-configuration. This is worth knowing if you are an AI agent reading this file.
-
-
-### Project `README.md` (universal — works with all AI tools)
-
-Add a section near the top of your project README:
-
-```markdown
-## AI Agent Instructions
-
-This project uses [Ebean ORM](https://ebean.io). Step-by-step guides for common
-Ebean tasks (Maven setup, database configuration, query writing, transactions,
-test containers, DB migrations, Lombok) are at:
-
-**https://github.com/ebean-orm/ebean/tree/HEAD/docs/guides/**
-
-AI agents should fetch and follow the relevant guide before performing Ebean-related
-tasks.
-```
-
-### Why README is important
-
-Many AI agents (Copilot, Claude, Cursor, Aider) read the project `README.md`
-automatically as part of understanding the codebase. A visible link in README is the
-most universally effective way to ensure any agent working on your project will
-discover the guides without requiring tool-specific configuration files.
-
-------
-
-### GitHub Copilot — `.github/copilot-instructions.md`
-
-```markdown
-## Ebean ORM
-
-This project uses [Ebean ORM](https://ebean.io). Step-by-step guides for common
-tasks are at: https://github.com/ebean-orm/ebean/tree/HEAD/docs/guides/
-
-Key guides (fetch and follow these 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
-- Write queries with query beans: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/writing-ebean-query-beans.md
-- Immutable bean cache for read-only references: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/immutable-bean-cache.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
-- Lombok with entity beans: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/lombok-with-ebean-entity-beans.md
-```
-
-### Claude Code — `CLAUDE.md`
-
-Same content as above — Claude Code reads `CLAUDE.md` at the project root.
-
-### AGENTS.md — OpenAI Codex / GitHub Copilot coding agent
-
-Place an `AGENTS.md` at your repo root:
-
-```markdown
-## Ebean ORM
-
-This project uses [Ebean ORM](https://ebean.io). Step-by-step guides for common
-tasks are at: https://github.com/ebean-orm/ebean/tree/HEAD/docs/guides/
-
-Key guides (fetch and follow these 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
-- Write queries with query beans: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/writing-ebean-query-beans.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
-- Entity bean creation: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/entity-bean-creation.md
-```
-
-### Cursor — `.cursor/rules/ebean.mdc`
-
-```markdown
----
-description: Ebean ORM task guidance
-globs: ["**/*.java", "**/pom.xml"]
-alwaysApply: false
----
-
-## Ebean ORM
-
-This project uses Ebean ORM. Before performing any Ebean-related task, fetch and
-follow the relevant step-by-step guide from:
-https://github.com/ebean-orm/ebean/tree/HEAD/docs/guides/
-```

docs/guides/add-ebean-db-migration-generation.md

@@ -1,366 +0,0 @@
-# Guide: Add Ebean Database Migration Generation to an Existing Maven Project
-
-## Purpose
-
-This guide provides step-by-step instructions for adding Ebean DB migration generation
-to an existing Maven project that already uses Ebean ORM. Ebean generates migrations by
-performing a diff of the current entity model against the previously recorded model state,
-producing platform-specific DDL SQL scripts.
-
-These instructions are designed for AI agents and developers to follow precisely.
-
----
-
-## Prerequisites
-
-- An existing Maven project with Ebean ORM configured (entity beans present)
-- `ebean-test` is already a test-scoped dependency (from POM setup guide)
-- The project targets PostgreSQL (adjust `Platform.POSTGRES` for other databases)
-
----
-
-## Step 1 — Verify migration dependencies
-
-### Generation tooling (`ebean-ddl-generator`)
-
-`ebean-test` (already present as a test dependency) transitively includes
-`ebean-ddl-generator`, which provides the `DbMigration` class. No additional dependency
-is required for generation.
-
-### Runtime migration runner (`ebean-migration`)
-
-`ebean-migration` is the library that runs migrations on application startup.
-It is typically included **transitively** via `io.ebean:ebean-postgres` (or the
-equivalent platform dependency). Verify it is on the classpath by running:
-
-```bash
-mvn dependency:tree | grep ebean-migration
-```
-
-If it is **not** present transitively, add it explicitly as a compile-scope dependency:
-
-```xml
-<dependency>
-    <groupId>io.ebean</groupId>
-    <artifactId>ebean-migration</artifactId>
-    <version>${ebean.version}</version>
-</dependency>
-```
-
----
-
-## Step 2 — Create `GenerateDbMigration.java`
-
-Create the following class in `src/test/java/main/`. This `main` method is run manually
-by a developer (or AI agent) whenever entity beans change and a new migration is needed.
-
-```java
-package main;
-
-import io.ebean.annotation.Platform;
-import io.ebean.dbmigration.DbMigration;
-
-import java.io.IOException;
-
-/**
- * Generate the next database migration based on a diff of the entity model.
- * Run this main method after making entity bean changes to produce the migration SQL.
- */
-public class GenerateDbMigration {
-
-    public static void main(String[] args) throws IOException {
-
-        DbMigration migration = DbMigration.create();
-        migration.setPlatform(Platform.POSTGRES);
-
-        migration.setVersion("1.1");           // set to the next migration version
-        migration.setName("add-customer");     // short description of the change
-
-        migration.generateMigration();
-    }
-}
-```
-
-### Version naming convention
-
-Ebean supports two common version formats — choose one and apply it consistently:
-
-| Format | Example | Notes |
-|--------|---------|-------|
-| **Date-based** | `20240820` | `YYYYMMDD`; used when changes are tied to dates; easily sortable |
-| **Semantic** | `1.1`, `1.2`, `2.0` | Traditional versioning; useful for release-based workflows |
-
-The version controls execution order — Ebean runs migrations in ascending version order.
-
-### Name convention
-
-The `name` should be a short, lowercase, hyphenated description of the change:
-- `add-customer-email`
-- `rename-machine-type`
-- `drop-unused-columns`
-
----
-
-## Step 3 — Configure the output path (if needed)
-
-By default, migration files are written to `src/main/resources/dbmigration/` relative
-to the **current working directory** when `generateMigration()` is called. This is
-usually the module root, which is correct for single-module projects.
-
-For **multi-module projects** where `GenerateDbMigration` is in a submodule but the
-resources directory is at a different relative path, specify it explicitly:
-
-```java
-// Relative path from the working directory (project root) to the module's resources
-migration.setPathToResources("my-module/src/main/resources");
-```
-
----
-
-## Step 4 — Run `GenerateDbMigration` to produce the first migration
-
-Run the `main` method via the IDE or Maven:
-
-```bash
-# Run via Maven exec plugin (or use IDE run configuration)
-mvn test-compile exec:java \
-    -Dexec.mainClass="main.GenerateDbMigration" \
-    -Dexec.classpathScope="test" \
-    -pl <your-module>
-```
-
-Ebean migration generation runs in **offline mode** — no database connection is required.
-
-### Expected output files
-
-After running, two files are created per migration in `src/main/resources/dbmigration/`:
-
-```
-src/main/resources/dbmigration/
-  1.1__add-customer.sql           ← DDL SQL to apply (commit this)
-  model/
-    1.1__add-customer.model.xml   ← logical model diff XML (commit this)
-```
-
-Both files must be committed to source control. The `.model.xml` file records the
-logical state of the diff and is used by subsequent migration generations to determine
-what has changed.
-
-If **no entity beans have changed** since the last migration, the command outputs:
-```
-DbMigration - no changes detected - no migration written
-```
-
----
-
-## Step 5 — Enable the migration runner
-
-Configure Ebean to run pending migrations automatically on application startup.
-
-### Preferred approach — programmatic via `DatabaseBuilder`
-
-Set `runMigration(true)` directly on the `DatabaseBuilder` when constructing
-the `Database` bean. This is the preferred approach as it is explicit, co-located with
-the database configuration, and does not rely on external property files.
-
-In the `@Factory` class that builds the `Database` bean (see the database configuration
-guide), add `.runMigration(true)` to the builder chain:
-
-```java
-@Bean
-Database database(ConfigWrapper config) {
-    var dataSource = DataSourceBuilder.create()
-        .url(config.getDatabaseUrl())
-        .username(config.getDatabaseUser())
-        .password(config.getDatabasePassword())
-        // ... other datasource settings ...
-        ;
-
-    return Database.builder()
-        .name("db")
-        .dataSourceBuilder(dataSource)
-        .runMigration(true)          // run pending migrations on startup
-        .build();
-}
-```
-
-If migrations should only run in certain environments (e.g., not in production, or
-only when a config flag is set), make it conditional:
-
-```java
-.runMigration(config.isRunMigrations())   // driven by config value
-```
-
-### Alternative — via application properties
-
-If programmatic configuration is not available or not preferred, set the property
-in `src/main/resources/application.properties`:
-
-```properties
-ebean.migration.run=true
-```
-
-Or in `src/main/resources/application.yaml`:
-```yaml
-ebean:
-  migration:
-    run: true
-```
-
-For a **named database** (i.e., `Database.builder().name("mydb")`), use the database
-name in the property key:
-
-```properties
-ebean.mydb.migration.run=true
-```
-
-### What the runner does at startup
-
-When migration running is enabled, Ebean will on each application start:
-1. Look at the migrations in `src/main/resources/dbmigration/`
-2. Compare against the `db_migration` table (created automatically on first run)
-3. Apply any migrations that have not yet been executed, in version order
-4. Record each successfully applied migration in `db_migration`
-
----
-
-## Step 6 — Commit the migration files
-
-Add both generated files to source control:
-
-```bash
-git add src/main/resources/dbmigration/1.1__add-customer.sql
-git add src/main/resources/dbmigration/model/1.1__add-customer.model.xml
-git commit -m "Add db migration 1.1: add-customer"
-```
-
----
-
-## Ongoing workflow — generating subsequent migrations
-
-For each future set of entity bean changes:
-
-1. Make changes to the entity bean classes
-2. Update `GenerateDbMigration.java` with the **new version** and **new name**:
-   ```java
-   migration.setVersion("1.2");
-   migration.setName("add-address-table");
-   ```
-3. Run the `main` method — a new `.sql` and `.model.xml` pair is written
-4. Review the generated `.sql` to confirm it reflects the intended changes
-5. Commit both files
-
----
-
-## Understanding the output files
-
-### Apply SQL (`.sql`)
-
-The apply SQL file contains the DDL that will be executed against the database:
-
-```sql
--- apply changes
-alter table customer add column email varchar(255);
-```
-
-### Model XML (`.model.xml`)
-
-The model XML records the logical diff in a database-agnostic format. Ebean uses
-this file on the next generation run to determine what has already been captured.
-It is not executed against the database.
-
-```xml
-<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
-<migration xmlns="http://ebean-orm.github.io/xml/ns/dbmigration">
-  <changeSet type="apply">
-    <addColumn tableName="customer">
-      <column name="email" type="varchar(255)"/>
-    </addColumn>
-  </changeSet>
-</migration>
-```
-
----
-
-## Optional configurations
-
-### Multiple database platforms
-
-To generate migrations for multiple platforms simultaneously, use `addPlatform()`
-instead of `setPlatform()`:
-
-```java
-migration.addPlatform(Platform.POSTGRES);
-migration.addPlatform(Platform.SQLSERVER17);
-migration.addPlatform(Platform.MYSQL);
-```
-
-Each platform gets its own subdirectory under `dbmigration/`.
-
-### Include index
-
-When enabled the migration generation also generates a file that contains
-all the migrations and their associated hashes. This is a performance
-optimisation (that will become the default) and means that the migration
-runner just needs to read the one resource and has the pre-computed hash
-values (so does not need to read each migration resource and compute the
-hash for each of those at runtime).
-
-```java
-migration.setIncludeIndex(true);
-```
-
-### Strict mode
-
-Strict mode (on by default) errors if there are any pending drops not yet applied.
-Set to `false` to allow generation to proceed regardless:
-
-```java
-migration.setStrictMode(false);
-```
-
-### Applying pending drops
-
-Destructive changes (drop column, drop table) are **not** included in the apply
-SQL by default — they are recorded as `pendingDrops` in the model XML. This allows
-the application to be deployed without immediately dropping columns (important for
-rolling deployments).
-
-The migration runner logs a message when pending drops exist:
-```
-INFO  DbMigration - Pending un-applied drops in versions [1.1]
-```
-
-When ready to apply the drops, set `setGeneratePendingDrop` to the version that
-contains the pending drops:
-
-```java
-migration.setVersion("1.3");
-migration.setName("drop-pending-from-1.1");
-migration.setGeneratePendingDrop("1.1");  // apply drops recorded in version 1.1
-migration.generateMigration();
-```
-
-### Custom dbSchema
-
-If the project uses a named Postgres schema (set via `ebean.dbSchema` in
-`application.properties`), no additional configuration is needed in
-`GenerateDbMigration` — Ebean picks up the schema from the application config
-automatically when running in offline mode.
-
-```properties
-# application.properties
-ebean.dbSchema=myschema
-```
-
----
-
-## Troubleshooting
-
-| Symptom | Likely cause | Fix |
-|---------|-------------|-----|
-| `no changes detected - no migration written` | Entity beans unchanged since last migration | Make entity bean changes first, then re-run |
-| `DbMigration - Pending un-applied drops` | A previous migration has drops not yet applied | Either suppress with `setStrictMode(false)` or apply drops with `setGeneratePendingDrop(...)` |
-| Generated SQL is empty or wrong | Wrong working directory path | Set `setPathToResources(...)` to the correct module-relative path |
-| `ClassNotFoundException` for entity classes | Test classpath not including main classes | Ensure `exec.classpathScope=test` or run via IDE with test classpath |
-| Migrations not running on startup | Property key wrong or `ebean-migration` missing | Verify `ebean[.name].migration.run=true` and that `ebean-migration` is on the classpath |

docs/guides/add-ebean-postgres-database-config.md

@@ -1,291 +0,0 @@
-# Guide: Add Ebean ORM (PostgreSQL) to an Existing Maven Project — Step 2: Database Configuration
-
-## Purpose
-
-This guide provides step-by-step instructions for configuring an Ebean `Database` bean
-using **Avaje Inject** (`@Factory` / `@Bean`), backed by a PostgreSQL datasource built
-with Ebean's `DataSourceBuilder`. Follow every step in order. This is Step 3 of 3.
-
----
-
-## Prerequisites
-
-- **Step 1 complete**: `pom.xml` already includes `ebean-postgres`, `ebean-maven-plugin`,
-  and `querybean-generator` (see `add-ebean-postgres-maven-pom.md`)
-- **Step 2 complete**: Test container setup is working and `mvn verify` passes
-  (see `add-ebean-postgres-test-container.md`)
-- **Avaje Inject** is on the classpath (e.g. `io.avaje:avaje-inject`)
-- A configuration source is available at runtime (e.g. `avaje-config` reading
-  `application.yml` or environment variables)
-- The following configuration keys are resolvable at runtime (adapt names to your project):
-  | Key | Description |
-  |-----|-------------|
-  | `db_url` | JDBC URL for the master/write connection |
-  | `db_user` | Database username |
-  | `db_pass` | Database password |
-  | `db_master_min_connections` | Minimum pool size (default: 1) |
-  | `db_master_initial_connections` | Initial pool size at startup — set high to pre-warm on pod start (see K8s note below) |
-  | `db_master_max_connections` | Maximum pool size (default: 200) |
-
----
-
-## Step 1 — Locate or create the `@Factory` class
-
-Look for an existing Avaje Inject `@Factory`-annotated class in the project
-(often named `AppConfig`, `DatabaseConfig`, or similar). If one exists, add the new
-`@Bean` method to it. If none exists, create one:
-
-```java
-package com.example.configuration;
-
-import io.avaje.inject.Bean;
-import io.avaje.inject.Factory;
-
-@Factory
-class DatabaseConfig {
-    // beans will be added in the steps below
-}
-```
-
----
-
-## Step 2 — Add the `Database` bean method (minimal — master datasource only)
-
-Add the following `@Bean` method to the `@Factory` class. This creates an Ebean
-`Database` backed by a single master (read-write) PostgreSQL datasource.
-
-```java
-import io.ebean.Database;
-import io.ebean.datasource.DataSourceBuilder;
-
-@Bean
-Database database() {
-    var dataSource = DataSourceBuilder.create()
-        .url(/* resolve from config, e.g.: */ Config.get("db_url"))
-        .username(Config.get("db_user"))
-        .password(Config.get("db_pass"))
-        .driver("org.postgresql.Driver")
-        .schema("myschema")                    // set to your target schema
-        .applicationName("my-app")             // visible in pg_stat_activity
-        .minConnections(Config.getInt("db_master_min_connections", 1))
-        .initialConnections(Config.getInt("db_master_initial_connections", 10))
-        .maxConnections(Config.getInt("db_master_max_connections", 200));
-
-    return Database.builder()
-        .name("db")                            // logical name for this Database instance
-        .dataSourceBuilder(dataSource)
-        .build();
-}
-```
-
-### Field guidance
-
-| Field | Notes |
-|-------|-------|
-| `url` | Full JDBC URL, e.g. `jdbc:postgresql://host:5432/dbname` |
-| `schema` | The Postgres schema Ebean should use (omit if using `public`) |
-| `applicationName` | Shown in `pg_stat_activity.application_name`; helps with DB-side diagnostics |
-| `name("db")` | Logical Ebean database name; relevant if multiple Database instances exist |
-| `minConnections` | Connections kept open at all times; pool will not shrink below this |
-| `initialConnections` | Connections opened at startup; see K8s warm-up note below |
-| `maxConnections` | Hard upper limit on concurrent connections |
-
-### Connection pool sizing for Kubernetes (and similar orchestrated environments)
-
-When a pod starts in Kubernetes it will receive live traffic as soon as it passes
-readiness checks — often before the connection pool has had a chance to grow to handle
-the load. This can cause latency spikes on the first wave of requests while the pool
-expands one connection at a time.
-
-Use `initialConnections` to **pre-warm the pool at startup** so it is already sized
-for peak load when the pod goes live:
-
-```
-minConnections:     2    ← floor; pool will shrink back here when idle
-initialConnections: 20   ← opened at pod start, before first request arrives
-maxConnections:     50   ← hard ceiling
-```
-
-The lifecycle is:
-1. **Pod starts** — pool opens `initialConnections` connections immediately.
-2. **Pod receives traffic** — pool is already at capacity; no growth latency.
-3. **Traffic drops** — idle connections are closed; pool trims back toward `minConnections`.
-4. **Next traffic spike** — pool grows again up to `maxConnections` on demand.
-
-Set `initialConnections` to a value high enough that the pool does not need to grow
-during the first minute of live traffic. A common starting point is 50–75% of
-`maxConnections`.
-
----
-
-## Step 3 — Inject configuration via a constructor or config helper (recommended)
-
-Rather than calling `Config.get(...)` inline, inject a typed config helper or the
-Avaje `Configuration` bean if one is available. This makes the factory testable and
-keeps the wiring explicit. For example:
-
-```java
-@Bean
-Database database(Configuration config) {
-    String url  = config.get("db_url");
-    String user = config.get("db_user");
-    String pass = config.get("db_pass");
-    int    min  = config.getInt("db_master_min_connections", 1);
-    int    init = config.getInt("db_master_initial_connections", 10);
-    int    max  = config.getInt("db_master_max_connections", 200);
-
-    var dataSource = DataSourceBuilder.create()
-        .url(url)
-        .username(user)
-        .password(pass)
-        .driver("org.postgresql.Driver")
-        .schema("myschema")
-        .applicationName("my-app")
-        .minConnections(min)
-        .initialConnections(init)
-        .maxConnections(max);
-
-    return Database.builder()
-        .name("db")
-        .dataSourceBuilder(dataSource)
-        .skipDataSourceCheck(true)
-        .build();
-}
-```
-
-If the project has a dedicated config-wrapper class (a `@Component` that reads config
-keys), accept it as a parameter instead of `Configuration`.
-
----
-
-## Step 4 (Optional) — Add a read-only datasource
-
-For production services that have a separate read-replica, add a second
-`DataSourceBuilder` for read-only queries and wire it via
-`readOnlyDataSourceBuilder(...)`. The read-only datasource:
-
-- Uses `readOnly(true)` and `autoCommit(true)` (Ebean routes read queries there automatically)
-- Typically has a higher max connection count than the master
-- Benefits from a prepared-statement cache (`pstmtCacheSize`)
-
-```java
-@Bean
-Database database(Configuration config) {
-    String masterUrl   = config.get("db_url");
-    String readOnlyUrl = config.get("db_url_readonly");
-    String user        = config.get("db_user");
-    String pass        = config.get("db_pass");
-
-    var masterDataSource = buildDataSource(user, pass)
-        .url(masterUrl)
-        .minConnections(config.getInt("db_master_min_connections", 1))
-        .initialConnections(config.getInt("db_master_initial_connections", 10))
-        .maxConnections(config.getInt("db_master_max_connections", 50));
-
-    var readOnlyDataSource = buildDataSource(user, pass)
-        .url(readOnlyUrl)
-        .readOnly(true)
-        .autoCommit(true)
-        .pstmtCacheSize(250)          // cache up to 250 prepared statements per connection
-        .maxInactiveTimeSecs(600)     // close idle connections after 10 minutes
-        .minConnections(config.getInt("db_readonly_min_connections", 2))
-        .initialConnections(config.getInt("db_readonly_initial_connections", 10))
-        .maxConnections(config.getInt("db_readonly_max_connections", 200));
-
-    return Database.builder()
-        .name("db")
-        .dataSourceBuilder(masterDataSource)
-        .readOnlyDataSourceBuilder(readOnlyDataSource)
-        .build();
-}
-
-private static DataSourceBuilder buildDataSource(String user, String pass) {
-    return DataSourceBuilder.create()
-        .username(user)
-        .password(pass)
-        .driver("org.postgresql.Driver")
-        .schema("myschema")
-        .applicationName("my-app")
-        .addProperty("prepareThreshold", "2");   // PostgreSQL: server-side prepared statements
-}
-```
-
-### Additional configuration keys for the read-only datasource
-
-| Key | Description | Default |
-|-----|-------------|---------|
-| `db_url_readonly` | JDBC URL for the read replica | — |
-| `db_master_initial_connections` | Initial master pool size at startup | 10 |
-| `db_readonly_min_connections` | Minimum pool size | 2 |
-| `db_readonly_initial_connections` | Initial pool size at startup | same as min |
-| `db_readonly_max_connections` | Maximum pool size | 20 |
-
----
-
-## Step 5 (Optional) — Enable the migration runner
-
-If the project uses Ebean's built-in DB migration runner to apply SQL migrations on
-startup, enable it on the `DatabaseBuilder`:
-
-```java
-return Database.builder()
-    .name("db")
-    .dataSourceBuilder(dataSource)
-    .runMigration(true)          // run pending migrations on startup
-    .build();
-```
-
-This is equivalent to setting `ebean.migration.run=true` in `application.properties`
-but is preferred because it keeps all database configuration in one place. To make it
-conditional (e.g. only in non-production environments):
-
-```java
-.runMigration(config.getBoolean("db.runMigrations", false))
-```
-
-See the DB migration generation guide (`add-ebean-db-migration-generation.md`) for
-full details on generating and managing migration files.
-
----
-
-## See Also
-
-For advanced connection pool configuration, production deployment patterns, and connection
-validation best practices, see the [ebean-datasource guides](https://github.com/ebean-orm/ebean-datasource/tree/master/docs/guides/):
-
-- **[Creating DataSource Pools](https://github.com/ebean-orm/ebean-datasource/blob/master/docs/guides/create-datasource-pool.md)** — Covers read-only pools (`readOnly(true)` + `autoCommit(true)`), Kubernetes deployment strategies using `initialConnections`, and AWS Lambda optimization
-- **[AWS Aurora Read-Write Split](https://github.com/ebean-orm/ebean-datasource/blob/master/docs/guides/aws-aurora-read-write-split.md)** — Setting up dual DataSources with Aurora reader and writer endpoints, including Ebean secondary datasource routing
-- **[Connection Validation Best Practices](https://github.com/ebean-orm/ebean-datasource/blob/master/docs/guides/connection-validation-best-practices.md)** — Why `Connection.isValid()` is the recommended default and when (rarely) explicit `heartbeatSql` is needed
-
----
-
-## Verification
-
-1. Start the application (or run `mvn test -pl <your-module>`).
-2. Look for log output similar to:
-
-   ```
-   INFO  o.a.datasource.pool.ConnectionPool - DataSourcePool [db] autoCommit[false] min[1] max[5]
-   INFO  io.ebean.internal.DefaultContainer - DatabasePlatform name:db platform:postgres
-   ```
-
-3. If you see `DataSourcePool` and `DatabasePlatform` log lines, Ebean is connected and
-   the database bean is wired correctly.
-
----
-
-## Troubleshooting
-
-| Symptom | Likely cause | Fix |
-|---------|-------------|-----|
-| `ClassNotFoundException: org.postgresql.Driver` | PostgreSQL JDBC driver missing | Add `org.postgresql:postgresql` dependency (see Step 1 guide) |
-| `Cannot connect to database` at startup | DB unreachable but `skipDataSourceCheck` is `false` | Set `.skipDataSourceCheck(true)` |
-| Ebean enhancement warnings in logs | `ebean-maven-plugin` not configured | Complete Step 1 guide |
-| `NullPointerException` reading config key | Config key not defined | Add the key to `application.yml` or environment |
-
----
-
-## Related
-
-The test container setup (Step 2) should already be complete and passing
-before this step. See `add-ebean-postgres-test-container.md`.

docs/guides/add-ebean-postgres-maven-pom.md

@@ -1,285 +0,0 @@
-# Guide: Add Ebean ORM (PostgreSQL) to an Existing Maven Project — Step 1: POM Setup
-
-## Purpose
-
-This guide provides step-by-step instructions for modifying an existing Maven `pom.xml`
-to add Ebean ORM with PostgreSQL support. Follow every step in order. This is Step 1 of 3.
-
----
-
-## Prerequisites
-
-- An existing Maven project (`pom.xml` already exists)
-- Java 11 or higher
-- The project does **not** yet include any Ebean dependencies
-
----
-
-## Step 0 — Gather requirements from the user
-
-Before modifying any files, ask the user the following questions to determine
-the correct setup path. Record the answers — they affect dependency choices
-in this step and the approach used in Steps 2 and 3.
-
-### Mandatory gate (do not skip)
-
-- Do **not** continue to Step 1+ until the DI path is explicitly recorded.
-- Do **not** infer the **None** path by default. Use **None** only when the user explicitly confirms no DI framework.
-- If the user asks for a partial action (for example, "do only step 3"), keep the previously selected DI path; do not switch paths implicitly.
-
-### DI path precedence (when user has not answered yet)
-
-Use this precedence order:
-
-1. Existing project context (highest priority): if dependencies/config already show Avaje Inject or Spring, select that path.
-2. Explicit user answer in this guide's questions.
-3. Recommended default only when context is genuinely unknown: Avaje Inject.
-
-If context remains ambiguous, ask one multiple-choice clarification question and wait for the answer before editing files.
-
-### Question 1: Dependency injection framework
-
-> "Does this project use (or will it use) a DI framework? If so, which one?"
-
-| Answer | Effect |
-|--------|--------|
-| **Avaje Inject** | Add `avaje-inject` + `avaje-inject-test` dependencies; use `@TestScope @Factory` for test container (Step 2); use `@Factory`/`@Bean` for production database (Step 3) |
-| **Spring** | Use Spring `@TestConfiguration` for test container (Step 2); use Spring `@Configuration`/`@Bean` for production database (Step 3) |
-| **None** | Use declarative `application-test.yaml` for test container (Step 2); use programmatic `Database.builder()` directly in application code (Step 3) |
-
-### Question 2: PostGIS
-
-> "Do you need PostGIS spatial extensions (geometry types, spatial queries)?"
-
-| Answer | Effect |
-|--------|--------|
-| **Yes** | Use `PostgisContainer` in test setup (Step 2); may need `net.postgis:postgis-jdbc` dependency |
-| **No** | Use `PostgresContainer` in test setup (Step 2) |
-
-### Question 3: Read replica
-
-> "Does your production environment use a separate read-replica (read-only) database?"
-
-| Answer | Effect |
-|--------|--------|
-| **Yes** | Configure a read-only `DataSourceBuilder` in production database config (Step 3) |
-| **No** | Single datasource only (Step 3) |
-
-### Defaults
-
-If the user is unsure or setting up a new project, recommend:
-- **Avaje Inject** (lightweight, fast compile-time DI)
-- **No PostGIS** (can be added later)
-- **No read replica** (can be added later)
-
----
-
-## Step 1 — Define the Ebean version property
-
-Open the module's `pom.xml` (the one that will use Ebean directly, i.e. the module
-containing the database configuration and entity classes).
-
-Inside the `<properties>` block, add the `ebean.version` property if it does not
-already exist:
-
-```xml
-<properties>
-    <!-- add this line; use latest stable from https://github.com/ebean-orm/ebean/releases -->
-    <ebean.version>17.2.0</ebean.version>
-</properties>
-```
-
-> If the project has a parent POM that already defines `ebean.version`, skip this step.
-
----
-
-## Step 2 — Add the PostgreSQL JDBC driver dependency
-
-Inside the `<dependencies>` block, add the PostgreSQL JDBC driver:
-
-```xml
-<dependency>
-    <groupId>org.postgresql</groupId>
-    <artifactId>postgresql</artifactId>
-    <version>42.7.8</version>
-</dependency>
-```
-
-> Check [Maven Central](https://central.sonatype.com/artifact/org.postgresql/postgresql)
-> for the latest version. If the parent POM manages the PostgreSQL version, omit the
-> `<version>` tag.
-
----
-
-## Step 3 — Add the Ebean PostgreSQL platform dependency
-
-Inside the `<dependencies>` block, add the Ebean Postgres platform dependency:
-
-```xml
-<dependency>
-    <groupId>io.ebean</groupId>
-    <artifactId>ebean-postgres</artifactId>
-    <version>${ebean.version}</version>
-</dependency>
-```
-
-This single artifact pulls in the Ebean core, the datasource connection pool
-(`ebean-datasource`), and all Postgres-specific support.
-
----
-
-## Step 4 — Add the ebean-test dependency (test scope)
-
-`ebean-test` configures Ebean for tests and enables automatic Docker container management
-for Postgres test instances:
-
-```xml
-<!-- test dependencies -->
-<dependency>
-    <groupId>io.ebean</groupId>
-    <artifactId>ebean-test</artifactId>
-    <version>${ebean.version}</version>
-    <scope>test</scope>
-</dependency>
-```
-
----
-
-## Step 4b — Add DI framework dependencies (if applicable)
-
-If the user chose **Avaje Inject** in Step 0, add the following dependencies and
-annotation processor. Skip this step if the user chose Spring or no DI.
-
-### Dependencies
-
-```xml
-<dependency>
-    <groupId>io.avaje</groupId>
-    <artifactId>avaje-inject</artifactId>
-    <version>11.5</version>
-</dependency>
-<dependency>
-    <groupId>io.avaje</groupId>
-    <artifactId>avaje-inject-test</artifactId>
-    <version>11.5</version>
-    <scope>test</scope>
-</dependency>
-```
-
-> Check [Maven Central](https://central.sonatype.com/artifact/io.avaje/avaje-inject)
-> for the latest version.
-
-### Annotation processor
-
-The `avaje-inject-generator` must be added to the `annotationProcessorPaths` in
-`maven-compiler-plugin` (added in Step 6 below). When adding both processors,
-the final `<annotationProcessorPaths>` block should include both:
-
-```xml
-<annotationProcessorPaths>
-    <path> <!-- generate ebean query beans -->
-        <groupId>io.ebean</groupId>
-        <artifactId>querybean-generator</artifactId>
-        <version>${ebean.version}</version>
-    </path>
-    <path> <!-- generate avaje-inject DI code -->
-        <groupId>io.avaje</groupId>
-        <artifactId>avaje-inject-generator</artifactId>
-        <version>11.5</version>
-    </path>
-</annotationProcessorPaths>
-```
-
----
-
-## Step 5 — Add the ebean-maven-plugin (bytecode enhancement)
-
-Ebean requires bytecode enhancement to provide dirty-checking and lazy-loading.
-The `ebean-maven-plugin` performs this enhancement at build time.
-
-Inside the `<build><plugins>` block, add:
-
-```xml
-<plugin> <!-- perform ebean enhancement -->
-    <groupId>io.ebean</groupId>
-    <artifactId>ebean-maven-plugin</artifactId>
-    <version>${ebean.version}</version>
-    <extensions>true</extensions>
-</plugin>
-```
-
----
-
-## Step 6 — Add the querybean-generator annotation processor
-
-The `querybean-generator` annotation processor generates type-safe query bean classes
-at compile time. It must be registered as an `annotationProcessorPath` inside
-`maven-compiler-plugin`.
-
-### Case A — No existing `maven-compiler-plugin` configuration
-
-Add the full plugin entry to `<build><plugins>`:
-
-```xml
-<plugin>
-    <groupId>org.apache.maven.plugins</groupId>
-    <artifactId>maven-compiler-plugin</artifactId>
-    <version>3.15.0</version>
-    <configuration>
-        <annotationProcessorPaths>
-            <path> <!-- generate ebean query beans -->
-                <groupId>io.ebean</groupId>
-                <artifactId>querybean-generator</artifactId>
-                <version>${ebean.version}</version>
-            </path>
-        </annotationProcessorPaths>
-    </configuration>
-</plugin>
-```
-
-### Case B — `maven-compiler-plugin` already exists with `<annotationProcessorPaths>`
-
-Locate the existing `<annotationProcessorPaths>` block inside the existing
-`maven-compiler-plugin` entry and add the new `<path>` inside it. Do **not** add a
-second `<configuration>` block or a second `<annotationProcessorPaths>` block.
-
-Example — if the existing block already has a path for, say, `avaje-nima-generator`:
-
-```xml
-<annotationProcessorPaths>
-    <path>
-        <groupId>io.avaje</groupId>
-        <artifactId>avaje-nima-generator</artifactId>
-        <version>${avaje-nima.version}</version>
-    </path>
-    <!-- ADD the new path here, inside the existing block -->
-    <path>
-        <groupId>io.ebean</groupId>
-        <artifactId>querybean-generator</artifactId>
-        <version>${ebean.version}</version>
-    </path>
-</annotationProcessorPaths>
-```
-
----
-
-## Verification
-
-Run the following to confirm the POM is valid and both main and test sources compile:
-
-```bash
-mvn test-compile
-```
-
-Expected result: `BUILD SUCCESS` with no errors from Ebean or the annotation processor.
-Using `test-compile` rather than `compile` ensures test dependencies and test
-source files are also verified.
-
----
-
-## Next Step
-
-Proceed to **Step 2: Test container setup**
-(`add-ebean-postgres-test-container.md`) to wire an injectable test `Database`
-backed by `ebean-test` containers. Verify with `mvn verify` before continuing
-to production database configuration.

docs/guides/add-ebean-postgres-test-container.md

@@ -1,435 +0,0 @@
-# Guide: Add Ebean ORM (PostgreSQL) to an Existing Maven Project - Step 2: Test Container Setup
-
-## Purpose
-
-This guide provides step-by-step instructions for setting up a PostgreSQL Docker
-container for tests, exposing an `io.ebean.Database` instance for use in test
-classes. This is Step 2 of 3.
-
-Complete this step before configuring the production database in Step 3. Getting
-the test container working first gives you a fast feedback loop - you can verify
-entity changes compile, enhance, and persist correctly with `mvn verify` before
-wiring up production datasource configuration.
-
----
-
-## Prerequisites
-
-- **Step 1 complete**: `pom.xml` includes `ebean-postgres`, `ebean-maven-plugin`,
-  `querybean-generator`, and **`ebean-test`** as a test-scoped dependency
-  (see `add-ebean-postgres-maven-pom.md`)
-- **Step 0 answers recorded**: DI framework choice and PostGIS requirement
-- **Docker** is installed and running on the developer machine
-
----
-
-## Overview: Choosing your approach
-
-The approach depends on the DI framework choice made in Step 0:
-
-| DI framework | Approach | How |
-|--------------|----------|-----|
-| **Avaje Inject** | Programmatic | `@TestScope @Factory` class with injectable `Database` bean |
-| **Spring** | Programmatic | `@TestConfiguration` class with `@Bean` methods |
-| **None** | Declarative | `application-test.yaml` + plain JUnit test |
-
-Follow the path that matches your choice below.
-
----
-
-## Path A — Programmatic with Avaje Inject (recommended)
-
-This approach uses `@TestScope @Factory` to expose the container and `Database`
-as injectable beans. It offers more control (image mirrors, custom config) and
-makes `Database` directly injectable into test classes.
-
-### A.1 — Verify Avaje Inject test dependencies
-
-Confirm the following are present in `pom.xml` (in addition to `ebean-test`):
-
-```xml
-<dependency>
-    <groupId>io.avaje</groupId>
-    <artifactId>avaje-inject</artifactId>
-    <version>${avaje-inject.version}</version>
-</dependency>
-<dependency>
-    <groupId>io.avaje</groupId>
-    <artifactId>avaje-inject-test</artifactId>
-    <version>${avaje-inject.version}</version>
-    <scope>test</scope>
-</dependency>
-```
-
-And the `avaje-inject-generator` annotation processor in `maven-compiler-plugin`:
-
-```xml
-<path>
-    <groupId>io.avaje</groupId>
-    <artifactId>avaje-inject-generator</artifactId>
-    <version>${avaje-inject.version}</version>
-</path>
-```
-
-### A.2 — Create a `@TestScope @Factory` class
-
-Create a new class in the test source tree (e.g., `src/test/java/.../testconfig/TestConfiguration.java`):
-
-```java
-package com.example.testconfig;
-
-import io.avaje.inject.Bean;
-import io.avaje.inject.Factory;
-import io.avaje.inject.test.TestScope;
-import io.ebean.Database;
-
-@TestScope
-@Factory
-class TestConfiguration {
-    // bean methods added below
-}
-```
-
-### A.3 — Add a container bean and a Database bean
-
-#### Plain PostgreSQL
-
-```java
-import io.ebean.test.containers.PostgresContainer;
-
-@TestScope
-@Factory
-class TestConfiguration {
-
-    @Bean
-    PostgresContainer postgres() {
-        return PostgresContainer.builder("17")   // Postgres image version
-            .dbName("my_app")                    // database to create inside the container
-            .build()
-            .start();
-    }
-
-    @Bean
-    Database database(PostgresContainer container) {
-        return container.ebean()
-            .builder()
-            .build();
-    }
-}
-```
-
-#### PostGIS (PostgreSQL + PostGIS extension)
-
-Use `PostgisContainer` instead. The default image is
-`ghcr.io/baosystems/postgis:{version}` and the extensions `hstore`, `pgcrypto`,
-and `postgis` are installed automatically.
-
-```java
-import io.ebean.test.containers.PostgisContainer;
-
-@TestScope
-@Factory
-class TestConfiguration {
-
-    @Bean
-    PostgisContainer postgres() {
-        return PostgisContainer.builder("17")
-            .dbName("my_app")
-            .build()
-            .start();
-    }
-
-    @Bean
-    Database database(PostgisContainer container) {
-        return container.ebean()
-            .builder()
-            .build();
-    }
-}
-```
-
-#### Key differences
-
-| | PostgresContainer | PostgisContainer |
-|---|---|---|
-| Docker image | `postgres:{version}` | `ghcr.io/baosystems/postgis:{version}` |
-| Default extensions | `hstore, pgcrypto` | `hstore, pgcrypto, postgis` |
-| Default port | 6432 | 6432 |
-| Optional LW mode | — | `.useLW(true)` (see Optional section) |
-
-### A.4 — Write a test
-
-Annotate the test class with `@InjectTest` and inject `Database` with `@Inject`:
-
-```java
-package com.example.testconfig;
-
-import io.avaje.inject.test.InjectTest;
-import io.ebean.Database;
-import jakarta.inject.Inject;
-import org.junit.jupiter.api.Test;
-
-import static org.assertj.core.api.Assertions.assertThat;
-
-@InjectTest
-class DatabaseTest {
-
-    @Inject
-    Database database;
-
-    @Test
-    void database_isAvailable() {
-        assertThat(database).isNotNull();
-    }
-}
-```
-
-### A.5 — Verify
-
-```bash
-mvn verify
-```
-
-Expected log output:
-
-```
-INFO  Container ut_postgres running with port:6432 ...
-INFO  connectivity confirmed for ut_postgres
-INFO  DataSourcePool [my_app] autoCommit[false] ...
-INFO  DatabasePlatform name:my_app platform:postgres
-INFO  Executing db-create-all.sql - ...
-```
-
-**Important:** Verify this step passes with `mvn verify` before proceeding to
-Step 3 (production database configuration).
-
----
-
-## Path B — Programmatic with Spring
-
-Use Spring’s `@TestConfiguration` to provide the container and `Database` beans.
-
-### B.1 — Create a `@TestConfiguration` class
-
-```java
-package com.example.testconfig;
-
-import io.ebean.Database;
-import io.ebean.test.containers.PostgresContainer;
-import org.springframework.boot.test.context.TestConfiguration;
-import org.springframework.context.annotation.Bean;
-import org.springframework.context.annotation.Primary;
-
-@TestConfiguration
-class TestDatabaseConfig {
-
-    @Bean
-    PostgresContainer postgres() {
-        return PostgresContainer.builder("17")
-            .dbName("my_app")
-            .build()
-            .start();
-    }
-
-    @Primary
-    @Bean
-    Database database(PostgresContainer container) {
-        return container.ebean()
-            .builder()
-            .build();
-    }
-}
-```
-
-For PostGIS, use `PostgisContainer` instead (same pattern as Path A).
-
-### B.2 — Write a test
-
-```java
-package com.example;
-
-import io.ebean.Database;
-import org.junit.jupiter.api.Test;
-import org.springframework.beans.factory.annotation.Autowired;
-import org.springframework.boot.test.context.SpringBootTest;
-
-import static org.assertj.core.api.Assertions.assertThat;
-
-@SpringBootTest
-class DatabaseTest {
-
-    @Autowired
-    Database database;
-
-    @Test
-    void database_isAvailable() {
-        assertThat(database).isNotNull();
-    }
-}
-```
-
-### B.3 — Verify
-
-Run `mvn verify` and confirm the same log output as Path A.
-
----
-
-## Path C — Declarative (no DI framework)
-
-This is the simplest approach but offers less control. `ebean-test` reads a
-YAML config file and automatically manages the Docker container and `Database`
-instance. Use this when the project has no DI framework.
-
-### C.1 — Create `application-test.yaml`
-
-Create `src/test/resources/application-test.yaml`:
-
-```yaml
-ebean:
-  test:
-    platform: postgres
-    ddlMode: dropCreate
-    dbName: my_app
-```
-
-For PostGIS, use `platform: postgis` instead.
-
-### C.2 — Write a test
-
-Use `DB.getDefault()` to obtain the `Database` instance:
-
-```java
-package com.example;
-
-import io.ebean.DB;
-import io.ebean.Database;
-import org.junit.jupiter.api.Test;
-
-import static org.assertj.core.api.Assertions.assertThat;
-
-class DatabaseTest {
-
-    @Test
-    void database_isAvailable() {
-        Database database = DB.getDefault();
-        assertThat(database).isNotNull();
-    }
-}
-```
-
-### C.3 — Verify
-
-```bash
-mvn verify
-```
-
-Expected log output:
-
-```
-INFO  Container ut_postgres running with port:6432 ...
-INFO  connectivity confirmed for ut_postgres
-INFO  DataSourcePool [my_app] autoCommit[false] ...
-INFO  DatabasePlatform name:my_app platform:postgres
-```
-
-**Important:** Verify this passes before proceeding to Step 3.
-
-Skip to [Optional configurations](#optional-configurations) or proceed to Step 3.
-
----
-
-## Optional configurations
-
-### Image mirror (for CI / private registry)
-
-If CI builds pull images from a private registry (e.g., AWS ECR) instead of Docker Hub
-or GitHub Container Registry, specify a mirror. The mirror is **only used in CI** -
-it is ignored on local developer machines (where Docker Hub / GHCR is used directly).
-
-```java
-@Bean
-PostgresContainer postgres() {
-    return PostgresContainer.builder("16")
-        .dbName("my_app")
-        .mirror("123456789.dkr.ecr.ap-southeast-2.amazonaws.com/mirrored")
-        .build()
-        .start();
-}
-```
-
-Alternatively, set the mirror globally via a system property or
-`ebean.test.containers.mirror` in a properties file, avoiding code changes per project.
-
-### Read-only datasource (for tests using read-replica simulation)
-
-Call `.autoReadOnlyDataSource(true)` on the `DatabaseBuilder` to automatically
-create a second read-only datasource pointing at the same container:
-
-```java
-@Bean
-Database database(PostgresContainer container) {
-    return container.ebean()
-        .builder()
-        .autoReadOnlyDataSource(true)   // test read-only queries against same container
-        .build();
-}
-```
-
-### Dump metrics on shutdown
-
-Useful for performance analysis during test runs:
-
-```java
-@Bean
-Database database(PostgresContainer container) {
-    return container.ebean()
-        .builder()
-        .dumpMetricsOnShutdown(true)
-        .dumpMetricsOptions("loc,sql,hash")
-        .build();
-}
-```
-
-### PostGIS: LW mode (HexWKB)
-
-For PostGIS with DriverWrapperLW (HexWKB binary geometry encoding), set `.useLW(true)`.
-This switches the JDBC URL prefix to `jdbc:postgresql_lwgis://` and requires the
-`net.postgis:postgis-jdbc` dependency on the test classpath:
-
-```xml
-<!-- add to pom.xml test dependencies when using useLW(true) -->
-<dependency>
-    <groupId>net.postgis</groupId>
-    <artifactId>postgis-jdbc</artifactId>
-    <version>2024.1.0</version>
-    <scope>test</scope>
-</dependency>
-```
-
-```java
-@Bean
-PostgisContainer postgres() {
-    return PostgisContainer.builder("16")
-        .dbName("my_app")
-        .useLW(true)    // use HexWKB + DriverWrapperLW
-        .build()
-        .start();
-}
-```
-
-> **Note**: LW mode is not required for most PostGIS use cases. Only enable it if
-> your entities use binary geometry types (e.g., `net.postgis.jdbc.geometry.Geometry`)
-> that require the `DriverWrapperLW` driver.
-
----
-
-## Keeping the container running (local development)
-
-By default, `ebean-test` stops the Docker container when tests finish. To keep it
-running between test runs (much faster for local development), create a marker file:
-
-```bash
-mkdir -p ~/.ebean && touch ~/.ebean/ignore-docker-shutdown
-```
-
-On CI servers, omit this file so containers are cleaned up after each build.

docs/guides/entity-bean-creation.md

@@ -1,797 +0,0 @@
-# Entity Bean Creation Guide for AI Agents
-
-**Target Audience:** AI systems (Claude, Copilot, ChatGPT, etc.)
-**Purpose:** Learn how to generate clean, idiomatic Ebean entity beans
-**Key Insight:** Ebean entity fields must be non-public (no public fields). Accessors don't need JavaBeans naming conventions; no manual equals/hashCode implementation is needed
-**Language:** Java
-**Framework:** Ebean ORM
-
----
-
-## Quick Rules
-
-Before writing entity code, remember:
-
-| Requirement | Needed? | Notes                                                                                                                 |
-|-------------|---------|-----------------------------------------------------------------------------------------------------------------------|
-| `@Entity` annotation | ✅ **YES** | Marks class as persistent entity                                                                                      |
-| `@Id` annotation | ✅ **YES** | Marks primary key field                                                                                               |
-| Getters/setters (or other accessors) | ✅ **YES** | Needed for application code to access fields. Naming can be JavaBeans, fluent, or custom — no specific convention required. |
-| Default constructor | ❌ **NO** | Not required. Ebean can instantiate without it.                                                                       |
-| equals/hashCode | ❌ **NO** | Ebean auto-enhances these at compile time.                                                                            |
-| toString() | ❌ **NO** | Ebean auto-enhances this. Don't implement with getters.                                                               |
-| `@Version` | ⚠️ **OPTIONAL** | Use for optimistic locking. Highly recommended.                                                                       |
-| `@WhenCreated` | ⚠️ **OPTIONAL** | Auto-timestamp creation time. Highly recommended. Use for audit trail.                                                |
-| `@WhenModified` | ⚠️ **OPTIONAL** | Auto-timestamp modification time. Highly recommended. Use for audit trail.                                            |
-
-**Critical:**
-- Prefer primitive `long` for `@Id` and `@Version`, NOT `Long` object.
-- Fields should be non-public: **private**, **protected**, or package-private.
-- If you add accessors, they do NOT need to follow Java bean conventions.
-
----
-
-## Naming Conventions: The D* (Domain) Prefix Pattern
-
-Entity beans represent internal domain/persistence model details. It's a common best practice in Ebean projects to use the **D* prefix** (D for Domain) for entity class names.
-
-**Why use D* prefix?**
-
-1. **Avoid name clashes with DTOs** - Your public API may have `Customer` (DTO), but your entity is `DCustomer` (Domain). They're clearly different.
-2. **Signal intent clearly** - The D prefix immediately tells developers "this is an internal domain class, not part of the public API"
-3. **Clarify conversions** - When converting `DCustomer` → `Customer` (DTO), the direction is obvious
-4. **Separate concerns** - API classes in one package (no prefix), domain classes in another (with D prefix)
-
-**Example naming pattern:**
-- Entity: `DCustomer`, `DOrder`, `DProduct`, `DInvoice`
-- DTO: `Customer`, `Order`, `Product`, `Invoice`
-- Converter: `DCustomerMapper.toDTO(DCustomer)` → `Customer`
-
-**Where to place entities:**
-- Entities: `com.example.domain.entity` (or `persistence`)
-- DTOs: `com.example.api.model` or `com.example.dto`
-
-**When to use D* prefix:**
-- ✅ **DO** use for entity beans (internal domain model)
-- ✅ **DO** use when you have parallel DTO classes with similar names
-- ❌ **DON'T** use for DTOs or public API classes
-- ❌ **DON'T** use if you have no DTOs and entities are your public API
-
-Example with and without prefix:
-
-```java
-// With D* prefix (recommended - allows both entity and DTO to exist)
-@Entity
-public class DCustomer {
-  @Id private long id;
-  private String name;
-  // ... entity-specific fields and methods
-}
-
-// Public API DTO (no D prefix)
-public record Customer(long id, String name) {
-  // ... conversion method
-}
-
-// Conversion
-public static Customer toDTO(DCustomer entity) {
-  return new Customer(entity.getId(), entity.getName());
-}
-```
-
-This naming convention is optional but highly recommended for projects with separate domain and API layers.
-
----
-
-## Minimal Entity (No Boilerplate)
-
-This is a complete, valid Ebean entity:
-
-```java
-@Entity
-public class Customer {
-  @Id
-  private long id;
-  private String name;
-
-  public long getId() {
-    return id;
-  }
-
-  public String getName() {
-    return name;
-  }
-
-  public void setName(String name) {
-    this.name = name;
-  }
-}
-```
-
-**Why this works:**
-- ✅ `@Entity` marks it as persistent
-- ✅ `@Id private long id` is the primary key
-- ✅ Private fields (Ebean does NOT support public fields without expert flags enabled)
-- ✅ Accessors can follow any naming convention, and can be omitted when field access is preferred
-- ✅ No default constructor needed
-- ✅ No equals/hashCode needed (Ebean enhances these)
-
-**What Ebean does at compile time:**
-- Enhances equals/hashCode based on @Id
-- Adds field change tracking
-- Enables lazy loading
-- Enhances toString()
-
-**Result:** Your entity is now fully functional with zero boilerplate.
-
----
-
-## Pattern 1: Basic Entity
-
-**Use this when:** You need a simple persistent object.
-
-```java
-@Entity
-public class Product {
-  @Id
-  private long id;
-  private String name;
-  private String description;
-  private BigDecimal price;
-
-  public long getId() {
-    return id;
-  }
-
-  public String getName() {
-    return name;
-  }
-
-  public void setName(String name) {
-    this.name = name;
-  }
-
-  public String getDescription() {
-    return description;
-  }
-
-  public void setDescription(String description) {
-    this.description = description;
-  }
-
-  public BigDecimal getPrice() {
-    return price;
-  }
-
-  public void setPrice(BigDecimal price) {
-    this.price = price;
-  }
-}
-```
-
-**What you get:**
-- Primary key: `id` (private field, accessed via getter)
-- Three properties: `name`, `description`, `price` (private fields, accessed via getters/setters)
-- Automatic equals/hashCode based on id
-- Full ORM functionality
-
----
-
-## Pattern 2: Entity with Audit Trail
-
-**Use this when:** You need to track who/when created/modified data.
-
-```java
-@Entity
-public class Order {
-  @Id
-  private long id;
-  @Version
-  private long version;
-  @WhenCreated
-  private Instant createdAt;
-  @WhenModified
-  private Instant modifiedAt;
-
-  private String orderNumber;
-  private BigDecimal totalAmount;
-
-  public long getId() {
-    return id;
-  }
-
-  public long getVersion() {
-    return version;
-  }
-
-  public Instant getCreatedAt() {
-    return createdAt;
-  }
-
-  public Instant getModifiedAt() {
-    return modifiedAt;
-  }
-
-  public String getOrderNumber() {
-    return orderNumber;
-  }
-
-  public void setOrderNumber(String orderNumber) {
-    this.orderNumber = orderNumber;
-  }
-
-  public BigDecimal getTotalAmount() {
-    return totalAmount;
-  }
-
-  public void setTotalAmount(BigDecimal totalAmount) {
-    this.totalAmount = totalAmount;
-  }
-}
-```
-
-**What you get:**
-- `version`: Optimistic locking (prevents concurrent update conflicts)
-- `createdAt`: Automatically set when inserted (Ebean manages this)
-- `modifiedAt`: Automatically updated on every modification (Ebean manages this)
-
-**Example usage:**
-```java
-// Create
-Order order = new Order();
-order.setOrderNumber("ORD-001");
-order.setTotalAmount(new BigDecimal("99.99"));
-database.save(order);  // createdAt is automatically set by Ebean
-
-// Modify
-order.setTotalAmount(new BigDecimal("109.99"));
-database.update(order);  // version incremented, modifiedAt updated automatically
-
-// Check when modified
-System.out.println(order.getModifiedAt());  // Current timestamp
-```
-
----
-
-## Pattern 3: Entity with Constructor
-
-**Use this when:** Domain logic requires initialization or validation.
-
-```java
-@Entity
-public class Invoice {
-  @Id
-  private long id;
-  @Version
-  private long version;
-
-  private String invoiceNumber;
-  private String customerName;
-  private BigDecimal amount;
-
-  public Invoice(String invoiceNumber, String customerName, BigDecimal amount) {
-    this.invoiceNumber = invoiceNumber;
-    this.customerName = customerName;
-    this.amount = amount;
-  }
-
-  public long getId() {
-    return id;
-  }
-
-  public long getVersion() {
-    return version;
-  }
-
-  public String getInvoiceNumber() {
-    return invoiceNumber;
-  }
-
-  public String getCustomerName() {
-    return customerName;
-  }
-
-  public BigDecimal getAmount() {
-    return amount;
-  }
-}
-```
-
-**When to add a constructor:**
-- ✅ Required fields must be set during creation
-- ✅ Validation needs to happen on initialization
-- ✅ Domain logic needs setup
-
-**When NOT to add:**
-- ❌ If users will just set fields afterwards anyway
-- ❌ If there are many optional fields
-
----
-
-## Pattern 4: Entity with Relationships
-
-**Use this when:** You need associations to other entities.
-
-```java
-@Entity
-public class Customer {
-  @Id
-  private long id;
-  @Version
-  private long version;
-  @WhenCreated
-  private Instant createdAt;
-
-  private String name;
-  private String email;
-
-  @OneToMany(mappedBy = "customer")
-  private List<Order> orders;  // Use List, not Set
-
-  @ManyToOne
-  private Address billingAddress;
-
-  public long getId() {
-    return id;
-  }
-
-  public long getVersion() {
-    return version;
-  }
-
-  public Instant getCreatedAt() {
-    return createdAt;
-  }
-
-  public String getName() {
-    return name;
-  }
-
-  public void setName(String name) {
-    this.name = name;
-  }
-
-  public String getEmail() {
-    return email;
-  }
-
-  public void setEmail(String email) {
-    this.email = email;
-  }
-
-  public List<Order> getOrders() {
-    return orders;
-  }
-
-  public Address getBillingAddress() {
-    return billingAddress;
-  }
-
-  public void setBillingAddress(Address billingAddress) {
-    this.billingAddress = billingAddress;
-  }
-}
-```
-
-**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
-
----
-
-## What NOT to Do (Anti-Patterns)
-
-### ❌ Anti-Pattern 1: Public Fields
-
-**DON'T:**
-```java
-@Entity
-public class Customer {
-  @Id public long id;  // ❌ Public field - not supported
-  public String name;  // ❌ Public field - not supported
-}
-```
-
-**DO:**
-```java
-@Entity
-public class Customer {
-  @Id
-  private long id;  // ✅ Private field with getter
-  private String name;  // ✅ Private field with accessors
-
-  public long getId() {
-    return id;
-  }
-
-  public String getName() {
-    return name;
-  }
-
-  public void setName(String name) {
-    this.name = name;
-  }
-}
-```
-
-**Why:** Ebean does NOT support public fields. Fields must be private and accessed via getters/setters or other accessor methods. Public fields bypass Ebean's tracking mechanisms and will cause data consistency issues.
-
----
-
-### ❌ Anti-Pattern 2: Use Long Object Instead of Primitive
-
-**DON'T:**
-```java
-@Entity
-public class Customer {
-  @Id
-  private Long id;  // ❌ Object type
-  private String name;
-}
-```
-
-**DO:**
-```java
-@Entity
-public class Customer {
-  @Id
-  private long id;  // ✅ Primitive type
-  private String name;
-}
-```
-
-**Why:** Performance, nullability semantics, Ebean optimization.
-
----
-
-### ❌ Anti-Pattern 3: Implement equals/hashCode
-
-**DON'T:**
-```java
-@Entity
-public class Customer {
-  @Id
-  private long id;
-  private String name;
-
-  @Override
-  public boolean equals(Object o) {  // ❌ Unnecessary
-    if (this == o) return true;
-    if (o == null || getClass() != o.getClass()) return false;
-    Customer customer = (Customer) o;
-    return id == customer.id;
-  }
-
-  @Override
-  public int hashCode() {  // ❌ Unnecessary
-    return Objects.hash(id);
-  }
-}
-```
-
-**DO:**
-```java
-@Entity
-public class Customer {
-  @Id
-  private long id;
-  private String name;
-
-  public long getId() {
-    return id;
-  }
-
-  public String getName() {
-    return name;
-  }
-
-  public void setName(String name) {
-    this.name = name;
-  }
-  // Ebean enhances equals/hashCode automatically
-}
-```
-
-**Why:** Ebean's enhancement is optimized for ORM operations. Your implementation might conflict with Ebean's tracking.
-
----
-
-### ❌ Anti-Pattern 4: Use Set for Collections
-
-**DON'T:**
-```java
-@Entity
-public class Customer {
-  @Id
-  private long id;
-
-  @OneToMany(mappedBy = "customer")
-  private Set<Order> orders;  // ❌ Set calls equals/hashCode before IDs assigned
-}
-```
-
-**DO:**
-```java
-@Entity
-public class Customer {
-  @Id
-  private long id;
-
-  @OneToMany(mappedBy = "customer")
-  private List<Order> orders;  // ✅ List doesn't require equals/hashCode on unsaved beans
-}
-```
-
-**Why:** Set calls equals/hashCode immediately. New beans don't have IDs yet, causing issues.
-
----
-
-### ❌ Anti-Pattern 5: toString() with Getters
-
-**DON'T:**
-```java
-@Entity
-public class Customer {
-  @Id
-  private long id;
-  private String name;
-
-  @Override
-  public String toString() {  // ❌ Uses getters
-    return "Customer{" +
-        "id=" + getId() +
-        ", name='" + getName() + '\'' +
-        '}';
-  }
-
-  public long getId() { return id; }
-  public String getName() { return name; }
-}
-```
-
-**Why:** In a debugger, toString() is called automatically. Getters can trigger lazy loading, changing debug behavior.
-
-**DO:** Either don't implement toString(), or access fields directly:
-```java
-@Override
-public String toString() {
-  return "Customer{" +
-      "id=" + id +
-      ", name='" + name + '\'' +
-      '}';
-}
-```
-
----
-
-### ❌ Anti-Pattern 6: @Column(name=...) for Naming Convention
-
-**DON'T:**
-```java
-@Entity
-public class Customer {
-  @Id
-  private long id;
-
-  @Column(name = "first_name")  // ❌ Unnecessary
-  private String firstName;
-}
-```
-
-**DO:**
-```java
-@Entity
-public class Customer {
-  @Id
-  private long id;
-
-  private String firstName;  // ✅ Ebean uses naming convention: first_name
-}
-```
-
-**Why:** Ebean's naming convention handles this automatically. Only use @Column when your database column doesn't match the convention.
-
----
-
-## What Ebean Enhancement Provides
-
-At compile time, Ebean enhances your entity classes:
-
-1. **equals/hashCode** - Based on @Id, optimal for ORM
-2. **Field change tracking** - Knows which fields were modified
-3. **Lazy loading** - Collections and relationships load on demand
-4. **Persistence context** - Manages identity and state
-5. **toString()** - Auto-implemented (don't override with getters)
-
-**Result:** Your entity bean is minimal, but fully featured.
-
----
-
-## Field Types
-
-**Recommended for ID/Version:**
-- `long` (primitive) ✅ Use this
-- `int` (primitive) ✅ Use this
-- `UUID` ✅ Use this
-
-**Not recommended:**
-- `Long` object ⚠️ Avoid (use primitive long)
-- `Integer` object ⚠️ Avoid (use primitive int)
-
-**For other fields:**
-- Use standard Java types: `String`, `BigDecimal`, `Instant`, `LocalDate`, etc.
-- Use primitives where nullable semantics don't apply: `int`, `long`, `boolean`
-- Use objects where null has meaning: `String`, `BigDecimal`, `LocalDate`
-
----
-
-## Example: Building an Entity Step by Step
-
-Start minimal, add what you need:
-
-**Step 1: Minimal**
-```java
-@Entity
-public class BlogPost {
-  @Id long id;
-  String title;
-  String content;
-
-  public long getId() { return id; }
-  public String getTitle() { return title; }
-  public void setTitle(String title) { this.title = title; }
-  public String getContent() { return content; }
-  public void setContent(String content) { this.content = content; }
-}
-```
-
-**Step 2: Add audit trail**
-```java
-@Entity
-public class BlogPost {
-  @Id long id;
-  @Version long version;
-  @WhenCreated Instant createdAt;
-  @WhenModified Instant modifiedAt;
-
-  String title;
-  String content;
-
-  public long getId() { return id; }
-  public long getVersion() { return version; }
-  public Instant getCreatedAt() { return createdAt; }
-  public Instant getModifiedAt() { return modifiedAt; }
-  public String getTitle() { return title; }
-  public void setTitle(String title) { this.title = title; }
-  public String getContent() { return content; }
-  public void setContent(String content) { this.content = content; }
-}
-```
-
-**Step 3: Add author relationship**
-```java
-@Entity
-public class BlogPost {
-  @Id long id;
-  @Version long version;
-  @WhenCreated Instant createdAt;
-  @WhenModified Instant modifiedAt;
-
-  String title;
-  String content;
-
-  @ManyToOne
-  Author author;
-
-  public long getId() { return id; }
-  public long getVersion() { return version; }
-  public Instant getCreatedAt() { return createdAt; }
-  public Instant getModifiedAt() { return modifiedAt; }
-  public String getTitle() { return title; }
-  public void setTitle(String title) { this.title = title; }
-  public String getContent() { return content; }
-  public void setContent(String content) { this.content = content; }
-  public Author getAuthor() { return author; }
-  public void setAuthor(Author author) { this.author = author; }
-}
-```
-
-**Step 4: Add constructor if needed**
-```java
-@Entity
-public class BlogPost {
-  @Id long id;
-  @Version long version;
-  @WhenCreated Instant createdAt;
-  @WhenModified Instant modifiedAt;
-
-  String title;
-  String content;
-
-  @ManyToOne
-  Author author;
-
-  public BlogPost(String title, String content, Author author) {
-    this.title = title;
-    this.content = content;
-    this.author = author;
-  }
-
-  public long getId() { return id; }
-  public long getVersion() { return version; }
-  public Instant getCreatedAt() { return createdAt; }
-  public Instant getModifiedAt() { return modifiedAt; }
-  public String getTitle() { return title; }
-  public void setTitle(String title) { this.title = title; }
-  public String getContent() { return content; }
-  public void setContent(String content) { this.content = content; }
-  public Author getAuthor() { return author; }
-  public void setAuthor(Author author) { this.author = author; }
-}
-```
-
-Each step adds only what's necessary for the entity structure. Accessors are always included so application code can use the entity.
-
----
-
-## Usage Examples
-
-### Creating and saving
-```java
-Customer customer = new Customer();
-customer.setName("Alice");
-database.save(customer);  // id auto-generated
-```
-
-### Finding
-```java
-Customer found = database.find(Customer.class, 1);
-System.out.println(found.getName());
-```
-
-### Updating
-```java
-found.setName("Bob");
-database.update(found);  // version auto-incremented
-```
-
-### Collections (relationships)
-```java
-Customer customer = database.find(Customer.class, 1);
-List<Order> orders = customer.getOrders();  // Lazy loads automatically
-```
-
----
-
-## Summary for AI Agents
-
-When generating Ebean entity beans:
-
-✅ **DO:**
-- Use primitive `long` for @Id and @Version
-- Keep entities minimal (just fields + @Entity + @Id)
-- Use @Version for concurrency control
-- Use @WhenCreated/@WhenModified for audit trail
-- Use List for collections, not Set
-- Add constructors only if domain logic requires it
-- Add getters/setters for all fields that application code needs to read or write
-
-❌ **DON'T:**
-- Use Long object for @Id/@Version
-- Implement equals/hashCode
-- Implement toString() with getters
-- Use Set for @OneToMany/@ManyToMany
-- Add unnecessary @Column annotations
-- Add default constructors "just in case"
-
-**Result:** Clean, readable, maintainable entity beans with full ORM functionality and zero boilerplate.
-
----
-
-## Related Documentation
-
-- Entity Bean Best Practices: `/docs/best-practice/`
-- JPA Mapping Reference: `/docs/mapping/jpa/`
-- Ebean Extensions: `/docs/mapping/extensions/`
-- First Entity Guide: `/docs/intro/first-entity/`

docs/guides/immutable-bean-cache.md

@@ -1,136 +0,0 @@
-# Immutable bean cache for read-only references
-
-This guide shows how to use `ImmutableBeanCache` for read-mostly assoc-one
-references (for example `Label` references reused across many entities).
-
-Use this when you want:
-
-- fewer lazy-load SQL calls for assoc-one references via caching
-- reusable fetch-group-based loading for cache misses
-
----
-
-## Step 1 - Build an immutable cache (typical via builder)
-
-```java
-FetchGroup<Label> fetchGroup = FetchGroup.of(Label.class)
-  .select("version")
-  .fetch("labelTexts", "locale, localeText")
-  .build();
-
-ImmutableBeanCache<Label> labelCache = ImmutableBeanCaches.builder(Label.class)
-  .loading(database, fetchGroup)
-  .maxSize(10_000)
-  .maxIdleSeconds(300)
-  .maxSecondsToLive(6_000)
-  .build();
-```
-
-`loading(...)` uses the query shape:
-
-- `select(fetchGroup)`
-- `setUnmodifiable(true)`
-- `where().idIn(ids)`
-- `findMap()`
-
-Alternative domain example:
-
-```java
-FetchGroup<Customer> customerGroup = FetchGroup.of(Customer.class)
-  .select("name,version")
-  .fetch("billingAddress", "line1,city")
-  .fetch("shippingAddress", "line1,city")
-  .build();
-
-ImmutableBeanCache<Customer> customerCache = ImmutableBeanCaches.builder(Customer.class)
-  .loading(database, customerGroup)
-  .build();
-```
-
----
-
-## Step 2 - Attach cache to the root query
-
-```java
-AttributeDescriptor one = DB.find(AttributeDescriptor.class)
-  .setId(id)
-  .setUnmodifiable(true)
-  .using(labelCache)
-  .findOne();
-```
-
-`using(...)` is on the root query. Ebean will use this cache for matching
-bean types when resolving references.
-
----
-
-## Use loading helper for simple memoization
-
-If you don't need policy controls, use the shorthand helper:
-
-```java
-ImmutableBeanCache<Label> labelCache =
-  ImmutableBeanCaches.loading(Label.class, database, FetchGroup.of(Label.class, "version"));
-```
-
-With `ebean-core` on the classpath, builder policy settings are backed by core
-cache implementation (including periodic trim / eviction).
-
----
-
-## Unmodifiable vs mutable query behavior
-
-### Unmodifiable query path
-
-`setUnmodifiable(true)` disables lazy loading. If you need association content
-in cached beans make sure that is included in the fetch group.
-
-```java
-FetchGroup<Label> withTexts = FetchGroup.of(Label.class)
-  .select("version")
-  .fetch("labelTexts", "locale, localeText")
-  .build();
-```
-
-### Mutable query path
-
-On a mutable query (no `setUnmodifiable(true)`), references populated from the
-immutable cache are still mutable beans in that object graph. Additional
-unloaded properties can still lazy load as normal.
-
-Typical pattern:
-
-1. cache serves already-loaded reference properties (for example `version`)
-2. later access to unloaded properties (for example `labelTexts`) triggers
-   normal lazy loading
-
----
-
-## Understand secondary query behavior (`+query`, `+lazy`)
-
-When root queries execute secondary loads (`fetchQuery(...)` or `fetchLazy(...)`),
-the immutable caches configured on the root query are propagated to those
-secondary queries.
-
-That means assoc-one references resolved in secondary query paths can still hit
-the immutable cache.
-
----
-
-## Operational note (TTL / max size)
-
-Use `ImmutableBeanCaches.builder(...)` when you need explicit TTL/max-size
-policy. `ImmutableBeanCaches.loading(...)` remains the simple helper for
-loader-based memoization.
-
-
----
-
-## Testing checklist
-
-1. Hit / partial hit / miss behavior for `getAll(ids)`
-2. Unmodifiable path: no lazy SQL when reading loaded reference properties
-3. Mutable path: additional unloaded properties can still lazy load
-4. Secondary `fetchQuery` and `fetchLazy` paths inherit immutable caches
-5. If needed associations are in fetch group, assert no extra SQL for those
-   accesses

docs/guides/lombok-with-ebean-entity-beans.md

@@ -1,206 +0,0 @@
-# Guide: Using Lombok with Ebean Entity Beans
-
-## Purpose
-
-This guide explains which Lombok annotations are safe and recommended for Ebean
-entity beans, which ones to avoid, and why. It is written as prescriptive instructions
-for AI agents and developers.
-
----
-
-## The Core Rule
-
-> **Do NOT use `@Data` on Ebean entity beans.**
-
-Use `@Getter` + `@Setter` instead, with the optional `@Accessors(chain = true)` for
-a fluent setter style.
-
----
-
-## Why `@Data` is Incompatible with Ebean
-
-`@Data` is a convenience annotation that is equivalent to applying `@Getter`,
-`@Setter`, `@RequiredArgsConstructor`, `@ToString`, and `@EqualsAndHashCode` together.
-Three of those are problematic for Ebean entity beans:
-
-### 1. `@EqualsAndHashCode` (included in `@Data`) — breaks entity identity
-
-`@Data` generates `hashCode()` and `equals()` based on all non-static, non-transient
-fields. Ebean entity beans have identity semantics — two references to the same database
-row should be considered equal based on their `@Id` value, not field-by-field comparison.
-
-Problems caused:
-- Inconsistent `hashCode` before and after persist (the `@Id` field is `0` on a new
-  entity, then changes after insert — violating the `hashCode` contract for collections)
-- Entities placed in a `Set` or `HashMap` before saving will be unfindable after saving
-- Ebean's internal identity map and dirty checking can be confused
-
-### 2. `@ToString` (included in `@Data`) — triggers unexpected lazy loading
-
-`@Data` generates a `toString()` that accesses **all** fields, including
-`@OneToMany` and `@ManyToOne` associations. Accessing an unloaded lazy association
-outside of a transaction triggers a `LazyInitialisationException` or fires an unexpected
-SQL query, which can:
-- Cause subtle bugs in logging statements
-- Trigger N+1 queries in test output or debug logging
-- Fail with an exception if no active transaction exists
-
-### 3. `@RequiredArgsConstructor` (included in `@Data`) — unnecessary for Ebean
-
-Ebean does not require a default constructor — it can construct entity instances without
-one. `@RequiredArgsConstructor` therefore adds nothing useful to entity beans.
-
----
-
-## Recommended Annotation Set
-
-Use exactly these three Lombok annotations on every Ebean entity bean:
-
-```java
-@Entity
-@Getter
-@Setter
-@Accessors(chain = true)
-@Table(name = "my_table")
-public class MyEntity {
-    // ...
-}
-```
-
-| Annotation | Purpose |
-|---|---|
-| `@Getter` | Generates `getFoo()` / `isFoo()` accessor methods |
-| `@Setter` | Generates `setFoo(value)` mutator methods; Ebean enhancement intercepts these for dirty tracking |
-| `@Accessors(chain = true)` | Makes setters return `this`, enabling fluent/builder-style property setting |
-
----
-
-## `@Accessors(chain = true)` — Fluent Setter Style
-
-With `chain = true`, setters return `this` instead of `void`, allowing method chaining:
-
-```java
-// without chain = true (void setters)
-CMachine machine = new CMachine();
-machine.setMake("Toyota");
-machine.setModel("Hilux");
-machine.setStatus("active");
-
-// with @Accessors(chain = true)
-CMachine machine = new CMachine()
-    .setMake("Toyota")
-    .setModel("Hilux")
-    .setStatus("active");
-```
-
-This is particularly useful when building test data:
-
-```java
-CMachine machine = new CMachine()
-    .setGid(UUID.randomUUID())
-    .setMachineType("HV")
-    .setStatus("active")
-    .setMake("Komatsu")
-    .setModel("PC200");
-
-database.save(machine);
-```
-
-Ebean's bytecode enhancement is fully compatible with chained setters — the
-enhancement intercepts each `setFoo()` call to record which fields have been modified
-(dirty checking), regardless of whether the setter returns `void` or `this`.
-
----
-
-## `@Accessors(fluent = true)` — also compatible
-
-`@Accessors(fluent = true)` removes the `get`/`set`/`is` prefix, generating `name()`
-(getter) and `name(value)` (setter) instead of `getName()` and `setName(value)`.
-
-Ebean does **not** require JavaBeans naming conventions — it can work with any accessor
-method style, including fluent accessors with no prefix. `@Accessors(fluent = true)` is
-therefore compatible with Ebean.
-
-`@Accessors(chain = true)` is the more common choice in practice (it keeps the familiar
-`get`/`set` prefix while adding method chaining), but `fluent = true` is a valid
-alternative if that style is preferred consistently across the codebase.
-
----
-
-## Full Entity Bean Example
-
-```java
-package com.example.repository.data;
-
-import io.ebean.annotation.WhenCreated;
-import io.ebean.annotation.WhenModified;
-import jakarta.persistence.*;
-import lombok.Getter;
-import lombok.Setter;
-import lombok.experimental.Accessors;
-
-import java.time.Instant;
-import java.util.List;
-import java.util.UUID;
-
-@Entity
-@Getter
-@Setter
-@Accessors(chain = true)
-@Table(name = "machine")
-public class CMachine {
-
-    @Id
-    private long id;
-
-    @Version
-    private int version;
-
-    @Column(nullable = false, unique = true)
-    private UUID gid;
-
-    @Column(nullable = false, length = 10)
-    private String machineType;
-
-    @Column(length = 200)
-    private String make;
-
-    @Column(length = 200)
-    private String model;
-
-    @WhenCreated
-    private Instant created;
-
-    @WhenModified
-    private Instant lastModified;
-}
-```
-
----
-
-## Summary: Lombok Annotations and Ebean Compatibility
-
-| Lombok Annotation | Compatible? | Notes                                                                                                                                                             |
-|---|---|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `@Getter` | ✅ Safe | Use on every entity bean                                                                                                                                          |
-| `@Setter` | ✅ Safe | Use on every entity bean; enhancement intercepts these                                                                                                            |
-| `@Accessors(chain = true)` | ✅ Safe | Recommended for fluent construction style                                                                                                                         |
-| `@ToString` | ❌ Avoid | Ebean does a better job and handles recursion                                                                                                                     |
-| `@EqualsAndHashCode` | ❌ Avoid | Breaks entity identity and `@Id`-based equality                                                                                                                   |
-| `@Data` | ❌ Avoid | Includes `@EqualsAndHashCode` and `@ToString` — both problematic                                                                                                  |
-| `@Value` | ❌ Avoid | Makes fields final — incompatible with Ebean's field-level bytecode enhancement                                                                                   |
-| `@Accessors(fluent = true)` | ✅ Safe | Removes `get`/`set` prefix — Ebean does not require JavaBeans naming conventions and works with any accessor style                                                |
-| `@Builder` | ⚠️ Careful | Usable on non-entity helper/factory classes; on entity beans it requires a no-arg constructor alongside it and offers no advantage over `@Accessors(chain = true)` |
-
----
-
-## Relationship with Ebean Bytecode Enhancement
-
-Ebean's bytecode enhancement (applied by `ebean-maven-plugin` at build time) modifies
-the `setXxx()` methods of entity beans to:
-1. Mark the field as dirty (changed) so only modified fields are included in UPDATE statements
-2. Support lazy loading of associations when a getter is called on an unloaded field
-
-For this to work correctly, Ebean needs:
-- Accessor methods for each persistent field (any naming style is fine — `getFoo()`, `foo()`, or no accessors at all; Ebean can also access fields directly)
-- No override of `hashCode()` / `equals()` that would interfere with the identity map — which means **no `@Data` or `@EqualsAndHashCode`**

docs/guides/persisting-and-transactions-with-ebean.md

@@ -1,447 +0,0 @@
-# Guide: Persist Changes and Manage Transactions with Ebean
-
-## Purpose
-
-This guide gives step-by-step instructions for AI agents and developers to save,
-update, delete, and batch changes with Ebean while choosing the correct
-transaction boundary.
-
-Use this guide when you need to:
-
-- create a new entity row
-- update one or more existing rows
-- delete rows safely
-- decide between implicit transactions, `@Transactional`, and explicit
-  transactions
-- batch or bulk-write many rows efficiently
-
-The default recommendation is:
-
-1. Choose the correct persistence operation first
-2. Use implicit transactions for a single isolated write
-3. Use `@Transactional` for multi-step application workflows
-4. Use explicit transactions only when you need explicit control
-5. Use bulk update or batching for large write sets
-
----
-
-## Prerequisites
-
-- The project already uses Ebean ORM
-- Entity beans and database configuration already exist
-- You know which `Database` is being used (`DB.getDefault()` or a named database)
-
-If the project is not yet configured, first follow:
-
-- [`add-ebean-postgres-database-config.md`](add-ebean-postgres-database-config.md)
-- [`entity-bean-creation.md`](entity-bean-creation.md)
-
----
-
-## Step 1 - Choose the correct persistence operation before editing code
-
-Do not start with `database.save(...)` by habit. First decide what kind of change the
-caller is making.
-
-| Need | Preferred API | Use when |
-|------|---------------|----------|
-| Insert a bean that is definitely new | `database.insert(bean)` | New-create flow, seed data, fixture setup |
-| Save a bean that may be new or existing | `database.save(bean)` | Common default when bean state determines insert vs update |
-| Update a bean that is definitely existing | `database.update(bean)` | Existing row should be updated only |
-| Delete one bean | `database.delete(bean)` | Remove a loaded entity bean |
-| Update many rows without loading beans | `database.update(...)` or `query.asUpdate()` | Set-based write, not per-row business logic |
-| Delete many rows without loading beans | bulk update/delete API or `database.sqlUpdate(...)` | Set-based deletion |
-
-### Agent rule
-
-Choose the operation that matches intent:
-
-- known new row -> `insert`
-- known existing row -> `update`
-- uncertain/new-or-existing -> `save`
-- many rows -> bulk update/delete, not a loop of individual saves
-
-### Style note
-
-Use a `Database` instance for all persistence operations: `database.save(bean)`,
-`database.insert(bean)`, `database.update(bean)`, `database.delete(bean)`.
-Inject the `Database` bean or obtain it via `DB.getDefault()`. Avoid using the
-static `DB.*` convenience methods.
-
----
-
-## Step 2 - Persist single-bean changes with the correct API
-
-### Example - insert a known new bean
-
-```java
-Customer customer = new Customer();
-customer.setName("Rob");
-customer.setEmail("rob@example.com");
-
-database.insert(customer);
-```
-
-### Example - update an existing bean
-
-```java
-Customer customer = new QCustomer()
-  .id.equalTo(customerId)
-  .findOne();
-
-customer.setStatus(Customer.Status.ACTIVE);
-
-database.update(customer);
-```
-
-### When to prefer `insert()` over `save()`
-
-Use `insert()` when the code is creating a brand new row and should fail if the
-operation does not behave like an insert.
-
-### When to prefer `update()` over `save()`
-
-Use `update()` when the bean is definitely existing and the method should not
-silently behave like an insert.
-
----
-
-## Step 3 - Check cascade mappings before assuming related beans will persist or delete
-
-Ebean follows cascade rules defined on mapping annotations such as
-`@OneToMany`, `@OneToOne`, `@ManyToOne`, and `@ManyToMany`.
-
-The default is **no cascade**.
-
-### Example
-
-```java
-@Entity
-public class Order {
-
-  @ManyToOne
-  private Customer customer; // no cascade by default
-
-  @OneToMany(cascade = CascadeType.ALL)
-  private List<OrderDetail> details; // save + delete cascade
-}
-```
-
-```java
-database.save(order);
-```
-
-With the mapping above:
-
-- `details` are cascaded
-- `customer` is **not** cascaded
-
-### Agent rules for cascades
-
-1. Inspect the mapping before writing save/delete logic
-2. Do not assume `@ManyToOne` cascades
-3. Avoid adding cascade to shared parent references unless ownership is truly
-   intended
-4. If a relationship should not cascade, save/delete related beans explicitly
-
----
-
-## Step 4 - Let Ebean use an implicit transaction for a single isolated write
-
-If the method performs one isolated persistence operation, Ebean can manage the
-transaction implicitly.
-
-### Good fit for implicit transaction
-
-```java
-Customer customer = new QCustomer()
-  .id.equalTo(customerId)
-  .findOne();
-
-customer.setStatus(Customer.Status.INACTIVE);
-database.save(customer);
-```
-
-### Good fit
-
-- one save
-- one update
-- one delete
-- small helper method with a single write
-
-### Poor fit
-
-- multiple writes that must commit or roll back together
-- query + save + save workflow
-- any method where later failure must roll back earlier writes
-
-### Important
-
-Queries also use implicit transactions when needed. You generally do **not**
-need to wrap ordinary read queries in an explicit transaction "just in case".
-
----
-
-## Step 5 - Use `@Transactional` for multi-step service workflows
-
-When multiple Ebean operations belong to one unit of work, use
-`@Transactional`.
-
-### Example - service method
-
-```java
-import io.ebean.annotation.Transactional;
-
-@Transactional
-public void shipOrder(long orderId) {
-
-  Order order = new QOrder()
-    .id.equalTo(orderId)
-    .findOne();
-
-  order.setStatus(Order.Status.SHIPPED);
-  database.save(order);
-
-  Shipment shipment = new Shipment(order, Instant.now());
-  database.insert(shipment);
-}
-```
-
-All database work inside the method runs in one transaction and commits only if
-the method completes successfully.
-
-### Use `Transaction.current()` only when needed
-
-If the method needs access to the current transaction itself:
-
-```java
-Transaction txn = Transaction.current();
-```
-
-Do this only for transaction-specific behavior such as comments, savepoints, or
-other advanced control. Do not fetch the current transaction if the method does
-not need it.
-
-### Agent rules for `@Transactional`
-
-1. Put it on application/service workflow methods, not everywhere by default
-2. Keep the transaction focused on database work
-3. Avoid remote HTTP calls, message publishing, or long-running CPU work inside
-   the transaction if those can be moved outside
-
-### Named database note
-
-If the method uses a non-default database, obtain that `Database` instance via
-`DB.byName("...")` and consistently use that database for both queries and
-writes.
-
----
-
-## Step 6 - Use `beginTransaction()` when you need explicit control
-
-Use an explicit transaction when you need manual `commit()`, batching, explicit
-flush, savepoints, or other low-level transaction control.
-
-### Example - explicit transaction with try-with-resources
-
-```java
-try (Transaction txn = database.beginTransaction()) {
-
-  Order order = new QOrder()
-    .id.equalTo(orderId)
-    .findOne();
-
-  order.cancel();
-  database.save(order);
-
-  AuditLog auditLog = new AuditLog("order-cancelled", orderId);
-  database.insert(auditLog);
-
-  txn.commit();
-}
-```
-
-If `commit()` is not reached, closing the transaction rolls it back.
-
-### Useful explicit controls
-
-- `txn.commit()` - commit current work
-- `txn.setRollbackOnly()` - force rollback-only behavior
-- `txn.flush()` - push batched statements to the database now
-
-### Agent rule
-
-Prefer `@Transactional` unless explicit transaction control is actually needed.
-Do not use `beginTransaction()` only because it feels "safer".
-
----
-
-## Step 7 - Use `createTransaction()` only for non-thread-local transaction handling
-
-`createTransaction()` creates a transaction that is **not** placed into the
-thread-local scope. This is a specialized tool.
-
-Use it when:
-
-- the transaction will be passed explicitly
-- you need more than one transaction in the same thread
-- you are coordinating work across threads or lower-level APIs
-
-### Example - explicit transaction passed to query and save
-
-```java
-Database database = DB.getDefault();
-
-try (Transaction txn = database.createTransaction()) {
-
-  Customer customer = new QCustomer(txn)
-    .email.equalTo(email)
-    .findOne();
-
-  customer.setInactive(true);
-  database.save(customer, txn);
-
-  txn.commit();
-}
-```
-
-### Agent rule
-
-If you are not deliberately bypassing thread-local transaction scope, do **not**
-use `createTransaction()`. Most service code should use `@Transactional` or
-`beginTransaction()`.
-
----
-
-## Step 8 - Use bulk update/delete or JDBC batch for many-row writes
-
-Loops of `database.save(...)` are often the wrong tool for large write sets.
-
-### Prefer bulk update for set-based changes
-
-If the update can be expressed as "change all rows matching this predicate",
-perform one bulk update instead of loading and saving each bean.
-
-### Example - bulk update with query beans
-
-```java
-var cust = QCustomer.alias();
-
-int rows = new QCustomer()
-  .status.equalTo(Customer.Status.NEW)
-  .asUpdate()
-  .set(cust.status, Customer.Status.ACTIVE)
-  .update();
-```
-
-### Example - bulk update with `database.update(...)`
-
-```java
-int rows = database.update(Customer.class)
-  .set("status", Customer.Status.ACTIVE)
-  .where()
-  .eq("status", Customer.Status.NEW)
-  .update();
-```
-
-### Prefer JDBC batch for many individual inserts/updates
-
-If each row has different values and must still go through per-bean persistence,
-use batching.
-
-```java
-Database database = DB.getDefault();
-
-try (Transaction txn = database.beginTransaction()) {
-  txn.setBatchMode(true);
-  txn.setBatchSize(100);
-  txn.setGetGeneratedKeys(false);
-
-  for (Customer customer : customersToInsert) {
-    database.insert(customer, txn);
-  }
-
-  txn.commit();
-}
-```
-
-### Alternative - annotation-driven batching
-
-```java
-@Transactional(batchSize = 50)
-public void importCustomers(List<Customer> customers) {
-  for (Customer customer : customers) {
-    database.insert(customer);
-  }
-}
-```
-
-### Batch caveats
-
-- Executing a query inside a batched transaction can flush the batch
-- Mixing bean persistence and `SqlUpdate` can also flush the batch
-- Accessing generated/unloaded properties on batched beans can flush the batch
-
-If the workflow depends on delayed flushing, review the batch-flush rules before
-adding more queries inside the same transaction.
-
----
-
-## Common anti-patterns
-
-### Anti-pattern 1 - Saving many rows one by one without batch or bulk update
-
-If you are changing hundreds or thousands of rows, first ask whether it should
-be a bulk update or a batched transaction.
-
-### Anti-pattern 2 - Assuming child beans cascade automatically
-
-Cascade is not automatic. Inspect the mapping first.
-
-### Anti-pattern 3 - Wrapping external calls inside the database transaction
-
-Do not keep transactions open while waiting on HTTP calls, queues, or other
-slow external systems unless the design genuinely requires it.
-
-### Anti-pattern 4 - Using `createTransaction()` for ordinary service code
-
-Most service code should not bypass thread-local transaction handling.
-
-### Anti-pattern 5 - Using `save()` when you really need `insert()` or `update()`
-
-If operation intent matters, choose the more specific API.
-
----
-
-## Troubleshooting
-
-| Symptom | Likely cause | Fix |
-|---------|--------------|-----|
-| Child beans were not saved or deleted | Missing cascade mapping | Inspect annotations and add explicit save/delete or the correct cascade |
-| Earlier writes committed even though later work failed | The whole workflow was not inside one transaction | Wrap the unit of work in `@Transactional` or an explicit transaction |
-| `OptimisticLockException` on update/delete | Concurrent modification or stale version | Re-fetch, merge, or handle concurrency explicitly |
-| Batch writes flush earlier than expected | Query, mixed SQL, or property access triggered flush | Review batch flush rules and transaction flow |
-| Explicit transaction example does not affect the expected database | Mixed default DB and named DB usage | Use the same `Database` instance consistently for query and write |
-
----
-
-## Summary workflow for AI agents
-
-When asked to add persistence logic:
-
-1. Choose `insert`, `save`, `update`, `delete`, or bulk update based on intent
-2. Inspect cascade mappings before assuming related beans will persist/delete
-3. Use implicit transactions for one isolated write
-4. Use `@Transactional` for multi-step units of work
-5. Use `beginTransaction()` only when explicit transaction control is needed
-6. Use `createTransaction()` only for explicit, non-thread-local handling
-7. Use bulk update or batching for large write sets
-
----
-
-## Related documentation
-
-- [Entity Bean Creation](entity-bean-creation.md)
-- [Testing with TestEntityBuilder](testing-with-testentitybuilder.md)
-- [Ebean persist docs](https://ebean.io/docs/persist)
-- [Ebean transaction docs](https://ebean.io/docs/transactions)

docs/guides/testing-with-testentitybuilder.md

@@ -1,817 +0,0 @@
-# Guide: Testing with TestEntityBuilder
-
-## Purpose
-
-This guide explains how to use `TestEntityBuilder` to rapidly create test entity instances with auto-populated random values. It is written as practical instructions for developers and AI agents building tests for Ebean applications.
-
-`TestEntityBuilder` eliminates boilerplate test setup by automatically generating realistic test data for all scalar fields, while respecting entity constraints and relationships. This is particularly valuable for:
-
-- **Integration tests** that need representative data without caring about specific values
-- **Persistence layer tests** that verify save/update/delete operations work correctly
-- **Query and filter tests** where you need multiple entities with varied data
-- **Rapid test setup** that reduces test code verbosity and improves readability
-
----
-
-## Setup & Dependencies
-
-### Add ebean-test to Your Project
-
-The `TestEntityBuilder` class is provided by the `ebean-test` module.
-
-**Maven:**
-```xml
-<dependency>
-  <groupId>io.ebean</groupId>
-  <artifactId>ebean-test</artifactId>
-  <version>${ebean.version}</version>
-  <scope>test</scope>
-</dependency>
-```
-
-**Gradle:**
-```gradle
-testImplementation "io.ebean:ebean-test:${ebeanVersion}"
-```
-
-Use a version that matches your Ebean runtime (`ebean.version` /
-`ebeanVersion`), or replace with an explicit fixed version if your build does
-not centralize dependency versions.
-
-> **Minimum version:** `TestEntityBuilder` was introduced in `ebean-test 17.5.0`. If your
-> existing Ebean version is below this, upgrade before proceeding — mismatched Ebean
-> runtime and test versions are not supported.
-
-### Import the Class
-
-```java
-import io.ebean.test.TestEntityBuilder;
-```
-
----
-
-## Basic Usage
-
-### Create a Builder Instance
-
-`TestEntityBuilder` uses a builder pattern for configuration:
-
-```java
-TestEntityBuilder builder = TestEntityBuilder.builder(database).build();
-```
-
-The `Database` parameter specifies which Ebean database instance to use for entity type
-lookups and persistence operations. Pass the injected `Database` bean (see
-[Using with Dependency Injection](#using-with-dependency-injection) below) rather than
-`DB.getDefault()` when working in a Spring or Avaje Inject context. For the same reason,
-use the injected `database` bean for **all** persistence operations in your tests
-(`database.save()`, `database.find()`, etc.) rather than mixing in static `DB.*` calls.
-
-### Build an Entity (In-Memory)
-
-The `build()` method creates an instance with populated fields **without persisting to the database:**
-
-```java
-Product product = builder.build(Product.class);
-
-// Fields are populated:
-// - id: unset (typically 0 for primitive long, null for boxed Long)
-// - name: random UUID-based string
-// - price: random BigDecimal
-// - inStock: true
-// - createdAt: current instant
-// - etc.
-
-// Not persisted yet (`@Id` is still unset until the entity is persisted).
-```
-
-### Build and Save (Persist to Database)
-
-The `save()` method creates, persists, and returns an entity with the database-assigned `@Id`:
-
-```java
-Product product = builder.save(Product.class);
-
-// Entity is now in the database:
-assert database.find(Product.class, product.getId()) != null;
-```
-
-### Save Multiple Entities
-
-The `saveAll()` method persists multiple pre-built entities in a single call:
-
-```java
-Product p1 = builder.build(Product.class);
-Product p2 = builder.build(Product.class);
-builder.saveAll(p1, p2);
-
-// Both are now in the database with assigned IDs:
-assert p1.getId() != null;
-assert p2.getId() != null;
-```
-
-This is equivalent to `database.saveAll(p1, p2)` but avoids needing a separate
-`Database` reference in tests that already hold a `TestEntityBuilder`.
-
-### Access the Underlying Database
-
-The `database()` method returns the `Database` instance used internally by the builder.
-This is useful in tests where you want a single injected object (`TestEntityBuilder`) but
-still need to perform `find()`, `delete()`, or other database operations:
-
-```java
-Product saved = builder.save(Product.class);
-
-// Use builder.database() instead of injecting a separate Database bean:
-Product found = builder.database().find(Product.class, saved.getId());
-assert found != null;
-```
-
----
-
-## Using with Dependency Injection
-
-Most applications using Ebean also use a DI framework. The recommended pattern is to
-register `TestEntityBuilder` as a bean in the test DI context so it can be injected
-directly into test classes — eliminating `@BeforeEach` setup boilerplate entirely.
-
-### Avaje Inject — `@TestScope @Factory`
-
-Add a `@Bean` method to your test-scoped `@Factory` class:
-
-```java
-import io.ebean.Database;
-import io.ebean.test.ContainerDatabase;
-import io.avaje.inject.Bean;
-import io.avaje.inject.Factory;
-import io.avaje.inject.test.TestScope;
-import io.ebean.test.TestEntityBuilder;
-
-@TestScope
-@Factory
-class TestConfiguration {
-
-  @Bean
-  PostgresContainer postgres() {
-    return PostgresContainer.builder("17")   // Postgres image version
-        .dbName("my_app")                    // database to create inside the container
-        .build()
-        .start();
-  }
-
-  @Bean
-  Database database(PostgresContainer container) {
-    return container.ebean()
-        .builder()
-        .build();
-  }
-
-  @Bean
-  TestEntityBuilder testEntityBuilder(Database database) {
-    return TestEntityBuilder.builder(database).build();
-  }
-}
-```
-
-Then inject it directly into test classes using `@InjectTest`:
-
-```java
-@InjectTest
-class OrderControllerTest {
-
-  @Inject Database database;
-  @Inject TestEntityBuilder builder;
-
-  @Test
-  void findByStatus() {
-    var order = builder.build(Order.class).setStatus(OrderStatus.PENDING);
-    database.save(order);
-
-    // ... test assertions
-  }
-}
-```
-
-Both patterns produce a single shared `TestEntityBuilder` instance, wired
-from the managed `Database` bean — no `@BeforeEach` required.
-
-### Spring Boot — `@TestConfiguration`
-
-Add a `@TestConfiguration` class that provides `TestEntityBuilder` as a bean:
-
-```java
-@TestConfiguration
-class TestConfig {
-
-  @Bean
-  PostgresContainer postgres() {
-    return PostgresContainer.builder("17")   // Postgres image version
-      .dbName("my_app")                    // database to create inside the container
-      .build()
-      .start();
-  }
-
-  // use @Primary if your main application context also wires a Database bean
-  // or conditionally wire the main Database bean to exclude it from tests
-  @Primary
-  @Bean
-  Database database(PostgresContainer container) {
-    return container.ebean()
-      .builder()
-      .build();
-  }
-
-  @Bean
-  TestEntityBuilder testEntityBuilder(Database database) {
-    return TestEntityBuilder.builder(database).build();
-  }
-}
-```
-
-Then inject it directly into test classes:
-
-```java
-@SpringBootTest
-class OrderControllerTest {
-
-  @Autowired Database database;
-  @Autowired TestEntityBuilder builder;
-
-  @Test
-  void findByStatus() {
-    var order = builder.build(Order.class).setStatus(OrderStatus.PENDING);
-    database.save(order);
-
-    // ... test assertions
-  }
-}
-```
-
----
-
-## Type-Specific Value Generation
-
-`TestEntityBuilder` generates appropriate random values for each Java/SQL type. Customize this behavior by subclassing `RandomValueGenerator` (see "Custom Value Generators" below).
-
-| Type | Generated Value | Notes |
-|------|-----------------|-------|
-| `String` | UUID-derived (8 chars by default) | Truncated to column length if `@Column(length=...)` is set |
-| Email fields | `uuid@domain.com` format | Detected when property name contains "email" (case-insensitive) |
-| `Integer` / `int` | Random in `[1, 1_000)` | |
-| `Long` / `long` | Random in `[1, 100_000)` | |
-| `Short` / `short` | Random in `[1, 100)` | See note on flag fields below |
-| `Double` / `double` | Random in `[1, 100)` | |
-| `Float` / `float` | Random in `[1, 100)` | |
-| `BigDecimal` | Respects precision and scale | Precision and scale from `@Column(precision=..., scale=...)` |
-| `Boolean` / `boolean` | `true` | Override in custom generator if needed |
-| `UUID` | Random UUID | Via `UUID.randomUUID()` |
-| `LocalDate` | Today's date | Via `LocalDate.now()` |
-| `LocalDateTime` | Current datetime | Via `LocalDateTime.now()` |
-| `Instant` | Current instant | Via `Instant.now()` |
-| `OffsetDateTime` | Current time with zone | Via `OffsetDateTime.now()` |
-| `ZonedDateTime` | Current time with zone | Via `ZonedDateTime.now()` |
-| `Enum` | First constant | Override in custom generator if needed |
-| Other types | `null` | Set these fields manually in tests |
-
-### String Length Constraints
-
-`TestEntityBuilder` respects column length constraints defined in the entity:
-
-```java
-@Entity
-public class User {
-  @Column(length = 50)
-  private String username;
-}
-
-User user = builder.build(User.class);
-assert user.getUsername().length() <= 50;  // ✅ Constraint respected
-```
-
-### BigDecimal Precision and Scale
-
-For `BigDecimal` fields, the builder respects the database column precision and scale:
-
-```java
-@Entity
-public class LineItem {
-  @Column(precision = 10, scale = 2)  // max 99_999_999.99
-  private BigDecimal amount;
-}
-
-LineItem item = builder.build(LineItem.class);
-assert item.getAmount().scale() == 2;
-```
-
-### Short Fields Used as Boolean Flags
-
-Some legacy schemas use `short` to represent boolean-like flags (e.g. `active = 1`
-means active, `0` means inactive). `TestEntityBuilder` generates a random short in
-`[1, 100)`, which will be non-zero but not necessarily `1`. If your application
-code checks `entity.getActive() == 1` specifically, override the field after building:
-
-```java
-Organisation org = builder.build(Organisation.class)
-    .setActive((short) 1);  // explicit override — random short won't do
-```
-
----
-
-## Entity Relationships
-
-### Cascade-Persist Relationships: Recursively Built
-
-Relationships marked with `cascade = PERSIST` are recursively populated:
-
-```java
-@Entity
-public class Order {
-  @ManyToOne(cascade = CascadeType.PERSIST)
-  private Customer customer;
-}
-
-Order order = builder.build(Order.class);
-
-// Both order and customer are built:
-assert order != null;
-assert order.getCustomer() != null;
-// Before persist, @Id values are typically unset
-// (0 for primitive IDs, null for boxed IDs).
-
-// When saved, cascade handles both:
-Order saved = builder.save(Order.class);
-assert saved.getId() != null;
-assert saved.getCustomer().getId() != null;  // parent also saved
-```
-
-### Non-Cascade Relationships: Left Null
-
-Relationships without cascade persist are not auto-created — even if marked `optional = false`.
-Create and save the related entity first (the builder works well here), then assign it manually
-before saving the parent:
-
-```java
-@Entity
-public class BlogPost {
-  @ManyToOne
-  private Author author;  // No cascade = left null by builder
-}
-
-BlogPost post = builder.build(BlogPost.class);
-assert post.getAuthor() == null;
-
-// Use the builder to create the related entity, then set it manually:
-Author author = builder.save(Author.class);
-post.setAuthor(author);
-database.save(post);
-```
-
-### Collection Relationships: Left Empty
-
-Collection relationships (`@OneToMany`, `@ManyToMany`) are left empty. On Ebean-enhanced
-entities these fields are initialised to empty Ebean-managed lists (not `null`), so calling
-`.add()` or `.addAll()` directly is safe:
-
-```java
-@Entity
-public class Author {
-  @OneToMany(mappedBy = "author")
-  private List<BlogPost> posts;  // Left empty
-}
-
-Author author = builder.build(Author.class);
-assert author.getPosts().isEmpty();
-
-// Populate if needed for testing:
-author.getPosts().addAll(Arrays.asList(post1, post2, post3));
-```
-
-### Cycle Detection: Prevents Infinite Recursion
-
-If two entities reference each other with cascade persist, the builder detects the cycle and breaks it by leaving one reference null:
-
-```java
-@Entity
-public class Person {
-  @ManyToOne(cascade = CascadeType.PERSIST)
-  private Organization org;
-}
-
-@Entity
-public class Organization {
-  @ManyToOne(cascade = CascadeType.PERSIST)
-  private Person founder;
-}
-
-Person person = builder.build(Person.class);
-// One reference will be null to break the cycle:
-// either person.org or person.org.founder is null
-```
-
----
-
-## Custom Value Generators
-
-### Why Customize?
-
-The default `RandomValueGenerator` uses generic random values. For domain-specific testing, you may want:
-
-- Email addresses with your company domain
-- Realistic phone numbers
-- Product SKUs following a pattern
-- Addresses in specific regions
-- Monetary amounts within realistic ranges
-
-### Creating a Custom Generator
-
-Subclass `RandomValueGenerator` and override individual `random*()` methods:
-
-```java
-class CompanyTestDataGenerator extends RandomValueGenerator {
-
-  @Override
-  protected String randomString(String propName, int maxLength) {
-    if (propName != null && propName.toLowerCase().contains("email")) {
-      // Use company domain instead of generic @domain.com
-      String localPart = UUID.randomUUID().toString().substring(0, 8);
-      String email = localPart + "@mycompany.com";
-      if (maxLength > 0 && email.length() > maxLength) {
-        return email.substring(0, maxLength);
-      }
-      return email;
-    }
-    return super.randomString(propName, maxLength);
-  }
-
-  // Override other methods as needed:
-  @Override
-  protected Object randomEnum(Class<?> type) {
-    if (type == OrderStatus.class) {
-      // Bias towards common statuses for realistic test data
-      return ThreadLocalRandom.current().nextDouble() < 0.8
-        ? OrderStatus.PENDING
-        : OrderStatus.COMPLETED;
-    }
-    return super.randomEnum(type);
-  }
-}
-```
-
-### Using a Custom Generator
-
-Pass the custom generator when building:
-
-```java
-TestEntityBuilder builder = TestEntityBuilder.builder(database)
-    .valueGenerator(new CompanyTestDataGenerator())
-    .build();
-
-User user = builder.build(User.class);
-assert user.getEmail().endsWith("@mycompany.com");
-```
-
-In a DI context, register this as the bean:
-
-```java
-// Spring Boot
-@Bean
-TestEntityBuilder testEntityBuilder(Database database) {
-  return TestEntityBuilder.builder(database)
-      .valueGenerator(new CompanyTestDataGenerator())
-      .build();
-}
-```
-
-### Example: Money Type
-
-```java
-public class MoneyValueGenerator extends RandomValueGenerator {
-
-  @Override
-  protected BigDecimal randomBigDecimal(int precision, int scale) {
-    // Generate prices in a realistic range: $5.00 to $999.99
-    BigDecimal price = BigDecimal.valueOf(
-      ThreadLocalRandom.current().nextDouble(5.0, 1000.0)
-    );
-    return price.setScale(2, RoundingMode.HALF_UP);
-  }
-}
-```
-
----
-
-## Best Practices
-
-### 1. Use for Integration Tests, Not Unit Tests
-
-✅ **Good:** Integration test with database
-```java
-@Test
-void whenSaving_thenCanRetrieve() {
-  Product product = builder.save(Product.class);
-  Product found = database.find(Product.class, product.getId());
-  assertThat(found).isNotNull();
-}
-```
-
-❌ **Poor:** Validation test requiring specific values
-```java
-@Test
-void whenNameIsBlank_thenThrowException() {
-  Product product = builder.build(Product.class);  // name is random!
-  product.setName("");  // have to override anyway
-  // ... test proceeds
-}
-```
-
-### 2. Override Values for Specific Test Scenarios
-
-When test requirements demand specific field values, manually override after building:
-
-```java
-@Test
-void whenStockIsLow_thenShowWarning() {
-  Product product = builder.build(Product.class);
-  product.setQuantity(2);  // Specific value for this test
-
-  boolean shouldWarn = product.shouldShowLowStockWarning();
-  assertThat(shouldWarn).isTrue();
-}
-```
-
-### 3. Create Fixture Factories for Common Patterns
-
-For shared domain-specific setup, encapsulate build patterns in an instance helper class
-rather than a static factory. In a DI context, this class can be registered as a bean
-alongside `TestEntityBuilder`:
-
-```java
-// Spring Boot
-@TestConfiguration
-class TestConfig {
-
-  @Bean
-  TestEntityBuilder testEntityBuilder(Database database) {
-    return TestEntityBuilder.builder(database).build();
-  }
-
-  @Bean
-  OrderTestFactory orderTestFactory(TestEntityBuilder builder, Database database) {
-    return new OrderTestFactory(builder, database);
-  }
-}
-
-public class OrderTestFactory {
-
-  private final TestEntityBuilder builder;
-  private final Database database;
-
-  public OrderTestFactory(TestEntityBuilder builder, Database database) {
-    this.builder = builder;
-    this.database = database;
-  }
-
-  public Order savePendingOrder() {
-    Order order = builder.build(Order.class);
-    order.setStatus(OrderStatus.PENDING);
-    database.save(order);
-    return order;
-  }
-
-  public Order saveShippedOrder() {
-    Order order = builder.build(Order.class);
-    order.setStatus(OrderStatus.SHIPPED);
-    order.setShippedAt(Instant.now());
-    database.save(order);
-    return order;
-  }
-}
-
-// Usage in tests:
-@SpringBootTest
-class OrderControllerTest {
-
-  @Autowired OrderTestFactory orderFactory;
-
-  @Test
-  void whenOrderPending_thenCanUpdate() {
-    Order order = orderFactory.savePendingOrder();
-    // ... test logic
-  }
-}
-```
-
-### 4. Build Multiple Distinct Instances
-
-Each call to `build()` or `save()` produces a new instance with fresh random values:
-
-```java
-@Test
-void whenFetchingMultipleOrders_thenAllUnique() {
-  Order order1 = builder.save(Order.class);
-  Order order2 = builder.save(Order.class);
-  Order order3 = builder.save(Order.class);
-
-  assertThat(order1.getId()).isNotEqualTo(order2.getId());
-  assertThat(order2.getId()).isNotEqualTo(order3.getId());
-  assertThat(order1.getOrderNumber()).isNotEqualTo(order2.getOrderNumber());
-}
-```
-
----
-
-## Complete Examples
-
-### Example 1: Integration Test with Spring Boot
-
-Register `TestEntityBuilder` as a `@TestConfiguration` bean, then inject it alongside
-the repository under test:
-
-```java
-@TestConfiguration
-class TestConfig {
-  @Bean
-  TestEntityBuilder testEntityBuilder(Database database) {
-    return TestEntityBuilder.builder(database).build();
-  }
-}
-
-@SpringBootTest
-class OrderRepositoryTest {
-
-  @Autowired OrderRepository orderRepository;
-  @Autowired TestEntityBuilder builder;
-
-  @Test
-  void whenFindingOrdersByStatus_thenReturnsMatching() {
-    Order pending1 = builder.build(Order.class);
-    pending1.setStatus(OrderStatus.PENDING);
-
-    Order pending2 = builder.build(Order.class);
-    pending2.setStatus(OrderStatus.PENDING);
-
-    Order shipped = builder.build(Order.class);
-    shipped.setStatus(OrderStatus.SHIPPED);
-
-    builder.saveAll(pending1, pending2, shipped);
-
-    List<Order> pending = orderRepository.findByStatus(OrderStatus.PENDING);
-    assertThat(pending).hasSize(2);
-  }
-}
-```
-
-### Example 2: Integration Test with Avaje Inject
-
-```java
-@TestScope
-@Factory
-class TestConfiguration {
-  @Bean
-  TestEntityBuilder testEntityBuilder(Database database) {
-    return TestEntityBuilder.builder(database).build();
-  }
-}
-
-@InjectTest
-class OrderControllerTest {
-
-  @Inject TestEntityBuilder builder;
-
-  @Test
-  void whenFindingOrdersByStatus_thenReturnsMatching() {
-    Order pending1 = builder.build(Order.class);
-    pending1.setStatus(OrderStatus.PENDING);
-
-    Order pending2 = builder.build(Order.class);
-    pending2.setStatus(OrderStatus.PENDING);
-
-    Order shipped = builder.build(Order.class);
-    shipped.setStatus(OrderStatus.SHIPPED);
-
-    builder.saveAll(pending1, pending2, shipped);
-
-    // ... test assertions
-  }
-}
-```
-
-### Example 3: Recursive Relationship Building
-
-```java
-@Test
-void whenBuildingOrderWithCustomer_thenBothPopulated() {
-  Order order = builder.build(Order.class);
-
-  // Customer is recursively built because of @ManyToOne(cascade=PERSIST)
-  assertThat(order.getCustomer()).isNotNull();
-  // Before persist, @Id values are typically unset
-  // (0 for primitive IDs, null for boxed IDs).
-  assertThat(order.getCustomer().getName()).isNotNull();
-
-  // Saving cascades to customer:
-  Order saved = builder.save(Order.class);
-  assertThat(saved.getId()).isNotNull();
-  assertThat(saved.getCustomer().getId()).isNotNull();
-}
-```
-
-### Example 4: Custom Generator for Domain Values
-
-```java
-// Custom generator for your domain
-class ECommerceTestDataGenerator extends RandomValueGenerator {
-  @Override
-  protected BigDecimal randomBigDecimal(int precision, int scale) {
-    // Product prices typically range $10-$500
-    return BigDecimal.valueOf(
-      ThreadLocalRandom.current().nextDouble(10.0, 500.0)
-    ).setScale(2, RoundingMode.HALF_UP);
-  }
-}
-
-@Test
-void usingCustomGenerator() {
-  TestEntityBuilder builder = TestEntityBuilder.builder(database)
-      .valueGenerator(new ECommerceTestDataGenerator())
-      .build();
-
-  Product product = builder.build(Product.class);
-  assertThat(product.getPrice())
-      .isBetween(BigDecimal.TEN, BigDecimal.valueOf(500.0));
-}
-```
-
----
-
-## Troubleshooting
-
-### "No BeanDescriptor found for [Class] — is it an @Entity?"
-
-**Cause:** The class you're trying to build is not registered as an Ebean entity.
-
-**Solution:** Ensure the class is annotated with `@Entity` and registered with the Database:
-```java
-@Entity
-@Table(name = "products")
-public class Product {
-  // ...
-}
-```
-
-### Fields are unset even though I expected them to be populated
-
-**Cause:** `TestEntityBuilder` does **not** populate:
-- `@Id` fields (identity/primary key; left unset until persist)
-- `@Version` fields (optimistic locking; left unset until persist)
-- `@Transient` fields
-- `@OneToMany` collections
-- Non-cascade `@ManyToOne` relationships
-
-**Solution:** Set only the fields your test scenario cares about, then persist.
-`@Id` and `@Version` are usually database-managed and should typically be left
-unset before save:
-```java
-Product product = builder.build(Product.class);
-product.setName("specific-name");  // test-specific override
-database.save(product);            // database assigns @Id/@Version
-```
-
-### Building recursive relationships causes StackOverflowError
-
-**Cause:** Two or more entities mutually reference each other without cycle detection.
-
-**Solution:** This should be handled automatically by cycle detection. If not, manually set one reference to null:
-```java
-Person person = builder.build(Person.class);
-person.getOrganization().setFounder(null);  // Break cycle
-```
-
-### Values generated are "too random" for my test
-
-**Cause:** Default `RandomValueGenerator` uses true random values, which aren't suitable when your test needs predictable data.
-
-**Solution:** Create a custom generator that produces deterministic values:
-```java
-class DeterministicTestDataGenerator extends RandomValueGenerator {
-  private int counter = 0;
-
-  @Override
-  protected String randomString(String propName, int maxLength) {
-    return "test_" + (counter++);
-  }
-}
-```
-
----
-
-## Summary
-
-`TestEntityBuilder` accelerates test development by:
-
-1. **Reducing boilerplate** — No need to manually set every field
-2. **Improving readability** — Tests focus on what matters, not setup
-3. **Enabling variety** — Each build produces distinct random values
-4. **Respecting constraints** — Column lengths and decimal scales are enforced
-5. **Supporting customization** — Extend `RandomValueGenerator` for domain needs
-

docs/guides/writing-ebean-query-beans.md

@@ -1,488 +0,0 @@
-# Guide: Write Ebean Queries with Query Beans
-
-## Purpose
-
-This guide gives step-by-step instructions for AI agents and developers to write
-application queries using Ebean query beans.
-
-Use this guide when the project already has Ebean configured and you need to:
-
-- add a repository/service query
-- replace string-based ORM queries with type-safe query beans
-- tune what data is fetched to avoid over-fetching or N+1 issues
-- return DTO projections for list screens or API responses
-
-The default recommendation is:
-
-1. Prefer query beans first
-2. Prefer entity queries for domain logic
-3. For read-only entity graphs, prefer `setUnmodifiable(true)`
-4. Prefer DTO projection for summary/read-model use cases
-5. Only drop to raw SQL when the ORM query cannot express the requirement cleanly
-
----
-
-## Prerequisites
-
-- The project already uses Ebean ORM
-- Query bean generation is configured (for Maven this usually means
-  `querybean-generator` is registered as an annotation processor)
-- Entity beans already exist
-- A compile/build has run successfully since the last entity model change
-
-If query beans are not yet configured, first follow:
-[`add-ebean-postgres-maven-pom.md`](add-ebean-postgres-maven-pom.md)
-
----
-
-## Step 1 - Verify the generated `Q*` query bean exists
-
-For each entity bean, Ebean generates a query bean with the same name prefixed
-with `Q`.
-
-Examples:
-
-- `Customer` -> `QCustomer`
-- `Order` -> `QOrder`
-- `Contact` -> `QContact`
-
-Import the generated type from the query bean package:
-
-```java
-import org.example.domain.query.QCustomer;
-```
-
-If the `Q*` type does not exist or the IDE cannot resolve it:
-
-1. Confirm the entity compiled successfully
-2. Run a normal project compile/build
-3. If the entity was renamed or moved, run a full rebuild rather than relying on
-   incremental compilation
-
-### Important caveat - entity rename
-
-After refactoring an entity name, old generated query beans can remain on disk
-until the next full build. If both old and new `Q*` types appear to exist, do a
-clean rebuild before editing application queries.
-
----
-
-## Step 2 - Choose the terminal query method before writing predicates
-
-Decide what the caller actually needs. This determines the terminal method and
-often the right query shape.
-
-| Need | Preferred method | Notes |
-|------|------------------|-------|
-| 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 |
-| 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 |
-
-### Example - existence check
-
-```java
-boolean alreadyUsed = new QCustomer()
-  .email.equalTo(email)
-  .exists();
-```
-
-### Example - unique lookup
-
-```java
-Customer customer = new QCustomer()
-  .email.equalTo(email)
-  .findOne();
-```
-
-Do **not** use `findOne()` for predicates that can match multiple rows.
-
----
-
-## Step 3 - Build predicates by traversing properties and associations
-
-With query beans, write predicates directly against properties. When you
-traverse an association, Ebean adds the necessary joins automatically.
-
-### Example - root property predicates
-
-```java
-List<Customer> customers = new QCustomer()
-  .status.equalTo(Customer.Status.ACTIVE)
-  .name.istartsWith("rob")
-  .findList();
-```
-
-### Example - association traversal
-
-```java
-List<Customer> customers = new QCustomer()
-  .billingAddress.city.equalTo("Auckland")
-  .findList();
-```
-
-### Example - collection predicate
-
-```java
-List<Customer> customers = new QCustomer()
-  .contacts.isEmpty()
-  .findList();
-```
-
-### Agent rule
-
-When adding a new query:
-
-1. Start from the root entity that the caller wants back
-2. Add predicates with query bean properties
-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
-
----
-
-## Step 4 - Add ordering, limits, and pagination deliberately
-
-Do not leave list queries unordered unless the call site truly does not care.
-For UI lists, APIs, and background jobs, explicit ordering is usually better.
-
-### Example - ordered list with limit
-
-```java
-List<Customer> customers = new QCustomer()
-  .status.equalTo(Customer.Status.ACTIVE)
-  .orderBy().name.asc()
-  .setMaxRows(50)
-  .findList();
-```
-
-### Example - offset/limit pagination
-
-```java
-List<Customer> customers = new QCustomer()
-  .status.equalTo(Customer.Status.ACTIVE)
-  .orderBy().id.asc()
-  .setFirstRow(offset)
-  .setMaxRows(pageSize)
-  .findList();
-```
-
-### Example - paged list with total count
-
-```java
-PagedList<Customer> page = new QCustomer()
-  .status.equalTo(Customer.Status.ACTIVE)
-  .orderBy().id.asc()
-  .setFirstRow(offset)
-  .setMaxRows(pageSize)
-  .findPagedList();
-
-page.loadRowCount();
-List<Customer> customers = page.getList();
-int totalRowCount = page.getTotalRowCount();
-```
-
-### Agent rule
-
-- Use `findList()` when the caller only needs rows
-- Use `findPagedList()` when the caller also needs page metadata or total counts
-- Pair pagination with a stable `orderBy()` so page boundaries stay predictable
-
----
-
-## Step 5 - Control fetched data with `select()` and `fetch()`
-
-By default, entity queries can load more of the object graph than the caller
-actually needs. Use `select()` and `fetch()` to control the root and association
-properties that are loaded.
-
-### Root properties with `select()`
-
-Use `select()` to define which properties should be fetched on the root entity.
-
-### Associated bean properties with `fetch()`
-
-Use `fetch()` to define what should be fetched on associated paths.
-
-### Example - partial entity query
-
-```java
-private static final QCustomer CUST = QCustomer.alias();
-private static final QContact CONT = QContact.alias();
-
-List<Customer> customers = new QCustomer()
-  .select(CUST.name, CUST.status, CUST.whenCreated)
-  .contacts.fetch(CONT.email)
-  .name.istartsWith("rob")
-  .findList();
-```
-
-In this example:
-
-- `select(...)` tunes the root `Customer` properties
-- `contacts.fetch(...)` tunes the associated `Contact` properties
-- the query still returns `Customer` entity beans
-
-### Agent rules for partial entity queries
-
-1. Only use `select()`/`fetch()` when you know what the caller will read next
-2. Do not treat partially loaded entities like fully populated API DTOs
-3. If the caller only needs summary fields, prefer a DTO projection instead
-
----
-
-## Step 6 - Use `setUnmodifiable(true)` for read-only entity graphs
-
-`setUnmodifiable(true)` turns the returned object graph into an unmodifiable,
-read-only graph.
-
-This means:
-
-- setters cannot mutate returned beans
-- associated collections are unmodifiable
-- lazy loading is disabled
-- accessing an unloaded property throws `LazyInitialisationException`
-- the query uses `PersistenceContextScope.QUERY`
-
-### Example - read-only entity graph
-
-```java
-private static final QCustomer CUST = QCustomer.alias();
-private static final QContact CONT = QContact.alias();
-
-List<Customer> customers = new QCustomer()
-  .select(CUST.name, CUST.status, CUST.whenCreated)
-  .contacts.fetch(CONT.email)
-  .status.equalTo(Customer.Status.ACTIVE)
-  .setUnmodifiable(true)
-  .findList();
-```
-
-### When to prefer `setUnmodifiable(true)`
-
-Use it when the result is meant to be read-only, such as:
-
-- service/query methods returning entity graphs for display or serialization
-- query results you want the application to treat as immutable
-- cached query results or other shared read models backed by entity graphs
-- partial entity graphs where you want accidental lazy loading to fail fast
-
-### When **not** to use it
-
-Do **not** use `setUnmodifiable(true)` when the caller will:
-
-- modify the beans and save them later
-- rely on lazy loading of associations or unloaded scalar properties
-- treat the result as a working persistence model rather than a read-only view
-
-### Agent rule
-
-If you are returning entity beans for read-only use, `setUnmodifiable(true)`
-should be the default recommendation. If the caller needs a mutable model or a
-serialized summary shape, choose mutable entities or DTO projection instead.
-
-If you need cached assoc-one references for unmodifiable graphs, see
-[Immutable bean cache for read-only references](immutable-bean-cache.md).
-
----
-
-## Step 7 - Use `fetchQuery()` for to-many paths and `FetchGroup` for reusable query shapes
-
-Ebean applies important SQL rules when translating ORM queries:
-
-1. It does not generate SQL cartesian products
-2. It honors `maxRows` in SQL
-
-This means to-many paths often need special handling.
-
-### Use `fetchQuery()` when:
-
-- the query includes a `OneToMany` or `ManyToMany` path
-- the query includes `setMaxRows(...)`
-- the query loads multiple to-many paths
-- you want the query shape to make the secondary-query behavior explicit
-
-### Example - explicit secondary queries for to-many paths
-
-```java
-private static final QCustomer CUST = QCustomer.alias();
-
-List<Order> orders = new QOrder()
-  .customer.fetch(CUST.name)
-  .lines.fetchQuery()
-  .shipments.fetchQuery()
-  .status.equalTo(Order.Status.NEW)
-  .setMaxRows(100)
-  .findList();
-```
-
-### Use `FetchGroup` when:
-
-- the same fetch shape is reused in multiple places
-- you want to separate predicate logic from fetch-shape tuning
-- you want an immutable, static query-shape definition
-
-### Example - reusable fetch group
-
-```java
-private static final QCustomer CUST = QCustomer.alias();
-
-private static final FetchGroup<Customer> CUSTOMER_SUMMARY =
-  QCustomer.forFetchGroup()
-    .select(CUST.name, CUST.status, CUST.whenCreated)
-    .billingAddress.fetch()
-    .buildFetchGroup();
-
-List<Customer> customers = new QCustomer()
-  .select(CUSTOMER_SUMMARY)
-  .status.equalTo(Customer.Status.ACTIVE)
-  .findList();
-```
-
-### Agent rule
-
-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.
-
----
-
-## Step 8 - Use DTO projection when the caller does not need entity beans
-
-For list screens, API summaries, exports, or read-model views, the caller often
-does **not** need managed entity beans. In those cases, project directly to a
-DTO using `asDto(...)`.
-
-### Example - DTO projection with query beans
-
-```java
-import static org.example.domain.query.QCustomer.Alias.id;
-import static org.example.domain.query.QCustomer.Alias.name;
-
-public record CustomerSummary(long id, String name) {}
-
-List<CustomerSummary> summaries = new QCustomer()
-  .select(id, name)
-  .status.equalTo(Customer.Status.ACTIVE)
-  .orderBy().name.asc()
-  .asDto(CustomerSummary.class)
-  .findList();
-```
-
-### Prefer DTO projection when:
-
-- the caller will serialize the result directly
-- only a subset of fields is needed
-- 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
-
----
-
-## Step 9 - Only fall back to raw SQL when the ORM query is not a good fit
-
-Prefer the following order:
-
-1. Query bean query
-2. Query bean query + `asDto(...)`
-3. `database.findDto(...)` or DTO query
-4. Native SQL / `SqlQuery` / `RawSql`
-
-### Typical reasons to use raw SQL
-
-- vendor-specific SQL that query beans do not express well
-- advanced aggregation or database functions
-- hand-tuned reporting queries
-- stored procedures or raw JDBC workflows
-
-Do **not** jump to raw SQL just because the query joins multiple tables. Query
-beans already handle ordinary relationship traversal well.
-
----
-
-## Common anti-patterns
-
-### Anti-pattern 1 - Using raw SQL first
-
-**Avoid:**
-
-```java
-List<Customer> customers = database.findNative(Customer.class,
-  "select c.* from customer c join address a on a.id = c.billing_address_id where a.city = ?")
-  .setParameter(1, city)
-  .findList();
-```
-
-**Prefer:**
-
-```java
-List<Customer> customers = new QCustomer()
-  .billingAddress.city.equalTo(city)
-  .findList();
-```
-
-### Anti-pattern 2 - Using `findOne()` on a non-unique predicate
-
-**Avoid:**
-
-```java
-Customer customer = new QCustomer()
-  .status.equalTo(Customer.Status.ACTIVE)
-  .findOne();
-```
-
-**Why:** Many rows can match; this is not a unique lookup.
-
-### Anti-pattern 3 - Returning partially loaded entities as API models
-
-If the caller only needs summary fields, return a DTO instead of partially
-loaded entities that might later trigger more loading or confuse serializers.
-
-### Anti-pattern 4 - Returning mutable entity graphs for read-only use
-
-If the caller is only meant to read the result, prefer `setUnmodifiable(true)`
-so accidental setter calls, collection mutation, and lazy loading fail fast.
-
-### Anti-pattern 5 - Fetching every relationship "just in case"
-
-Do not eagerly fetch large object graphs unless the immediate caller will use
-them. Query tuning is part of the job.
-
-
----
-
-## Troubleshooting
-
-| Symptom | Likely cause | Fix |
-|---------|--------------|-----|
-| `Cannot resolve symbol QCustomer` | Query bean generation not configured or build not run | Check the annotation processor and run a build |
-| Old `Q*` class still appears after entity rename | Stale generated source/class output | Run a clean rebuild |
-| `findOne()` fails because multiple rows match | Predicate is not unique | Use `findList()` or tighten the predicate |
-| Returned entities only have some fields loaded | `select()` or `FetchGroup` limited the query shape | Add the required fields or switch to DTO projection |
-| Setter calls or collection mutation fail on query results | `setUnmodifiable(true)` returned a read-only graph | Remove `setUnmodifiable(true)` or treat the result as read-only |
-| Accessing an unloaded property throws `LazyInitialisationException` | `setUnmodifiable(true)` disables lazy loading | Fetch the property up front or use DTO projection |
-| Ebean executes secondary queries for a to-many path | ORM rules avoided cartesian product or honored `maxRows` | This is expected; use `fetchQuery()` explicitly when appropriate |
-
----
-
-## Summary workflow for AI agents
-
-When asked to add or modify an Ebean query:
-
-1. Verify the relevant `Q*` type exists
-2. Choose the terminal method first (`exists`, `findOne`, `findList`, `findPagedList`, `asDto`)
-3. Add predicates with query bean properties and association traversal
-4. Add explicit ordering and pagination if relevant
-5. If the result is read-only entity data, consider `setUnmodifiable(true)`
-6. Tune the fetch shape with `select()` / `fetch()` / `fetchQuery()` / `FetchGroup`
-7. Prefer DTO projection for read models and serialized responses
-8. Only use raw SQL if the ORM query is genuinely the wrong tool
-
----
-
-## Related documentation
-
-- [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)
-- [Ebean query docs](https://ebean.io/docs/query/)

ebean-api/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>16.6.0</version>
+    <version>12.16.3</version>
   </parent>
 
   <name>ebean api</name>
@@ -13,47 +13,49 @@
 
   <dependencies>
 
+    <!--
+    Projects are expected to explicit depend on version
+    of slf4j that they want to use
+    -->
     <dependency>
-      <groupId>io.avaje</groupId>
-      <artifactId>avaje-applog</artifactId>
-      <version>1.0</version>
-    </dependency>
-
-    <!-- exclude avaje-applog-slf4j to direct logging to something else -->
-    <dependency>
-      <groupId>io.avaje</groupId>
-      <artifactId>avaje-applog-slf4j</artifactId>
-      <version>1.0</version>
-    </dependency>
-
-    <dependency>
-      <groupId>org.jspecify</groupId>
-      <artifactId>jspecify</artifactId>
-      <version>1.0.0</version>
+      <groupId>org.slf4j</groupId>
+      <artifactId>slf4j-api</artifactId>
+      <version>1.7.30</version>
+      <scope>provided</scope>
     </dependency>
 
     <dependency>
       <groupId>io.avaje</groupId>
       <artifactId>avaje-config</artifactId>
-      <version>4.2</version>
+      <version>1.7</version>
+    </dependency>
+
+    <!--
+    Class retention Nonnull and Nullable annotations
+    to assist with IDE auto-completion with Ebean API
+    -->
+    <dependency>
+      <groupId>io.avaje</groupId>
+      <artifactId>avaje-lang</artifactId>
+      <version>1.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
-      <artifactId>jakarta-persistence-api</artifactId>
-      <version>${ebean-persistence-api.version}</version>
+      <artifactId>persistence-api</artifactId>
+      <version>2.2.5</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-annotation</artifactId>
-      <version>${ebean-annotation.version}</version>
+      <version>7.7</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-types</artifactId>
-      <version>${ebean-types.version}</version>
+      <version>2.2</version>
     </dependency>
 
     <dependency>
@@ -62,14 +64,6 @@
       <version>${ebean-datasource.version}</version>
     </dependency>
 
-    <!-- Support MdcBackgroundExecutorWrapper -->
-    <dependency>
-      <groupId>org.slf4j</groupId>
-      <artifactId>slf4j-api</artifactId>
-      <version>1.7.36</version>
-      <optional>true</optional>
-    </dependency>
-
     <!-- Jackson core used internally by Ebean -->
     <dependency>
       <groupId>com.fasterxml.jackson.core</groupId>
@@ -86,25 +80,51 @@
       <optional>true</optional>
     </dependency>
 
+    <!-- Provided scope so that the H2HistoryTrigger can live in Ebean core
+     and not require a separate module for it -->
+    <dependency>
+      <groupId>com.h2database</groupId>
+      <artifactId>h2</artifactId>
+      <version>${h2database.version}</version>
+      <optional>true</optional>
+    </dependency>
+
+    <dependency>
+      <groupId>javax.transaction</groupId>
+      <artifactId>jta</artifactId>
+      <version>1.1</version>
+      <optional>true</optional>
+    </dependency>
+
+    <dependency>
+      <groupId>javax.servlet</groupId>
+      <artifactId>javax.servlet-api</artifactId>
+      <version>3.1.0</version>
+      <optional>true</optional>
+    </dependency>
+
+    <dependency>
+      <groupId>io.avaje</groupId>
+      <artifactId>junit</artifactId>
+      <version>1.1</version>
+      <scope>test</scope>
+    </dependency>
+
   </dependencies>
 
   <build>
-    <resources>
-      <resource>
-        <directory>src/main/resources</directory>
-        <filtering>true</filtering>
-        <includes>
-          <include>**/ebean-maven-version.txt</include>
-        </includes>
-      </resource>
-      <resource>
-        <directory>src/main/resources</directory>
-        <filtering>false</filtering>
-        <excludes>
-          <exclude>**/ebean-maven-version.txt</exclude>
-        </excludes>
-      </resource>
-    </resources>
+    <plugins>
+      <plugin>
+        <groupId>io.repaint.maven</groupId>
+        <artifactId>tiles-maven-plugin</artifactId>
+        <version>2.24</version>
+        <extensions>true</extensions>
+        <configuration>
+          <tiles>
+            <tile>io.avaje.tile:moditech-module:1.0</tile>
+          </tiles>
+        </configuration>
+      </plugin>
+    </plugins>
   </build>
-
 </project>

ebean-api/src/main/java/io/ebean/AcquireLockException.java

@@ -1,6 +1,6 @@
 package io.ebean;
 
-import jakarta.persistence.PessimisticLockException;
+import javax.persistence.PessimisticLockException;
 
 /**
  * Thrown when failing to acquire a pessimistic lock.

ebean-api/src/main/java/io/ebean/BackgroundExecutor.java

@@ -1,9 +1,10 @@
 package io.ebean;
 
-import org.jspecify.annotations.NullMarked;
+import io.avaje.lang.NonNullApi;
 
 import java.util.concurrent.Callable;
 import java.util.concurrent.Future;
+import java.util.concurrent.ScheduledExecutorService;
 import java.util.concurrent.ScheduledFuture;
 import java.util.concurrent.TimeUnit;
 
@@ -19,7 +20,7 @@ import java.util.concurrent.TimeUnit;
  * This also propagates MDC context from the current thread to the
  * background task if defined.
  */
-@NullMarked
+@NonNullApi
 public interface BackgroundExecutor {
 
   /**
@@ -38,6 +39,26 @@ public interface BackgroundExecutor {
    */
   void execute(Runnable task);
 
+  /**
+   * Deprecated - migrate to scheduleWithFixedDelay().
+   * Execute a task periodically with a fixed delay between each execution.
+   * <p>
+   * For example, execute a runnable every minute.
+   * <p>
+   * The delay is the time between executions no matter how long the task took.
+   * That is, this method has the same behaviour characteristics as
+   * {@link ScheduledExecutorService#scheduleWithFixedDelay(Runnable, long, long, TimeUnit)}
+   */
+  @Deprecated
+  void executePeriodically(Runnable task, long delay, TimeUnit unit);
+
+  /**
+   * Deprecated - migrate to scheduleWithFixedDelay().
+   * Execute a task periodically additionally with an initial delay different from delay.
+   */
+  @Deprecated
+  void executePeriodically(Runnable task, long initialDelay, long delay, TimeUnit unit);
+
   /**
    * Execute a task periodically with a given delay.
    *

ebean-api/src/main/java/io/ebean/BeanAccessException.java

@@ -1,25 +0,0 @@
-package io.ebean;
-
-/**
- * Unsupported access of a property on an entity bean.
- * <p>
- * Attempted a lazy load operation on a bean that has disabled lazy loading
- * or attempt to mutate an unmodifiable bean.
- */
-public class BeanAccessException extends UnsupportedOperationException {
-  private static final long serialVersionUID = 1;
-
-  /**
-   * Create with no message.
-   */
-  public BeanAccessException() {
-    super();
-  }
-
-  /**
-   * Create with message.
-   */
-  public BeanAccessException(String message) {
-    super(message);
-  }
-}

ebean-api/src/main/java/io/ebean/BeanFinder.java

@@ -1,7 +1,7 @@
 package io.ebean;
 
-import org.jspecify.annotations.NullMarked;
-import org.jspecify.annotations.Nullable;
+import io.avaje.lang.NonNullApi;
+import io.avaje.lang.Nullable;
 import java.util.List;
 import java.util.Optional;
 
@@ -12,7 +12,6 @@ import java.util.Optional;
  * </p>
  * <pre>{@code
  *
- * @Component
  * public class CustomerFinder extends BeanFinder<Long,Customer> {
  *
  *   @Inject
@@ -27,31 +26,29 @@ import java.util.Optional;
  *
  * @param <I> The ID type
  * @param <T> The Bean type
- *
- * @see BeanRepository
  */
-@NullMarked
+@NonNullApi
 public abstract class BeanFinder<I,T> {
 
-  protected final Database database;
+  protected final Database server;
   protected final Class<T> type;
 
   /**
    * Create with the given bean type and Database instance.
    *
    * @param type The bean type
-   * @param database The Database instance typically created via Spring factory or equivalent.
+   * @param server The Database instance typically created via Spring factory or equivalent.
    */
-  protected BeanFinder(Class<T> type, Database database) {
+  protected BeanFinder(Class<T> type, Database server) {
     this.type = type;
-    this.database = database;
+    this.server = server;
   }
 
   /**
    * Return the Database to use.
    */
   public Database db() {
-    return database;
+    return server;
   }
 
   /**
@@ -73,10 +70,10 @@ public abstract class BeanFinder<I,T> {
    * <p>
    * This is equivalent to {@link DB#byName(String)}
    *
-   * @param name The name of the Database. If this is null then the default Database is returned.
+   * @param server The name of the Database. If this is null then the default Database is returned.
    */
-  public Database db(String name) {
-    return DB.byName(name);
+  public Database db(String server) {
+    return DB.byName(server);
   }
 
   /**

ebean-api/src/main/java/io/ebean/BeanRepository.java

@@ -1,20 +1,16 @@
 package io.ebean;
 
-import org.jspecify.annotations.NullMarked;
+import io.avaje.lang.NonNullApi;
 import io.ebean.bean.EntityBean;
 
 import java.util.Collection;
 
 /**
- * Provides find and persist functionality for use with "Dependency Injection style" use of Ebean.
+ * Provides finder functionality for use with "Dependency Injection style" use of Ebean.
  * <p>
- * Extend the BeanRepository with additional finder and persisting methods as needed by the
- * application. The intention is to keep all the related logic together, for example, all the
- * persisting and finding logic for Customer would be in CustomerRepository.
- *
  * <pre>{@code
  *
- * @Component
+ * @Repository
  * public class CustomerRepository extends BeanRepository<Long,Customer> {
  *
  *   @Inject
@@ -36,7 +32,7 @@ import java.util.Collection;
  * @param <I> The ID type
  * @param <T> The Bean type
  */
-@NullMarked
+@NonNullApi
 public abstract class BeanRepository<I, T> extends BeanFinder<I, T> {
 
   /**
@@ -54,10 +50,10 @@ public abstract class BeanRepository<I, T> extends BeanFinder<I, T> {
    * }</pre>
    *
    * @param type   The bean type
-   * @param database The Database instance typically created via Spring factory or equivalent
+   * @param server The Database instance typically created via Spring factory or equivalent
    */
-  protected BeanRepository(Class<T> type, Database database) {
-    super(type, database);
+  protected BeanRepository(Class<T> type, Database server) {
+    super(type, server);
   }
 
   /**
@@ -126,8 +122,8 @@ public abstract class BeanRepository<I, T> extends BeanFinder<I, T> {
   /**
    * Save all the beans in the collection.
    */
-  public int saveAll(Collection<T> beans) {
-    return db().saveAll(beans);
+  public int saveAll(Collection<T> bean) {
+    return db().saveAll(bean);
   }
 
   /**

ebean-api/src/main/java/io/ebean/BeanState.java

@@ -74,22 +74,51 @@ public interface BeanState {
    */
   Set<String> loadedProps();
 
+  /**
+   * Deprecated migrate to loadedProps().
+   */
+  @Deprecated
+  default Set<String> getLoadedProps() {
+    return loadedProps();
+  }
+
   /**
    * Return the set of changed properties.
    */
   Set<String> changedProps();
 
+  /**
+   * Deprecated migrate to changedProps().
+   */
+  @Deprecated
+  default Set<String> getChangedProps() {
+    return changedProps();
+  }
+
   /**
    * Return a map of the updated properties and their new and old values.
    */
   Map<String, ValuePair> dirtyValues();
 
+  /**
+   * Deprecated migrate to dirtyValues().
+   */
+  @Deprecated
+  default Map<String, ValuePair> getDirtyValues() {
+    return dirtyValues();
+  }
+
   /**
    * Return true if the bean is readOnly.
    * <p>
    * If a setter is called on a readOnly bean it will throw an exception.
    */
-  boolean isUnmodifiable();
+  boolean isReadOnly();
+
+  /**
+   * Set the readOnly status for the bean.
+   */
+  void setReadOnly(boolean readOnly);
 
   /**
    * Advanced - Used to programmatically build a partially or fully loaded
@@ -110,9 +139,24 @@ public interface BeanState {
    */
   Map<String, Exception> loadErrors();
 
+  /**
+   * Deprecated migrate to loadErrors().
+   */
+  @Deprecated
+  default Map<String, Exception> getLoadErrors() {
+    return loadErrors();
+  }
+
   /**
    * Return the sort order value for an order column.
    */
   int sortOrder();
 
+  /**
+   * Deprecated migrate to sortOrder().
+   */
+  @Deprecated
+  default int getSortOrder() {
+    return sortOrder();
+  }
 }

ebean-api/src/main/java/io/ebean/DB.java

@@ -1,14 +1,15 @@
 package io.ebean;
 
-import org.jspecify.annotations.NullMarked;
-import org.jspecify.annotations.Nullable;
+import io.avaje.lang.NonNullApi;
+import io.avaje.lang.Nullable;
 import io.ebean.annotation.TxIsolation;
 import io.ebean.cache.ServerCacheManager;
 import io.ebean.plugin.Property;
+import io.ebean.text.csv.CsvReader;
 import io.ebean.text.json.JsonContext;
 
-import jakarta.persistence.OptimisticLockException;
-import jakarta.persistence.PersistenceException;
+import javax.persistence.OptimisticLockException;
+import javax.persistence.PersistenceException;
 import java.util.Collection;
 import java.util.List;
 import java.util.Map;
@@ -21,9 +22,10 @@ import java.util.concurrent.Callable;
  * DB additionally provides a convenient way to use the 'default' Database.
  * <p>
  * <h3>Default database</h3>
+ * <p>
  * One of the Database instances can be registered as the "default database"
  * and can be obtained using <code>DB.getDefault()</code>
- *
+ * </p>
  * <pre>{@code
  *
  * Database database = DB.getDefault();
@@ -34,7 +36,7 @@ import java.util.concurrent.Callable;
  * <p>
  * Multiple database instances can be registered with DB and we can obtain them
  * using <code>DB.byName()</code>
- *
+ * </p>
  * <pre>{@code
  *
  * Database hrDatabase = DB.byName("hr");
@@ -45,6 +47,7 @@ import java.util.concurrent.Callable;
  * <p>
  * DB has methods like {@link #find(Class)} and {@link #save(Object)} which are
  * just convenience for using the default database.
+ * </p>
  *
  * <pre>{@code
  *
@@ -57,7 +60,7 @@ import java.util.concurrent.Callable;
  *
  * }</pre>
  */
-@NullMarked
+@NonNullApi
 public final class DB {
 
   private static final DbContext context = DbContext.getInstance();
@@ -114,26 +117,39 @@ public final class DB {
    * build the WHERE and HAVING clauses. Alternatively you can use the
    * ExpressionFactory directly to create expressions to add to the query where
    * clause.
+   * </p>
    * <p>
    * Alternatively you can use the {@link Expr} as a shortcut to the
    * ExpressionFactory of the 'Default' database.
+   * </p>
    * <p>
    * You generally need to the an ExpressionFactory (or {@link Expr}) to build
    * an expression that uses OR like Expression e = Expr.or(..., ...);
+   * </p>
    */
   public static ExpressionFactory expressionFactory() {
     return getDefault().expressionFactory();
   }
 
+  /**
+   * Deprecated migrate to expressionFactory().
+   */
+  @Deprecated
+  public static ExpressionFactory getExpressionFactory() {
+    return expressionFactory();
+  }
+
   /**
    * Return the next identity value for a given bean type.
    * <p>
    * This will only work when a IdGenerator is on this bean type such as a DB
    * sequence or UUID.
+   * </p>
    * <p>
    * For DB's supporting getGeneratedKeys and sequences such as Oracle10 you do
    * not need to use this method generally. It is made available for more
    * complex cases where it is useful to get an ID prior to some processing.
+   * </p>
    */
   public static Object nextId(Class<?> beanType) {
     return getDefault().nextId(beanType);
@@ -143,14 +159,17 @@ public final class DB {
    * Start a transaction with 'REQUIRED' semantics.
    * <p>
    * With REQUIRED semantics if an active transaction already exists that transaction will be used.
+   * </p>
    * <p>
    * The transaction is stored in a ThreadLocal variable and typically you only
    * need to use the returned Transaction <em>IF</em> you wish to do things like
    * use batch mode, change the transaction isolation level, use savepoints or
    * log comments to the transaction log.
+   * </p>
    * <p>
-   * Example of using a transaction to span multiple calls to find(), save() etc.
-   *
+   * Example of using a transaction to span multiple calls to find(), save()
+   * etc.
+   * </p>
    * <pre>{@code
    *
    *   try (Transaction transaction = DB.beginTransaction()) {
@@ -168,6 +187,7 @@ public final class DB {
    * With Database we can pass the transaction to the various find(), save() and execute()
    * methods. This gives us the ability to create the transactions externally from Ebean
    * and use the transaction explicitly via the various methods available on Database.
+   * </p>
    */
   public static Transaction beginTransaction() {
     return getDefault().beginTransaction();
@@ -179,6 +199,7 @@ public final class DB {
    * You will want to do this if you want multiple Transactions in a single
    * thread or generally use transactions outside of the TransactionThreadLocal
    * management.
+   * </p>
    */
   public static Transaction createTransaction() {
     return getDefault().createTransaction();
@@ -198,6 +219,7 @@ public final class DB {
    * <p>
    * Note that this provides an try finally alternative to using {@link #executeCall(TxScope, Callable)} or
    * {@link #execute(TxScope, Runnable)}.
+   * </p>
    * <p>
    * <h3>REQUIRES_NEW example:</h3>
    * <pre>{@code
@@ -237,7 +259,7 @@ public final class DB {
   }
 
   /**
-   * The batch will be flushing automatically but, you can use this to explicitly
+   * The batch will be flushing automatically but you can use this to explicitly
    * flush the batch if you like.
    * <p>
    * Flushing occurs automatically when:
@@ -256,7 +278,7 @@ public final class DB {
 
   /**
    * Register a TransactionCallback on the currently active transaction.
-   * <p>
+   * <p/>
    * If there is no currently active transaction then a PersistenceException is thrown.
    *
    * @param transactionCallback the transaction callback to be registered with the current transaction
@@ -266,6 +288,51 @@ public final class DB {
     getDefault().register(transactionCallback);
   }
 
+  /**
+   * Commit the current transaction.
+   */
+  public static void commitTransaction() {
+    getDefault().commitTransaction();
+  }
+
+  /**
+   * Rollback the current transaction.
+   */
+  public static void rollbackTransaction() {
+    getDefault().rollbackTransaction();
+  }
+
+  /**
+   * If the current transaction has already been committed do nothing otherwise
+   * rollback the transaction.
+   * <p>
+   * It is preferable to use <em>try with resources</em> rather than this.
+   * </p>
+   * <p>
+   * Useful to put in a finally block to ensure the transaction is ended, rather
+   * than a rollbackTransaction() in each catch block.
+   * </p>
+   * <p>
+   * Code example:
+   * </p>
+   * <pre>{@code
+   *   DB.beginTransaction();
+   *   try {
+   *     // do some fetching and or persisting
+   *
+   *     // commit at the end
+   *     DB.commitTransaction();
+   *
+   *   } finally {
+   *     // if commit didn't occur then rollback the transaction
+   *     DB.endTransaction();
+   *   }
+   * }</pre>
+   */
+  public static void endTransaction() {
+    getDefault().endTransaction();
+  }
+
   /**
    * Mark the current transaction as rollback only.
    */
@@ -278,6 +345,7 @@ public final class DB {
    * <p>
    * When null is passed in for b, then the 'OldValues' of a is used for the
    * difference comparison.
+   * </p>
    */
   public static Map<String, ValuePair> diff(Object a, Object b) {
     return getDefault().diff(a, b);
@@ -288,15 +356,18 @@ public final class DB {
    * <p>
    * If there is no current transaction one will be created and committed for
    * you automatically.
+   * </p>
    * <p>
    * Save can cascade along relationships. For this to happen you need to
    * specify a cascade of CascadeType.ALL or CascadeType.PERSIST on the
    * OneToMany, OneToOne or ManyToMany annotation.
+   * </p>
    * <p>
    * When a save cascades via a OneToMany or ManyToMany Ebean will automatically
    * set the 'parent' object to the 'detail' object. In the example below in
    * saving the order and cascade saving the order details the 'parent' order
    * will be set against each order detail when it is saved.
+   * </p>
    */
   public static void save(Object bean) throws OptimisticLockException {
     getDefault().save(bean);
@@ -347,9 +418,11 @@ public final class DB {
    * <b>Stateless updates:</b> Note that the bean does not have to be previously fetched to call
    * update().You can create a new instance and set some of its properties programmatically for via
    * JSON/XML marshalling etc. This is described as a 'stateless update'.
+   * </p>
    * <p>
    * <b>Optimistic Locking: </b> Note that if the version property is not set when update() is
    * called then no optimistic locking is performed (internally ConcurrencyMode.NONE is used).
+   * </p>
    * <p>
    * <pre>{@code
    *
@@ -466,16 +539,20 @@ public final class DB {
    * Delete the bean.
    * <p>
    * This will return true if the bean was deleted successfully or JDBC batch is being used.
+   * </p>
    * <p>
    * If there is no current transaction one will be created and committed for
    * you automatically.
+   * </p>
    * <p>
    * If the bean is configured with <code>@SoftDelete</code> then this will perform a soft
    * delete rather than a hard/permanent delete.
+   * </p>
    * <p>
    * If the Bean does not have a version property (or loaded version property) and
    * the bean does not exist then this returns false indicating that nothing was
    * deleted. Note that, if JDBC batch mode is used then this always returns true.
+   * </p>
    */
   public static boolean delete(Object bean) throws OptimisticLockException {
     return getDefault().delete(bean);
@@ -535,6 +612,7 @@ public final class DB {
    * <p>
    * Note that this resets OneToMany and ManyToMany properties so that if they
    * are accessed a lazy load will refresh the many property.
+   * </p>
    */
   public static void refresh(Object bean) {
     getDefault().refresh(bean);
@@ -542,7 +620,6 @@ public final class DB {
 
   /**
    * Refresh a 'many' property of a bean.
-   *
    * <pre>{@code
    *
    *   Order order = ...;
@@ -563,7 +640,7 @@ public final class DB {
    * Get a reference object.
    * <p>
    * This is sometimes described as a proxy (with lazy loading).
-   *
+   * </p>
    * <pre>{@code
    *
    *   Product product = DB.getReference(Product.class, 1);
@@ -584,6 +661,14 @@ public final class DB {
     return getDefault().reference(beanType, id);
   }
 
+  /**
+   * Deprecated migrate to beanId().
+   */
+  @Deprecated
+  public static <T> T getReference(Class<T> beanType, Object id) {
+    return reference(beanType, id);
+  }
+
   /**
    * Sort the list using the sortByClause which can contain a comma delimited
    * list of property names and keywords asc, desc, nullsHigh and nullsLow.
@@ -599,13 +684,13 @@ public final class DB {
    * <p>
    * Note that the sorting uses a Comparator and Collections.sort(); and does
    * not invoke a DB query.
-   *
+   * </p>
    * <pre>{@code
    *
    *   // find orders and their customers
    *   List<Order> list = DB.find(Order.class)
    *     .fetch("customer")
-   *     .orderBy("id")
+   *     .order("id")
    *     .findList();
    *
    *   // sort by customer name ascending, then by order shipDate
@@ -634,8 +719,9 @@ public final class DB {
    *
    * }</pre>
    * <p>
-   * If you want more control over the query then you can use createQuery() and Query.findOne();
-   *
+   * If you want more control over the query then you can use createQuery() and
+   * Query.findOne();
+   * </p>
    * <pre>{@code
    *
    *   // ... additionally fetching customer, customer shipping address,
@@ -675,25 +761,40 @@ public final class DB {
   }
 
   /**
-   * Look to execute a native sql query that does not return beans but instead
-   * returns SqlRow or uses {@link RowMapper}.
+   * Look to execute a native sql query that does not returns beans but instead
+   * returns SqlRow or direct access to ResultSet (see {@link SqlQuery#findList(RowMapper)}.
+   *
    * <p>
    * Refer to {@link DtoQuery} for native sql queries returning DTO beans.
+   * </p>
    * <p>
    * Refer to {@link #findNative(Class, String)} for native sql queries returning entity beans.
+   * </p>
    */
   public static SqlQuery sqlQuery(String sql) {
     return getDefault().sqlQuery(sql);
   }
 
+  /**
+   * Deprecated - migrate to sqlQuery().
+   * <p>
+   * This is an alias for {@link #sqlQuery(String)}.
+   */
+  @Deprecated
+  public static SqlQuery createSqlQuery(String sql) {
+    return sqlQuery(sql);
+  }
+
   /**
    * Look to execute a native sql insert update or delete statement.
    * <p>
    * Use this to execute a Insert Update or Delete statement. The statement will
    * be native to the database and contain database table and column names.
+   * </p>
    *
    * <p>
    * See {@link SqlUpdate} for example usage.
+   * </p>
    *
    * @return The SqlUpdate instance to set parameters and execute
    */
@@ -701,6 +802,16 @@ public final class DB {
     return getDefault().sqlUpdate(sql);
   }
 
+  /**
+   * Deprecated - migrate to sqlUpdate().
+   * <p>
+   * This is an alias for {@link #sqlUpdate(String)}.
+   */
+  @Deprecated
+  public static SqlUpdate createSqlUpdate(String sql) {
+    return sqlUpdate(sql);
+  }
+
   /**
    * Create a CallableSql to execute a given stored procedure.
    *
@@ -717,9 +828,10 @@ public final class DB {
    * <p>
    * The orm update differs from the sql update in that it you can use the bean
    * name and bean property names rather than table and column names.
+   * </p>
    * <p>
    * An example:
-   *
+   * </p>
    * <pre>{@code
    *
    *   // The bean name and properties - "topic","postCount" and "id"
@@ -741,11 +853,18 @@ public final class DB {
     return getDefault().createUpdate(beanType, ormUpdate);
   }
 
+  /**
+   * Create a CsvReader for a given beanType.
+   */
+  public static <T> CsvReader<T> createCsvReader(Class<T> beanType) {
+    return getDefault().createCsvReader(beanType);
+  }
 
   /**
    * Create a named query.
    * <p>
    * For RawSql the named query is expected to be in ebean.xml.
+   * </p>
    *
    * @param beanType   The type of entity bean
    * @param namedQuery The name of the query
@@ -761,12 +880,15 @@ public final class DB {
    * <p>
    * You can use the methods on the Query object to specify fetch paths,
    * predicates, order by, limits etc.
+   * </p>
    * <p>
    * You then use findList(), findSet(), findMap() and findOne() to execute
    * the query and return the collection or bean.
+   * </p>
    * <p>
    * Note that a query executed by {@link Query#findList()} etc will execute against
    * the same database from which is was created.
+   * </p>
    *
    * @param beanType the class of entity to be fetched
    * @return A ORM Query for this beanType
@@ -818,6 +940,7 @@ public final class DB {
    * This is actually the same as {@link #createQuery(Class)}. The reason it
    * exists is that people used to JPA will probably be looking for a
    * createQuery method (the same as entityManager).
+   * </p>
    *
    * @param beanType the type of entity bean to find
    * @return A ORM Query object for this beanType
@@ -830,7 +953,7 @@ public final class DB {
    * Create a query using native SQL.
    * <p>
    * The native SQL can contain named parameters or positioned parameters.
-   *
+   * </p>
    * <pre>{@code
    *
    *   String sql = "select c.id, c.name from customer c where c.name like ? order by c.name";
@@ -855,6 +978,7 @@ public final class DB {
    * <p>
    * DTO beans are just normal bean like classes with public constructor(s) and setters.
    * They do not need to be registered with Ebean before use.
+   * </p>
    *
    * @param dtoType The type of the DTO bean the rows will be mapped into.
    * @param sql     The SQL query to execute.
@@ -891,8 +1015,10 @@ public final class DB {
    * going back to the database.
    * <p>
    * This produces and returns a new list with the sort and filters applied.
+   * </p>
    * <p>
    * Refer to {@link Filter} for an example of its use.
+   * </p>
    */
   public static <T> Filter<T> filter(Class<T> beanType) {
     return getDefault().filter(beanType);
@@ -903,7 +1029,7 @@ public final class DB {
    * <p>
    * The scope can control the transaction type, isolation and rollback
    * semantics.
-   *
+   * </p>
    * <pre>{@code
    *
    * // set specific transactional scope settings
@@ -911,7 +1037,7 @@ public final class DB {
    *
    * DB.execute(scope, new TxRunnable() {
    *   public void run() {
-   *     User u1 = DB.find(User.class, 1);
+   * 	   User u1 = DB.find(User.class, 1);
    *     ...
    *   }
    * });
@@ -927,7 +1053,7 @@ public final class DB {
    * <p>
    * The default scope runs with REQUIRED and by default will rollback on any
    * exception (checked or runtime).
-   *
+   * </p>
    * <pre>{@code
    *
    * DB.execute(() -> {
@@ -952,7 +1078,7 @@ public final class DB {
    * <p>
    * The scope can control the transaction type, isolation and rollback
    * semantics.
-   *
+   * </p>
    * <pre>{@code
    *
    * // set specific transactional scope settings
@@ -960,9 +1086,9 @@ public final class DB {
    *
    * DB.executeCall(scope, new Callable<String>() {
    *   public String call() {
-   *     User u1 = DB.find(User.class, 1);
-   *     ...
-   *     return u1.getEmail();
+   * 	   User u1 = DB.find(User.class, 1);
+   * 		 ...
+   * 		 return u1.getEmail();
    *   }
    * });
    * }</pre>
@@ -976,10 +1102,11 @@ public final class DB {
    * <p>
    * The default scope runs with REQUIRED and by default will rollback on any
    * exception (checked or runtime).
+   * </p>
    * <p>
    * This is basically the same as TxRunnable except that it returns an Object
    * (and you specify the return type via generics).
-   *
+   * </p>
    * <pre>{@code
    *
    * DB.executeCall(() -> {
@@ -1008,19 +1135,23 @@ public final class DB {
    * <p>
    * If you use DB.execute(UpdateSql) then the table modification information
    * is automatically deduced and you do not need to call this method yourself.
+   * </p>
    * <p>
    * This information is used to invalidate objects out of the cache and
    * potentially text indexes. This information is also automatically broadcast
    * across the cluster.
+   * </p>
    * <p>
    * If there is a transaction then this information is placed into the current
    * transactions event information. When the transaction is committed this
    * information is registered (with the transaction manager). If this
    * transaction is rolled back then none of the transaction event information
    * registers including the information you put in via this method.
+   * </p>
    * <p>
    * If there is NO current transaction when you call this method then this
    * information is registered immediately (with the transaction manager).
+   * </p>
    *
    * @param tableName the name of the table that was modified
    * @param inserts   true if rows where inserted into the table
@@ -1035,11 +1166,20 @@ public final class DB {
    * Return the BeanState for a given entity bean.
    * <p>
    * This will return null if the bean is not an enhanced entity bean.
+   * </p>
    */
   public static BeanState beanState(Object bean) {
     return getDefault().beanState(bean);
   }
 
+  /**
+   * Deprecated migrate to beanState().
+   */
+  @Deprecated
+  public static BeanState getBeanState(Object bean) {
+    return beanState(bean);
+  }
+
   /**
    * Return the value of the Id property for a given bean.
    */
@@ -1047,6 +1187,14 @@ public final class DB {
     return getDefault().beanId(bean);
   }
 
+  /**
+   * Deprecated migrate to beanId().
+   */
+  @Deprecated
+  public static Object getBeanId(Object bean) {
+    return beanId(bean);
+  }
+
   /**
    * Load and lock the bean using {@code select for update}.
    * <p>
@@ -1062,6 +1210,14 @@ public final class DB {
     getDefault().lock(bean);
   }
 
+  /**
+   * Deprecated migrate to cacheManager().
+   */
+  @Deprecated
+  public static ServerCacheManager getServerCacheManager() {
+    return getDefault().cacheManager();
+  }
+
   /**
    * Return the manager of the level 2 cache ("L2" cache).
    */
@@ -1077,6 +1233,14 @@ public final class DB {
     return getDefault().backgroundExecutor();
   }
 
+  /**
+   * Deprecated migrate to backgroundExecutor().
+   */
+  @Deprecated
+  public static BackgroundExecutor getBackgroundExecutor() {
+    return backgroundExecutor();
+  }
+
   /**
    * Return the JsonContext for reading/writing JSON.
    */

ebean-api/src/main/java/io/ebean/DInTuples.java

@@ -1,49 +0,0 @@
-package io.ebean;
-
-import io.ebean.service.SpiInTuples;
-
-import java.util.ArrayList;
-import java.util.Collections;
-import java.util.List;
-
-/**
- * Default implementation of SpiInTuples.
- */
-final class DInTuples implements SpiInTuples {
-
-  private final String[] properties;
-  private final int propertyCount;
-  private final List<Object[]> entries = new ArrayList<>();
-
-
-  DInTuples(String[] properties) {
-    this.properties = properties;
-    this.propertyCount = properties.length;
-  }
-
-  @Override
-  public InTuples add(Object... values) {
-    if (values.length != propertyCount) {
-      throw new IllegalArgumentException("Require " + propertyCount + " values but got " + values.length);
-    }
-    entries.add(values);
-    return this;
-  }
-
-  /**
-   * Return the first property name.
-   */
-  @Override
-  public String[] properties() {
-    return properties;
-  }
-
-  /**
-   * Return all the value pairs.
-   */
-  @Override
-  public List<Object[]> entries() {
-    return Collections.unmodifiableList(entries);
-  }
-
-}

ebean-api/src/main/java/io/ebean/DInsertOptionsBuilder.java

@@ -1,104 +0,0 @@
-package io.ebean;
-
-final class DInsertOptionsBuilder implements InsertOptions.Builder {
-
-  private Boolean getGeneratedKeys;
-  private boolean onConflictUpdate;
-  private boolean onConflictNothing;
-  private String constraint;
-  private String uniqueColumns;
-  private String updateSet;
-
-  @Override
-  public InsertOptions.Builder onConflictNothing() {
-    this.onConflictNothing = true;
-    return this;
-  }
-
-  @Override
-  public InsertOptions.Builder onConflictUpdate() {
-    this.onConflictUpdate = true;
-    return this;
-  }
-
-  @Override
-  public InsertOptions.Builder constraint(String constraint) {
-    this.constraint = constraint;
-    return this;
-  }
-
-  @Override
-  public InsertOptions.Builder uniqueColumns(String uniqueColumns) {
-    this.uniqueColumns = uniqueColumns;
-    return this;
-  }
-
-  @Override
-  public InsertOptions.Builder updateSet(String updateSet) {
-    this.updateSet = updateSet;
-    return this;
-  }
-
-  @Override
-  public InsertOptions.Builder getGeneratedKeys(boolean getGeneratedKeys) {
-    this.getGeneratedKeys = getGeneratedKeys;
-    return this;
-  }
-
-  @Override
-  public InsertOptions build() {
-    return new Options(constraint, uniqueColumns, updateSet, onConflictUpdate, onConflictNothing, getGeneratedKeys);
-  }
-
-  static final class Options implements InsertOptions {
-
-    private static final String UPDATE = "U";
-    private static final String NOTHING = "N";
-    private static final String NORMAL = "_";
-    private final String key;
-    private final Boolean getGeneratedKeys;
-    private final String constraint;
-    private final String uniqueColumns;
-    private final String updateSet;
-
-    Options(String constraint, String uniqueColumns, String updateSet, boolean onConflictUpdate, boolean onConflictNothing, Boolean getGeneratedKeys) {
-      this.constraint = constraint;
-      this.uniqueColumns = uniqueColumns;
-      this.updateSet = updateSet;
-      this.getGeneratedKeys = getGeneratedKeys;
-      this.key = (onConflictUpdate ? UPDATE : onConflictNothing ? NOTHING : NORMAL)
-        + '+' + plus(constraint)
-        + '+' + plus(uniqueColumns)
-        + '+' + plus(updateSet);
-    }
-
-    private String plus(String val) {
-      return val == null ? "" : val;
-    }
-
-    @Override
-    public String key() {
-      return key;
-    }
-
-    @Override
-    public String constraint() {
-      return constraint;
-    }
-
-    @Override
-    public String uniqueColumns() {
-      return uniqueColumns;
-    }
-
-    @Override
-    public String updateSet() {
-      return updateSet;
-    }
-
-    @Override
-    public Boolean getGetGeneratedKeys() {
-      return getGeneratedKeys;
-    }
-  }
-}

ebean-api/src/main/java/io/ebean/DPaging.java

@@ -1,50 +0,0 @@
-package io.ebean;
-
-final class DPaging implements Paging {
-
-  static final Paging NONE = new DPaging(0, 0, null);
-
-  static Paging build(int pgIndex, int pgSize, OrderBy<?> orderBy) {
-    return new DPaging(pgIndex, pgSize, orderBy);
-  }
-
-  static Paging build(int pgIndex, int pgSize) {
-    return new DPaging(pgIndex, pgSize, null);
-  }
-
-  private final int pageNumber;
-  private final int pageSize;
-  private final OrderBy<?> orderBy;
-
-  DPaging(int pageNumber, int pageSize, OrderBy<?> orderBy) {
-    this.pageNumber = pageNumber;
-    this.pageSize = pageSize;
-    this.orderBy = orderBy;
-  }
-
-  @Override
-  public int pageIndex() {
-    return pageNumber;
-  }
-
-  @Override
-  public int pageSize() {
-    return pageSize;
-  }
-
-  @Override
-  public OrderBy<?> orderBy() {
-    return orderBy;
-  }
-
-  @Override
-  public Paging withPage(int pageNumber) {
-    return new DPaging(pageNumber, pageSize, orderBy);
-  }
-
-  @Override
-  public Paging withOrderBy(String orderByClause) {
-    return new DPaging(pageNumber, pageSize, OrderBy.of(orderByClause));
-  }
-
-}

ebean-api/src/main/java/io/ebean/DataIntegrityException.java

@@ -1,9 +1,9 @@
 package io.ebean;
 
-import jakarta.persistence.PersistenceException;
+import javax.persistence.PersistenceException;
 
 /**
- * Thrown when a foreign key constraint is enforced or a field is too large.
+ * Thrown when a foreign key constraint is enforced.
  */
 public class DataIntegrityException extends PersistenceException {
   private static final long serialVersionUID = -6740171949170180970L;
@@ -14,11 +14,4 @@ public class DataIntegrityException extends PersistenceException {
   public DataIntegrityException(String message, Throwable cause) {
     super(message, cause);
   }
-
-  /**
-   * Create with message only.
-   */
-  public DataIntegrityException(String message) {
-    super(message);
-  }
 }

ebean-api/src/main/java/io/ebean/DatabaseFactory.java

@@ -1,10 +1,14 @@
 package io.ebean;
 
 import io.ebean.config.ContainerConfig;
+import io.ebean.config.DatabaseConfig;
 import io.ebean.service.SpiContainer;
 import io.ebean.service.SpiContainerFactory;
-import jakarta.persistence.PersistenceException;
 
+import javax.persistence.PersistenceException;
+import java.util.Iterator;
+import java.util.Properties;
+import java.util.ServiceLoader;
 import java.util.concurrent.locks.ReentrantLock;
 
 /**
@@ -22,7 +26,7 @@ import java.util.concurrent.locks.ReentrantLock;
  * methods on the DB singleton such as {@link DB#find(Class)} are just a
  * convenient way of using the 'default/primary' Database.
  */
-public final class DatabaseFactory {
+public class DatabaseFactory {
 
   private static final ReentrantLock lock = new ReentrantLock();
   private static SpiContainer container;
@@ -72,10 +76,9 @@ public final class DatabaseFactory {
    *
    * }</pre>
    */
-  public static Database create(DatabaseBuilder builder) {
+  public static Database create(DatabaseConfig config) {
     lock.lock();
     try {
-      var config = builder.settings();
       if (config.getName() == null) {
         throw new PersistenceException("The name is null (it is required)");
       }
@@ -99,7 +102,7 @@ public final class DatabaseFactory {
   /**
    * Create using the DatabaseConfig additionally specifying a classLoader to use as the context class loader.
    */
-  public static Database createWithContextClassLoader(DatabaseBuilder config, ClassLoader classLoader) {
+  public static Database createWithContextClassLoader(DatabaseConfig config, ClassLoader classLoader) {
     lock.lock();
     try {
       ClassLoader currentContextLoader = Thread.currentThread().getContextClassLoader();
@@ -129,7 +132,7 @@ public final class DatabaseFactory {
     }
   }
 
-  private static Database createInternal(DatabaseBuilder.Settings config) {
+  private static Database createInternal(DatabaseConfig config) {
     return container(config.getContainerConfig()).createServer(config);
   }
 
@@ -143,9 +146,12 @@ public final class DatabaseFactory {
     if (container != null) {
       return container;
     }
+
     if (containerConfig == null) {
       // effectively load configuration from ebean.properties
+      Properties properties = DbPrimary.getProperties();
       containerConfig = new ContainerConfig();
+      containerConfig.loadFromProperties(properties);
     }
     container = createContainer(containerConfig);
     return container;
@@ -154,11 +160,11 @@ public final class DatabaseFactory {
   /**
    * Create the container instance using the configuration.
    */
-  private static SpiContainer createContainer(ContainerConfig containerConfig) {
-    SpiContainerFactory factory = XBootstrapService.containerFactory();
-    if (factory == null) {
-      throw new IllegalStateException("Service loader didn't find a SpiContainerFactory?");
+  protected static SpiContainer createContainer(ContainerConfig containerConfig) {
+    Iterator<SpiContainerFactory> factories = ServiceLoader.load(SpiContainerFactory.class).iterator();
+    if (factories.hasNext()) {
+      return factories.next().create(containerConfig);
     }
-    return factory.create(containerConfig);
+    throw new IllegalStateException("Service loader didn't find a SpiContainerFactory?");
   }
 }

ebean-api/src/main/java/io/ebean/DbContext.java

@@ -2,20 +2,20 @@ package io.ebean;
 
 import io.ebean.config.BeanNotEnhancedException;
 import io.ebean.datasource.DataSourceConfigurationException;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 
-import jakarta.persistence.PersistenceException;
+import javax.persistence.PersistenceException;
 import java.util.HashMap;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.locks.ReentrantLock;
 
-import static java.lang.System.Logger.Level.ERROR;
-
 /**
  * Holds Database instances.
  */
 final class DbContext {
 
-  private static final System.Logger log = EbeanVersion.log;
+  private static final Logger log = LoggerFactory.getLogger("io.ebean");
   static {
     EbeanVersion.getVersion();
   }
@@ -23,9 +23,14 @@ final class DbContext {
   private static final DbContext INSTANCE = new DbContext();
 
   private final ConcurrentHashMap<String, Database> concMap = new ConcurrentHashMap<>();
+
   private final HashMap<String, Database> syncMap = new HashMap<>();
+
   private final ReentrantLock lock = new ReentrantLock();
 
+  /**
+   * The 'default' Database.
+   */
   private Database defaultDatabase;
 
   private DbContext() {
@@ -38,19 +43,16 @@ final class DbContext {
         }
       }
     } catch (BeanNotEnhancedException e) {
-      String msg = "Bean is not enhanced? See https://ebean.io/docs/trouble-shooting#not-enhanced";
-      log.log(ERROR, msg, e);
       throw e;
 
     } catch (DataSourceConfigurationException e) {
       String msg = "Configuration error creating DataSource for the default Database." +
         " This typically means a missing application-test.yaml or missing ebean-test dependency." +
         " See https://ebean.io/docs/trouble-shooting#datasource";
-      log.log(ERROR, msg, e);
       throw new DataSourceConfigurationException(msg, e);
 
     } catch (Throwable e) {
-      log.log(ERROR, "Error trying to create the default Database", e);
+      log.error("Error trying to create the default Database", e);
       throw new RuntimeException(e);
     }
   }
@@ -67,9 +69,9 @@ final class DbContext {
    */
   Database getDefault() {
     if (defaultDatabase == null) {
-      String msg = "The default Database has not been defined?"
-        + " This is normally set via the ebean.datasource.default property."
-        + " Otherwise it should be registered programmatically via registerServer()";
+      String msg = "The default Database has not been defined?";
+      msg += " This is normally set via the ebean.datasource.default property.";
+      msg += " Otherwise it should be registered programmatically via registerServer()";
       throw new PersistenceException(msg);
     }
     return defaultDatabase;

ebean-api/src/main/java/io/ebean/DbPrimary.java

@@ -10,7 +10,7 @@ import java.util.concurrent.locks.ReentrantLock;
  * <p/>
  * Intended for internal use as part of bootup, construction, registration of the default database.
  */
-final class DbPrimary {
+class DbPrimary {
 
   private static final ReentrantLock lock = new ReentrantLock();
   private static String defaultServerName;
@@ -44,12 +44,25 @@ final class DbPrimary {
    * Return the default database name.
    */
   static String getDefaultServerName() {
+    lock.lock();
+    try {
+      getProperties();
+      return defaultServerName;
+    } finally {
+      lock.unlock();
+    }
+  }
+
+  /**
+   * Return the default configuration Properties.
+   */
+  static Properties getProperties() {
     lock.lock();
     try {
       if (defaultServerName == null) {
         defaultServerName = determineDefaultServerName();
       }
-      return defaultServerName;
+      return Config.asProperties();
     } finally {
       lock.unlock();
     }
@@ -63,9 +76,9 @@ final class DbPrimary {
     defaultServerName = System.getProperty("db", defaultServerName);
     defaultServerName = System.getProperty("ebean_db", defaultServerName);
     if (isEmpty(defaultServerName)) {
-      defaultServerName = Config.getOptional("datasource.default").orElse(null);
+      defaultServerName = Config.get("datasource.default", null);
       if (isEmpty(defaultServerName)) {
-        defaultServerName = Config.getOptional("ebean.default.datasource").orElse(null);
+        defaultServerName = Config.get("ebean.default.datasource", null);
       }
     }
     if (defaultServerName == null) {

ebean-api/src/main/java/io/ebean/DocumentStore.java

@@ -1,7 +1,7 @@
 package io.ebean;
 
-import org.jspecify.annotations.NullMarked;
-import org.jspecify.annotations.Nullable;
+import io.avaje.lang.NonNullApi;
+import io.avaje.lang.Nullable;
 import io.ebean.docstore.DocQueryContext;
 import io.ebean.docstore.RawDoc;
 
@@ -14,7 +14,7 @@ import java.util.function.Predicate;
 /**
  * Document storage operations.
  */
-@NullMarked
+@NonNullApi
 public interface DocumentStore {
 
   /**

ebean-api/src/main/java/io/ebean/DtoQuery.java

@@ -1,10 +1,8 @@
 package io.ebean;
 
-import org.jspecify.annotations.NullMarked;
-import org.jspecify.annotations.Nullable;
+import io.avaje.lang.NonNullApi;
+import io.avaje.lang.Nullable;
 
-import javax.sql.DataSource;
-import java.sql.Connection;
 import java.util.Collection;
 import java.util.List;
 import java.util.Optional;
@@ -42,7 +40,7 @@ import java.util.stream.Stream;
  *
  * }</pre>
  */
-@NullMarked
+@NonNullApi
 public interface DtoQuery<T> extends CancelableQuery {
 
   /**
@@ -131,26 +129,10 @@ public interface DtoQuery<T> extends CancelableQuery {
    */
   DtoQuery<T> setParameter(String name, Object value);
 
-  /**
-   * Bind the named parameter to SQL NULL.
-   */
-  DtoQuery<T> setNullParameter(String name, int jdbcType);
-
   /**
    * Bind the named multi-value array parameter which we would use with Postgres ANY.
    * <p>
    * For Postgres this binds an ARRAY rather than expands into multiple bind values.
-   * <pre>{@code
-   *
-   *   String sql = "select id, name from o_customer where id = any(:idList)";
-   *
-   *   var ids = List.of(1, 2, 3);
-   *
-   *   List<CustomerDto> list2 = DB.findDto(CustomerDto.class, sql)
-   *       .setArrayParameter("idList", ids)
-   *       .findList();
-   *
-   * }</pre>
    */
   DtoQuery<T> setArrayParameter(String name, Collection<?> values);
 
@@ -159,11 +141,6 @@ public interface DtoQuery<T> extends CancelableQuery {
    */
   DtoQuery<T> setParameter(int position, Object value);
 
-  /**
-   * Set a positioned parameter to SQL NULL.
-   */
-  DtoQuery<T> setNullParameter(int position, int jdbcType);
-
   /**
    * Set the index of the first row of the results to return.
    */
@@ -218,32 +195,4 @@ public interface DtoQuery<T> extends CancelableQuery {
    * 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).
-   * <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.
-   *
-   * @see #usingMaster()
-   */
-  DtoQuery<T> usingMaster(boolean useMaster);
-
 }

ebean-api/src/main/java/io/ebean/DuplicateKeyException.java

@@ -2,28 +2,6 @@ package io.ebean;
 
 /**
  * Thrown when a duplicate is attempted on a unique constraint.
- * <p>
- * In terms of catching this exception with the view of continuing processing
- * using the same transaction look to use {@link Transaction#rollbackAndContinue()}.
- *
- * <pre>{@code
- *
- *   try (Transaction txn = database.beginTransaction()) {
- *
- *     try {
- *       ...
- *       database.save(bean);
- *       database.flush();
- *     } catch (DuplicateKeyException e) {
- *       // carry on processing using the transaction
- *       txn.rollbackAndContinue();
- *       ...
- *     }
- *
- *     txn.commit();
- *   }
- *
- * }</pre>
  */
 public class DuplicateKeyException extends DataIntegrityException {
   private static final long serialVersionUID = -4771932723285724817L;