Guides
July 15, 2026 · View on GitHub
See also: AGENTS.md — a minimal template for AI agent onboarding and automation in Ebean ORM projects.
Step-by-step guides written as instructions for AI agents and developers.
For a high-level capability reference (scope, core APIs, and AI guidance), see ../LIBRARY.md.
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 dependencies, the enhancement plugin, and the querybean-generator annotation processor to pom.xml |
| 2 | Test container setup | Start a PostgreSQL (or PostGIS) Docker container for tests using @TestScope @Factory with Avaje Inject; verify the test database works with mvn verify before adding production configuration |
| 3 | Database configuration | Configure the production Ebean Database bean using DataSourceBuilder and DatabaseBuilder with Avaje Inject |
Migration & upgrades
| Guide | Description |
|---|---|
Migrate to Database.builder() | Replace legacy new DatabaseConfig() and DatabaseFactory.create(...) code with Database.builder() and DatabaseBuilder.build(). Includes common rewrites, fluent builder equivalents, and manual-review cases for semi-automated upgrades |
| Migrate JSON APIs from Jackson core to avaje-json-core | Cut over JsonParser/JsonGenerator/JsonFactory usage to JsonReader/JsonWriter/JsonStream, including DatabaseBuilder/DatabaseConfig JSON config changes and validation checklist |
Observability
| Guide | Description |
|---|---|
| Ebean OpenTelemetry tracing | Add ebean-opentelemetry, register GlobalOpenTelemetry once before Ebean databases are built, and troubleshoot missing spans or double-registration errors |
| Ebean query metrics and naming | How Ebean query metric names are derived from setLabel(..) and profile locations; secondary (lazy/query) load naming; inline SQL comments; collecting metrics at runtime; mapping to avaje-metrics tags |
| Ebean query plan capture | Enable and configure database query plan (EXPLAIN) capture for slow queries; bind capture vs plan capture; periodic and on-demand collection; thresholds, load limits, EXPLAIN dialect, and listeners |
Entity beans
| Guide | Description |
|---|---|
| Entity Bean Creation | How to generate clean, idiomatic Ebean entity beans for AI agents; patterns and anti-patterns; field visibility and accessor guidance; minimal boilerplate |
| Lombok with Ebean entity beans | Which Lombok annotations to use and avoid on entity beans; why @Data is incompatible with Ebean; how to use @Getter + @Setter + @Accessors(chain = true) |
@DbJson mapping support (built-in vs Jackson) | Which @DbJson / @DbJsonB property types are handled by the built-in avaje-json-core support versus which require ebean-jackson-mapper (Jackson ObjectMapper); supported String/List/Set/Map matrix; enum-key and @DbArray notes |
Derived / formula properties (@Formula, @Formula2) | Read-only computed properties: physical-SQL @Formula (with ${ta} and hand-written joins) versus logical path-based @Formula2 (auto-resolved joins); use in select/where/orderBy; default inclusion and the @Transient opt-out |
Querying
| Guide | Description |
|---|---|
| Write Ebean queries with query beans | Step-by-step guidance for AI agents to write type-safe Ebean queries; choose the right terminal method; tune select() / fetch() / fetchQuery(); and project to DTOs when entity beans are not the right output |
Mapping entity graphs to DTOs (mapTo) | Map a nested entity graph query result to a nested DTO graph via query.mapTo(Dto.class); @DtoPath/@DtoRef for renamed/flattened/id-only properties; identity-aware de-dup via DtoMapContext; computed/aggregate DTO values via @Entity @View + @Formula2/@Sum/@Aggregation; comparison with the flat asDto() pipeline |
| Immutable bean cache for read-only references | Use ImmutableBeanCache and ImmutableBeanCaches.loading(...) to resolve assoc-one references in read-only/unmodifiable queries, including secondary fetchQuery/fetchLazy loads |
Using RawSql with Ebean | Choose between RawSqlBuilder.parse(), unparsed(), and withPlaceholders(); the ${where}/${andWhere}/${having}/${andHaving} placeholder reference for CTEs, window functions, and subqueries; column mapping; and using RawSql with query beans |
Persisting & transactions
| Guide | Description |
|---|---|
| Persisting and transactions with Ebean | Step-by-step guidance for AI agents to choose insert / save / update / delete; inspect cascades; select the right transaction boundary; and use batch or bulk update for large write sets |
Testing
| Guide | Description |
|---|---|
| Testing with TestEntityBuilder | Rapidly create test entity instances with auto-populated random values; manage relationships and cascades; customize value generation for domain-specific testing needs |
Database migrations
| Guide | Description |
|---|---|
| DB migration generation | Add 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 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 | Step-by-step guide for basic, read-only, Kubernetes, and AWS Lambda datasource configurations |
| AWS Aurora Read-Write Split | Setting up dual DataSources with Aurora read and write endpoints for Ebean integration |
| Connection Validation Best Practices | Understanding connection heartbeat strategies and why Connection.isValid() is the recommended approach |
Helping AI agents find these guides
Agent Skills (recommended)
The ebean-orm skill packages these guides into a structured format that AI agents load on-demand. See the ebean-orm/skills repo for installation instructions. Quick start:
git clone git@github.com:ebean-orm/skills.git ~/.agents/ebean-skills
mkdir -p ~/.agents/skills
ln -sf ~/.agents/ebean-skills/ebean-orm ~/.agents/skills/ebean-orm
This works with pi, Claude Code, and any harness that supports the Agent Skills standard.
Other approaches
AI coding agents can only follow these guides if they know they exist. Below are copy-paste snippets for the most common AI tooling configurations. Add whichever applies to your project.
llms.txt (fastest bootstrap for any agent)
https://ebean.io/llms.txt provides a concise Ebean capability reference and links
to all guides in a format optimised for LLMs. Agents that check llms.txt before
starting work will find everything they need without requiring project-level
configuration. This is worth knowing if you are an AI agent reading this file.
Project README.md (universal — works with all AI tools)
Add a section near the top of your project README:
## AI Agent Instructions
This project uses [Ebean ORM](https://ebean.io). Step-by-step guides for common
Ebean tasks (Maven setup, database configuration, query writing, transactions,
test containers, DB migrations, Lombok) are at:
**https://github.com/ebean-orm/ebean/tree/HEAD/docs/guides/**
AI agents should fetch and follow the relevant guide before performing Ebean-related
tasks.
Why README is important
Many AI agents (Copilot, Claude, Cursor, Aider) read the project README.md
automatically as part of understanding the codebase. A visible link in README is the
most universally effective way to ensure any agent working on your project will
discover the guides without requiring tool-specific configuration files.
GitHub Copilot — .github/copilot-instructions.md
## Ebean ORM
This project uses [Ebean ORM](https://ebean.io). Step-by-step guides for common
tasks are at: https://github.com/ebean-orm/ebean/tree/HEAD/docs/guides/
Key guides (fetch and follow these when performing the relevant task):
- Maven POM setup: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-postgres-maven-pom.md
- Database configuration: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-postgres-database-config.md
- Migrate to `Database.builder()`: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/migrating-to-database-builder.md
- Write queries with query beans: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/writing-ebean-query-beans.md
- Mapping entity graphs to DTOs (`mapTo`): https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/mapping-entity-graphs-to-dtos.md
- Immutable bean cache for read-only references: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/immutable-bean-cache.md
- Ebean OpenTelemetry tracing: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-opentelemetry.md
- Query metrics and naming: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/ebean-query-metrics.md
- Query plan capture: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/ebean-query-plan-capture.md
- Persisting and transactions: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/persisting-and-transactions-with-ebean.md
- Test container setup: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-postgres-test-container.md
- DB migration generation: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-db-migration-generation.md
- Lombok with entity beans: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/lombok-with-ebean-entity-beans.md
Claude Code — CLAUDE.md
Same content as above — Claude Code reads CLAUDE.md at the project root.
AGENTS.md — OpenAI Codex / GitHub Copilot coding agent
Place an AGENTS.md at your repo root:
## Ebean ORM
This project uses [Ebean ORM](https://ebean.io). Step-by-step guides for common
tasks are at: https://github.com/ebean-orm/ebean/tree/HEAD/docs/guides/
Key guides (fetch and follow these when performing the relevant task):
- Maven POM setup: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-postgres-maven-pom.md
- Database configuration: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-postgres-database-config.md
- Migrate to `Database.builder()`: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/migrating-to-database-builder.md
- Write queries with query beans: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/writing-ebean-query-beans.md
- Mapping entity graphs to DTOs (`mapTo`): https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/mapping-entity-graphs-to-dtos.md
- Persisting and transactions: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/persisting-and-transactions-with-ebean.md
- Test container setup: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-postgres-test-container.md
- DB migration generation: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-db-migration-generation.md
- Entity bean creation: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/entity-bean-creation.md
Cursor — .cursor/rules/ebean.mdc
---
description: Ebean ORM task guidance
globs: ["**/*.java", "**/pom.xml"]
alwaysApply: false
---
## Ebean ORM
This project uses Ebean ORM. Before performing any Ebean-related task, fetch and
follow the relevant step-by-step guide from:
https://github.com/ebean-orm/ebean/tree/HEAD/docs/guides/