If your development workflow uses a skill-aware coding agent, install the ebean-orm skill first. This is the preferred way to give the agent Ebean-specific guidance.

  • Keeps Ebean instructions out of your normal prompts
  • Covers setup, entity modeling, querying, persistence, testing, and migrations
  • Works with skill-aware tools such as pi and Claude Code

See Agent Skills for installation and setup details.

AI Agent Instructions

This page collects the Ebean resources that coding agents can use when working in an Ebean project.

If Agent Skills are not available, the fastest option is to fetch https://ebean.io/llms.txt. It provides a concise capability reference and links to the relevant step-by-step guides.

Step-by-step guides

These are prescriptive guides for common Ebean tasks. Fetch and follow the relevant guide before making Ebean-related changes.

Full guide index: https://github.com/ebean-orm/ebean/tree/HEAD/docs/guides/

Guide Description
Maven POM setup Add Ebean dependencies, the enhancement plugin, and querybean-generator to pom.xml
Database configuration Configure the Ebean Database bean using DataSourceBuilder and DatabaseBuilder with Avaje Inject
Test container setup Start a PostgreSQL or PostGIS Docker container for tests using @TestScope @Factory
Write queries with query beans Type-safe Q-bean queries — choose terminal methods, tune select/fetch, project to DTOs
Persisting and transactions Choose insert/save/update/delete, cascade rules, @Transactional, batch writes
DB migration generation Generate schema diff migrations offline with GenerateDbMigration.java
Entity bean creation Clean, idiomatic entity beans — annotations, field patterns, relationships, anti-patterns
Lombok with entity beans Which Lombok annotations to use and avoid; why @Data is incompatible with Ebean
Testing with TestEntityBuilder Rapidly create test entity instances with auto-populated random values

Add to your project

Add the relevant snippet to your project so coding agents working in your codebase can automatically discover these guides.

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
- Write queries with query beans: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/writing-ebean-query-beans.md
- Persisting and transactions: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/persisting-and-transactions-with-ebean.md
- Test container setup: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-postgres-test-container.md
- DB migration generation: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-db-migration-generation.md
- Entity bean creation: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/entity-bean-creation.md

GitHub Copilot — .github/copilot-instructions.md

Same content as AGENTS.md above — add an ## Ebean ORM section.

Claude Code — CLAUDE.md

Same content as AGENTS.md above — Claude Code reads CLAUDE.md at the project root.

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/