Version 16.5.0

Default prepared statement cache increased from 100 to 300. This could have the
effect of increased memory consumption for applications traded off with potentially
improved performance due to me cached prepared statements for larger applications.

Note that the Postgres itself has a default of 250.

.github/workflows/build.yml

@@ -2,6 +2,7 @@
 name: Build
 
 on:
+  workflow_dispatch:
   pull_request:
   push:
     branches: master
@@ -20,14 +21,14 @@ jobs:
         os: [ubuntu-latest]
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Java
-      uses: actions/setup-java@v3
+      uses: actions/setup-java@v4
       with:
         java-version: ${{ matrix.java_version }}
         distribution: 'zulu'
     - name: Maven cache
-      uses: actions/cache@v3
+      uses: actions/cache@v4
       env:
         cache-name: maven-cache
       with:
@@ -39,5 +40,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
+      run: mvn -T 8 clean test -Pdefault
 

.github/workflows/db2luw.yml

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

.github/workflows/h2database.yml

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

.github/workflows/jdk-ea.yml

@@ -20,14 +20,14 @@ jobs:
         os: [ubuntu-latest]
 
     steps:
-    - uses: actions/checkout@v3
+    - 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@v3
+      uses: actions/cache@v4
       env:
         cache-name: maven-cache
       with:
@@ -37,5 +37,5 @@ jobs:
     - name: Maven version
       run: mvn --version
     - name: Build with Maven
-      run: mvn -T 8 test
+      run: mvn test -Pea
 

.github/workflows/mariadb.yml

@@ -20,19 +20,19 @@ jobs:
         os: [ubuntu-latest]
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Java
-      uses: actions/setup-java@v3
+      uses: actions/setup-java@v4
       with:
         java-version: ${{ matrix.java_version }}
         distribution: 'adopt'
     - name: Maven cache
-      uses: actions/cache@v3
+      uses: actions/cache@v4
       env:
         cache-name: maven-cache
       with:
         path:
           ~/.m2
         key: build-${{ env.cache-name }}
-    - name: mariadb 10.6
+    - name: mariadb 10.11
       run: mvn -T 8 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@v3
+    - uses: actions/checkout@v4
     - name: Set up Java
-      uses: actions/setup-java@v3
+      uses: actions/setup-java@v4
       with:
         java-version: ${{ matrix.java_version }}
         distribution: 'adopt'
     - name: Maven cache
-      uses: actions/cache@v3
+      uses: actions/cache@v4
       env:
         cache-name: maven-cache
       with:

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

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

.github/workflows/mysql.yml

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

.github/workflows/oracle.yml

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

.github/workflows/postgres.yml

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

.github/workflows/sqlserver-2019.yml

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

.github/workflows/sqlserver.yml

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

.github/workflows/valhalla.yml

@@ -0,0 +1,41 @@
+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 * * *'
+    - cron: '10 3 * * 3'
 
 jobs:
   build:
@@ -20,14 +20,14 @@ jobs:
         os: [ubuntu-latest]
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Java
-      uses: actions/setup-java@v3
+      uses: actions/setup-java@v4
       with:
         java-version: ${{ matrix.java_version }}
         distribution: 'adopt'
     - name: Maven cache
-      uses: actions/cache@v3
+      uses: actions/cache@v4
       env:
         cache-name: maven-cache
       with:

README.md

@@ -3,6 +3,7 @@
 [![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/)
 
 ##### 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)
@@ -56,12 +57,7 @@ Work at the highest level of abstraction and drop down levels as needed.
     <tr>
       <td align="center" valign="middle">
         <a href="https://www.foconis.de/" target="_blank">
-          <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">
+          <img width="222px" src="https://group.foconis.com/download/ci/logo/png-72dpi/logo-quer/foconis-analytics-quer.png">
         </a>
       </td>
       <td align="center" valign="middle">
@@ -85,6 +81,16 @@ or [github discussions](https://github.com/ebean-orm/ebean/discussions)
 ## Documentation
 Goto [https://ebean.io/docs/](https://ebean.io/docs/)
 
+## Guides
+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)
 

composites/ebean-clickhouse/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>14.0.2</version>
+    <version>16.5.0</version>
     <relativePath>../..</relativePath>
   </parent>
 
@@ -17,13 +17,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-core</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
@@ -42,13 +42,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-querybean</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-platform-clickhouse</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
   </dependencies>

composites/ebean-cockroach/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>14.0.2</version>
+    <version>16.5.0</version>
     <relativePath>../..</relativePath>
   </parent>
 
@@ -17,13 +17,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-core</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
@@ -42,13 +42,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-querybean</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-platform-postgres</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
   </dependencies>

composites/ebean-db2/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>14.0.2</version>
+    <version>16.5.0</version>
     <relativePath>../..</relativePath>
   </parent>
 
@@ -17,13 +17,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-core</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
@@ -42,13 +42,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-querybean</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-platform-db2</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
   </dependencies>

composites/ebean-h2/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>14.0.2</version>
+    <version>16.5.0</version>
     <relativePath>../..</relativePath>
   </parent>
 
@@ -17,13 +17,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-core</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
@@ -42,13 +42,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-querybean</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-platform-h2</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
   </dependencies>

composites/ebean-hana/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>14.0.2</version>
+    <version>16.5.0</version>
     <relativePath>../..</relativePath>
   </parent>
 
@@ -17,13 +17,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-core</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
@@ -42,13 +42,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-querybean</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-platform-hana</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
   </dependencies>

composites/ebean-mariadb/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>14.0.2</version>
+    <version>16.5.0</version>
     <relativePath>../..</relativePath>
   </parent>
 
@@ -17,13 +17,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-core</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
@@ -42,13 +42,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-querybean</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-platform-mariadb</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
   </dependencies>

composites/ebean-mysql/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>14.0.2</version>
+    <version>16.5.0</version>
     <relativePath>../..</relativePath>
   </parent>
 
@@ -17,13 +17,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-core</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
@@ -42,13 +42,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-querybean</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-platform-mysql</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
   </dependencies>

composites/ebean-net-postgis/pom.xml

@@ -0,0 +1,85 @@
+<?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.5.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.5.0</version>
+    </dependency>
+
+    <dependency>
+      <groupId>io.ebean</groupId>
+      <artifactId>ebean-core</artifactId>
+      <version>16.5.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.5.0</version>
+    </dependency>
+
+    <dependency>
+      <groupId>io.ebean</groupId>
+      <artifactId>ebean-platform-postgres</artifactId>
+      <version>16.5.0</version>
+    </dependency>
+
+    <dependency>
+      <groupId>io.ebean</groupId>
+      <artifactId>ebean-net-postgis-types</artifactId>
+      <version>16.5.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

@@ -0,0 +1,7 @@
+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

@@ -0,0 +1,10 @@
+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

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>14.0.2</version>
+    <version>16.5.0</version>
     <relativePath>../..</relativePath>
   </parent>
 
@@ -17,13 +17,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-core</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
@@ -42,13 +42,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-querybean</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-platform-nuodb</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
   </dependencies>

composites/ebean-oracle/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>14.0.2</version>
+    <version>16.5.0</version>
     <relativePath>../..</relativePath>
   </parent>
 
@@ -17,13 +17,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-core</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
@@ -42,13 +42,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-querybean</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-platform-oracle</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
   </dependencies>

composites/ebean-pgvector/pom.xml

@@ -0,0 +1,85 @@
+<?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.5.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.5.0</version>
+    </dependency>
+
+    <dependency>
+      <groupId>io.ebean</groupId>
+      <artifactId>ebean-core</artifactId>
+      <version>16.5.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.5.0</version>
+    </dependency>
+
+    <dependency>
+      <groupId>io.ebean</groupId>
+      <artifactId>ebean-platform-postgres</artifactId>
+      <version>16.5.0</version>
+    </dependency>
+
+    <dependency>
+      <groupId>io.ebean</groupId>
+      <artifactId>ebean-pgvector-types</artifactId>
+      <version>16.5.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

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

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

@@ -0,0 +1,9 @@
+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

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>14.0.2</version>
+    <version>16.5.0</version>
     <relativePath>../..</relativePath>
   </parent>
 
@@ -22,13 +22,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-core</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
@@ -47,19 +47,19 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-querybean</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-platform-postgres</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-postgis-types</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>

composites/ebean-postgres/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>14.0.2</version>
+    <version>16.5.0</version>
     <relativePath>../..</relativePath>
   </parent>
 
@@ -17,13 +17,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-core</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
@@ -42,13 +42,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-querybean</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-platform-postgres</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
   </dependencies>

composites/ebean-sqlite/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>14.0.2</version>
+    <version>16.5.0</version>
     <relativePath>../..</relativePath>
   </parent>
 
@@ -17,13 +17,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-core</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
@@ -42,13 +42,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-querybean</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-platform-sqlite</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
   </dependencies>

composites/ebean-sqlserver/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>14.0.2</version>
+    <version>16.5.0</version>
     <relativePath>../..</relativePath>
   </parent>
 
@@ -17,13 +17,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-core</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
@@ -42,13 +42,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-querybean</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-platform-sqlserver</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
   </dependencies>

composites/ebean-yugabyte/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>14.0.2</version>
+    <version>16.5.0</version>
     <relativePath>../..</relativePath>
   </parent>
 
@@ -17,13 +17,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-core</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
@@ -42,13 +42,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-querybean</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-platform-postgres</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
   </dependencies>

composites/ebean/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>14.0.2</version>
+    <version>16.5.0</version>
     <relativePath>../..</relativePath>
   </parent>
 
@@ -17,13 +17,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-core</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
@@ -41,7 +41,7 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-jackson-mapper</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
@@ -60,13 +60,13 @@
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-querybean</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-platform-all</artifactId>
-      <version>14.0.2</version>
+      <version>16.5.0</version>
     </dependency>
 
   </dependencies>

composites/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>14.0.2</version>
+    <version>16.5.0</version>
   </parent>
 
   <artifactId>composites</artifactId>
@@ -24,6 +24,8 @@
     <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>

docs/guides/README.md

@@ -0,0 +1,109 @@
+# Guides
+
+Step-by-step guides written as instructions for AI agents and developers.
+
+## 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 | [Database configuration](add-ebean-postgres-database-config.md) | Configure the Ebean `Database` bean using `DataSourceBuilder` and `DatabaseBuilder` with Avaje Inject |
+| 3 | [Test container setup](add-ebean-postgres-test-container.md) | Start a PostgreSQL (or PostGIS) Docker container for tests using `@TestScope @Factory` with Avaje Inject; covers image mirror, read-only datasource, and PostGIS variant |
+
+## Entity beans
+
+| Guide | Description |
+|-------|-------------|
+| [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)` |
+
+## 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
+
+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.
+
+
+### 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, test containers, DB migrations,
+Lombok) are at:
+
+**https://github.com/ebean-orm/ebean/tree/main/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/main/docs/guides/
+
+Key guides (fetch and follow these when performing the relevant task):
+- Maven POM setup: https://raw.githubusercontent.com/ebean-orm/ebean/main/docs/guides/add-ebean-postgres-maven-pom.md
+- Database configuration: https://raw.githubusercontent.com/ebean-orm/ebean/main/docs/guides/add-ebean-postgres-database-config.md
+- Test container setup: https://raw.githubusercontent.com/ebean-orm/ebean/main/docs/guides/add-ebean-postgres-test-container.md
+- DB migration generation: https://raw.githubusercontent.com/ebean-orm/ebean/main/docs/guides/add-ebean-db-migration-generation.md
+- Lombok with entity beans: https://raw.githubusercontent.com/ebean-orm/ebean/main/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.
+
+### 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/main/docs/guides/
+```

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

@@ -0,0 +1,366 @@
+# 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

@@ -0,0 +1,282 @@
+# 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 2 of 2.
+
+---
+
+## Prerequisites
+
+- **Step 1 complete**: `pom.xml` already includes `ebean-postgres`, `ebean-maven-plugin`,
+  and `querybean-generator` (see `add-ebean-postgres-maven-pom.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 |

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

@@ -0,0 +1,175 @@
+# 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 2.
+
+---
+
+## Prerequisites
+
+- An existing Maven project (`pom.xml` already exists)
+- Java 11 or higher
+- The project does **not** yet include any Ebean dependencies
+
+---
+
+## 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 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 the project compiles:
+
+```bash
+mvn compile -pl <your-module-name>
+```
+
+Expected result: `BUILD SUCCESS` with no errors from Ebean or the annotation processor.
+
+---
+
+## Next Step
+
+Proceed to **Step 2: Configure the Datasource and Ebean Database bean**
+(`add-ebean-postgres-database-config.md`).

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

@@ -0,0 +1,293 @@
+# Guide: Add Ebean ORM (PostgreSQL) to an Existing Maven Project — Step 3: Test Container Setup
+
+## Purpose
+
+This guide provides step-by-step instructions for setting up a PostgreSQL Docker
+container for tests using `ebean-test-containers`, exposing an `io.ebean.Database`
+bean via an Avaje Inject `@TestScope @Factory` class. This is Step 3 of 3.
+
+Two variants are covered:
+- **Variant A** — plain PostgreSQL
+- **Variant B** — PostgreSQL with PostGIS extension
+
+---
+
+## 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 2 complete**: A production `Database` bean exists (see `add-ebean-postgres-database-config.md`)
+- **Avaje Inject** is on the classpath with test support (`io.avaje:avaje-inject-test`)
+- **Docker** is installed and running on the developer machine
+
+---
+
+## Overview: Declarative vs Programmatic approach
+
+`ebean-test` supports two ways to configure the test database:
+
+| Approach | How | Best for |
+|----------|-----|---------|
+| **Declarative** | `src/test/resources/application-test.yaml` | Simple projects with no DI, no image mirrors |
+| **Programmatic** | `@TestScope @Factory` class | Avaje Inject tests, private image mirrors (ECR), more control |
+
+This guide uses the **programmatic approach** because it integrates naturally with
+Avaje Inject, allows a private mirror to be specified (useful in CI with ECR or similar),
+and makes the `Database` injectable into tests.
+
+---
+
+## Step 1 — Verify ebean-test is a test dependency
+
+Confirm the following is present in `pom.xml` (added in Step 1):
+
+```xml
+<dependency>
+    <groupId>io.ebean</groupId>
+    <artifactId>ebean-test</artifactId>
+    <version>${ebean.version}</version>
+    <scope>test</scope>
+</dependency>
+```
+
+`ebean-test` transitively brings in `ebean-test-containers` which provides
+`PostgresContainer` and `PostgisContainer`.
+
+---
+
+## Step 2 — Create a `@TestScope @Factory` class
+
+Create a new class in the test source tree (e.g., `src/test/java/.../testconfig/TestConfiguration.java`).
+Annotate it with `@TestScope` and `@Factory` so Avaje Inject uses it only in tests.
+
+```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 in the steps below
+}
+```
+
+---
+
+## Step 3 — Add a container bean and a Database bean
+
+### Variant A — 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();
+    }
+}
+```
+
+### Variant B — PostGIS (PostgreSQL + PostGIS extension)
+
+Use `PostgisContainer` instead of `PostgresContainer`. 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")    // PostGIS image version (Postgres 17)
+            .dbName("my_app")
+            .build()
+            .start();
+    }
+
+    @Bean
+    Database database(PostgisContainer container) {
+        return container.ebean()
+            .builder()
+            .build();
+    }
+}
+```
+
+### Key differences from Variant A
+
+| | 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) |
+
+---
+
+## Step 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();
+    }
+}
+```
+
+---
+
+## Verification
+
+Run the tests:
+
+```bash
+mvn test -pl <your-module>
+```
+
+Expected log output confirming the container started and Ebean connected:
+
+```
+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 - ...
+```
+
+---
+
+## 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/lombok-with-ebean-entity-beans.md

@@ -0,0 +1,206 @@
+# 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 `LazyInitializationException` 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`**

ebean-api/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <artifactId>ebean-parent</artifactId>
     <groupId>io.ebean</groupId>
-    <version>14.0.2</version>
+    <version>16.5.0</version>
   </parent>
 
   <name>ebean api</name>
@@ -26,20 +26,16 @@
       <version>1.0</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.1</version>
+      <groupId>org.jspecify</groupId>
+      <artifactId>jspecify</artifactId>
+      <version>1.0.0</version>
     </dependency>
 
     <dependency>
       <groupId>io.avaje</groupId>
       <artifactId>avaje-config</artifactId>
-      <version>3.12</version>
+      <version>4.2</version>
     </dependency>
 
     <dependency>
@@ -90,23 +86,6 @@
       <optional>true</optional>
     </dependency>
 
-    <!-- JAVAX-DEPENDENCY-START ___
-    <dependency>
-      <groupId>javax.servlet</groupId>
-      <artifactId>javax.servlet-api</artifactId>
-      <version>3.1.0</version>
-      <optional>true</optional>
-    </dependency>
-    ____ JAVAX-DEPENDENCY-END -->
-    <!-- JAKARTA-DEPENDENCY-START -->
-    <dependency>
-      <groupId>jakarta.servlet</groupId>
-      <artifactId>jakarta.servlet-api</artifactId>
-      <version>6.0.0</version>
-      <optional>true</optional>
-    </dependency>
-    <!-- JAKARTA-DEPENDENCY-END -->
-
   </dependencies>
 
   <build>

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

@@ -1,10 +1,9 @@
 package io.ebean;
 
-import io.avaje.lang.NonNullApi;
+import org.jspecify.annotations.NullMarked;
 
 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;
 
@@ -20,7 +19,7 @@ import java.util.concurrent.TimeUnit;
  * This also propagates MDC context from the current thread to the
  * background task if defined.
  */
-@NonNullApi
+@NullMarked
 public interface BackgroundExecutor {
 
   /**

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

@@ -0,0 +1,25 @@
+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 io.avaje.lang.NonNullApi;
-import io.avaje.lang.Nullable;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 import java.util.List;
 import java.util.Optional;
 
@@ -30,7 +30,7 @@ import java.util.Optional;
  *
  * @see BeanRepository
  */
-@NonNullApi
+@NullMarked
 public abstract class BeanFinder<I,T> {
 
   protected final Database database;

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

@@ -1,6 +1,6 @@
 package io.ebean;
 
-import io.avaje.lang.NonNullApi;
+import org.jspecify.annotations.NullMarked;
 import io.ebean.bean.EntityBean;
 
 import java.util.Collection;
@@ -36,7 +36,7 @@ import java.util.Collection;
  * @param <I> The ID type
  * @param <T> The Bean type
  */
-@NonNullApi
+@NullMarked
 public abstract class BeanRepository<I, T> extends BeanFinder<I, T> {
 
   /**

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

@@ -89,12 +89,7 @@ public interface BeanState {
    * <p>
    * If a setter is called on a readOnly bean it will throw an exception.
    */
-  boolean isReadOnly();
-
-  /**
-   * Set the readOnly status for the bean.
-   */
-  void setReadOnly(boolean readOnly);
+  boolean isUnmodifiable();
 
   /**
    * Advanced - Used to programmatically build a partially or fully loaded

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

@@ -1,7 +1,7 @@
 package io.ebean;
 
-import io.avaje.lang.NonNullApi;
-import io.avaje.lang.Nullable;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 import io.ebean.annotation.TxIsolation;
 import io.ebean.cache.ServerCacheManager;
 import io.ebean.plugin.Property;
@@ -57,7 +57,7 @@ import java.util.concurrent.Callable;
  *
  * }</pre>
  */
-@NonNullApi
+@NullMarked
 public final class DB {
 
   private static final DbContext context = DbContext.getInstance();
@@ -605,7 +605,7 @@ public final class DB {
    *   // find orders and their customers
    *   List<Order> list = DB.find(Order.class)
    *     .fetch("customer")
-   *     .order("id")
+   *     .orderBy("id")
    *     .findList();
    *
    *   // sort by customer name ascending, then by order shipDate

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

@@ -0,0 +1,50 @@
+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/Database.java

@@ -1,7 +1,7 @@
 package io.ebean;
 
-import io.avaje.lang.NonNullApi;
-import io.avaje.lang.Nullable;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 import io.ebean.annotation.Platform;
 import io.ebean.annotation.TxIsolation;
 import io.ebean.cache.ServerCacheManager;
@@ -83,7 +83,7 @@ import java.util.concurrent.Callable;
  * @see DatabaseFactory
  * @see DatabaseConfig
  */
-@NonNullApi
+@NullMarked
 public interface Database {
 
   /**
@@ -137,6 +137,7 @@ public interface Database {
   /**
    * Return the associated read only DataSource for this Database instance (can be null).
    */
+  @Nullable
   DataSource readOnlyDataSource();
 
   /**
@@ -400,7 +401,7 @@ public interface Database {
    *   // find orders and their customers
    *   List<Order> list = database.find(Order.class)
    *     .fetch("customer")
-   *     .order("id")
+   *     .orderBy("id")
    *     .findList();
    *
    *   // sort by customer name ascending, then by order shipDate
@@ -772,18 +773,6 @@ public interface Database {
    */
   <T> T reference(Class<T> beanType, Object id);
 
-  /**
-   * Return the extended API for Database.
-   * <p>
-   * The extended API has the options for executing queries that take an explicit
-   * transaction as an argument.
-   * <p>
-   * Typically, we only need to use the extended API when we do NOT want to use the
-   * usual ThreadLocal based mechanism to obtain the current transaction but instead
-   * supply the transaction explicitly.
-   */
-  ExtendedServer extended();
-
   /**
    * Either Insert or Update the bean depending on its state.
    * <p>

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

@@ -989,6 +989,14 @@ public interface DatabaseBuilder {
   @Deprecated
   DatabaseBuilder setNamingConvention(NamingConvention namingConvention);
 
+  /**
+   * Set the AggregateFormulaContext which is used to determine if a database function
+   * is an aggregate function (like sum, min, max, avg etc).
+   * <p>
+   * Use this to override the default known aggregation functions.
+   */
+  DatabaseConfig aggregateFormulaContext(AggregateFormulaContext aggregateFormulaContext);
+
   /**
    * Set to true if all DB column and table names should use quoted identifiers.
    * <p>
@@ -1062,6 +1070,11 @@ public interface DatabaseBuilder {
    */
   DatabaseBuilder readOnlyDatabase(boolean readOnlyDatabase);
 
+  /**
+   * Set to false such that the instance does not register a JVM shutdown hook.
+   */
+  DatabaseBuilder shutdownHook(boolean shutdownHook);
+
   /**
    * Set a DataSource.
    */
@@ -1968,8 +1981,8 @@ public interface DatabaseBuilder {
   DatabaseBuilder setLocalOnlyL2Cache(boolean localOnlyL2Cache);
 
   /**
-   * Controls if Ebean should ignore <code>&x64;javax.validation.contstraints.NotNull</code> or
-   * <code>&x64;jakarta.validation.contstraints.NotNull</code>
+   * Controls if Ebean should ignore <code>&#64;javax.validation.contstraints.NotNull</code> or
+   * <code>&#64;jakarta.validation.contstraints.NotNull</code>
    * with respect to generating a <code>NOT NULL</code> column.
    * <p>
    * Normally when Ebean sees javax NotNull annotation it means that column is defined as NOT NULL.
@@ -2019,6 +2032,11 @@ public interface DatabaseBuilder {
   @Deprecated
   DatabaseBuilder setQueryPlanTTLSeconds(int queryPlanTTLSeconds);
 
+  /**
+   * Set the EXPLAIN (with options) to use for query plan capture.
+   */
+  DatabaseBuilder queryPlanExplain(String queryPlanExplain);
+
   /**
    * Create a new PlatformConfig based of the one held but with overridden properties by reading
    * properties with the given path and prefix.
@@ -2600,6 +2618,11 @@ public interface DatabaseBuilder {
      */
     NamingConvention getNamingConvention();
 
+    /**
+     * Return the AggregateFormulaContext.
+     */
+    AggregateFormulaContext aggregateFormulaContext();
+
     /**
      * Return true if all DB column and table names should use quoted identifiers.
      */
@@ -2638,6 +2661,11 @@ public interface DatabaseBuilder {
      */
     boolean readOnlyDatabase();
 
+    /**
+     * Return if a JVM shutdown hook should be registered.
+     */
+    boolean shutdownHook();
+
     /**
      * Return the DataSource.
      */
@@ -3044,6 +3072,11 @@ public interface DatabaseBuilder {
      */
     int getQueryPlanTTLSeconds();
 
+    /**
+     * Return the EXPLAIN (with options) to use for capturing query plans.
+     */
+    String getQueryPlanExplain();
+
     /**
      * Return mapping locations to search for xml mapping via class path search.
      */

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

@@ -5,8 +5,6 @@ import io.ebean.service.SpiContainer;
 import io.ebean.service.SpiContainerFactory;
 import jakarta.persistence.PersistenceException;
 
-import java.util.Iterator;
-import java.util.ServiceLoader;
 import java.util.concurrent.locks.ReentrantLock;
 
 /**
@@ -157,10 +155,10 @@ public final class DatabaseFactory {
    * Create the container instance using the configuration.
    */
   private static SpiContainer createContainer(ContainerConfig containerConfig) {
-    Iterator<SpiContainerFactory> factories = ServiceLoader.load(SpiContainerFactory.class).iterator();
-    if (factories.hasNext()) {
-      return factories.next().create(containerConfig);
+    SpiContainerFactory factory = XBootstrapService.containerFactory();
+    if (factory == null) {
+      throw new IllegalStateException("Service loader didn't find a SpiContainerFactory?");
     }
-    throw new IllegalStateException("Service loader didn't find a SpiContainerFactory?");
+    return factory.create(containerConfig);
   }
 }

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

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

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

@@ -1,7 +1,7 @@
 package io.ebean;
 
-import io.avaje.lang.NonNullApi;
-import io.avaje.lang.Nullable;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 import javax.sql.DataSource;
 import java.sql.Connection;
@@ -42,7 +42,7 @@ import java.util.stream.Stream;
  *
  * }</pre>
  */
-@NonNullApi
+@NullMarked
 public interface DtoQuery<T> extends CancelableQuery {
 
   /**
@@ -140,6 +140,17 @@ public interface DtoQuery<T> extends CancelableQuery {
    * 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);
 
@@ -223,5 +234,16 @@ public interface DtoQuery<T> extends CancelableQuery {
    * source. We use {@code usingMaster()} to instead ensure that the query is executed
    * against the master data source.
    */
-  DtoQuery<T> usingMaster();
+  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/EmptyPagedList.java

@@ -5,6 +5,8 @@ import java.util.List;
 import java.util.concurrent.Future;
 
 /**
+ * @deprecated migrate to using {@link PagedList#emptyList()} only.
+ * <p>
  * An empty PagedList.
  * <p>
  * For use in application code when we need to return a PagedList but don't want to
@@ -17,7 +19,8 @@ import java.util.concurrent.Future;
  *
  * }</pre>
  */
-public class EmptyPagedList<T> implements PagedList<T> {
+@Deprecated(forRemoval = true)
+public final class EmptyPagedList<T> implements PagedList<T> {
 
   @Override
   public void loadCount() {

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

@@ -1,7 +1,7 @@
 package io.ebean;
 
-import io.avaje.lang.NonNullApi;
-import io.avaje.lang.Nullable;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 import io.ebean.search.*;
 
 import jakarta.persistence.NonUniqueResultException;
@@ -31,7 +31,7 @@ import java.util.function.Predicate;
  *
  * @see Query#where()
  */
-@NonNullApi
+@NullMarked
 public interface ExpressionList<T> {
 
   /**
@@ -53,14 +53,6 @@ public interface ExpressionList<T> {
    */
   Query<T> orderById(boolean orderById);
 
-  /**
-   * @deprecated migrate to {@link #orderBy(String)}
-   */
-  @Deprecated(since = "13.19", forRemoval = true)
-  default ExpressionList<T> order(String orderByClause) {
-    return orderBy(orderByClause);
-  }
-
   /**
    * Set the order by clause replacing the existing order by clause if there is
    * one.
@@ -71,14 +63,6 @@ public interface ExpressionList<T> {
    */
   ExpressionList<T> orderBy(String orderBy);
 
-  /**
-   * @deprecated migrate to {@link #orderBy()}.
-   */
-  @Deprecated(forRemoval = true)
-  default OrderBy<T> order() {
-    return orderBy();
-  }
-
   /**
    * Return the OrderBy so that you can append an ascending or descending
    * property to the order by clause.
@@ -221,18 +205,6 @@ public interface ExpressionList<T> {
    */
   int delete();
 
-  /**
-   * Execute as a delete query deleting the 'root level' beans that match the predicates
-   * in the query.
-   * <p>
-   * Note that if the query includes joins then the generated delete statement may not be
-   * optimal depending on the database platform.
-   * </p>
-   *
-   * @return the number of rows that were deleted.
-   */
-  int delete(Transaction transaction);
-
   /**
    * Execute as a update query.
    *
@@ -241,14 +213,6 @@ public interface ExpressionList<T> {
    */
   int update();
 
-  /**
-   * Execute as a update query with the given transaction.
-   *
-   * @return the number of rows that were updated.
-   * @see UpdateQuery
-   */
-  int update(Transaction transaction);
-
   /**
    * Execute the query returning true if a row is found.
    * <p>
@@ -349,7 +313,7 @@ public interface ExpressionList<T> {
    *  List<String> names =
    *    DB.find(Customer.class)
    *      .select("name")
-   *      .order().asc("name")
+   *      .orderBy().asc("name")
    *      .findSingleAttributeList();
    *
    * }</pre>
@@ -362,7 +326,7 @@ public interface ExpressionList<T> {
    *      .setDistinct(true)
    *      .select("name")
    *      .where().eq("status", Customer.Status.NEW)
-   *      .order().asc("name")
+   *      .orderBy().asc("name")
    *      .setMaxRows(100)
    *      .findSingleAttributeList();
    *
@@ -1707,7 +1671,7 @@ public interface ExpressionList<T> {
    *        .eq("status", Customer.Status.ACTIVE)
    *        .gt("id", 0)
    *        .endAnd()
-   *      .order().asc("name")
+   *      .orderBy().asc("name")
    *      .findList();
    * }</pre>
    */
@@ -1728,7 +1692,7 @@ public interface ExpressionList<T> {
    *    .or()
    *      .eq("status", Customer.Status.ACTIVE)
    *      .isNull("anniversary")
-   *    .order().asc("name")
+   *    .orderBy().asc("name")
    *    .findList();
    *
    * }</pre>
@@ -1748,7 +1712,7 @@ public interface ExpressionList<T> {
    *        .eq("status", Customer.Status.ACTIVE)
    *        .gt("id", 0)
    *        .endAnd()
-   *      .order().asc("name")
+   *      .orderBy().asc("name")
    *      .findList();
    *
    * }</pre>
@@ -1782,7 +1746,7 @@ public interface ExpressionList<T> {
    *       .gt("id", 1)
    *       .eq("anniversary", onAfter)
    *       .endNot()
-   *     .order()
+   *     .orderBy()
    *       .asc("name")
    *     .findList();
    *

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

@@ -1,21 +0,0 @@
-package io.ebean;
-
-import java.time.Clock;
-
-/**
- * The extended API for Database.
- */
-public interface ExtendedServer {
-
-  /**
-   * Deprecated but no yet determined suitable replacement (to support testing only change of clock).
-   * <p>
-   * Set the Clock to use for <code>@WhenCreated</code> and <code>@WhenModified</code>.
-   * <p>
-   * Note that we only expect to change the Clock for testing purposes.
-   * </p>
-   */
-  @Deprecated
-  void setClock(Clock clock);
-
-}

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

@@ -1,6 +1,6 @@
 package io.ebean;
 
-import io.avaje.lang.NonNullApi;
+import org.jspecify.annotations.NullMarked;
 import io.ebean.service.SpiFetchGroupQuery;
 
 /**
@@ -61,7 +61,7 @@ import io.ebean.service.SpiFetchGroupQuery;
  *
  * @param <T> The bean type the Fetch group can be applied to
  */
-@NonNullApi
+@NullMarked
 public interface FetchGroup<T> {
 
   /**
@@ -84,7 +84,7 @@ public interface FetchGroup<T> {
    * @return The FetchGroup with the given select clause
    */
   static <T> FetchGroup<T> of(Class<T> cls, String select) {
-    return XServiceProvider.fetchGroupOf(cls, select);
+    return XBootstrapService.fetchGroupOf(cls, select);
   }
 
   /**
@@ -108,14 +108,14 @@ public interface FetchGroup<T> {
    * @return The FetchGroupBuilder with the given select clause which we will add fetch clauses to
    */
   static <T> FetchGroupBuilder<T> of(Class<T> cls) {
-    return XServiceProvider.fetchGroupOf(cls);
+    return XBootstrapService.fetchGroupOf(cls);
   }
 
   /**
    * Return a query to be used by query beans for constructing FetchGroup.
    */
   static <T> SpiFetchGroupQuery<T> queryFor(Class<T> beanType) {
-    return XServiceProvider.fetchGroupQueryFor(beanType);
+    return XBootstrapService.fetchGroupQueryFor(beanType);
   }
 
 }

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

@@ -1,6 +1,6 @@
 package io.ebean;
 
-import io.avaje.lang.NonNullApi;
+import org.jspecify.annotations.NullMarked;
 
 /**
  * Builds a FetchGroup by adding fetch clauses.
@@ -23,7 +23,7 @@ import io.avaje.lang.NonNullApi;
  *
  * }</pre>
  */
-@NonNullApi
+@NullMarked
 public interface FetchGroupBuilder<T> {
 
   /**

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

@@ -1,6 +1,6 @@
 package io.ebean;
 
-import io.avaje.lang.NonNullApi;
+import org.jspecify.annotations.NullMarked;
 
 import java.util.List;
 import java.util.Set;
@@ -79,7 +79,7 @@ import java.util.Set;
  *
  * @param <T> the entity bean type
  */
-@NonNullApi
+@NullMarked
 public interface Filter<T> {
 
   /**

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

@@ -1,7 +1,7 @@
 package io.ebean;
 
-import io.avaje.lang.NonNullApi;
-import io.avaje.lang.Nullable;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 import java.util.List;
 
 /**
@@ -35,7 +35,7 @@ import java.util.List;
  *   public List<Customer> findNew() {
  *     return query().where()
  *       .eq("status", Customer.Status.NEW)
- *       .order("name")
+ *       .orderBy("name")
  *       .findList()
  *   }
  * }
@@ -60,7 +60,7 @@ import java.util.List;
  * @see BeanRepository
  * @see BeanFinder
  */
-@NonNullApi
+@NullMarked
 public class Finder<I, T> {
 
   /**

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

@@ -0,0 +1,74 @@
+package io.ebean;
+
+import jakarta.persistence.PersistenceException;
+
+import java.util.Map;
+import java.util.concurrent.Future;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
+
+/**
+ * FutureMap represents the result of a background query execution that will
+ * return a map of entities.
+ * <p>
+ * It extends the java.util.concurrent.Future with the ability to cancel the
+ * query, check if it is finished and get the resulting list waiting for the
+ * query to finish (ie. the standard features of java.util.concurrent.Future).
+ * </p>
+ * <p>
+ * A simple example:
+ * </p>
+ * <pre>{@code
+ *
+ *  // create a query to find all orders
+ * Query<Long,Order> query = DB.find(Order.class)
+ * .setMapKey("id");
+ *
+ *  // execute the query in a background thread
+ *  // immediately returning the futureMap
+ * FutureMap<Long,Order> futureMap = query.findFutureMap();
+ *
+ *  // do something else ...
+ *
+ * if (!futureMap.isDone()){
+ * 	// we can cancel the query execution. This will cancel
+ * // the underlying query if that is supported by the JDBC
+ * // driver and database
+ * 	futureMap.cancel(true);
+ * }
+ *
+ * if (!futureMap.isCancelled()){
+ * 	// wait for the query to finish and return the map
+ * 	Map<Long,Order> map = futureMap.get();
+ * 	...
+ * }
+ *
+ * }</pre>
+ */
+public interface FutureMap<K, T> extends Future<Map<K, T>> {
+
+  /**
+   * Return the query that is being executed by a background thread.
+   */
+  Query<T> getQuery();
+
+  /**
+   * Same as {@link #get()} but wraps InterruptedException and ExecutionException in the
+   * unchecked PersistenceException.
+   *
+   * @return The query list result
+   * @throws PersistenceException when a InterruptedException or ExecutionException occurs.
+   */
+  Map<K, T> getUnchecked();
+
+  /**
+   * Same as {@link #get(long, TimeUnit)} but wraps InterruptedException
+   * and ExecutionException in the unchecked PersistenceException.
+   *
+   * @return The query list result
+   * @throws TimeoutException     if the wait timed out
+   * @throws PersistenceException if a InterruptedException or ExecutionException occurs.
+   */
+  Map<K, T> getUnchecked(long timeout, TimeUnit unit) throws TimeoutException;
+
+}

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

@@ -1,6 +1,6 @@
 package io.ebean;
 
-import io.avaje.lang.Nullable;
+import org.jspecify.annotations.Nullable;
 
 /**
  * Options to be used with insert such as ON CONFLICT DO UPDATE | NOTHING.

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

@@ -61,7 +61,7 @@ package io.ebean;
  *            .eq("status", Customer.Status.ACTIVE)
  *            .gt("id", 0)
  *            .endAnd()
- *      .order().asc("name");
+ *      .orderBy().asc("name");
  *
  * q.findList();
  * String s = q.getGeneratedSql();

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

@@ -0,0 +1,19 @@
+package io.ebean;
+
+/**
+ * Thrown when trying to access a property that isn't loaded on an entity
+ * that is unmodifiable or has disabled lazy loading.
+ * <p>
+ * On a normal mutable entity accessing the property would invoke lazy loading. On
+ * a unmodifiable entity with lazy loading disabled, accessing an unloaded property
+ * throws this LazyInitialisationException instead.
+ */
+public class LazyInitialisationException extends BeanAccessException {
+
+  /**
+   * Create specifying the property that was being accessed.
+   */
+  public LazyInitialisationException(String message) {
+    super(message);
+  }
+}

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

@@ -16,4 +16,7 @@ public interface ModifyAwareType {
    */
   void setMarkedDirty(boolean markedDirty);
 
+  default Object freeze() {
+    return this; // throw new UnsupportedOperationException();
+  }
 }

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

@@ -8,13 +8,11 @@ import java.util.Objects;
 /**
  * Represents an Order By for a Query.
  * <p>
- * Is a ordered list of OrderBy.Property objects each specifying a property and
+ * Is an ordered list of OrderBy.Property objects each specifying a property and
  * whether it is ascending or descending order.
- * </p>
  * <p>
- * Typically you will not construct an OrderBy yourself but use one that exists
+ * Typically, you will not construct an OrderBy yourself but use one that exists
  * on the Query object.
- * </p>
  */
 public class OrderBy<T> implements Serializable {
 
@@ -25,8 +23,22 @@ public class OrderBy<T> implements Serializable {
   private final List<Property> list;
 
   /**
+   * Create an OrderBy parsing the given order by clause.
+   * <p>
+   * The order by clause follows SQL order by clause with comma's between each
+   * property and optionally "asc" or "desc" to represent ascending or
+   * descending order respectively.
+   */
+  public static <P> OrderBy<P> of(String orderByClause) {
+    return new OrderBy<>(orderByClause);
+  }
+
+  /**
+   * @deprecated This method will be removed from public API.
+   * <p>
    * Create an empty OrderBy with no associated query.
    */
+  @Deprecated(forRemoval = true)
   public OrderBy() {
     this.list = new ArrayList<>(3);
   }
@@ -36,20 +48,17 @@ public class OrderBy<T> implements Serializable {
   }
 
   /**
-   * Create an orderBy parsing the order by clause.
-   * <p>
-   * The order by clause follows SQL order by clause with comma's between each
-   * property and optionally "asc" or "desc" to represent ascending or
-   * descending order respectively.
-   * </p>
+   * @deprecated migrate to {@link OrderBy#of(String)}.
    */
+  @Deprecated(forRemoval = true)
   public OrderBy(String orderByClause) {
     this(null, orderByClause);
   }
 
   /**
-   * Construct with a given query and order by clause.
+   * @deprecated This method will be removed from public API.
    */
+  @Deprecated(forRemoval = true)
   public OrderBy(Query<T> query, String orderByClause) {
     this.query = query;
     this.list = new ArrayList<>(3);
@@ -110,8 +119,11 @@ public class OrderBy<T> implements Serializable {
   }
 
   /**
+   * @deprecated This method will become internal only API.
+   * <p>
    * Return a copy of this OrderBy with the path trimmed.
    */
+  @Deprecated(forRemoval = true)
   public OrderBy<T> copyWithTrim(String path) {
     List<Property> newList = new ArrayList<>(list.size());
     for (Property aList : list) {
@@ -186,15 +198,15 @@ public class OrderBy<T> implements Serializable {
     if (list.isEmpty()) {
       return null;
     }
-    StringBuilder sb = new StringBuilder();
+    var append = new StringAppend();
     for (int i = 0; i < list.size(); i++) {
       Property property = list.get(i);
       if (i > 0) {
-        sb.append(", ");
+        append.append(", ");
       }
-      sb.append(property.toStringFormat());
+      property.toStringFormat(append);
     }
-    return sb.toString();
+    return append.toString();
   }
 
   @Override
@@ -231,6 +243,55 @@ public class OrderBy<T> implements Serializable {
     return this;
   }
 
+  /**
+   * Append the order by clause.
+   */
+  public interface Append {
+
+    /**
+     * Append a property expression.
+     */
+    Append property(String property);
+
+    /**
+     * Append a literal.
+     */
+    Append append(String literal);
+
+    /**
+     * Parse and append an expression.
+     */
+    Append parse(String expression);
+  }
+
+  private static final class StringAppend implements Append {
+
+    private final StringBuilder builder = new StringBuilder();
+
+    @Override
+    public String toString() {
+      return builder.toString();
+    }
+
+    @Override
+    public Append property(String property) {
+      builder.append(property);
+      return this;
+    }
+
+    @Override
+    public Append append(String literal) {
+      builder.append(literal);
+      return this;
+    }
+
+    @Override
+    public Append parse(String raw) {
+      builder.append(raw);
+      return this;
+    }
+  }
+
   /**
    * A property and its ascending descending order.
    */
@@ -309,36 +370,25 @@ public class OrderBy<T> implements Serializable {
 
     @Override
     public String toString() {
-      return toStringFormat();
+      return property;
     }
 
-    public String toStringFormat() {
-      if (nulls == null && collation == null) {
-        if (ascending) {
-          return property;
+    public void toStringFormat(Append append) {
+      if (collation != null)  {
+        if (collation.contains("${}")) {
+          // this is a complex collation, e.g. DB2 - we must replace the property
+          append.parse(collation.replace("${}", property));
         } else {
-          return property + " desc";
+          append.property(property).append(" collate ").append(collation);
         }
       } else {
-        StringBuilder sb = new StringBuilder();
-        if (collation != null)  {
-          if (collation.contains("${}")) {
-            // this is a complex collation, e.g. DB2 - we must replace the property
-            sb.append(collation.replace("${}", property));
-          } else {
-            sb.append(property);
-            sb.append(" collate ").append(collation);
-          }
-        } else {
-          sb.append(property);
-        }
-        if (!ascending) {
-          sb.append(' ').append("desc");
-        }
-        if (nulls != null) {
-          sb.append(' ').append(nulls).append(' ').append(highLow);
-        }
-        return sb.toString();
+        append.property(property);
+      }
+      if (!ascending) {
+        append.append(" desc");
+      }
+      if (nulls != null) {
+        append.append(" ").append(nulls).append(" ").append(highLow);
       }
     }
 

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

@@ -25,7 +25,7 @@ import java.util.concurrent.Future;
  *
  *     PagedList<Order> pagedList = DB.find(Order.class)
  *       .where().eq("status", Order.Status.NEW)
- *       .order().asc("id")
+ *       .orderBy().asc("id")
  *       .setFirstRow(0)
  *       .setMaxRows(50)
  *       .findPagedList();

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

@@ -0,0 +1,90 @@
+package io.ebean;
+
+import org.jspecify.annotations.Nullable;
+
+/**
+ * Used to specify Paging on a Query as an alternative to setting each of the
+ * maxRows, firstRow and orderBy clause via:
+ * {@link Query#setMaxRows(int)} + {@link Query#setFirstRow(int)} + {@link Query#setOrderBy(OrderBy)}.
+ * <p>
+ * Example use:
+ *
+ * <pre>{@code
+ *
+ *   var orderBy = OrderBy.of("lastName desc nulls first, firstName asc");
+ *   var paging = Paging.of(0, 100, orderBy);
+ *
+ *   new QCustomer()
+ *       .name.isNotNull()
+ *       .setPaging(paging)
+ *       .findList();
+ *
+ * }</pre>
+ */
+public interface Paging {
+
+  /**
+   * Create a Paging with the given page index size and orderBy.
+   *
+   * @param pageIndex the page index starting from zero
+   * @param pageSize  the page size (effectively max rows)
+   * @param orderBy   order by for the query result
+   */
+  static Paging of(int pageIndex, int pageSize, @Nullable OrderBy<?> orderBy) {
+    return DPaging.build(pageIndex, pageSize, orderBy);
+  }
+
+  /**
+   * Create a Paging with a raw order by clause.
+   *
+   * @param pageIndex     the page index starting from zero
+   * @param pageSize      the page size (effectively max rows)
+   * @param orderByClause raw order by clause for ordering the query result
+   */
+  static Paging of(int pageIndex, int pageSize, @Nullable String orderByClause) {
+    return of(pageIndex, pageSize, OrderBy.of(orderByClause));
+  }
+
+  /**
+   * Create a Paging that will use the id property for ordering.
+   *
+   * @param pageIndex the page index starting from zero
+   * @param pageSize  the page size (effectively max rows)
+   */
+  static Paging of(int pageIndex, int pageSize) {
+    return DPaging.build(pageIndex, pageSize);
+  }
+
+  /**
+   * Return a Paging that will not apply any pagination to a query.
+   */
+  static Paging ofNone() {
+    return DPaging.NONE;
+  }
+
+  /**
+   * Return the page index.
+   */
+  int pageIndex();
+
+  /**
+   * Return the page size.
+   */
+  int pageSize();
+
+  /**
+   * Return the order by.
+   */
+  OrderBy<?> orderBy();
+
+  /**
+   * Return a Paging using the given page index.
+   */
+  Paging withPage(int pageIndex);
+
+  /**
+   * Return a Paging using the given order by clause.
+   */
+  Paging withOrderBy(String orderByClause);
+
+}

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

@@ -30,7 +30,7 @@ import java.util.Objects;
  *   .where()
  *   .eq("store", "def")
  *   .inPairs(pairs)       // IN clause with 'pairs' of values
- *   .order("sku desc")
+ *   .orderBy("sku desc")
  *
  *   // query expressions cover the natural key properties
  *   // so we can choose to hit the L2 bean cache if we want

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

@@ -13,21 +13,21 @@ public interface ProfileLocation {
    * Create and return a new ProfileLocation.
    */
   static ProfileLocation create() {
-    return XServiceProvider.profileLocationFactory().create();
+    return XBootstrapService.profileLocationFactory().create();
   }
 
   /**
    * Create and return a new ProfileLocation with line number.
    */
   static ProfileLocation createWithLine() {
-    return XServiceProvider.profileLocationFactory().createWithLine();
+    return XBootstrapService.profileLocationFactory().createWithLine();
   }
 
   /**
    * Create and return a new ProfileLocation with a given lineNumber and label.
    */
   static ProfileLocation create(String label) {
-    return XServiceProvider.profileLocationFactory().create(label);
+    return XBootstrapService.profileLocationFactory().create(label);
   }
 
   /**

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

@@ -0,0 +1,249 @@
+package io.ebean;
+
+/**
+ * Builder for ORM Query projection (the select and fetch part).
+ *
+ * @param <SELF> The builder type
+ * @param <T>    The entity bean type
+ */
+public interface QueryBuilderProjection<SELF extends QueryBuilderProjection<SELF, T>, T> {
+
+  /**
+   * Apply the path properties replacing the select and fetch clauses.
+   * <p>
+   * This is typically used when the FetchPath is applied to both the query and the JSON output.
+   */
+  SELF apply(FetchPath fetchPath);
+
+  /**
+   * Specify the properties to fetch on the root level entity bean in comma delimited format.
+   * <p>
+   * The Id property is automatically included in the properties to fetch unless setDistinct(true)
+   * is set on the query.
+   * </p>
+   * <p>
+   * Use {@link #fetch(String, String)} to specify specific properties to fetch
+   * on other non-root level paths of the object graph.
+   * </p>
+   * <pre>{@code
+   *
+   * List<Customer> customers = DB.find(Customer.class)
+   *     // Only fetch the customer id, name and status.
+   *     // This is described as a "Partial Object"
+   *     .select("name, status")
+   *     .where.ilike("name", "rob%")
+   *     .findList();
+   *
+   * }</pre>
+   *
+   * @param fetchProperties the properties to fetch for this bean (* = all properties).
+   */
+  SELF select(String fetchProperties);
+
+  /**
+   * Set DISTINCT ON clause. This is a Postgres only SQL feature.
+   *
+   * @param distinctOn The properties to include in the DISTINCT ON clause.
+   */
+  SELF distinctOn(String distinctOn);
+
+  /**
+   * Apply the fetchGroup which defines what part of the object graph to load.
+   */
+  SELF select(FetchGroup<T> fetchGroup);
+
+  /**
+   * Specify a path to fetch eagerly including specific properties.
+   * <p>
+   * Ebean will endeavour to fetch this path using a SQL join. If Ebean determines that it can
+   * not use a SQL join (due to maxRows or because it would result in a cartesian product) Ebean
+   * will automatically convert this fetch query into a "query join" - i.e. use fetchQuery().
+   * </p>
+   * <pre>{@code
+   *
+   * // query orders...
+   * List<Order> orders = DB.find(Order.class)
+   *       // fetch the customer...
+   *       // ... getting the customers name and phone number
+   *       .fetch("customer", "name, phoneNumber")
+   *
+   *       // ... also fetch the customers billing address (* = all properties)
+   *       .fetch("customer.billingAddress", "*")
+   *       .findList();
+   * }</pre>
+   * <p>
+   * If columns is null or "*" then all columns/properties for that path are fetched.
+   * </p>
+   * <pre>{@code
+   *
+   * // fetch customers (their id, name and status)
+   * List<Customer> customers = DB.find(Customer.class)
+   *     .select("name, status")
+   *     .fetch("contacts", "firstName,lastName,email")
+   *     .findList();
+   *
+   * }</pre>
+   *
+   * @param path            the property path we wish to fetch eagerly.
+   * @param fetchProperties properties of the associated bean that you want to include in the
+   *                        fetch (* means all properties, null also means all properties).
+   */
+  SELF fetch(String path, String fetchProperties);
+
+  /**
+   * Fetch the path and properties using a "query join" (separate SQL query).
+   * <p>
+   * This is the same as:
+   * </p>
+   * <pre>{@code
+   *
+   *  fetch(path, fetchProperties, FetchConfig.ofQuery())
+   *
+   * }</pre>
+   * <p>
+   * This would be used instead of a fetch() when we use a separate SQL query to fetch this
+   * part of the object graph rather than a SQL join.
+   * <p>
+   * We might typically get a performance benefit when the path to fetch is a OneToMany
+   * or ManyToMany, the 'width' of the 'root bean' is wide and the cardinality of the many
+   * is high.
+   *
+   * @param path            the property path we wish to fetch eagerly.
+   * @param fetchProperties properties of the associated bean that you want to include in the
+   *                        fetch (* means all properties, null also means all properties).
+   */
+  SELF fetchQuery(String path, String fetchProperties);
+
+  /**
+   * Fetch the path and properties using L2 bean cache.
+   *
+   * @param path            The path of the beans we are fetching from L2 cache.
+   * @param fetchProperties The properties that should be loaded.
+   */
+  SELF fetchCache(String path, String fetchProperties);
+
+  /**
+   * Fetch the path and properties lazily (via batch lazy loading).
+   * <p>
+   * This is the same as:
+   *
+   * <pre>{@code
+   *
+   *  fetch(path, fetchProperties, FetchConfig.ofLazy())
+   *
+   * }</pre>
+   * <p>
+   * The reason for using fetchLazy() is to either:
+   * <ul>
+   * <li>Control/tune what is fetched as part of lazy loading</li>
+   * <li>Make use of the L2 cache, build this part of the graph from L2 cache</li>
+   * </ul>
+   *
+   * @param path            the property path we wish to fetch lazily.
+   * @param fetchProperties properties of the associated bean that you want to include in the
+   *                        fetch (* means all properties, null also means all properties).
+   */
+  SELF fetchLazy(String path, String fetchProperties);
+
+  /**
+   * Additionally specify a FetchConfig to use a separate query or lazy loading
+   * to load this path.
+   * <pre>{@code
+   *
+   * // fetch customers (their id, name and status)
+   * List<Customer> customers = DB.find(Customer.class)
+   *     .select("name, status")
+   *     .fetch("contacts", "firstName,lastName,email", FetchConfig.ofLazy(10))
+   *     .findList();
+   *
+   * }</pre>
+   *
+   * @param path the property path we wish to fetch eagerly.
+   */
+  SELF fetch(String path, String fetchProperties, FetchConfig fetchConfig);
+
+  /**
+   * Specify a path to fetch eagerly including all its properties.
+   * <p>
+   * Ebean will endeavour to fetch this path using a SQL join. If Ebean determines that it can
+   * not use a SQL join (due to maxRows or because it would result in a cartesian product) Ebean
+   * will automatically convert this fetch query into a "query join" - i.e. use fetchQuery().
+   * </p>
+   * <pre>{@code
+   *
+   * // fetch customers (their id, name and status)
+   * List<Customer> customers = DB.find(Customer.class)
+   *     // eager fetch the contacts
+   *     .fetch("contacts")
+   *     .findList();
+   *
+   * }</pre>
+   *
+   * @param path the property path we wish to fetch eagerly.
+   */
+  SELF fetch(String path);
+
+  /**
+   * Fetch the path eagerly using a "query join" (separate SQL query).
+   * <p>
+   * This is the same as:
+   * <pre>{@code
+   *
+   *  fetch(path, FetchConfig.ofQuery())
+   *
+   * }</pre>
+   * <p>
+   * This would be used instead of a fetch() when we use a separate SQL query to fetch this
+   * part of the object graph rather than a SQL join.
+   * <p>
+   * We might typically get a performance benefit when the path to fetch is a OneToMany
+   * or ManyToMany, the 'width' of the 'root bean' is wide and the cardinality of the many
+   * is high.
+   *
+   * @param path the property path we wish to fetch eagerly
+   */
+  SELF fetchQuery(String path);
+
+  /**
+   * Fetch the path eagerly using L2 cache.
+   */
+  SELF fetchCache(String path);
+
+  /**
+   * Fetch the path lazily (via batch lazy loading).
+   * <p>
+   * This is the same as:
+   * </p>
+   * <pre>{@code
+   *
+   *  fetch(path, FetchConfig.ofLazy())
+   *
+   * }</pre>
+   * <p>
+   * The reason for using fetchLazy() is to either:
+   * </p>
+   * <ul>
+   * <li>Control/tune what is fetched as part of lazy loading</li>
+   * <li>Make use of the L2 cache, build this part of the graph from L2 cache</li>
+   * </ul>
+   *
+   * @param path the property path we wish to fetch lazily.
+   */
+  SELF fetchLazy(String path);
+
+  /**
+   * Additionally specify a JoinConfig to specify a "query join" and or define
+   * the lazy loading query.
+   * <pre>{@code
+   *
+   * // fetch customers (their id, name and status)
+   * List<Customer> customers = DB.find(Customer.class)
+   *     // lazy fetch contacts with a batch size of 100
+   *     .fetch("contacts", FetchConfig.ofLazy(100))
+   *     .findList();
+   *
+   * }</pre>
+   */
+  SELF fetch(String path, FetchConfig fetchConfig);
+
+}

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

@@ -25,7 +25,7 @@ import java.util.Iterator;
  *
  *  Query<Customer> query = database.find(Customer.class)
  *     .where().gt("id", 0)
- *     .order("id")
+ *     .orderBy("id")
  *     .setMaxRows(2);
  *
  *  QueryIterator<Customer> it = query.findIterate();

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

@@ -111,7 +111,7 @@ package io.ebean;
  *     .fetch("order.customer", "name")
  *     .where().gt("order.id", 0)
  *     .having().gt("totalAmount", 20)
- *     .order().desc("totalAmount")
+ *     .orderBy().desc("totalAmount")
  *     .setMaxRows(10)
  *     .findList();
  *

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

@@ -22,14 +22,14 @@ public interface RawSqlBuilder {
    * resultSet.
    */
   static RawSql resultSet(ResultSet resultSet, String... propertyNames) {
-    return XServiceProvider.rawSql().resultSet(resultSet, propertyNames);
+    return XBootstrapService.rawSql().resultSet(resultSet, propertyNames);
   }
 
   /**
    * Create and return a SqlRow based on the resultSet with dbTrueValue and binaryOptimizedUUID options.
    */
   static SqlRow sqlRow(ResultSet resultSet, final String dbTrueValue, boolean binaryOptimizedUUID) throws SQLException {
-    return XServiceProvider.rawSql().sqlRow(resultSet, dbTrueValue, binaryOptimizedUUID);
+    return XBootstrapService.rawSql().sqlRow(resultSet, dbTrueValue, binaryOptimizedUUID);
   }
 
   /**
@@ -38,7 +38,7 @@ public interface RawSqlBuilder {
    * this query.
    */
   static RawSqlBuilder unparsed(String sql) {
-    return XServiceProvider.rawSql().unparsed(sql);
+    return XBootstrapService.rawSql().unparsed(sql);
   }
 
   /**
@@ -55,7 +55,7 @@ public interface RawSqlBuilder {
    * </p>
    */
   static RawSqlBuilder parse(String sql) {
-    return XServiceProvider.rawSql().parsed(sql);
+    return XBootstrapService.rawSql().parsed(sql);
   }
 
   /**

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

@@ -1,11 +1,12 @@
 package io.ebean;
 
-import io.avaje.lang.NonNullApi;
-import io.avaje.lang.Nullable;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 import javax.sql.DataSource;
 import java.io.Serializable;
 import java.sql.Connection;
+import java.util.Collection;
 import java.util.List;
 import java.util.Optional;
 import java.util.function.Consumer;
@@ -39,7 +40,7 @@ import java.util.function.Predicate;
  *
  * }</pre>
  */
-@NonNullApi
+@NullMarked
 public interface SqlQuery extends Serializable, CancelableQuery {
 
   /**
@@ -62,7 +63,17 @@ public interface SqlQuery extends Serializable, CancelableQuery {
    * source. We use {@code usingMaster()} to instead ensure that the query is executed
    * against the master data source.
    */
-  SqlQuery usingMaster();
+  default SqlQuery usingMaster() {
+    return usingMaster(true);
+  }
+
+  /**
+   * Ensure the master DataSource is used when useMaster is true. Otherwise, the read only
+   * data source can be used if defined.
+   *
+   * @see #usingMaster()
+   */
+  SqlQuery usingMaster(boolean useMaster);
 
   /**
    * Execute the query returning a list.
@@ -171,7 +182,7 @@ public interface SqlQuery extends Serializable, CancelableQuery {
    *   List<SqlRow> list =
    *     DB.sqlQuery(sql)
    *       .setParameter("Rob")
-   *       .setParameter("Status.NEW)
+   *       .setParameter(Status.NEW)
    *       .findList();
    *
    *   // the same as ...
@@ -241,11 +252,45 @@ public interface SqlQuery extends Serializable, CancelableQuery {
    */
   SqlQuery setParameter(int position, Object value);
 
+  /**
+   * Bind the array parameter by its index position for use with Postgres ANY.
+   * <p>
+   * For Postgres this binds an ARRAY rather than expands into multiple bind values.
+   * <pre>{@code
+   *
+   *    String sql = "select name from customer where id = any(?)";
+   *
+   *    List<SqlRow> list =
+   *      DB.sqlQuery(sql)
+   *        .setArrayParameter(1, List.of(1, 2, 3))
+   *        .findList();
+   *
+   * }</pre>
+   */
+  SqlQuery setArrayParameter(int position, Collection<?> value);
+
   /**
    * Bind the named parameter value.
    */
   SqlQuery setParameter(String name, Object value);
 
+  /**
+   * Bind the named 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 name from customer where id = any(:idList)";
+   *
+   *    List<SqlRow> list =
+   *      DB.sqlQuery(sql)
+   *        .setArrayParameter("idList", List.of(1, 2, 3))
+   *        .findList();
+   *
+   * }</pre>
+   */
+  SqlQuery setArrayParameter(String name, Collection<?> value);
+
   /**
    * Set the index of the first row of the results to return.
    */
@@ -322,6 +367,14 @@ public interface SqlQuery extends Serializable, CancelableQuery {
    */
   interface TypeQuery<T> {
 
+    /**
+     * Ensure the master DataSource is used when useMaster is true. Otherwise, the read only
+     * data source can be used if defined.
+     *
+     * @see SqlQuery#usingMaster(boolean)
+     */
+    TypeQuery<T> usingMaster(boolean useMaster);
+
     /**
      * Execute the query using the given transaction.
      */

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

@@ -0,0 +1,22 @@
+package io.ebean;
+
+/**
+ * Attempted to modify a read only entity.
+ */
+public class UnmodifiableEntityException extends BeanAccessException {
+  private static final long serialVersionUID = 1;
+
+  /**
+   * Create with no message.
+   */
+  public UnmodifiableEntityException() {
+    super();
+  }
+
+  /**
+   * Create with message.
+   */
+  public UnmodifiableEntityException(String message) {
+    super(message);
+  }
+}

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

@@ -0,0 +1,95 @@
+package io.ebean;
+
+import io.ebean.metric.MetricFactory;
+import io.ebean.service.*;
+
+import java.util.ServiceLoader;
+
+/**
+ * Bootstrap internal services.
+ */
+public final class XBootstrapService {
+
+  private static final SpiContainerFactory containerFactory;
+  private static final SpiRawSqlService rawSqlService;
+  private static final SpiProfileLocationFactory profileLocationFactory;
+  private static final SpiFetchGroupService fetchGroupService;
+  private static final MetricFactory metricFactory;
+  private static final SpiJsonService jsonService;
+  static {
+    SpiContainerFactory _factory = null;
+    SpiRawSqlService _raw = null;
+    SpiProfileLocationFactory _profile = null;
+    SpiFetchGroupService _fetch = null;
+    MetricFactory _metric = null;
+    SpiJsonService _json = null;
+    for (BootstrapService extension : ServiceLoader.load(BootstrapService.class)) {
+      if (extension instanceof SpiContainerFactory) {
+        _factory = (SpiContainerFactory)extension;
+      } else if (extension instanceof SpiRawSqlService) {
+        _raw = (SpiRawSqlService)extension;
+      } else if (extension instanceof SpiProfileLocationFactory) {
+        _profile = (SpiProfileLocationFactory)extension;
+      } else if (extension instanceof SpiFetchGroupService) {
+        _fetch = (SpiFetchGroupService)extension;
+      } else if (extension instanceof MetricFactory) {
+        _metric = (MetricFactory)extension;
+      } else if (extension instanceof SpiJsonService) {
+        _json = (SpiJsonService)extension;
+      }
+    }
+    containerFactory = _factory;
+    rawSqlService = _raw;
+    profileLocationFactory = _profile;
+    fetchGroupService = _fetch;
+    metricFactory = _metric;
+    jsonService = _json;
+  }
+
+  /**
+   * Return the MetricFactory found in boostrap service loading.
+   */
+  public static MetricFactory metricFactory() {
+    return metricFactory;
+  }
+
+  /**
+   * Return the SpiJsonService found in boostrap service loading.
+   */
+  public static SpiJsonService jsonService() {
+    return jsonService;
+  }
+
+  static SpiContainerFactory containerFactory() {
+    return containerFactory;
+  }
+
+  static SpiRawSqlService rawSql() {
+    return rawSqlService;
+  }
+
+  static SpiProfileLocationFactory profileLocationFactory() {
+    return profileLocationFactory;
+  }
+
+  /**
+   * Return the FetchGroup with the given select clause.
+   */
+  static <T> FetchGroup<T> fetchGroupOf(Class<T> cls, String select) {
+    return fetchGroupService.of(cls, select);
+  }
+
+  /**
+   * Return the FetchGroupBuilder with the given select clause.
+   */
+  static <T> FetchGroupBuilder<T> fetchGroupOf(Class<T> cls) {
+    return fetchGroupService.of(cls);
+  }
+
+  /**
+   * Return the FetchGroup Query for building fetch groups via query beans.
+   */
+  static <T> SpiFetchGroupQuery<T> fetchGroupQueryFor(Class<T> cls) {
+    return fetchGroupService.queryFor(cls);
+  }
+}

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

@@ -1,76 +0,0 @@
-package io.ebean;
-
-import io.ebean.service.SpiFetchGroupQuery;
-import io.ebean.service.SpiFetchGroupService;
-import io.ebean.service.SpiProfileLocationFactory;
-import io.ebean.service.SpiRawSqlService;
-
-import java.util.Iterator;
-import java.util.ServiceLoader;
-
-/**
- * Lookup internal services.
- */
-final class XServiceProvider {
-
-  private static SpiRawSqlService rawSqlService = initRawSql();
-
-  private static SpiProfileLocationFactory profileLocationFactory = initProfileLocation();
-
-  private static SpiFetchGroupService fetchGroupService = initSpiFetchGroupService();
-
-  private static SpiFetchGroupService initSpiFetchGroupService() {
-    return loadFirstService(SpiFetchGroupService.class);
-  }
-
-  private static SpiRawSqlService initRawSql() {
-    return loadFirstService(SpiRawSqlService.class);
-  }
-
-  private static SpiProfileLocationFactory initProfileLocation() {
-    return loadFirstService(SpiProfileLocationFactory.class);
-  }
-
-  private static <T> T loadFirstService(Class<T> cls) {
-    Iterator<T> loader = ServiceLoader.load(cls).iterator();
-    if (loader.hasNext()) {
-      return loader.next();
-    }
-    throw new IllegalStateException("No service implementation found for " + cls);
-  }
-
-  /**
-   * Return the RawSqlService implementation.
-   */
-  static SpiRawSqlService rawSql() {
-    return rawSqlService;
-  }
-
-  /**
-   * Return the RawSqlService implementation.
-   */
-  static SpiProfileLocationFactory profileLocationFactory() {
-    return profileLocationFactory;
-  }
-
-  /**
-   * Return the FetchGroup with the given select clause.
-   */
-  static <T> FetchGroup<T> fetchGroupOf(Class<T> cls, String select) {
-    return fetchGroupService.of(cls, select);
-  }
-
-  /**
-   * Return the FetchGroupBuilder with the given select clause.
-   */
-  static <T> FetchGroupBuilder<T> fetchGroupOf(Class<T> cls) {
-    return fetchGroupService.of(cls);
-  }
-
-  /**
-   * Return the FetchGroup Query for building fetch groups via query beans.
-   */
-  static <T> SpiFetchGroupQuery<T> fetchGroupQueryFor(Class<T> cls) {
-    return fetchGroupService.queryFor(cls);
-  }
-}

ebean-api/src/main/java/io/ebean/bean/BeanCollection.java

@@ -119,18 +119,6 @@ public interface BeanCollection<E> extends Serializable, ToStringAware {
    */
   void setLoader(BeanCollectionLoader beanLoader);
 
-  /**
-   * Set to true if you want the BeanCollection to be treated as read only. This
-   * means no elements can be added or removed etc.
-   */
-  void setReadOnly(boolean readOnly);
-
-  /**
-   * Return true if the collection should be treated as readOnly and no elements
-   * can be added or removed etc.
-   */
-  boolean isReadOnly();
-
   /**
    * Add the bean to the collection. This is disallowed for BeanMap.
    */
@@ -237,7 +225,7 @@ public interface BeanCollection<E> extends Serializable, ToStringAware {
   boolean wasTouched();
 
   /**
-   * Return a shallow copy of this collection that is modifiable.
+   * Freeze the collection returning an unmodifiable version.
    */
-  BeanCollection<E> shallowCopy();
+  Object freeze();
 }

ebean-api/src/main/java/io/ebean/bean/EntityBeanIntercept.java

@@ -148,18 +148,6 @@ public interface EntityBeanIntercept extends Serializable {
    */
   boolean isLoadedFromCache();
 
-  /**
-   * Return true if the bean should be treated as readOnly. If a setter method
-   * is called when it is readOnly an Exception is thrown.
-   */
-  boolean isReadOnly();
-
-  /**
-   * Set the readOnly status. If readOnly then calls to setter methods through
-   * an exception.
-   */
-  void setReadOnly(boolean readOnly);
-
   /**
    * Set the bean to be updated when persisted (for merge).
    */
@@ -552,4 +540,9 @@ public interface EntityBeanIntercept extends Serializable {
    * Update the 'next' mutable info returning the content that was obtained via dirty detection.
    */
   String mutableNext(int propertyIndex);
+
+  /**
+   * Return true if this entity bean should be frozen. Used to handle recursive freezing.
+   */
+  boolean freeze();
 }

ebean-api/src/main/java/io/ebean/bean/InterceptBase.java

@@ -0,0 +1,70 @@
+package io.ebean.bean;
+
+/**
+ * Common base features for EntityBeanIntercept.
+ */
+abstract class InterceptBase implements EntityBeanIntercept {
+
+  final EntityBean owner;
+  boolean fullyLoadedBean;
+
+  /**
+   * Create with a given entity.
+   */
+  InterceptBase(Object ownerBean) {
+    this.owner = (EntityBean) ownerBean;
+  }
+
+  /**
+   * EXPERIMENTAL - Constructor only for use by serialization frameworks.
+   */
+  InterceptBase() {
+    this.owner = null;
+  }
+
+  @Override
+  public final EntityBean owner() {
+    return owner;
+  }
+
+  @Override
+  public final boolean isFullyLoadedBean() {
+    return fullyLoadedBean;
+  }
+
+  @Override
+  public final void setFullyLoadedBean(boolean fullyLoadedBean) {
+    this.fullyLoadedBean = fullyLoadedBean;
+  }
+
+  @Override
+  public final String property(int propertyIndex) {
+    if (propertyIndex == -1) {
+      return null;
+    }
+    return owner._ebean_getPropertyName(propertyIndex);
+  }
+
+  @Override
+  public final int findProperty(String propertyName) {
+    final String[] names = owner._ebean_getPropertyNames();
+    for (int i = 0; i < names.length; i++) {
+      if (names[i].equals(propertyName)) {
+        return i;
+      }
+    }
+    return -1;
+  }
+
+  @Override
+  public final StringBuilder loadedPropertyKey() {
+    final StringBuilder sb = new StringBuilder();
+    final int len = propertyLength();
+    for (int i = 0; i < len; i++) {
+      if (isLoadedProperty(i)) {
+        sb.append(i).append(',');
+      }
+    }
+    return sb;
+  }
+}

ebean-api/src/main/java/io/ebean/bean/InterceptReadOnly.java

@@ -1,37 +1,44 @@
 package io.ebean.bean;
 
+import io.ebean.LazyInitialisationException;
+import io.ebean.UnmodifiableEntityException;
 import io.ebean.ValuePair;
 
-import java.util.Collections;
-import java.util.Map;
-import java.util.Set;
+import java.util.*;
 
 /**
  * EntityBeanIntercept optimised for read only use.
  * <p>
  * For the read only use this intercept doesn't need to hold any state that is normally
- * required for updates such as per property changed, loaded, dirty state, original values
+ * required for updates such as per property changed, dirty state, original values
  * bean state etc.
  */
-public class InterceptReadOnly implements EntityBeanIntercept {
+public final class InterceptReadOnly extends InterceptBase {
 
-  private final EntityBean owner;
+  private final boolean[] loaded;
+  private boolean frozen;
 
   /**
    * Create with a given entity.
    */
   public InterceptReadOnly(Object ownerBean) {
-    this.owner = (EntityBean) ownerBean;
+    super(ownerBean);
+    this.loaded = new boolean[owner._ebean_getPropertyNames().length];
+  }
+
+  @Override
+  public boolean freeze() {
+    if (frozen) {
+      return false;
+    } else {
+      frozen = true;
+      return true;
+    }
   }
 
   @Override
   public String toString() {
-    return "InterceptReadOnly{" + owner + '}';
-  }
-
-  @Override
-  public EntityBean owner() {
-    return owner;
+    return "InterceptReadOnly{frozen:" + frozen + " loaded:" + loadedPropertyNames() + '}';
   }
 
   @Override
@@ -94,18 +101,13 @@ public class InterceptReadOnly implements EntityBeanIntercept {
 
   }
 
-  @Override
-  public boolean isFullyLoadedBean() {
-    return false;
-  }
-
-  @Override
-  public void setFullyLoadedBean(boolean fullyLoadedBean) {
-
-  }
-
   @Override
   public boolean isPartial() {
+    for (boolean flag : loaded) {
+      if (!flag) {
+        return true;
+      }
+    }
     return false;
   }
 
@@ -136,7 +138,14 @@ public class InterceptReadOnly implements EntityBeanIntercept {
 
   @Override
   public boolean hasIdOnly(int idIndex) {
-    return false;
+    for (int i = 0; i < loaded.length; i++) {
+      if (i == idIndex) {
+        if (!loaded[i]) return false;
+      } else if (loaded[i]) {
+        return false;
+      }
+    }
+    return true;
   }
 
   @Override
@@ -159,16 +168,6 @@ public class InterceptReadOnly implements EntityBeanIntercept {
     return false;
   }
 
-  @Override
-  public boolean isReadOnly() {
-    return true;
-  }
-
-  @Override
-  public void setReadOnly(boolean readOnly) {
-
-  }
-
   @Override
   public void setForceUpdate(boolean forceUpdate) {
 
@@ -234,44 +233,38 @@ public class InterceptReadOnly implements EntityBeanIntercept {
     return null;
   }
 
-  @Override
-  public int findProperty(String propertyName) {
-    return 0;
-  }
-
-  @Override
-  public String property(int propertyIndex) {
-    return null;
-  }
-
   @Override
   public int propertyLength() {
-    return 0;
+    return loaded.length;
   }
 
   @Override
   public void setPropertyLoaded(String propertyName, boolean loaded) {
-
+    final int position = findProperty(propertyName);
+    if (position == -1) {
+      throw new IllegalArgumentException("Property not found - " + propertyName);
+    }
+    this.loaded[position] = loaded;
   }
 
   @Override
   public void setPropertyUnloaded(int propertyIndex) {
-
+    loaded[propertyIndex] = false;
   }
 
   @Override
   public void setLoadedProperty(int propertyIndex) {
-
+    loaded[propertyIndex] = true;
   }
 
   @Override
   public void setLoadedPropertyAll() {
-
+    Arrays.fill(loaded, true);
   }
 
   @Override
   public boolean isLoadedProperty(int propertyIndex) {
-    return false;
+    return loaded[propertyIndex];
   }
 
   @Override
@@ -321,7 +314,16 @@ public class InterceptReadOnly implements EntityBeanIntercept {
 
   @Override
   public Set<String> loadedPropertyNames() {
-    return Collections.emptySet();
+    if (fullyLoadedBean) {
+      return null;
+    }
+    final Set<String> props = new LinkedHashSet<>();
+    for (int i = 0; i < loaded.length; i++) {
+      if (loaded[i]) {
+        props.add(property(i));
+      }
+    }
+    return props;
   }
 
   @Override
@@ -369,14 +371,11 @@ public class InterceptReadOnly implements EntityBeanIntercept {
 
   }
 
-  @Override
-  public StringBuilder loadedPropertyKey() {
-    return null;
-  }
-
   @Override
   public boolean[] loaded() {
-    return new boolean[0];
+    final boolean[] ret = new boolean[loaded.length];
+    System.arraycopy(loaded, 0, ret, 0, ret.length);
+    return ret;
   }
 
   @Override
@@ -401,7 +400,7 @@ public class InterceptReadOnly implements EntityBeanIntercept {
 
   @Override
   public void initialisedMany(int propertyIndex) {
-
+    loaded[propertyIndex] = true;
   }
 
   @Override
@@ -416,12 +415,14 @@ public class InterceptReadOnly implements EntityBeanIntercept {
 
   @Override
   public void preGetter(int propertyIndex) {
-
+    if (!loaded[propertyIndex]) {
+      throw new LazyInitialisationException("Property not loaded: " + property(propertyIndex));
+    }
   }
 
   @Override
   public void preSetterMany(boolean interceptField, int propertyIndex, Object oldValue, Object newValue) {
-
+    throw new UnmodifiableEntityException("Attempting to modify " + property(propertyIndex));
   }
 
   @Override
@@ -436,57 +437,57 @@ public class InterceptReadOnly implements EntityBeanIntercept {
 
   @Override
   public void preSetter(boolean intercept, int propertyIndex, Object oldValue, Object newValue) {
-
+    throw new UnmodifiableEntityException("Attempting to modify " + property(propertyIndex));
   }
 
   @Override
   public void preSetter(boolean intercept, int propertyIndex, boolean oldValue, boolean newValue) {
-
+    throw new UnmodifiableEntityException("Attempting to modify " + property(propertyIndex));
   }
 
   @Override
   public void preSetter(boolean intercept, int propertyIndex, int oldValue, int newValue) {
-
+    throw new UnmodifiableEntityException("Attempting to modify " + property(propertyIndex));
   }
 
   @Override
   public void preSetter(boolean intercept, int propertyIndex, long oldValue, long newValue) {
-
+    throw new UnmodifiableEntityException("Attempting to modify " + property(propertyIndex));
   }
 
   @Override
   public void preSetter(boolean intercept, int propertyIndex, double oldValue, double newValue) {
-
+    throw new UnmodifiableEntityException("Attempting to modify " + property(propertyIndex));
   }
 
   @Override
   public void preSetter(boolean intercept, int propertyIndex, float oldValue, float newValue) {
-
+    throw new UnmodifiableEntityException("Attempting to modify " + property(propertyIndex));
   }
 
   @Override
   public void preSetter(boolean intercept, int propertyIndex, short oldValue, short newValue) {
-
+    throw new UnmodifiableEntityException("Attempting to modify " + property(propertyIndex));
   }
 
   @Override
   public void preSetter(boolean intercept, int propertyIndex, char oldValue, char newValue) {
-
+    throw new UnmodifiableEntityException("Attempting to modify " + property(propertyIndex));
   }
 
   @Override
   public void preSetter(boolean intercept, int propertyIndex, byte oldValue, byte newValue) {
-
+    throw new UnmodifiableEntityException("Attempting to modify " + property(propertyIndex));
   }
 
   @Override
   public void preSetter(boolean intercept, int propertyIndex, char[] oldValue, char[] newValue) {
-
+    throw new UnmodifiableEntityException("Attempting to modify " + property(propertyIndex));
   }
 
   @Override
   public void preSetter(boolean intercept, int propertyIndex, byte[] oldValue, byte[] newValue) {
-
+    throw new UnmodifiableEntityException("Attempting to modify " + property(propertyIndex));
   }
 
   @Override

ebean-api/src/main/java/io/ebean/bean/InterceptReadWrite.java

@@ -22,7 +22,7 @@ import java.util.concurrent.locks.ReentrantLock;
  * This provides the mechanisms to support deferred fetching of reference beans
  * and oldValues generation for concurrency checking.
  */
-public final class InterceptReadWrite implements EntityBeanIntercept {
+public final class InterceptReadWrite extends InterceptBase {
 
   private static final long serialVersionUID = -3664031775464862649L;
 
@@ -56,10 +56,6 @@ public final class InterceptReadWrite implements EntityBeanIntercept {
   private String ebeanServerName;
   private boolean deletedFromCollection;
 
-  /**
-   * The actual entity bean that 'owns' this intercept.
-   */
-  private final EntityBean owner;
   private EntityBean embeddedOwner;
   private int embeddedOwnerIndex;
   /**
@@ -67,7 +63,6 @@ public final class InterceptReadWrite implements EntityBeanIntercept {
    */
   private int state;
   private boolean forceUpdate;
-  private boolean readOnly;
   private boolean dirty;
   /**
    * Flag set to disable lazy loading.
@@ -77,7 +72,6 @@ public final class InterceptReadWrite implements EntityBeanIntercept {
    * Flag set when lazy loading failed due to the underlying bean being deleted in the DB.
    */
   private boolean lazyLoadFailure;
-  private boolean fullyLoadedBean;
   private boolean loadedFromCache;
   private final byte[] flags;
   private Object[] origValues;
@@ -101,7 +95,7 @@ public final class InterceptReadWrite implements EntityBeanIntercept {
    * Create with a given entity.
    */
   public InterceptReadWrite(Object ownerBean) {
-    this.owner = (EntityBean) ownerBean;
+    super(ownerBean);
     this.flags = new byte[owner._ebean_getPropertyNames().length];
   }
 
@@ -109,16 +103,20 @@ public final class InterceptReadWrite implements EntityBeanIntercept {
    * EXPERIMENTAL - Constructor only for use by serialization frameworks.
    */
   public InterceptReadWrite() {
-    this.owner = null;
+    super();
     this.flags = null;
   }
 
+  @Override
+  public boolean freeze() {
+    throw new UnsupportedOperationException("never expected");
+  }
+
   @Override
   public String toString() {
     return "InterceptReadWrite@" + hashCode() + "{state=" + state +
       (dirty ? " dirty;" : "") +
       (forceUpdate ? " forceUpdate;" : "") +
-      (readOnly ? " readOnly;" : "") +
       (disableLazyLoad ? " disableLazyLoad;" : "") +
       (lazyLoadFailure ? " lazyLoadFailure;" : "") +
       (fullyLoadedBean ? " fullyLoadedBean;" : "") +
@@ -131,11 +129,6 @@ public final class InterceptReadWrite implements EntityBeanIntercept {
       '}';
   }
 
-  @Override
-  public EntityBean owner() {
-    return owner;
-  }
-
   @Override
   public PersistenceContext persistenceContext() {
     return persistenceContext;
@@ -200,16 +193,6 @@ public final class InterceptReadWrite implements EntityBeanIntercept {
     this.ebeanServerName = beanLoader.name();
   }
 
-  @Override
-  public boolean isFullyLoadedBean() {
-    return fullyLoadedBean;
-  }
-
-  @Override
-  public void setFullyLoadedBean(boolean fullyLoadedBean) {
-    this.fullyLoadedBean = fullyLoadedBean;
-  }
-
   @Override
   public boolean isPartial() {
     for (byte flag : flags) {
@@ -298,16 +281,6 @@ public final class InterceptReadWrite implements EntityBeanIntercept {
     return loadedFromCache;
   }
 
-  @Override
-  public boolean isReadOnly() {
-    return readOnly;
-  }
-
-  @Override
-  public void setReadOnly(boolean readOnly) {
-    this.readOnly = readOnly;
-  }
-
   @Override
   public void setForceUpdate(boolean forceUpdate) {
     this.forceUpdate = forceUpdate;
@@ -411,25 +384,6 @@ public final class InterceptReadWrite implements EntityBeanIntercept {
     return origValues[propertyIndex];
   }
 
-  @Override
-  public int findProperty(String propertyName) {
-    final String[] names = owner._ebean_getPropertyNames();
-    for (int i = 0; i < names.length; i++) {
-      if (names[i].equals(propertyName)) {
-        return i;
-      }
-    }
-    return -1;
-  }
-
-  @Override
-  public String property(int propertyIndex) {
-    if (propertyIndex == -1) {
-      return null;
-    }
-    return owner._ebean_getPropertyName(propertyIndex);
-  }
-
   @Override
   public int propertyLength() {
     return flags.length;
@@ -668,18 +622,6 @@ public final class InterceptReadWrite implements EntityBeanIntercept {
     }
   }
 
-  @Override
-  public StringBuilder loadedPropertyKey() {
-    final StringBuilder sb = new StringBuilder();
-    final int len = propertyLength();
-    for (int i = 0; i < len; i++) {
-      if (isLoadedProperty(i)) {
-        sb.append(i).append(',');
-      }
-    }
-    return sb;
-  }
-
   @Override
   public boolean[] loaded() {
     final boolean[] ret = new boolean[flags.length];
@@ -708,7 +650,7 @@ public final class InterceptReadWrite implements EntityBeanIntercept {
         if (database == null) {
           throw new PersistenceException(ebeanServerName == null ? "No registered default server" : "Database [" + ebeanServerName + "] is not registered");
         }
-        // For stand alone reference bean or after deserialisation lazy load
+        // For stand-alone reference bean or after deserialisation lazy load
         // using the ebeanServer. Synchronise only on the bean.
         loadBeanInternal(loadProperty, database.pluginApi().beanLoader());
         return;
@@ -845,18 +787,12 @@ public final class InterceptReadWrite implements EntityBeanIntercept {
     if (state == STATE_NEW) {
       setLoadedProperty(propertyIndex);
     } else {
-      if (readOnly) {
-        throw new IllegalStateException("This bean is readOnly");
-      }
       setChangeLoaded(propertyIndex);
     }
   }
 
   @Override
   public void setChangedPropertyValue(int propertyIndex, boolean setDirtyState, Object origValue) {
-    if (readOnly) {
-      throw new IllegalStateException("This bean is readOnly");
-    }
     setChangedProperty(propertyIndex);
     if (setDirtyState) {
       setOriginalValue(propertyIndex, origValue);

ebean-api/src/main/java/io/ebean/cache/QueryCacheEntry.java

@@ -1,5 +1,6 @@
 package io.ebean.cache;
 
+import java.time.Instant;
 import java.util.Set;
 
 /**
@@ -10,11 +11,11 @@ import java.util.Set;
  * the query cache entry is treated as invalid.
  * </p>
  */
-public class QueryCacheEntry {
+public final class QueryCacheEntry {
 
   private final Object value;
   private final Set<String> dependentTables;
-  private final long timestamp;
+  private final Instant timestamp;
 
   /**
    * Create with dependent tables and timestamp.
@@ -23,7 +24,7 @@ public class QueryCacheEntry {
    * @param dependentTables The extra tables the query is dependent on (joins to)
    * @param timestamp       The timestamp that the query uses to check for modifications
    */
-  public QueryCacheEntry(Object value, Set<String> dependentTables, long timestamp) {
+  public QueryCacheEntry(Object value, Set<String> dependentTables, Instant timestamp) {
     this.value = value;
     this.dependentTables = dependentTables;
     this.timestamp = timestamp;
@@ -32,21 +33,21 @@ public class QueryCacheEntry {
   /**
    * Return the actual query result.
    */
-  public Object getValue() {
+  public Object value() {
     return value;
   }
 
   /**
    * Return the tables the query result is dependent on.
    */
-  public Set<String> getDependentTables() {
+  public Set<String> dependentTables() {
     return dependentTables;
   }
 
   /**
    * Return the timestamp used to check for modifications on the dependent tables.
    */
-  public long getTimestamp() {
+  public Instant timestamp() {
     return timestamp;
   }
 }

ebean-api/src/main/java/io/ebean/cache/ServerCache.java

@@ -1,6 +1,6 @@
 package io.ebean.cache;
 
-import io.avaje.lang.Nullable;
+import org.jspecify.annotations.Nullable;
 import io.ebean.meta.MetricVisitor;
 
 import java.util.LinkedHashMap;

ebean-api/src/main/java/io/ebean/common/AbstractBeanCollection.java

@@ -17,7 +17,6 @@ abstract class AbstractBeanCollection<E> implements BeanCollection<E> {
   private static final long serialVersionUID = 3365725236140187588L;
 
   protected final ReentrantLock lock = new ReentrantLock();
-  protected boolean readOnly;
   protected boolean disableLazyLoad;
   /**
    * The Database this is associated with. (used for lazy fetch).
@@ -55,7 +54,6 @@ abstract class AbstractBeanCollection<E> implements BeanCollection<E> {
     this.ebeanServerName = loader.name();
     this.ownerBean = ownerBean;
     this.propertyName = propertyName;
-    this.readOnly = ownerBean != null && ownerBean._ebean_getIntercept().isReadOnly();
   }
 
   @Override
@@ -103,22 +101,6 @@ abstract class AbstractBeanCollection<E> implements BeanCollection<E> {
     this.ebeanServerName = loader.name();
   }
 
-  @Override
-  public boolean isReadOnly() {
-    return readOnly;
-  }
-
-  @Override
-  public void setReadOnly(boolean readOnly) {
-    this.readOnly = readOnly;
-  }
-
-  void checkReadOnly() {
-    if (readOnly) {
-      throw new IllegalStateException("This collection is in ReadOnly mode");
-    }
-  }
-
   // ---------------------------------------------------------
   // Support for modify additions deletions etc - ManyToMany
   // ---------------------------------------------------------
@@ -212,14 +194,4 @@ abstract class AbstractBeanCollection<E> implements BeanCollection<E> {
     return modifyHolder != null && modifyHolder.wasTouched();
   }
 
-  /**
-   * Copies all relevant properties for a clone. See {@link #shallowCopy()}
-   */
-  protected void setFromOriginal(AbstractBeanCollection<E> other) {
-    this.disableLazyLoad = other.disableLazyLoad;
-    this.ebeanServerName = other.ebeanServerName;
-    this.loader = other.loader;
-    this.ownerBean = other.ownerBean;
-    this.propertyName = other.propertyName;
-  }
 }

ebean-api/src/main/java/io/ebean/common/BeanList.java

@@ -2,7 +2,6 @@ package io.ebean.common;
 
 import io.ebean.bean.*;
 
-import java.io.Serializable;
 import java.util.*;
 
 /**
@@ -39,6 +38,17 @@ public final class BeanList<E> extends AbstractBeanCollection<E> implements List
     super(loader, ownerBean, propertyName);
   }
 
+  @Override
+  public List<E> freeze() {
+    if (list == null) {
+      return null;
+    } else if (list.isEmpty()) {
+      return List.of();
+    } else {
+      return Collections.unmodifiableList(list);
+    }
+  }
+
   @Override
   public void toString(ToStringBuilder builder) {
     builder.addCollection(list);
@@ -223,7 +233,6 @@ public final class BeanList<E> extends AbstractBeanCollection<E> implements List
 
   @Override
   public void add(int index, E element) {
-    checkReadOnly();
     init();
     if (modifyListening) {
       modifyAddition(element);
@@ -238,7 +247,6 @@ public final class BeanList<E> extends AbstractBeanCollection<E> implements List
 
   @Override
   public boolean add(E bean) {
-    checkReadOnly();
     init();
     if (modifyListening) {
       if (list.add(bean)) {
@@ -253,7 +261,6 @@ public final class BeanList<E> extends AbstractBeanCollection<E> implements List
 
   @Override
   public boolean addAll(Collection<? extends E> beans) {
-    checkReadOnly();
     init();
     if (modifyListening) {
       // all elements in c are added (no contains checking)
@@ -264,7 +271,6 @@ public final class BeanList<E> extends AbstractBeanCollection<E> implements List
 
   @Override
   public boolean addAll(int index, Collection<? extends E> beans) {
-    checkReadOnly();
     init();
     if (modifyListening) {
       // all elements in c are added (no contains checking)
@@ -275,7 +281,6 @@ public final class BeanList<E> extends AbstractBeanCollection<E> implements List
 
   @Override
   public void clear() {
-    checkReadOnly();
     // TODO: when clear() and not initialised could be more clever
     // and fetch just the Id's
     initClear();
@@ -320,9 +325,6 @@ public final class BeanList<E> extends AbstractBeanCollection<E> implements List
   @Override
   public Iterator<E> iterator() {
     init();
-    if (readOnly) {
-      return new ReadOnlyListIterator<>(list.listIterator());
-    }
     if (modifyListening) {
       return new ModifyIterator<>(this, list.iterator());
     }
@@ -338,9 +340,6 @@ public final class BeanList<E> extends AbstractBeanCollection<E> implements List
   @Override
   public ListIterator<E> listIterator() {
     init();
-    if (readOnly) {
-      return new ReadOnlyListIterator<>(list.listIterator());
-    }
     if (modifyListening) {
       return new ModifyListIterator<>(this, list.listIterator());
     }
@@ -350,9 +349,6 @@ public final class BeanList<E> extends AbstractBeanCollection<E> implements List
   @Override
   public ListIterator<E> listIterator(int index) {
     init();
-    if (readOnly) {
-      return new ReadOnlyListIterator<>(list.listIterator(index));
-    }
     if (modifyListening) {
       return new ModifyListIterator<>(this, list.listIterator(index));
     }
@@ -368,7 +364,6 @@ public final class BeanList<E> extends AbstractBeanCollection<E> implements List
 
   @Override
   public E remove(int index) {
-    checkReadOnly();
     init();
     if (modifyListening) {
       E o = list.remove(index);
@@ -380,7 +375,6 @@ public final class BeanList<E> extends AbstractBeanCollection<E> implements List
 
   @Override
   public boolean remove(Object bean) {
-    checkReadOnly();
     init();
     if (modifyListening) {
       boolean isRemove = list.remove(bean);
@@ -394,7 +388,6 @@ public final class BeanList<E> extends AbstractBeanCollection<E> implements List
 
   @Override
   public boolean removeAll(Collection<?> beans) {
-    checkReadOnly();
     init();
     if (modifyListening) {
       boolean changed = false;
@@ -412,7 +405,6 @@ public final class BeanList<E> extends AbstractBeanCollection<E> implements List
 
   @Override
   public boolean retainAll(Collection<?> retainBeans) {
-    checkReadOnly();
     init();
     if (modifyListening) {
       boolean changed = false;
@@ -433,7 +425,6 @@ public final class BeanList<E> extends AbstractBeanCollection<E> implements List
 
   @Override
   public E set(int index, E element) {
-    checkReadOnly();
     init();
     if (modifyListening) {
       E o = list.set(index, element);
@@ -453,9 +444,6 @@ public final class BeanList<E> extends AbstractBeanCollection<E> implements List
   @Override
   public List<E> subList(int fromIndex, int toIndex) {
     init();
-    if (readOnly) {
-      return Collections.unmodifiableList(list.subList(fromIndex, toIndex));
-    }
     if (modifyListening) {
       return new ModifyList<>(this, list.subList(fromIndex, toIndex));
     }
@@ -475,67 +463,4 @@ public final class BeanList<E> extends AbstractBeanCollection<E> implements List
     return list.toArray(array);
   }
 
-  private static final class ReadOnlyListIterator<E> implements ListIterator<E>, Serializable {
-
-    private static final long serialVersionUID = 3097271091406323699L;
-
-    private final ListIterator<E> i;
-
-    ReadOnlyListIterator(ListIterator<E> i) {
-      this.i = i;
-    }
-
-    @Override
-    public void add(E o) {
-      throw new IllegalStateException("This collection is in ReadOnly mode");
-    }
-
-    @Override
-    public void remove() {
-      throw new IllegalStateException("This collection is in ReadOnly mode");
-    }
-
-    @Override
-    public void set(E o) {
-      throw new IllegalStateException("This collection is in ReadOnly mode");
-    }
-
-    @Override
-    public boolean hasNext() {
-      return i.hasNext();
-    }
-
-    @Override
-    public boolean hasPrevious() {
-      return i.hasPrevious();
-    }
-
-    @Override
-    public E next() {
-      return i.next();
-    }
-
-    @Override
-    public int nextIndex() {
-      return i.nextIndex();
-    }
-
-    @Override
-    public E previous() {
-      return i.previous();
-    }
-
-    @Override
-    public int previousIndex() {
-      return i.previousIndex();
-    }
-
-  }
-
-  @Override
-  public BeanCollection<E> shallowCopy() {
-    BeanList<E> copy = new BeanList<>(new CopyOnFirstWriteList<>(list));
-    copy.setFromOriginal(this);
-    return copy;
-  }
 }

ebean-api/src/main/java/io/ebean/common/BeanMap.java

@@ -37,6 +37,11 @@ public final class BeanMap<K, E> extends AbstractBeanCollection<E> implements Ma
     super(ebeanServer, ownerBean, propertyName);
   }
 
+  @Override
+  public Map<K, E> freeze() {
+    return map == null ? null : Collections.unmodifiableMap(map);
+  }
+
   @Override
   public void toString(ToStringBuilder builder) {
     if (map == null || map.isEmpty()) {
@@ -217,7 +222,6 @@ public final class BeanMap<K, E> extends AbstractBeanCollection<E> implements Ma
 
   @Override
   public void clear() {
-    checkReadOnly();
     initClear();
     if (modifyListening) {
       // add all beans to the removal list
@@ -243,9 +247,6 @@ public final class BeanMap<K, E> extends AbstractBeanCollection<E> implements Ma
   @Override
   public Set<Entry<K, E>> entrySet() {
     init();
-    if (readOnly) {
-      return Collections.unmodifiableSet(map.entrySet());
-    }
     return modifyListening ? new ModifyEntrySet<>(this, map.entrySet()) : map.entrySet();
   }
 
@@ -264,15 +265,11 @@ public final class BeanMap<K, E> extends AbstractBeanCollection<E> implements Ma
   @Override
   public Set<K> keySet() {
     init();
-    if (readOnly) {
-      return Collections.unmodifiableSet(map.keySet());
-    }
     return modifyListening ? new ModifyKeySet<>(this, map.keySet()) : map.keySet();
   }
 
   @Override
   public E put(K key, E value) {
-    checkReadOnly();
     init();
     if (modifyListening) {
       E oldBean = map.put(key, value);
@@ -289,7 +286,6 @@ public final class BeanMap<K, E> extends AbstractBeanCollection<E> implements Ma
 
   @Override
   public void putAll(Map<? extends K, ? extends E> puts) {
-    checkReadOnly();
     init();
     if (modifyListening) {
       for (Entry<? extends K, ? extends E> entry : puts.entrySet()) {
@@ -306,17 +302,16 @@ public final class BeanMap<K, E> extends AbstractBeanCollection<E> implements Ma
 
   @Override
   public void addBean(E bean) {
-    throw new IllegalStateException("Method not allowed on Map. Please use List instead.");
+    throw new UnsupportedOperationException("Method not allowed on Map. Please use List instead.");
   }
 
   @Override
   public void removeBean(E bean) {
-    throw new IllegalStateException("Method not allowed on Map. Please use List instead.");
+    throw new UnsupportedOperationException("Method not allowed on Map. Please use List instead.");
   }
 
   @Override
   public E remove(Object key) {
-    checkReadOnly();
     init();
     if (modifyListening) {
       E o = map.remove(key);
@@ -335,16 +330,6 @@ public final class BeanMap<K, E> extends AbstractBeanCollection<E> implements Ma
   @Override
   public Collection<E> values() {
     init();
-    if (readOnly) {
-      return Collections.unmodifiableCollection(map.values());
-    }
     return modifyListening ? new ModifyCollection<>(this, map.values()) : map.values();
   }
-
-  @Override
-  public BeanCollection<E> shallowCopy() {
-    BeanMap<K, E> copy = new BeanMap<>(new LinkedHashMap<>(map));
-    copy.setFromOriginal(this);
-    return copy;
-  }
 }

ebean-api/src/main/java/io/ebean/common/BeanSet.java

@@ -3,10 +3,7 @@ package io.ebean.common;
 import io.ebean.bean.*;
 
 import java.io.Serializable;
-import java.util.Collection;
-import java.util.Iterator;
-import java.util.LinkedHashSet;
-import java.util.Set;
+import java.util.*;
 
 /**
  * Set capable of lazy loading and modification aware.
@@ -38,6 +35,11 @@ public final class BeanSet<E> extends AbstractBeanCollection<E> implements Set<E
     super(loader, ownerBean, propertyName);
   }
 
+  @Override
+  public Set<E> freeze() {
+    return set == null ? null : Collections.unmodifiableSet(set);
+  }
+
   @Override
   public void toString(ToStringBuilder builder) {
     builder.addCollection(set);
@@ -211,7 +213,6 @@ public final class BeanSet<E> extends AbstractBeanCollection<E> implements Set<E
 
   @Override
   public boolean add(E bean) {
-    checkReadOnly();
     init();
     if (modifyListening) {
       if (set.add(bean)) {
@@ -226,7 +227,6 @@ public final class BeanSet<E> extends AbstractBeanCollection<E> implements Set<E
 
   @Override
   public boolean addAll(Collection<? extends E> beans) {
-    checkReadOnly();
     init();
     if (modifyListening) {
       boolean changed = false;
@@ -244,7 +244,6 @@ public final class BeanSet<E> extends AbstractBeanCollection<E> implements Set<E
 
   @Override
   public void clear() {
-    checkReadOnly();
     initClear();
     if (modifyListening) {
       for (E bean : set) {
@@ -275,9 +274,6 @@ public final class BeanSet<E> extends AbstractBeanCollection<E> implements Set<E
   @Override
   public Iterator<E> iterator() {
     init();
-    if (readOnly) {
-      return new ReadOnlyIterator<>(set.iterator());
-    }
     if (modifyListening) {
       return new ModifyIterator<>(this, set.iterator());
     }
@@ -286,7 +282,6 @@ public final class BeanSet<E> extends AbstractBeanCollection<E> implements Set<E
 
   @Override
   public boolean remove(Object bean) {
-    checkReadOnly();
     init();
     if (modifyListening) {
       if (set.remove(bean)) {
@@ -300,7 +295,6 @@ public final class BeanSet<E> extends AbstractBeanCollection<E> implements Set<E
 
   @Override
   public boolean removeAll(Collection<?> beans) {
-    checkReadOnly();
     init();
     if (modifyListening) {
       boolean changed = false;
@@ -317,7 +311,6 @@ public final class BeanSet<E> extends AbstractBeanCollection<E> implements Set<E
 
   @Override
   public boolean retainAll(Collection<?> beans) {
-    checkReadOnly();
     init();
     if (modifyListening) {
       boolean changed = false;
@@ -355,36 +348,4 @@ public final class BeanSet<E> extends AbstractBeanCollection<E> implements Set<E
     return set.toArray(array);
   }
 
-  private static final class ReadOnlyIterator<E> implements Iterator<E>, Serializable {
-
-    private static final long serialVersionUID = 2577697326745352605L;
-
-    private final Iterator<E> it;
-
-    ReadOnlyIterator(Iterator<E> it) {
-      this.it = it;
-    }
-
-    @Override
-    public boolean hasNext() {
-      return it.hasNext();
-    }
-
-    @Override
-    public E next() {
-      return it.next();
-    }
-
-    @Override
-    public void remove() {
-      throw new IllegalStateException("This collection is in ReadOnly mode");
-    }
-  }
-
-  @Override
-  public BeanCollection<E> shallowCopy() {
-    BeanSet<E> copy = new BeanSet<>(new LinkedHashSet<>(set));
-    copy.setFromOriginal(this);
-    return copy;
-  }
 }

ebean-api/src/main/java/io/ebean/common/CopyOnFirstWriteList.java

@@ -1,185 +0,0 @@
-package io.ebean.common;
-
-import java.io.Serializable;
-import java.util.AbstractList;
-import java.util.ArrayList;
-import java.util.Collection;
-import java.util.Comparator;
-import java.util.List;
-import java.util.concurrent.locks.ReentrantLock;
-import java.util.function.Predicate;
-import java.util.function.UnaryOperator;
-
-/**
- * List that copies itself on first write access. Needed to keep memory footprint low and the ability
- * to modify lists from cache.
- *
- * @author Roland Praml, FOCONIS AG
- */
-public final class CopyOnFirstWriteList<E> extends AbstractList<E> implements List<E>, Serializable {
-
-  private static final long serialVersionUID = 1L;
-
-  private final ReentrantLock lock = new ReentrantLock();
-
-  /**
-   * The underlying List implementation.
-   */
-  private List<E> list;
-
-  public CopyOnFirstWriteList(List<E> list) {
-    super();
-    this.list = list;
-  }
-
-  private volatile boolean copied = false;
-
-  @Override
-  public int size() {
-    return list.size();
-  }
-
-  @Override
-  public boolean isEmpty() {
-    return list.isEmpty();
-  }
-
-  @Override
-  public boolean contains(Object o) {
-    return list.contains(o);
-  }
-
-  @Override
-  public Object[] toArray() {
-    return list.toArray();
-  }
-
-  @Override
-  public <T> T[] toArray(T[] a) {
-    return list.toArray(a);
-  }
-
-  @Override
-  public boolean add(E e) {
-    checkCopyOnWrite();
-    return list.add(e);
-  }
-
-  @Override
-  public boolean remove(Object o) {
-    checkCopyOnWrite();
-    return list.remove(o);
-  }
-
-  @Override
-  public boolean containsAll(Collection<?> c) {
-    return list.containsAll(c);
-  }
-
-  @Override
-  public boolean addAll(Collection<? extends E> c) {
-    checkCopyOnWrite();
-    return list.addAll(c);
-  }
-
-  @Override
-  public boolean addAll(int index, Collection<? extends E> c) {
-    checkCopyOnWrite();
-    return list.addAll(index, c);
-  }
-
-  @Override
-  public boolean removeAll(Collection<?> c) {
-    checkCopyOnWrite();
-    return list.removeAll(c);
-  }
-
-  @Override
-  public boolean retainAll(Collection<?> c) {
-    checkCopyOnWrite();
-    return list.retainAll(c);
-  }
-
-  @Override
-  public void replaceAll(UnaryOperator<E> operator) {
-    checkCopyOnWrite();
-    list.replaceAll(operator);
-  }
-
-  @Override
-  public boolean removeIf(Predicate<? super E> filter) {
-    checkCopyOnWrite();
-    return list.removeIf(filter);
-  }
-
-  @Override
-  public void sort(Comparator<? super E> c) {
-    checkCopyOnWrite();
-    list.sort(c);
-  }
-
-  @Override
-  public void clear() {
-    if (!copied) {
-      list = new ArrayList<>();
-      copied = true;
-    }
-  }
-
-  @Override
-  public boolean equals(Object o) {
-    return list.equals(o);
-  }
-
-  @Override
-  public int hashCode() {
-    return list.hashCode();
-  }
-
-  @Override
-  public E get(int index) {
-    return list.get(index);
-  }
-
-  @Override
-  public E set(int index, E element) {
-    checkCopyOnWrite();
-    return list.set(index, element);
-  }
-
-  @Override
-  public void add(int index, E element) {
-    checkCopyOnWrite();
-    list.add(index, element);
-  }
-
-  @Override
-  public E remove(int index) {
-    checkCopyOnWrite();
-    return list.remove(index);
-  }
-
-  @Override
-  public int indexOf(Object o) {
-    return list.indexOf(o);
-  }
-
-  @Override
-  public int lastIndexOf(Object o) {
-    return list.lastIndexOf(o);
-  }
-
-  private void checkCopyOnWrite() {
-    if (!copied) {
-      lock.lock();
-      try {
-        if (!copied) {
-          list = new ArrayList<>(list);
-          copied = true;
-        }
-      } finally {
-        lock.unlock();
-      }
-    }
-  }
-}

ebean-api/src/main/java/io/ebean/config/AggregateFormulaContext.java

@@ -0,0 +1,66 @@
+package io.ebean.config;
+
+import java.util.Set;
+
+/**
+ * Used when parsing formulas to determine if they are aggregation formulas like
+ * sum, min, max, avg, count etc.
+ * <p>
+ * Ebean needs to determine if they are aggregation formulas to determine which
+ * properties should be included in a GROUP BY clause etc.
+ */
+public interface AggregateFormulaContext {
+
+  /**
+   * Return true if the outer function is an aggregate function (like sum, count, min, max, avg etc).
+   */
+  boolean isAggregate(String outerFunction);
+
+  /**
+   * Return true if the aggregate function returns a BIGINT type.
+   * This is true for functions like count that return a numeric value regardless of the
+   * type of the property or expression inside the outer function.
+   */
+  boolean isCount(String outerFunction);
+
+  /**
+   * Return true if the aggregate function returns a VARCHAR type.
+   * This is true for functions that return a string concatenation like group_concat etc
+   * regardless of the type of the property used inside the outer function.
+   */
+  boolean isConcat(String outerFunction);
+
+  /**
+   * Return a builder for the AggregateFormulaContext.
+   */
+  static Builder builder() {
+    return new AggregateFormulaContextBuilder();
+  }
+
+  /**
+   * A builder for the AggregateFormulaContext.
+   */
+  interface Builder {
+
+    /**
+     * Override the default set of aggregation functions.
+     */
+    Builder aggregateFunctions(Set<String> count);
+
+    /**
+     * Override the default set of concat functions.
+     */
+    Builder concatFunctions(Set<String> concat);
+
+    /**
+     * Override the default set of count functions.
+     */
+    Builder countFunctions(Set<String> count);
+
+    /**
+     * Build the AggregateFormulaContext.
+     */
+    AggregateFormulaContext build();
+  }
+
+}

ebean-api/src/main/java/io/ebean/config/AggregateFormulaContextBuilder.java

@@ -0,0 +1,61 @@
+package io.ebean.config;
+
+import java.util.Set;
+
+final class AggregateFormulaContextBuilder implements AggregateFormulaContext.Builder {
+
+  private Set<String> aggFunctions = Set.of("count", "max", "min", "avg", "sum", "group_concat", "string_agg", "listagg");
+  private Set<String> concat = Set.of("concat", "group_concat", "string_agg", "listagg");
+  private Set<String> count = Set.of("count");
+
+  @Override
+  public AggregateFormulaContext.Builder aggregateFunctions(Set<String> agg) {
+    this.aggFunctions = agg;
+    return this;
+  }
+
+  @Override
+  public AggregateFormulaContext.Builder concatFunctions(Set<String> concat) {
+    this.concat = concat;
+    return this;
+  }
+
+  @Override
+  public AggregateFormulaContext.Builder countFunctions(Set<String> count) {
+    this.count = count;
+    return this;
+  }
+
+  @Override
+  public AggregateFormulaContext build() {
+    return new FormulaContext(aggFunctions, concat, count);
+  }
+
+  private static final class FormulaContext implements AggregateFormulaContext {
+
+    private final Set<String> aggFunctions;
+    private final Set<String> concat;
+    private final Set<String> count;
+
+    private FormulaContext(Set<String> aggFunctions, Set<String> concat, Set<String> count) {
+      this.aggFunctions = aggFunctions;
+      this.concat = concat;
+      this.count = count;
+    }
+
+    @Override
+    public boolean isAggregate(String outerFunction) {
+      return aggFunctions.contains(outerFunction);
+    }
+
+    @Override
+    public boolean isCount(String outerFunction) {
+      return count.contains(outerFunction);
+    }
+
+    @Override
+    public boolean isConcat(String outerFunction) {
+      return concat.contains(outerFunction);
+    }
+  }
+}

ebean-api/src/main/java/io/ebean/config/ClassLoadConfig.java

@@ -1,5 +1,7 @@
 package io.ebean.config;
 
+import io.ebean.plugin.Lookups;
+
 /**
  * Helper to find classes taking into account the context class loader.
  */
@@ -73,9 +75,8 @@ public class ClassLoadConfig {
    */
   public Object newInstance(String className) {
     try {
-      Class<?> cls = forName(className);
-      return cls.getDeclaredConstructor().newInstance();
-    } catch (Exception e) {
+      return Lookups.newDefaultInstance(forName(className));
+    } catch (Throwable e) {
       throw new IllegalArgumentException("Error constructing " + className, e);
     }
   }

ebean-api/src/main/java/io/ebean/config/DatabaseConfig.java

@@ -129,7 +129,7 @@ public class DatabaseConfig implements DatabaseBuilder.Settings {
    * When true then include a sql comment in generated SELECT queries with the query
    * label or profile location label.
    */
-  private boolean includeLabelInSql;
+  private boolean includeLabelInSql = true;
 
   /**
    * Interesting classes such as entities, embedded, ScalarTypes,
@@ -251,7 +251,7 @@ public class DatabaseConfig implements DatabaseBuilder.Settings {
   /**
    * The default batch size for lazy loading
    */
-  private int lazyLoadBatchSize = 10;
+  private int lazyLoadBatchSize = 100;
 
   /**
    * The default batch size for 'query joins'.
@@ -311,6 +311,7 @@ public class DatabaseConfig implements DatabaseBuilder.Settings {
   private boolean skipDataSourceCheck;
 
   private boolean readOnlyDatabase;
+  private boolean shutdownHook = true;
 
   /**
    * The data source (if programmatically provided).
@@ -355,6 +356,8 @@ public class DatabaseConfig implements DatabaseBuilder.Settings {
    */
   private NamingConvention namingConvention = new UnderscoreNamingConvention();
 
+  private AggregateFormulaContext aggregateFormulaContext = AggregateFormulaContext.builder().build();
+
   /**
    * Behaviour of updates in JDBC batch to by default include all properties.
    */
@@ -481,6 +484,7 @@ public class DatabaseConfig implements DatabaseBuilder.Settings {
    * Time to live for query plans - defaults to 5 minutes.
    */
   private int queryPlanTTLSeconds = 60 * 5;
+  private String queryPlanExplain;
 
   /**
    * Set to true to globally disable L2 caching (typically for performance testing).
@@ -1277,6 +1281,17 @@ public class DatabaseConfig implements DatabaseBuilder.Settings {
     return this;
   }
 
+  @Override
+  public AggregateFormulaContext aggregateFormulaContext() {
+    return aggregateFormulaContext;
+  }
+
+  @Override
+  public DatabaseConfig aggregateFormulaContext(AggregateFormulaContext aggregateFormulaContext) {
+    this.aggregateFormulaContext = aggregateFormulaContext;
+    return this;
+  }
+
   @Override
   public boolean isAllQuotedIdentifiers() {
     return platformConfig.isAllQuotedIdentifiers();
@@ -1364,6 +1379,17 @@ public class DatabaseConfig implements DatabaseBuilder.Settings {
     return readOnlyDatabase;
   }
 
+  @Override
+  public DatabaseBuilder shutdownHook(boolean shutdownHook) {
+    this.shutdownHook = shutdownHook;
+    return this;
+  }
+
+  @Override
+  public boolean shutdownHook() {
+    return shutdownHook;
+  }
+
   @Override
   public DataSource getDataSource() {
     return dataSource;
@@ -2136,6 +2162,7 @@ public class DatabaseConfig implements DatabaseBuilder.Settings {
     loadDocStoreSettings(p);
 
     defaultServer = p.getBoolean("defaultServer", defaultServer);
+    shutdownHook = p.getBoolean("shutdownHook", shutdownHook);
     readOnlyDatabase = p.getBoolean("readOnlyDatabase", readOnlyDatabase);
     autoPersistUpdates = p.getBoolean("autoPersistUpdates", autoPersistUpdates);
     loadModuleInfo = p.getBoolean("loadModuleInfo", loadModuleInfo);
@@ -2151,6 +2178,7 @@ public class DatabaseConfig implements DatabaseBuilder.Settings {
     queryPlanCapturePeriodSecs = p.getLong("queryPlan.capturePeriodSecs", queryPlanCapturePeriodSecs);
     queryPlanCaptureMaxTimeMillis = p.getLong("queryPlan.captureMaxTimeMillis", queryPlanCaptureMaxTimeMillis);
     queryPlanCaptureMaxCount = p.getInt("queryPlan.captureMaxCount", queryPlanCaptureMaxCount);
+    queryPlanExplain = p.get("queryPlan.explain", queryPlanExplain);
     docStoreOnly = p.getBoolean("docStoreOnly", docStoreOnly);
     disableL2Cache = p.getBoolean("disableL2Cache", disableL2Cache);
     localOnlyL2Cache = p.getBoolean("localOnlyL2Cache", localOnlyL2Cache);
@@ -2402,6 +2430,17 @@ public class DatabaseConfig implements DatabaseBuilder.Settings {
     return queryPlanTTLSeconds;
   }
 
+  @Override
+  public String getQueryPlanExplain() {
+    return queryPlanExplain;
+  }
+
+  @Override
+  public DatabaseBuilder queryPlanExplain(String queryPlanExplain) {
+    this.queryPlanExplain = queryPlanExplain;
+    return this;
+  }
+
   @Override
   public DatabaseConfig setQueryPlanTTLSeconds(int queryPlanTTLSeconds) {
     this.queryPlanTTLSeconds = queryPlanTTLSeconds;

ebean-api/src/main/java/io/ebean/config/LookupProvider.java

@@ -0,0 +1,15 @@
+package io.ebean.config;
+
+import java.lang.invoke.MethodHandles.Lookup;
+
+/**
+ * Provides a Lookup instance for accessing entity/dto fields.
+ */
+public interface LookupProvider {
+
+  /**
+   * Return the Lookup.
+   */
+  Lookup provideLookup();
+
+}