Version 16.5.0

Update ebean-agent
Bump ebean-datasource dependency to 10.5 with increase default prepared statement cache (#3749 )
2026-09-20 11:17:36 +00:00 · 2026-04-12 22:31:24 +12:00 · 2026-04-12 22:27:52 +12:00 · 2026-04-12 22:27:02 +12:00 · 2026-04-12 17:21:04 +12:00 · 2026-04-12 17:20:45 +12:00
472 changed files with 9692 additions and 2795 deletions
@@ -2,6 +2,7 @@
 name: Build

 on:
+  workflow_dispatch:
  pull_request:
  push:
    branches: master
@@ -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

@@ -16,7 +16,7 @@ jobs:
    strategy:
      fail-fast: false
      matrix:
-        java_version: [GA,EA,23]
+        java_version: [GA,EA]
        os: [ubuntu-latest]

    steps:
@@ -37,5 +37,5 @@ jobs:
    - name: Maven version
      run: mvn --version
    - name: Build with Maven
-      run: mvn -T 8 test
+      run: mvn test -Pea

@@ -34,5 +34,5 @@ jobs:
        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
@@ -34,5 +34,5 @@ jobs:
        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
@@ -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)
@@ -59,11 +60,6 @@ Work at the highest level of abstraction and drop down levels as needed.
          <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">
-        <a href="https://www.payintech.com/" target="_blank">
-          <img width="222px" src="https://ebean.io/images/sponsor_PayinTech-logo-noir.png">
-        </a>
-      </td>
      <td align="center" valign="middle">
        <a href="https://www.premium-minds.com" target="_blank">
          <img width="222px" src="https://ebean.io/images/logo-med-principal.png">
@@ -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)

@@ -4,7 +4,7 @@
  <parent>
    <artifactId>ebean-parent</artifactId>
    <groupId>io.ebean</groupId>
-    <version>14.9.0</version>
+    <version>16.5.0</version>
    <relativePath>../..</relativePath>
  </parent>

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

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-core</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

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

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-clickhouse</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

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

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

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-core</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

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

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-postgres</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

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

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

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-core</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

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

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-db2</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

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

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

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-core</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

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

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-h2</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

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

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

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-core</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

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

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-hana</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

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

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

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-core</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

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

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-mariadb</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

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

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

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-core</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

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

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-mysql</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

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

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

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-core</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

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

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-postgres</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-net-postgis-types</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

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

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

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-core</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

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

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-nuodb</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

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

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

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-core</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

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

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-oracle</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

  </dependencies>
@@ -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>
@@ -0,0 +1,7 @@
+package io.ebean.pgvector.assembly;
+
+/**
+ * Nothing interesting here - required placeholder for javadoc.
+ */
+public class Assembly {
+}
@@ -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;
+
+}
@@ -4,7 +4,7 @@
  <parent>
    <artifactId>ebean-parent</artifactId>
    <groupId>io.ebean</groupId>
-    <version>14.9.0</version>
+    <version>16.5.0</version>
    <relativePath>../..</relativePath>
  </parent>

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

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-core</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

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

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-postgres</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-postgis-types</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

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

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

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-core</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

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

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-postgres</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

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

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

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-core</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

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

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-sqlite</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

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

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

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-core</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

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

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-sqlserver</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

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

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

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-core</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

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

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-postgres</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

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

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

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-core</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

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

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

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-all</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

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

  <artifactId>composites</artifactId>
@@ -25,6 +25,7 @@
    <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>
@@ -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/
+```
@@ -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 |
@@ -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 |
@@ -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`).
@@ -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.
@@ -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`**
@@ -4,7 +4,7 @@
  <parent>
    <artifactId>ebean-parent</artifactId>
    <groupId>io.ebean</groupId>
-    <version>14.9.0</version>
+    <version>16.5.0</version>
  </parent>

  <name>ebean api</name>
@@ -35,7 +35,7 @@
    <dependency>
      <groupId>io.avaje</groupId>
      <artifactId>avaje-config</artifactId>
-      <version>3.12</version>
+      <version>4.2</version>
    </dependency>

    <dependency>
@@ -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);
+  }
+}
@@ -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
@@ -137,6 +137,7 @@ public interface Database {
  /**
   * Return the associated read only DataSource for this Database instance (can be null).
   */
+  @Nullable
  DataSource readOnlyDataSource();

  /**
@@ -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>
@@ -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.
   */
@@ -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.
     */
@@ -234,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);
+
 }
@@ -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);
-
-}
@@ -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;
+
+}
@@ -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);
+  }
+}
@@ -16,4 +16,7 @@ public interface ModifyAwareType {
   */
  void setMarkedDirty(boolean markedDirty);

+  default Object freeze() {
+    return this; // throw new UnsupportedOperationException();
+  }
 }
@@ -1,6 +1,7 @@
 package io.ebean;

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

 /**
 * Object relational query for finding a List, Set, Map or single entity bean.
@@ -310,6 +311,7 @@ public interface Query<T> extends CancelableQuery, QueryBuilder<Query<T>, T> {
  /**
   * Return the Id value.
   */
+  @Nullable
  Object getId();

  /**
@@ -446,11 +448,13 @@ public interface Query<T> extends CancelableQuery, QueryBuilder<Query<T>, T> {
  /**
   * Return the "for update" wait mode to use.
   */
+  @Nullable
  LockWait getForUpdateLockWait();

  /**
   * Return the lock type (strength) to use with "for update".
   */
+  @Nullable
  LockType getForUpdateLockType();

  /**
@@ -135,7 +135,17 @@ public interface QueryBuilder<SELF extends QueryBuilder<SELF, T>, T> extends Que
   * source. We we use {@code usingMaster()} to instead ensure that the query is executed
   * against the master data source.
   */
-  SELF usingMaster();
+  default SELF usingMaster() {
+    return usingMaster(true);
+  }
+
+  /**
+   * Ensure the master DataSource is used when useMaster is true. Otherwise, the read only
+   * data source can be used if defined.
+   *
+   * @see #usingMaster()
+   */
+  SELF usingMaster(boolean useMaster);

  /**
   * Set the base table to use for this query.
@@ -388,9 +398,19 @@ public interface QueryBuilder<SELF extends QueryBuilder<SELF, T>, T> extends Que
  SELF setUseDocStore(boolean useDocStore);

  /**
-   * When set to true when you want the returned beans to be read only.
+   * When set to true when you want the returned beans to be unmodifiable read only.
+   * <p>
+   * This means that the returning graph can't be mutated via setters, all the collections
+   * are unmodifiable collections, lazy loading is disabled and that the query uses
+   * {@link PersistenceContextScope#QUERY}.
+   * <p>
+   * Attempting to mutate an unmodifiable bean will throw a <code>UnmodifiableEntityException</code>.
+   * Attempting to load an unloaded property will throw a <code>LazyInitialisationException</code>
+   *
+   * @see LazyInitialisationException
+   * @see UnmodifiableEntityException
   */
-  SELF setReadOnly(boolean readOnly);
+  SELF setUnmodifiable(boolean unmodifiable);

  /**
   * Set a timeout on this query.
@@ -437,6 +457,16 @@ public interface QueryBuilder<SELF extends QueryBuilder<SELF, T>, T> extends Que

  /**
   * Set the {@link CacheMode} to use the query for executing this query.
+   * <p>
+   * Since version 16.x using the query bean will set the query to use unmodifiable (see
+   * {@link #setUnmodifiable(boolean)}) so the returned object graph is unmodifiable
+   * and safe to cache by the application.
+   * <p>
+   * Attempting to mutate an unmodifiable bean will throw a <code>UnmodifiableEntityException</code>.
+   * Attempting to load an unloaded property will throw a <code>LazyInitialisationException</code>
+   *
+   * @see LazyInitialisationException
+   * @see UnmodifiableEntityException
   */
  SELF setUseQueryCache(CacheMode cacheMode);

@@ -952,6 +982,16 @@ public interface QueryBuilder<SELF extends QueryBuilder<SELF, T>, T> extends Que
   */
  FutureList<T> findFutureList();

+  /**
+   * Execute find map query in a background thread.
+   * <p>
+   * This query will execute in it's own PersistenceContext and using its own transaction.
+   * What that means is that it will not share any bean instances with other queries.
+   *
+   * @return a Future object for the map result of the query
+   */
+  <K> FutureMap<K,T> findFutureMap();
+
  /**
   * Return a PagedList for this query using firstRow and maxRows.
   * <p>
@@ -63,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.
@@ -357,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.
     */
@@ -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);
+  }
+}
@@ -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();
 }
@@ -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();
 }
@@ -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;
+  }
+}
@@ -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
@@ -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);
@@ -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;
  }
 }
@@ -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;
-  }
 }
@@ -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;
-  }
 }
@@ -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;
-  }
 }
@@ -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;
-  }
 }
@@ -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();
-      }
-    }
-  }
-}
@@ -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();
+  }
+
+}
@@ -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);
+    }
+  }
+}
@@ -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;
@@ -167,6 +167,7 @@ public class DatabasePlatform {
   * findIterate() and findVisit().
   */
  protected boolean forwardOnlyHintOnFindIterate;
+  protected boolean autoCommitFalseOnFindIterate;

  /**
   * If set then use the CONCUR_UPDATABLE hint when creating ResultSets.
@@ -528,6 +529,10 @@ public class DatabasePlatform {
    this.forwardOnlyHintOnFindIterate = forwardOnlyHintOnFindIterate;
  }

+  public boolean autoCommitFalseOnFindIterate() {
+    return autoCommitFalseOnFindIterate;
+  }
+
  /**
   * Return true if the ResultSet CONCUR_UPDATABLE Hint should be used on
   * createNativeSqlTree() PreparedStatements.
@@ -780,4 +785,5 @@ public class DatabasePlatform {
  public String inlineSqlHint(String hint) {
    return "/*+ " + hint + " */ ";
  }
+
 }
@@ -172,7 +172,6 @@ public class DbPlatformType implements ExtraDbTypes {
   * </p>
   */
  public String renderType(int deployLength, int deployScale, boolean strict) {
-
    int len = deployLength != 0 ? deployLength : defaultLength;
    if (len > maxLength) {
      return fallback.renderType(deployLength, deployScale, strict);
@@ -182,7 +181,6 @@ public class DbPlatformType implements ExtraDbTypes {
      if ((canHaveLength || !strict) && len > 0) {
        renderLengthScale(len, deployScale, sb);
      }
-
      return sb.toString();
    }
  }
@@ -46,6 +46,18 @@ public class DbPlatformTypeMapping {
  private static final DbPlatformType MULTILINESTRING = new DbPlatformType("multilinestring");
  private static final DbPlatformType MULTIPOLYGON = new DbPlatformType("multipolygon");

+  private static final DbPlatformType VECTOR = new DbPlatformType("vector", 2000, null);
+  private static final DbPlatformType VECTOR_HALF = new DbPlatformType("halfvec", 4000, null);
+  private static final DbPlatformType VECTOR_BIT = new DbPlatformType("bit", 64000, null);
+  private static final DbPlatformType VECTOR_SPARSE = new DbPlatformType("sparsevec", 1000, null);
+
+  /**
+   * Timestamp with max precision of 15, and fallback to plain timestamp without precision defined.
+   */
+  private static final DbPlatformType TIMESTAMP =
+    new DbPlatformType("timestamp", 0, 15,
+      new DbPlatformType("timestamp", false));
+
  private final Map<DbType, DbPlatformType> typeMap = new EnumMap<>(DbType.class);

  /**
@@ -82,7 +94,8 @@ public class DbPlatformTypeMapping {
    put(DbType.ARRAY);
    put(DbType.DATE);
    put(DbType.TIME);
-    put(DbType.TIMESTAMP);
+    put(DbType.TIMESTAMP, TIMESTAMP);
+
    put(DbType.LONGVARBINARY);
    put(DbType.LONGVARCHAR);
    // most commonly real maps to db float
@@ -93,6 +106,10 @@ public class DbPlatformTypeMapping {
    put(DbType.MULTIPOINT, MULTIPOINT);
    put(DbType.MULTILINESTRING, MULTILINESTRING);
    put(DbType.MULTIPOLYGON, MULTIPOLYGON);
+    put(DbType.VECTOR, VECTOR);
+    put(DbType.VECTOR_HALF, VECTOR_HALF);
+    put(DbType.VECTOR_BIT, VECTOR_BIT);
+    put(DbType.VECTOR_SPARSE, VECTOR_SPARSE);

    if (logicalTypes) {
      // keep it logical for 2 layer DDL generation
@@ -51,7 +51,12 @@ public enum DbType {
  JSONB(ExtraDbTypes.JSONB),
  JSONCLOB(ExtraDbTypes.JSONClob),
  JSONBLOB(ExtraDbTypes.JSONBlob),
-  JSONVARCHAR(ExtraDbTypes.JSONVarchar);
+  JSONVARCHAR(ExtraDbTypes.JSONVarchar),
+
+  VECTOR(ExtraDbTypes.VECTOR),
+  VECTOR_HALF(ExtraDbTypes.VECTOR_HALF),
+  VECTOR_BIT(ExtraDbTypes.VECTOR_BIT),
+  VECTOR_SPARSE(ExtraDbTypes.VECTOR_SPARSE);

  private final int id;

@@ -74,4 +74,24 @@ public interface ExtraDbTypes {
   */
  int MULTILINESTRING = 6007;

+  /**
+   * PGVector base type
+   */
+  int VECTOR = 7000;
+
+  /**
+   * PGVector half precision float type
+   */
+  int VECTOR_HALF = 7001;
+
+  /**
+   * PGVector binary type (bit)
+   */
+  int VECTOR_BIT = 7002;
+
+  /**
+   * PGVector sparse type
+   */
+  int VECTOR_SPARSE = 7003;
+
 }
@@ -157,7 +157,7 @@ public abstract class SequenceIdGenerator implements PlatformIdGenerator {
      if (newIds.isEmpty()) {
        throw new PersistenceException("Always expecting more than 1 row from " + sql);
      }
-
+      connection.commit();
      return newIds;

    } catch (SQLException e) {
@@ -97,8 +97,7 @@ public final class ShutdownManager {
  private static void registerShutdownHook() {
    lock.lock();
    try {
-      String value = System.getProperty("ebean.registerShutdownHook");
-      if (value == null || !value.trim().equalsIgnoreCase("false")) {
+      if ("true".equalsIgnoreCase(System.getProperty("ebean.registerShutdownHook", "true"))) {
        Runtime.getRuntime().addShutdownHook(shutdownHook);
      }
    } catch (IllegalStateException ex) {
@@ -1,18 +1,19 @@
 package io.ebean.meta;

-import java.util.HashSet;
-import java.util.Set;
+import java.util.*;
+
+import static java.util.Objects.requireNonNull;

 /**
 * Initiate query plan collection for plans by their hash or all query plans.
 */
 public class QueryPlanInit {

+  private final Map<String,Long> hashes = new HashMap<>();
+
  private boolean all;

-  private Set<String> hashes = new HashSet<>();
-
-  private long thresholdMicros;
+  private long defaultThresholdMicros;

  /**
   * Return true if this initiates bind collection on all query plans.
@@ -29,39 +30,74 @@ public class QueryPlanInit {
  }

  /**
-   * Return the query execution time threshold which must be exceeded to initiate
+   * Return the default query execution time threshold which must be exceeded to initiate
   * query plan collection.
   */
  public long thresholdMicros() {
-    return thresholdMicros;
+    return defaultThresholdMicros;
  }

  /**
-   * Set the query execution time threshold which must be exceeded to initiate
+   * Set the default query execution time threshold which must be exceeded to initiate
   * query plan collection.
   */
  public void thresholdMicros(long thresholdMicros) {
-    this.thresholdMicros = thresholdMicros;
+    this.defaultThresholdMicros = thresholdMicros;
  }

  /**
   * Return true if the query plan should be initiated based on it's hash.
   */
  public boolean includeHash(String hash) {
-    return all || hashes.contains(hash);
+    return all || hashes.containsKey(hash);
  }

  /**
   * Return the specific hashes that we want to collect query plans on.
+   *
+   * @param hash            The hash of the query plan.
+   * @param thresholdMicros The threshold in micros to use.
   */
-  public Set<String> hashes() {
-    return hashes;
+  public void add(String hash, long thresholdMicros) {
+    requireNonNull(hash);
+    if (!"all".equals(hash)) {
+      hashes.put(hash, thresholdMicros);
+    } else {
+      all = true;
+      if (thresholdMicros > 0) {
+        defaultThresholdMicros = thresholdMicros;
+      }
+    }
  }

  /**
-   * Set the specific hashes that we want to collect query plans on.
+   * Remove a hash from this request.
   */
-  public void hashes(Set<String> hashes) {
-    this.hashes = hashes;
+  public void remove(String hash) {
+    hashes.remove(hash);
+  }
+
+  /**
+   * Return the threshold in micros to use for the given hash.
+   */
+  public long thresholdMicros(String hash) {
+    Long threshold = hashes.get(hash);
+    return threshold == null || threshold < 1 ? defaultThresholdMicros : threshold;
+  }
+
+  /**
+   * Return true if there are no registered hashes and not collect <em>All</em> plans.
+   */
+  public boolean isEmpty() {
+    return !all && hashes.isEmpty();
+  }
+
+  @Override
+  public String toString() {
+    return "QueryPlanInit{" +
+      "all=" + all +
+      ", hashes=" + hashes +
+      ", thresholdMicros=" + defaultThresholdMicros +
+      '}';
  }
 }
@@ -0,0 +1,65 @@
+package io.ebean.config;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+import java.util.Set;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class AggregateFormulaContextTest {
+
+  @Test
+  void defaultContext() {
+    var defaultContext = AggregateFormulaContext.builder().build();
+    for (String aggFunction : List.of("count", "max", "min", "avg", "sum", "group_concat", "string_agg", "listagg")) {
+      assertThat(defaultContext.isAggregate(aggFunction)).isTrue();
+    }
+    for (String c : List.of("concat", "group_concat", "string_agg", "listagg")) {
+      assertThat(defaultContext.isConcat(c)).isTrue();
+    }
+    for (String c : List.of("count")) {
+      assertThat(defaultContext.isCount(c)).isTrue();
+    }
+
+    assertThat(defaultContext.isConcat("junk")).isFalse();
+    assertThat(defaultContext.isCount("junk")).isFalse();
+    assertThat(defaultContext.isAggregate("junk")).isFalse();
+  }
+
+  @Test
+  void overrideAggregateFunctions() {
+    AggregateFormulaContext mySum = AggregateFormulaContext.builder()
+      .aggregateFunctions(Set.of("my_sum"))
+      .build();
+
+    assertThat(mySum.isAggregate("my_sum")).isTrue();
+    assertThat(mySum.isAggregate("avg")).isFalse();
+    assertThat(mySum.isCount("count")).isTrue();
+    assertThat(mySum.isConcat("group_concat")).isTrue();
+  }
+
+  @Test
+  void overrideConcatFunctions() {
+    AggregateFormulaContext myConcat = AggregateFormulaContext.builder()
+      .concatFunctions(Set.of("my_concat"))
+      .build();
+
+    assertThat(myConcat.isAggregate("avg")).isTrue();
+    assertThat(myConcat.isCount("count")).isTrue();
+    assertThat(myConcat.isConcat("group_concat")).isFalse();
+    assertThat(myConcat.isConcat("my_concat")).isTrue();
+  }
+
+  @Test
+  void overrideCountFunctions() {
+    AggregateFormulaContext myCount = AggregateFormulaContext.builder()
+      .countFunctions(Set.of("my_count"))
+      .build();
+
+    assertThat(myCount.isAggregate("avg")).isTrue();
+    assertThat(myCount.isCount("count")).isFalse();
+    assertThat(myCount.isCount("my_count")).isTrue();
+    assertThat(myCount.isConcat("group_concat")).isTrue();
+  }
+}
@@ -77,6 +77,9 @@ class DatabaseConfigTest {
    props.setProperty("readOnlyDatabase", "true");
    props.setProperty("lengthCheck", "ON");
    props.setProperty("includeLabelInSql", "false");
+    props.setProperty("lazyLoadBatchSize", "50");
+    props.setProperty("queryBatchSize", "60");
+    props.setProperty("shutdownHook", "false");

    props.setProperty("queryPlan.enable", "true");
    props.setProperty("queryPlan.thresholdMicros", "10000");
@@ -84,6 +87,7 @@ class DatabaseConfigTest {
    props.setProperty("queryPlan.capturePeriodSecs", "42");
    props.setProperty("queryPlan.captureMaxTimeMillis", "560");
    props.setProperty("queryPlan.captureMaxCount", "7");
+    props.setProperty("queryPlan.explain", "explain (verbose)");

    config.loadFromProperties(props);

@@ -97,8 +101,11 @@ class DatabaseConfigTest {
    assertTrue(settings.isLoadModuleInfo());
    assertTrue(settings.skipDataSourceCheck());
    assertTrue(settings.readOnlyDatabase());
+    assertFalse(settings.shutdownHook());
    assertFalse(settings.isIncludeLabelInSql());
    assertThat(settings.getLengthCheck()).isEqualTo(LengthCheck.ON);
+    assertThat(settings.getLazyLoadBatchSize()).isEqualTo(50);
+    assertThat(settings.getQueryBatchSize()).isEqualTo(60);

    assertTrue(settings.isIdGeneratorAutomatic());
    assertFalse(settings.getPlatformConfig().isCaseSensitiveCollation());
@@ -129,15 +136,18 @@ class DatabaseConfigTest {
    assertEquals(42, settings.getQueryPlanCapturePeriodSecs());
    assertEquals(560, settings.getQueryPlanCaptureMaxTimeMillis());
    assertEquals(7, settings.getQueryPlanCaptureMaxCount());
+    assertEquals("explain (verbose)", settings.getQueryPlanExplain());

    assertThat(settings.getMappingLocations()).containsExactly("classpath:/foo","bar");

    config.persistBatch(PersistBatch.NONE)
      .persistBatchOnCascade(PersistBatch.NONE)
      .lengthCheck(LengthCheck.ON)
-      .lengthCheck(LengthCheck.UTF8);
+      .lengthCheck(LengthCheck.UTF8)
+      .queryPlanExplain("explain (buffers)");


+    assertThat(config.settings().getQueryPlanExplain()).isEqualTo("explain (buffers)");
    Properties props1 = new Properties();
    props1.setProperty("ebean.persistBatch", "ALL");
    props1.setProperty("ebean.persistBatchOnCascade", "ALL");
@@ -164,6 +174,7 @@ class DatabaseConfigTest {
    DatabaseBuilder.Settings config = new DatabaseConfig().settings();
    assertTrue(config.isIdGeneratorAutomatic());
    assertTrue(config.isDefaultServer());
+    assertTrue(config.shutdownHook());
    assertFalse(config.isAutoPersistUpdates());
    assertFalse(config.skipDataSourceCheck());

@@ -175,6 +186,8 @@ class DatabaseConfigTest {
    assertTrue(config.getPlatformConfig().isCaseSensitiveCollation());
    assertTrue(config.isAutoLoadModuleInfo());
    assertTrue(config.isLoadModuleInfo());
+    assertThat(config.getLazyLoadBatchSize()).isEqualTo(100);
+    assertThat(config.getQueryBatchSize()).isEqualTo(100);

    assertFalse(config.isQueryPlanEnable());
    assertEquals(Long.MAX_VALUE, config.getQueryPlanThresholdMicros());
@@ -182,9 +195,12 @@ class DatabaseConfigTest {
    assertEquals(600, config.getQueryPlanCapturePeriodSecs());
    assertEquals(10000L, config.getQueryPlanCaptureMaxTimeMillis());
    assertEquals(10, config.getQueryPlanCaptureMaxCount());
+    assertThat(config.getQueryPlanExplain()).isNull();
    assertThat(config.getLengthCheck()).isEqualTo(LengthCheck.OFF);
    assertTrue(config.isIncludeLabelInSql());

+    config.shutdownHook(false);
+    assertFalse(config.shutdownHook());
    config.setLoadModuleInfo(false);
    assertFalse(config.isAutoLoadModuleInfo());
    assertFalse(config.isLoadModuleInfo());
@@ -192,6 +208,10 @@ class DatabaseConfigTest {
    assertTrue(config.isAutoPersistUpdates());
    config.setSkipDataSourceCheck(true);
    assertTrue(config.skipDataSourceCheck());
+    config.lazyLoadBatchSize(20);
+    assertThat(config.getLazyLoadBatchSize()).isEqualTo(20);
+    config.queryBatchSize(30);
+    assertThat(config.getQueryBatchSize()).isEqualTo(30);
  }

  @Test
@@ -0,0 +1,43 @@
+package io.ebean.meta;
+
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class QueryPlanInitTest {
+
+  @Test
+  void initialQueryPlanInit() {
+    var init = new QueryPlanInit();
+    assertThat(init.isEmpty()).isTrue();
+    assertThat(init.isAll()).isFalse();
+    assertThat(init.thresholdMicros()).isEqualTo(0L);
+  }
+
+  @Test
+  void add_all() {
+    var init = new QueryPlanInit();
+    init.add("all", 57L);
+
+    assertThat(init.isEmpty()).isFalse();
+    assertThat(init.isAll()).isTrue();
+    assertThat(init.thresholdMicros()).isEqualTo(57L);
+  }
+
+  @Test
+  void addWithThresholds() {
+    var init = new QueryPlanInit();
+    init.thresholdMicros(1000);
+    init.add("xOne", 0);
+    init.add("xTwo", 2000L);
+
+    assertThat(init.isEmpty()).isFalse();
+    assertThat(init.isAll()).isFalse();
+    assertThat(init.includeHash("xJunk")).isFalse();
+    assertThat(init.includeHash("xOne")).isTrue();
+    assertThat(init.includeHash("xTwo")).isTrue();
+    assertThat(init.thresholdMicros("xJunk")).isEqualTo(1000L);
+    assertThat(init.thresholdMicros("xOne")).isEqualTo(1000L);
+    assertThat(init.thresholdMicros("xTwo")).isEqualTo(2000L);
+  }
+}
@@ -4,7 +4,7 @@
  <parent>
    <artifactId>ebean-parent</artifactId>
    <groupId>io.ebean</groupId>
-    <version>14.9.0</version>
+    <version>16.5.0</version>
  </parent>

  <name>ebean bom</name>
@@ -89,25 +89,25 @@
      <dependency>
        <groupId>io.ebean</groupId>
        <artifactId>ebean</artifactId>
-        <version>14.9.0</version>
+        <version>16.5.0</version>
      </dependency>

      <dependency>
        <groupId>io.ebean</groupId>
        <artifactId>ebean-api</artifactId>
-        <version>14.9.0</version>
+        <version>16.5.0</version>
      </dependency>

      <dependency>
        <groupId>io.ebean</groupId>
        <artifactId>ebean-core</artifactId>
-        <version>14.9.0</version>
+        <version>16.5.0</version>
      </dependency>

      <dependency>
        <groupId>io.ebean</groupId>
        <artifactId>ebean-core-type</artifactId>
-        <version>14.9.0</version>
+        <version>16.5.0</version>
      </dependency>

      <dependency>
@@ -125,13 +125,13 @@
      <dependency>
        <groupId>io.ebean</groupId>
        <artifactId>ebean-jackson-mapper</artifactId>
-        <version>14.9.0</version>
+        <version>16.5.0</version>
      </dependency>

      <dependency>
        <groupId>io.ebean</groupId>
        <artifactId>ebean-ddl-generator</artifactId>
-        <version>14.9.0</version>
+        <version>16.5.0</version>
      </dependency>

      <dependency>
@@ -155,37 +155,37 @@
      <dependency>
        <groupId>io.ebean</groupId>
        <artifactId>ebean-querybean</artifactId>
-        <version>14.9.0</version>
+        <version>16.5.0</version>
      </dependency>

      <dependency>
        <groupId>io.ebean</groupId>
        <artifactId>querybean-generator</artifactId>
-        <version>14.9.0</version>
+        <version>16.5.0</version>
      </dependency>

      <dependency>
        <groupId>io.ebean</groupId>
        <artifactId>kotlin-querybean-generator</artifactId>
-        <version>14.9.0</version>
+        <version>16.5.0</version>
      </dependency>

      <dependency>
        <groupId>io.ebean</groupId>
        <artifactId>ebean-test</artifactId>
-        <version>14.9.0</version>
+        <version>16.5.0</version>
      </dependency>

      <dependency>
        <groupId>io.ebean</groupId>
        <artifactId>ebean-redis</artifactId>
-        <version>14.9.0</version>
+        <version>16.5.0</version>
      </dependency>

      <dependency>
        <groupId>io.ebean</groupId>
        <artifactId>ebean-spring-txn</artifactId>
-        <version>14.9.0</version>
+        <version>16.5.0</version>
      </dependency>

      <!-- platforms -->
@@ -193,79 +193,91 @@
      <dependency>
        <groupId>io.ebean</groupId>
        <artifactId>ebean-clickhouse</artifactId>
-        <version>14.9.0</version>
+        <version>16.5.0</version>
      </dependency>

      <dependency>
        <groupId>io.ebean</groupId>
        <artifactId>ebean-db2</artifactId>
-        <version>14.9.0</version>
+        <version>16.5.0</version>
      </dependency>

      <dependency>
        <groupId>io.ebean</groupId>
        <artifactId>ebean-h2</artifactId>
-        <version>14.9.0</version>
+        <version>16.5.0</version>
      </dependency>

      <dependency>
        <groupId>io.ebean</groupId>
        <artifactId>ebean-hana</artifactId>
-        <version>14.9.0</version>
+        <version>16.5.0</version>
      </dependency>

      <dependency>
        <groupId>io.ebean</groupId>
        <artifactId>ebean-mariadb</artifactId>
-        <version>14.9.0</version>
+        <version>16.5.0</version>
      </dependency>

      <dependency>
        <groupId>io.ebean</groupId>
        <artifactId>ebean-mysql</artifactId>
-        <version>14.9.0</version>
+        <version>16.5.0</version>
      </dependency>

      <dependency>
        <groupId>io.ebean</groupId>
        <artifactId>ebean-nuodb</artifactId>
-        <version>14.9.0</version>
+        <version>16.5.0</version>
      </dependency>

      <dependency>
        <groupId>io.ebean</groupId>
        <artifactId>ebean-oracle</artifactId>
-        <version>14.9.0</version>
+        <version>16.5.0</version>
      </dependency>

      <dependency>
        <groupId>io.ebean</groupId>
        <artifactId>ebean-postgres</artifactId>
-        <version>14.9.0</version>
+        <version>16.5.0</version>
      </dependency>

      <dependency>
        <groupId>io.ebean</groupId>
        <artifactId>ebean-postgis</artifactId>
-        <version>14.9.0</version>
+        <version>16.5.0</version>
      </dependency>

      <dependency>
        <groupId>io.ebean</groupId>
        <artifactId>ebean-postgis-types</artifactId>
-        <version>14.9.0</version>
+        <version>16.5.0</version>
+      </dependency>
+
+      <dependency>
+        <groupId>io.ebean</groupId>
+        <artifactId>ebean-pgvector</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>io.ebean</groupId>
        <artifactId>ebean-sqlite</artifactId>
-        <version>14.9.0</version>
+        <version>16.5.0</version>
      </dependency>

      <dependency>
        <groupId>io.ebean</groupId>
        <artifactId>ebean-sqlserver</artifactId>
-        <version>14.9.0</version>
+        <version>16.5.0</version>
      </dependency>

    </dependencies>
@@ -0,0 +1,32 @@
+<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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <parent>
+    <groupId>io.ebean</groupId>
+    <artifactId>ebean-parent</artifactId>
+    <version>16.5.0</version>
+  </parent>
+  <artifactId>ebean-core-json</artifactId>
+  <name>ebean-core-json</name>
+  <scm>
+    <developerConnection>scm:git:git@github.com:ebean-orm/ebean.git</developerConnection>
+    <tag>HEAD</tag>
+  </scm>
+
+  <dependencies>
+    <dependency>
+      <groupId>io.ebean</groupId>
+      <artifactId>ebean-api</artifactId>
+      <version>16.5.0</version>
+    </dependency>
+
+    <!-- Jackson core used internally by Ebean -->
+    <dependency>
+      <groupId>com.fasterxml.jackson.core</groupId>
+      <artifactId>jackson-core</artifactId>
+      <version>${jackson.version}</version>
+      <optional>true</optional>
+    </dependency>
+
+  </dependencies>
+
+</project>
@@ -8,11 +8,7 @@ import io.ebean.service.SpiJsonService;
 import java.io.IOException;
 import java.io.Reader;
 import java.io.Writer;
-import java.util.Collection;
-import java.util.LinkedHashSet;
-import java.util.List;
-import java.util.Map;
-import java.util.Set;
+import java.util.*;

 /**
 * Utility that converts between JSON content and simple java Maps/Lists.
@@ -52,8 +48,8 @@ public final class DJsonService implements SpiJsonService {
  }

  /**
-   * Parse the json and return as a Map additionally specifying if the returned map should
-   * be modify aware meaning that it can detect when it has been modified.
+   * Parse the json and return as a Map additionally specifying if the returned map should be modify
+   * aware meaning that it can detect when it has been modified.
   */
  @Override
  public Map<String, Object> parseObject(String json, boolean modifyAware) throws IOException {
@@ -94,9 +90,8 @@ public final class DJsonService implements SpiJsonService {

  /**
   * Parse the json and return as a Map taking a JsonParser and a starting token.
-   * <p>
-   * Used when the first token is checked to see if the value is null prior to calling this.
-   * </p>
+   *
+   * <p>Used when the first token is checked to see if the value is null prior to calling this.
   */
  @Override
  public Map<String, Object> parseObject(JsonParser parser, JsonToken token) throws IOException {
@@ -8,15 +8,23 @@ import io.ebean.ModifyAwareType;
 import java.io.IOException;
 import java.io.Reader;
 import java.io.StringReader;
-import java.util.ArrayList;
-import java.util.LinkedHashMap;
-import java.util.List;
-import java.util.Map;
-import java.util.NoSuchElementException;
+import java.util.*;

 final class EJsonReader {

  static final JsonFactory json = new JsonFactory();
+  private final JsonParser parser;
+  private final boolean modifyAware;
+  private final ModifyAwareFlag modifyAwareOwner;
+  private int depth;
+  private Stack stack;
+  private Context currentContext;
+
+  EJsonReader(JsonParser parser, boolean modifyAware) {
+    this.parser = parser;
+    this.modifyAware = modifyAware;
+    this.modifyAwareOwner = modifyAware ? new ModifyAwareFlag() : null;
+  }

  @SuppressWarnings("unchecked")
  static Map<String, Object> parseObject(String json, boolean modifyAware) throws IOException {
@@ -102,24 +110,6 @@ final class EJsonReader {
    return new EJsonReader(parser, modifyAware).parseJson(token);
  }

-  private final JsonParser parser;
-
-  private final boolean modifyAware;
-
-  private final ModifyAwareFlag modifyAwareOwner;
-
-  private int depth;
-
-  private Stack stack;
-
-  private Context currentContext;
-
-  EJsonReader(JsonParser parser, boolean modifyAware) {
-    this.parser = parser;
-    this.modifyAware = modifyAware;
-    this.modifyAwareOwner = (modifyAware) ? new ModifyAwareFlag() : null;
-  }
-
  private void startArray() {
    depth++;
    stack.push(currentContext);
@@ -197,7 +187,6 @@ final class EJsonReader {
   */
  private void processJsonToken(JsonToken token) throws IOException {
    switch (token) {
-
      case START_ARRAY:
        startArray();
        break;
@@ -273,17 +262,17 @@ final class EJsonReader {
    }
  }

-  private static abstract class Context {
+  private abstract static class Context {
    Context next;

    abstract void popContext(Context temp);

    abstract Object getValue();

-    abstract void setKey(String key);
-
    abstract void setValue(Object value);

+    abstract void setKey(String key);
+
    abstract void setValueNull();
  }

@@ -312,13 +301,13 @@ final class EJsonReader {
    }

    @Override
-    void setKey(String key) {
-      this.key = key;
+    void setValue(Object value) {
+      map.put(key, value);
    }

    @Override
-    void setValue(Object value) {
-      map.put(key, value);
+    void setKey(String key) {
+      this.key = key;
    }

    @Override
@@ -364,5 +353,4 @@ final class EJsonReader {
      // not expected
    }
  }
-
 }
@@ -20,6 +20,11 @@ final class EJsonWriter {
   * Base jsonFactory implementation used when it is not passed in.
   */
  static final JsonFactory jsonFactory = new JsonFactory();
+  private final JsonGenerator jsonGenerator;
+
+  private EJsonWriter(JsonGenerator jsonGenerator) {
+    this.jsonGenerator = jsonGenerator;
+  }

  static String write(Object object) throws IOException {
    StringWriter writer = new StringWriter(200);
@@ -42,12 +47,6 @@ final class EJsonWriter {
    new EJsonWriter(jsonGenerator).writeCollection(null, collection);
  }

-  private final JsonGenerator jsonGenerator;
-
-  private EJsonWriter(JsonGenerator jsonGenerator) {
-    this.jsonGenerator = jsonGenerator;
-  }
-
  private void writeJson(Object object) {
    writeJson(null, object);
  }
@@ -210,5 +209,4 @@ final class EJsonWriter {
    }
    jsonGenerator.writeEndObject();
  }
-
 }
@@ -22,5 +22,4 @@ public final class ModifyAwareFlag implements ModifyAwareType, Serializable {
  public void setMarkedDirty(boolean markedDirty) {
    this.markedDirty = markedDirty;
  }
-
 }
@@ -14,9 +14,8 @@ public final class ModifyAwareIterator<E> implements Iterator<E> {

  /**
   * Create with an Owner and the underlying Iterator this wraps.
-   * <p>
-   * The owner is notified of the removals.
-   * </p>
+   *
+   * <p>The owner is notified of the removals.
   */
  public ModifyAwareIterator(ModifyAwareType owner, Iterator<E> it) {
    this.owner = owner;
@@ -38,5 +37,4 @@ public final class ModifyAwareIterator<E> implements Iterator<E> {
    owner.setMarkedDirty(true);
    it.remove();
  }
-
 }
@@ -3,12 +3,7 @@ package io.ebeaninternal.json;
 import io.ebean.ModifyAwareType;

 import java.io.Serializable;
-import java.util.Collection;
-import java.util.Iterator;
-import java.util.LinkedHashSet;
-import java.util.List;
-import java.util.ListIterator;
-import java.util.Objects;
+import java.util.*;

 /**
 * Modify aware wrapper of a list.
@@ -52,6 +47,11 @@ public final class ModifyAwareList<E> implements List<E>, ModifyAwareType, Seria
    return list.hashCode();
  }

+  @Override
+  public List<E> freeze() {
+    return Collections.unmodifiableList(list);
+  }
+
  @Override
  public boolean isMarkedDirty() {
    return owner.isMarkedDirty();
@@ -3,11 +3,7 @@ package io.ebeaninternal.json;
 import io.ebean.ModifyAwareType;

 import java.io.Serializable;
-import java.util.Collection;
-import java.util.LinkedHashSet;
-import java.util.Map;
-import java.util.Objects;
-import java.util.Set;
+import java.util.*;

 /**
 * Map that is wraps an underlying map for the purpose of detecting changes.
@@ -38,11 +34,11 @@ public final class ModifyAwareMap<K, V> implements Map<K, V>, ModifyAwareType, S
  public boolean equals(Object o) {
    if (this == o) return true;
    if (o instanceof ModifyAwareMap) {
-      ModifyAwareMap<?,?> that = (ModifyAwareMap<?,?>) o;
+      ModifyAwareMap<?, ?> that = (ModifyAwareMap<?, ?>) o;
      return Objects.equals(map, that.map);
    }
    if (!(o instanceof Map)) return false;
-    Map<?,?> that = (Map<?,?>) o;
+    Map<?, ?> that = (Map<?, ?>) o;
    return Objects.equals(map, that);
  }

@@ -51,6 +47,11 @@ public final class ModifyAwareMap<K, V> implements Map<K, V>, ModifyAwareType, S
    return map.hashCode();
  }

+  @Override
+  public Map<K, V> freeze() {
+    return Collections.unmodifiableMap(map);
+  }
+
  @Override
  public boolean isMarkedDirty() {
    return owner.isMarkedDirty();
@@ -111,7 +112,6 @@ public final class ModifyAwareMap<K, V> implements Map<K, V>, ModifyAwareType, S
    map.putAll(m);
  }

-
  @Override
  public void clear() {
    if (!map.isEmpty()) {
@@ -134,5 +134,4 @@ public final class ModifyAwareMap<K, V> implements Map<K, V>, ModifyAwareType, S
  public Set<Map.Entry<K, V>> entrySet() {
    return new ModifyAwareSet<>(this, map.entrySet());
  }
-
 }
@@ -3,10 +3,7 @@ package io.ebeaninternal.json;
 import io.ebean.ModifyAwareType;

 import java.io.Serializable;
-import java.util.Collection;
-import java.util.Iterator;
-import java.util.Objects;
-import java.util.Set;
+import java.util.*;

 /**
 * Wraps a Set for the purposes of detecting modifications.
@@ -33,6 +30,11 @@ public final class ModifyAwareSet<E> implements Set<E>, ModifyAwareType, Seriali
    this.set = underlying;
  }

+  @Override
+  public Set<E> freeze() {
+    return Collections.unmodifiableSet(set);
+  }
+
  @Override
  public boolean isMarkedDirty() {
    return owner.isMarkedDirty();
@@ -0,0 +1,9 @@
+module io.ebean.core.json {
+
+  requires io.ebean.api;
+
+  requires transitive com.fasterxml.jackson.core;
+  exports io.ebeaninternal.json to io.ebean.test, io.ebean.core;
+
+  provides io.ebean.service.BootstrapService with io.ebeaninternal.json.DJsonService;
+}
@@ -0,0 +1 @@
+io.ebeaninternal.json.DJsonService
@@ -4,7 +4,7 @@
  <parent>
    <artifactId>ebean-parent</artifactId>
    <groupId>io.ebean</groupId>
-    <version>14.9.0</version>
+    <version>16.5.0</version>
  </parent>

  <artifactId>ebean-core-type</artifactId>
@@ -16,7 +16,7 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-api</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

    <dependency>
@@ -7,6 +7,8 @@ import java.sql.SQLException;

 public interface DataReader {

+  boolean unmodifiable();
+
  void close() throws SQLException;

  boolean next() throws SQLException;
@@ -3,7 +3,7 @@
  <parent>
    <artifactId>ebean-parent</artifactId>
    <groupId>io.ebean</groupId>
-    <version>14.9.0</version>
+    <version>16.5.0</version>
  </parent>

  <artifactId>ebean-core</artifactId>
@@ -22,7 +22,13 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-api</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
+    </dependency>
+
+    <dependency>
+      <groupId>io.ebean</groupId>
+      <artifactId>ebean-core-json</artifactId>
+      <version>16.5.0</version>
    </dependency>

    <dependency>
@@ -46,7 +52,7 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-core-type</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
    </dependency>

    <dependency>
@@ -159,21 +165,21 @@
    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-h2</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
      <scope>test</scope>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-postgres</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
      <scope>test</scope>
    </dependency>

    <dependency>
      <groupId>io.ebean</groupId>
      <artifactId>ebean-platform-sqlserver</artifactId>
-      <version>14.9.0</version>
+      <version>16.5.0</version>
      <scope>test</scope>
    </dependency>

@@ -1,5 +1,6 @@
 package io.ebeaninternal.api;

+import io.ebean.bean.EntityBean;
 import java.util.ArrayList;
 import java.util.List;

@@ -13,10 +14,23 @@ public final class BindValuesKey {

  private final List<Object> values = new ArrayList<>();

+  private final SpiEbeanServer server;
+
+  public BindValuesKey(SpiEbeanServer server) {
+    this.server = server;
+  }
+
  /**
   * Add a bind value.
   */
  public BindValuesKey add(Object value) {
+    if (value instanceof EntityBean) {
+      // only interested in id to keep the memory footprint low
+      Object id = server.beanId(value);
+      if (id != null) {
+        value = id;
+      }
+    }
    values.add(value);
    return this;
  }
@@ -31,5 +45,4 @@ public final class BindValuesKey {
    return values.hashCode();
  }

-
 }
@@ -0,0 +1,10 @@
+package io.ebeaninternal.api;
+
+import io.ebean.config.AggregateFormulaContext;
+import io.ebeaninternal.server.query.STreeProperty;
+
+public interface FormulaBuilder {
+
+  STreeProperty create(AggregateFormulaContext context, String formula, String path);
+
+}
@@ -55,4 +55,9 @@ public interface LoadContext {
   * Use soft-references for streaming queries, so unreachable entries can be garbage collected.
   */
  void useReferences(boolean useReferences);
+
+  /**
+   * Return true to include a many as a secondary query for unmodified.
+   */
+  boolean includeSecondary(BeanPropertyAssocMany<?> many);
 }
@@ -41,7 +41,7 @@ final class NaturalKeyEntryBasic implements NaturalKeyEntry {
   * Create when query uses an IN PAIRS clause.
   */
  NaturalKeyEntryBasic(BeanNaturalKey naturalKey, List<NaturalKeyEq> eqList,
-                        String inMapProperty0, String inMapProperty1, Pairs.Entry pair) {
+                       String inMapProperty0, String inMapProperty1, Pairs.Entry pair) {
    load(eqList);
    map.put(inMapProperty0, pair.getA());
    map.put(inMapProperty1, pair.getB());
@@ -49,6 +49,14 @@ final class NaturalKeyEntryBasic implements NaturalKeyEntry {
    this.key = calculateKey(naturalKey);
  }

+  NaturalKeyEntryBasic(BeanNaturalKey naturalKey, List<NaturalKeyEq> eqList,
+                       Map<String, Object> properties, Object[] naturalKeyValue) {
+    load(eqList);
+    map.putAll(properties);
+    this.inValue = naturalKeyValue;
+    this.key = calculateKey(naturalKey);
+  }
+
  private void load(List<NaturalKeyEq> eqList) {
    if (eqList != null) {
      for (NaturalKeyEq eq : eqList) {
@@ -3,10 +3,7 @@ package io.ebeaninternal.api;
 import io.ebean.Pairs;
 import io.ebeaninternal.server.deploy.BeanNaturalKey;

-import java.util.ArrayList;
-import java.util.HashSet;
-import java.util.List;
-import java.util.Set;
+import java.util.*;

 /**
 * Collects the data for processing the natural key cache processing.
@@ -19,8 +16,9 @@ public final class NaturalKeyQueryData<T> {
   */
  private boolean hasIn;
  // IN Pairs clause - only one allowed
-  private String inProperty0, inProperty1;
  private List<Pairs.Entry> inPairs;
+  private String[] properties;
+  private List<Object[]> inTuples;
  // IN clause - only one allowed
  private List<Object> inValues;
  private String inProperty;
@@ -47,14 +45,39 @@ public final class NaturalKeyQueryData<T> {
    }
    if (matchProperty(property0) && matchProperty(property1)) {
      this.hasIn = true;
-      this.inProperty0 = property0;
-      this.inProperty1 = property1;
+      this.properties = new String[]{property0, property1};
      this.inPairs = new ArrayList<>(inPairs); // will be modified
      return this.inPairs;
    }
    return null;
  }

+  /**
+   * Match for In Tuples expression. We only allow one IN clause.
+   */
+  public List<Object[]> matchInTuples(String[] properties, List<Object[]> inTuples) {
+    if (hasIn) {
+      // only 1 IN allowed (to project naturalIds)
+      return null;
+    }
+
+    boolean matchAll = true;
+
+    for (String property : properties) {
+      if (!matchProperty(property)) {
+        matchAll = false;
+        break;
+      }
+    }
+    if (matchAll) {
+      this.hasIn = true;
+      this.properties = Arrays.copyOf(properties, properties.length);
+      this.inTuples = new ArrayList<>(inTuples);
+      return this.inTuples;
+    }
+    return null;
+  }
+
  /**
   * Match for IN expression. We only allow one IN clause.
   */
@@ -100,6 +123,8 @@ public final class NaturalKeyQueryData<T> {
      addInValues();
    } else if (inPairs != null) {
      addInPairs();
+    } else if (inTuples != null) {
+      addInTuples();
    } else {
      addEqualsKey();
    }
@@ -110,7 +135,17 @@ public final class NaturalKeyQueryData<T> {
    // a findList() with an IN Map clause so we project
    // for every IN value a natural key combination
    for (Pairs.Entry entry : inPairs) {
-      set.add(new NaturalKeyEntryBasic(naturalKey, eqList, inProperty0, inProperty1, entry));
+      set.add(new NaturalKeyEntryBasic(naturalKey, eqList, properties[0], properties[1], entry));
+    }
+  }
+
+  private void addInTuples() {
+    for (Object[] inTuple : inTuples) {
+      Map<String, Object> map = new HashMap<>();
+      for (int i = 0; i < inTuple.length; i++) {
+        map.put(properties[i], inTuple[i]);
+      }
+      set.add(new NaturalKeyEntryBasic(naturalKey, eqList, map, inTuple));
    }
  }

@@ -152,11 +187,8 @@ public final class NaturalKeyQueryData<T> {
    if (inProperty != null) {
      exprProps.add(inProperty);
    }
-    if (inProperty0 != null) {
-      exprProps.add(inProperty0);
-    }
-    if (inProperty1 != null) {
-      exprProps.add(inProperty1);
+    if (properties != null) {
+      exprProps.addAll(Arrays.asList(properties));
    }
    if (eqList != null) {
      for (NaturalKeyEq eq : eqList) {
@@ -173,6 +205,7 @@ public final class NaturalKeyQueryData<T> {
    int defined = (inValues == null) ? 0 : 1;
    defined += (inPairs == null) ? 0 : 2;
    defined += (eqList == null) ? 0 : eqList.size();
+    defined += (inTuples == null) ? 0 : properties.length;
    return defined == naturalKey.length();
  }

@@ -206,6 +239,9 @@ public final class NaturalKeyQueryData<T> {
    } else if (inPairs != null) {
      //noinspection SuspiciousMethodCalls
      inPairs.remove(inValue);
+    } else if (inTuples != null) {
+      //noinspection SuspiciousMethodCalls
+      inTuples.remove(inValue);
    }
  }
 }
@@ -142,6 +142,8 @@ public final class ScopeTrans {
      transaction.commit();
    } else {
      nestedCommit = true;
+      transaction.flush();
+      // restore the batch settings
      transaction.setFlushOnQuery(restoreBatchFlushOnQuery);
      transaction.setBatchMode(restoreBatch);
      transaction.setBatchOnCascade(restoreBatchOnCascade);
@@ -168,7 +168,7 @@ public final class ScopedTransaction extends SpiTransactionProxy {
  /**
   * Maybe rollback based on TxScope rollback on settings.
   */
-  public Exception caughtThrowable(Exception e) {
+  public <T extends Exception> T caughtThrowable(T e) {
    return current.caughtThrowable(e);
  }

@@ -14,4 +14,9 @@ public interface SpiBeanType {
   * or removals from the collection.
   */
  boolean isToManyDirty(EntityBean bean);
+
+  /**
+   * Return the FormulaBuilder for this type.
+   */
+  FormulaBuilder formulaBuilder();
 }
@@ -1,5 +1,6 @@
 package io.ebeaninternal.api;

+import io.ebeaninternal.server.query.STreeProperty;
 import org.jspecify.annotations.Nullable;
 import io.ebean.*;
 import io.ebean.bean.BeanCollectionLoader;
@@ -26,7 +27,7 @@ import java.util.stream.Stream;
 /**
 * Service Provider extension to EbeanServer.
 */
-public interface SpiEbeanServer extends SpiServer, ExtendedServer, BeanCollectionLoader {
+public interface SpiEbeanServer extends SpiServer, BeanCollectionLoader {

  /**
   * Return the NOW time from the Clock.
@@ -348,6 +349,8 @@ public interface SpiEbeanServer extends SpiServer, ExtendedServer, BeanCollectio

  <T> FutureList<T> findFutureList(SpiQuery<T> query);

+  <K, T> FutureMap<K, T> findFutureMap(SpiQuery<T> query);
+
  <T> PagedList<T> findPagedList(SpiQuery<T> query);

  <T> Set<T> findSet(SpiQuery<T> query);
@@ -375,4 +378,6 @@ public interface SpiEbeanServer extends SpiServer, ExtendedServer, BeanCollectio

  @Nullable
  SqlRow findOne(SpiSqlQuery query);
+
+  <T> STreeProperty createFormulaProperty(SpiBeanType desc, String formula, String path);
 }
@@ -780,9 +780,9 @@ public interface SpiQuery<T> extends Query<T>, SpiQueryFetch, TxnProfileEventCod
  CacheMode queryCacheMode();

  /**
-   * Return true if the beans returned by this query should be read only.
+   * Return true if the beans returned by this query should be unmodifiable.
   */
-  Boolean isReadOnly();
+  boolean isUnmodifiable();

  /**
   * Return the query timeout.
@@ -15,8 +15,4 @@ public interface SpiQueryManyJoin {
   */
  String fetchOrderBy();

-  /**
-   * Wrap the filter many expression with a condition allowing lEFT JOIN null matching row.
-   */
-  String idNullOr(String filterManyExpression);
 }
@@ -14,6 +14,7 @@ import io.ebeanservice.docstore.api.DocStoreTransaction;
 import jakarta.persistence.PersistenceException;
 import java.sql.Connection;
 import java.sql.SQLException;
+import java.time.Instant;

 /**
 * Extends Transaction with additional API required on server.
@@ -64,12 +65,12 @@ public interface SpiTransaction extends Transaction {
   * <p>
   * This is to handle bi-directional relationships where both sides Cascade.
   */
-  void registerDeleteBean(Integer hash);
+  void registerDeleteBean(Class<?> type, Object id);

  /**
   * Return true if this is a bean that has already been saved/deleted.
   */
-  boolean isRegisteredDeleteBean(Integer hash);
+  boolean isRegisteredDeleteBean(Class<?> type, Object id);

  /**
   * Unregister the persisted beans. Expected after persisting top level beans
@@ -95,7 +96,7 @@ public interface SpiTransaction extends Transaction {
  /**
   * Return the start timestamp for the transaction (JVM side).
   */
-  long startNanoTime();
+  Instant startTime();

  /**
   * Return true if this transaction has updateAllLoadedProperties set.
@@ -337,11 +338,6 @@ public interface SpiTransaction extends Transaction {
   */
  boolean isNestedUseSavepoint();

-  /**
-   * Return true if explicitly set to skip cache (ignores skipOnWrite).
-   */
-  boolean isSkipCacheExplicit();
-
  /**
   * Fire pre commit processing/listeners.
   */
@@ -361,4 +357,14 @@ public interface SpiTransaction extends Transaction {
   * Set the transaction to be inactive via external transaction manager.
   */
  void deactivateExternal();
+
+  /**
+   * Set autocommit to false for a findIterate query.
+   * <p>
+   * This is done for specific platforms that need it, in order to make
+   * use cursors to stream a large or unbounded query result to the client.
+   */
+  default void setAutoCommitOnFindIterate() {
+    throw new UnsupportedOperationException();
+  }
 }
@@ -14,6 +14,7 @@ import io.ebeanservice.docstore.api.DocStoreTransaction;
 import jakarta.persistence.PersistenceException;
 import java.sql.Connection;
 import java.sql.SQLException;
+import java.time.Instant;

 /**
 * Proxy for an underlying SpiTransaction (most of the API).
@@ -28,8 +29,8 @@ public abstract class SpiTransactionProxy implements SpiTransaction {
  }

  @Override
-  public long startNanoTime() {
-    return transaction.startNanoTime();
+  public Instant startTime() {
+    return transaction.startTime();
  }

  @Override
@@ -168,11 +169,6 @@ public abstract class SpiTransactionProxy implements SpiTransaction {
    transaction.setSkipCache(skipCache);
  }

-  @Override
-  public boolean isSkipCacheExplicit() {
-    return transaction.isSkipCacheExplicit();
-  }
-
  @Override
  public boolean isSkipCache() {
    return transaction.isSkipCache();
@@ -194,13 +190,13 @@ public abstract class SpiTransactionProxy implements SpiTransaction {
  }

  @Override
-  public void registerDeleteBean(Integer hash) {
-    transaction.registerDeleteBean(hash);
+  public void registerDeleteBean(Class<?> type, Object id) {
+    transaction.registerDeleteBean(type, id);
  }

  @Override
-  public boolean isRegisteredDeleteBean(Integer hash) {
-    return transaction.isRegisteredDeleteBean(hash);
+  public boolean isRegisteredDeleteBean(Class<?> type, Object id) {
+    return transaction.isRegisteredDeleteBean(type, id);
  }

  @Override
--- a/Show More
+++ b/Show More