AI Agent Instructions
This page is the entry point for AI coding agents (GitHub Copilot, Cursor, Claude Code, OpenAI Codex, etc.) working in projects that use Ebean ORM.
The fastest way to bootstrap Ebean knowledge is to fetch https://ebean.io/llms.txt — it contains a concise capability reference and links to all step-by-step guides.
Step-by-step guides
Prescriptive guides written for AI agents and developers. Fetch and follow the relevant guide before performing Ebean-related tasks.
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
Copy the relevant snippet into your project so AI agents working in your codebase 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/