Persistence Framework

https://ebean.io/docs
Admin
This documentation provides comprehensive guides and references for a persistence framework,...
Tokens:137,843
Snippets:1,935
Trust Score:7.4
Update:2 months ago
Show doc for...
Tokens:
Raw
### MySQL Docker Container Startup Logs

Source: https://ebean.io/docs/database/mysql

Example log output showing the startup process of a MySQL Docker container managed by Ebean's test utilities. Includes commands for container setup and database initialization.

```log
... INFO  io.ebean.docker.commands.Commands - Run container ut_mysql with port:4306 db:my_app user:my_app mode:Create shutdown:
... DEBUG io.ebean.docker.commands.Commands - docker run -d --name ut_mysql -p 4306:3306 -e MYSQL_ROOT_PASSWORD=admin mysql:5.6
```

--------------------------------

### Run ebeaninit for Project Setup

Source: https://ebean.io/docs/getting-started/cli-tool

Initiates the interactive ebeaninit process to set up an existing Maven or Gradle project. It guides through adding dependencies, plugins, sample entities, migration generation, and configuration files.

```bash
$ ebeaninit
-------------------------------------------------------------
ebeaninit  - interactive ebean initialiser - v1.10
-------------------------------------------------------------

It looks like Ebean is not configured for this project.
Do you want to run project setup to add dependencies and configuration ? [y/n] >

Using Java or Kotlin? [j/k] >

Add dependencies and enhancement plugin to pom? [y/n] >
Add JDBC driver dependency?
0 - No, I'll add it myself
p - Postgres
m - MySql or MariaDB
s - SQL Server
o - Oracle
h - Hana
c - Clickhouse
l - Sqlite
Select an option: [0/p/m/s/o/h/c/l] >
...updated pom.xml adding dependencies and enhancement plugin

Add a sample Entity bean? [y/n] >
Enter a package that will contain the entity beans (e.g. org.myapp.domain) >
...added sample code - BaseModel.java, Customer.java and CustomerTest.java

Add ebean.mf manifest to control enhancement? [y/n] >
Select a package that will contain the entity beans
0 - org.myapp.domain
1 - Other
Select an option: [0/1] >
Select the top level package @Transactional is used
0 - org.example.myapp
1 - Other
2 - None, I don't want to use @Transactional
Select an option: [0/1/2] >
... added ebean.mf

Add application-test.yaml to configure testing? [y/n] >
... added application-test.yaml

Add GenerateDbMigration to generate database migrations? [y/n] >
... added GenerateDbMigration.java


Please re-build the project and then you are all set to go.
You can re-run ebeaninit later to generate finders if you like.

Try running CustomerTest ...
Bye

```

--------------------------------

### Ebean Test Database Initialization Logs

Source: https://ebean.io/docs/ci-testing

Example log output demonstrating Ebean's process of connecting to a PostgreSQL database, creating the database and role, and enabling necessary extensions. This log confirms successful setup for testing.

```log
INFO  ?. io.ebean.EbeanVersion - ebean version: 17.2.0
INFO  ?. io.ebean.config.properties.LoadContext - loaded properties from [application.properties, application-test.yaml]
INFO  ?. io.ebean.test.config.platform.Config - Using jdbc settings - username:my_app url:jdbc:postgresql://localhost:6432/my_app driver:org.postgresql.Driver
TRACE ?. io.ebean.docker.commands.Commands - sqlRun: select 1 from pg_database where datname = 'my_app'
TRACE ?. io.ebean.docker.commands.Commands - sqlRun: select rolname from pg_roles where rolname = 'my_app'
DEBUG ?. io.ebean.docker.commands.Commands - sqlRun: create role my_app password 'test' login createrole
DEBUG ?. io.ebean.docker.commands.Commands - sqlRun: create database my_app with owner my_app
DEBUG ?. io.ebean.docker.commands.Commands - sqlRun: create extension if not exists hstore
DEBUG ?. io.ebean.docker.commands.Commands - sqlRun: create extension if not exists pgcrypto
DEBUG ?. io.ebean.docker.commands.Commands - Container ut_postgres ready with port 6432

```

--------------------------------

### Docker Test Container Logs

Source: https://ebean.io/docs/testing

These logs show the automated process of starting and setting up a Docker container for PostgreSQL, including database and user creation, extension setup, and connectivity checks. They also detail the DDL execution for dropping existing schema objects and creating new ones.

```log
... Docker test container start and setup

15:15:02.537 INFO  io.ebean.docker.commands.Commands - Container ut_postgres running with port:6432 db:test_ex user:test_ex mode:Create shutdown:
15:15:02.538 DEBUG io.ebean.docker.commands.Commands - docker exec -i ut_postgres pg_isready -h localhost -p 5432
15:15:02.645 DEBUG io.ebean.docker.commands.Commands - docker exec -i ut_postgres psql -U postgres -c select datname from pg_database
15:15:02.753 DEBUG io.ebean.docker.commands.Commands - docker exec -i ut_postgres psql -U postgres -c select rolname from pg_roles where rolname = 'test_ex'
15:15:02.871 DEBUG io.ebean.docker.commands.Commands - docker exec -i ut_postgres psql -U postgres -c select 1 from pg_database where datname = 'test_ex'
15:15:02.960 DEBUG io.ebean.docker.commands.Commands - create database extensions hstore,pgcrypto
15:15:02.960 DEBUG io.ebean.docker.commands.Commands - docker exec -i ut_postgres psql -U postgres -d test_ex -c create extension if not exists hstore
15:15:03.058 DEBUG io.ebean.docker.commands.Commands - docker exec -i ut_postgres psql -U postgres -d test_ex -c create extension if not exists pgcrypto
15:15:03.143 DEBUG io.ebean.docker.commands.Commands - waitForConnectivity ut_postgres ...
15:15:03.143 DEBUG io.ebean.docker.commands.Commands - checkConnectivity on ut_postgres ...
15:15:03.190 DEBUG io.ebean.docker.commands.Commands - connectivity confirmed for ut_postgres
15:15:03.190 DEBUG io.ebean.docker.commands.Commands - Container ut_postgres ready with port 6432

...

15:15:03.239 [main] INFO  o.a.datasource.pool.ConnectionPool - DataSourcePool [db] autoCommit[false] transIsolation[READ_COMMITTED] min[2] max[200]
15:15:03.277 [main] INFO  io.ebean.internal.DefaultContainer - DatabasePlatform name:db platform:postgres


... DDL Execution

15:15:03.618 [main] INFO  io.ebean.DDL - Executing extra-dll - 0 statements
15:15:03.618 [main] INFO  io.ebean.DDL - Executing db-drop-all.sql - 26 statements
15:15:03.649 [main] DEBUG io.ebean.DDL - executing 1 of 26 alter table if exists address drop constraint if exists fk_address_country_code
15:15:03.651 [main] DEBUG io.ebean.DDL - executing 2 of 26 drop index if exists ix_address_country_code
...
15:15:03.701 [main] INFO  io.ebean.DDL - Executing db-create-all.sql - 28 statements
15:15:03.701 [main] DEBUG io.ebean.DDL - executing 1 of 28 create table address ( id                            bigserial not null, line1...
15:15:03.709 [main] DEBUG io.ebean.DDL - executing 2 of 28 create table contact ( id                            bigserial not null, first_n...
...
15:15:03.841 [main] INFO  io.ebean.DDL - Executing extra-dll - 1 statements
15:15:03.842 [main] DEBUG io.ebean.DDL - executing 1 of 1 create or replace view order_agg_vw as select d.order_id as id, d.order_id as or...

```

--------------------------------

### Install Ebean Agent Skill - Clone and Copy

Source: https://ebean.io/docs/agents/skills

Alternative installation method involving cloning the repository and copying the skill directory.

```bash
git clone https://github.com/ebean-orm/skills.git /tmp/ebean-skills
mkdir -p ~/.agents/skills
cp -r /tmp/ebean-skills/ebean-orm ~/.agents/skills/ebean-orm
rm -rf /tmp/ebean-skills
```

--------------------------------

### Example CurrentUserProvider Implementation

Source: https://ebean.io/docs/features/who

Implement this interface to provide the current user's identifier. This example shows how to retrieve the user ID from a contextual source.

```java
/**
 * Returns the current user typically from a Thread local or similar context.
 */
public class MyCurrentUserProvider implements CurrentUserProvider {

  @Override
  public Object currentUser() {
    // Here you get the user id, from some kind of static
    // context access (session information, thread local, etc..)
    return someContext.getId();
  }
}

```

--------------------------------

### EQL Complete Example (16.x)

Source: https://ebean.io/docs/query/eql

Demonstrates constructing and executing an EQL query with parameters in Ebean 16.x.

```java
String eql = " where customer.name like :custName " +
             " and orderDate > :minOrderDate " +
             " order by id desc " +
             " limit 50 ";

List<Order> orders = DB.createQuery(Order.class, eql)
  .setParameter("custName", "Rob%")
  .setParameter("minOrderDate", lastWeek)
  .findList();
```

--------------------------------

### Transaction Scoped Persistence Context Example

Source: https://ebean.io/docs/architecture/persistence-context

Demonstrates how a new persistence context is started with a transaction and how subsequent fetches of the same entity return the same instance from the context.

```java
Ebean.beginTransaction();
try {
  // find "order 72" results in that instance being put
  // into the persistence context
  Order order = Ebean.find(Order.class, 72);

  // finds an existing "order 72" in the persistence context
  // ... so just returns that instance
  Order o2 = Ebean.find(Order.class, 72);
  Order o3 = Ebean.getReference(Order.class, 72);

  // all the same instance
  Assert.assertTrue(order == o2);
} finally {
  Ebean.endTransaction();
}
```

--------------------------------

### Install Ebean Agent Skill - Clone and Symlink

Source: https://ebean.io/docs/agents/skills

Recommended installation method using git clone and symbolic links. Updates are performed via git pull.

```bash
git clone https://github.com/ebean-orm/skills.git ~/.agents/ebean-skills
mkdir -p ~/.agents/skills
ln -sf ~/.agents/ebean-skills/ebean-orm ~/.agents/skills/ebean-orm
```

--------------------------------

### Example Aggregation Beans

Source: https://ebean.io/docs/query/aggregation

Illustrates specific examples of aggregation beans for summing different properties.

```java
@Aggregation("sum(distanceKms)")
BigDecimal distanceKms;

```

```java
@Aggregation("sum(useSeconds)")
Long useSeconds;

```

```java
@Aggregation("sum(cost)")
BigDecimal cost;

```

--------------------------------

### Example Postgres Typical Configuration

Source: https://ebean.io/docs/intro/configuration

Configuration for Postgres including schema, migration settings, and datasource details. Expects system properties for password and host.

```yaml
ebean:
  dbSchema: my_app  # use this schema rather than public
  migration:
    run: true       # run database migrations on startup

datasource:
  db:
    username: my_app
    password: ${myPassword}
    url: jdbc:postgresql://${myDatabaseHost}:5432/my_app

  ## Expects system properties to be set for:
  ## myPassword and myDatabaseHost
```

--------------------------------

### Install Ebean CLI Tool (Linux)

Source: https://ebean.io/docs/getting-started/cli-tool

Installs the Ebean CLI tool using a curl script on Linux systems.

```bash
curl -s https://ebean.io/cli-dist/install | bash
```

--------------------------------

### Complete EQL to Query Bean Migration Example

Source: https://ebean.io/docs/upgrading

This example shows a complete migration from a complex EQL query in 16.x to its equivalent using Query Beans in 17.x, including fetching specific properties and filtering.

```java
String eql = "select (id, name, email) " +
             "fetch customer (id, name) " +
             "where status = :status and " +
             "customer.billingAddress.city like :city " +
             "order by id desc " +
             "limit 100";

List<Contact> contacts = DB.createQuery(Contact.class, eql)
  .setParameter("status", Status.ACTIVE)
  .setParameter("city", "Auckland%")
  .findList();
```

```java
List<Contact> contacts = new QContact()
  .select("id, name, email")
  .fetch("customer", "id, name")
  .status.eq(Status.ACTIVE)
  .customer.billingAddress.city.contains("Auckland")
  .orderBy().id.desc()
  .setMaxRows(100)
  .findList();
```

--------------------------------

### Start MariaDB Docker Container Programmatically

Source: https://ebean.io/docs/database/mariadb

Use `ebean-test-docker` to programmatically start a MariaDB Docker container. Specify the image version, database name, and password.

```java
package main;

import io.ebean.docker.commands.MariaDBContainer;

public class Main {

  public static void main(String[] args) {

    MariaDBContainer container = MariaDBContainer.newBuilder("10.5")
      .dbName("unit")
      .password("unit")
      .build();

    container.start();
  }
}

```

--------------------------------

### Ebean Autotune XML Configuration Example

Source: https://ebean.io/docs/query/background/autotune

An example of the `ebean-autotune.xml` file, defining tuning rules for specific query origins. Each `origin` element specifies a `key`, `beanType`, `detail` (the tuning query), and the `original` query.

```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<autotune xmlns="http://ebean-orm.github.io/xml/ns/autotune">
  <origin key="wpbnw.BQejAr.Bzpaqe" beanType="org.example.domain.Order"
          detail="select (orderDate,shipDate,status)  fetch details (id,orderQty)"
          original="select ">
    <callStack>org.example.domain.finder.OrderFinder.byStatus(OrderFinder.java:38)
      org.example.domain.finder.OrderFinderTest.test(OrderFinderTest.java:20)
      sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
      sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
      sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
    </callStack>
  </origin>
  <origin key="wpbnw.BQejAr.CEn3iT" beanType="org.example.domain.Order"
          detail="select (orderDate,shipDate)  fetch customer (id,name) "
          original="select ">
    <callStack>org.example.domain.finder.OrderFinder.byStatus(OrderFinder.java:38)
      org.example.domain.finder.OrderFinderTest.testOther(OrderFinderTest.java:51)
      sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
      sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
      sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
    </callStack>
  </origin>
</autotune>
```

--------------------------------

### Install Ebean CLI Tool on Linux

Source: https://ebean.io/docs/getting-started/cli-tool-manualinstall

Download the Ebean CLI initialization JAR and script, create a symbolic link, and make the script executable.

```bash
cd ~/.local/bin

curl https://ebean.io/cli-dist/ebean-init-1.9.jar > ebean-init-1.9.jar
curl https://ebean.io/cli-dist/ebeaninit > ebeaninit

ln -s ebean-init-1.9.jar ebean-init.jar
chmod +x ebeaninit


```

--------------------------------

### Example of REQUIRES_NEW Transaction Scope with beginTransaction()

Source: https://ebean.io/docs/transactions/scopes

This demonstrates how to programmatically start a new transaction using TxScope.requiresNew(). Ensure to commit or rollback the transaction.

```java
import io.ebean.Database;
import io.ebean.TxScope;
import io.ebean.Transaction;

// Assuming 'database' is an instance of Database
try (Transaction transaction = database.beginTransaction(TxScope.requiresNew())) {
  // using a new transaction ...
  transaction.commit();
}
```

--------------------------------

### Start SQL Server Docker Container Programmatically

Source: https://ebean.io/docs/database/sqlserver

Use the `ebean-test-docker` dependency to programmatically start a SQL Server Docker container. This is useful for setting up isolated database environments for testing.

```java
package main;

import io.ebean.docker.commands.SqlServerContainer;

public class Main {

  public static void main(String[] args) {

    SqlServerContainer container = SqlServerContainer.newBuilder("2019-CU15-ubuntu-20.04")
      .dbName("my_app")
      .collation("SQL_Latin1_General_CP1_CS_AS")
      // .containerName("ut_sqlserver")
      // .port(1433)
      .build();

    container.start();
  }
}
```

--------------------------------

### Install Ebean Agent Skill - Project-Level

Source: https://ebean.io/docs/agents/skills

Method for installing the skill within a project's .agents/skills directory for team-wide availability. Remember to add the skill to git.

```bash
# from your project root
git clone https://github.com/ebean-orm/skills.git /tmp/ebean-skills
mkdir -p .agents/skills
cp -r /tmp/ebean-skills/ebean-orm .agents/skills/ebean-orm
rm -rf /tmp/ebean-skills
git add .agents/skills/ebean-orm
```

--------------------------------

### Programmatically Start Redis Docker Container

Source: https://ebean.io/docs/database/redis

Use `ebean-test-docker` to programmatically start a Redis Docker container. Ensure the dependency is included if `ebean-test` is not already present.

```java
package main;

import io.ebean.docker.commands.RedisContainer;

public class Main {

  public static void main(String[] args) {

    RedisContainer container = RedisContainer.newBuilder("latest")
      .build();

      container.start();
  }
}

```

--------------------------------

### Groovy Ebean Usage Example

Source: https://ebean.io/docs/features/jvmlanguages

Demonstrates basic Ebean operations in Groovy, such as getting a reference, finding lists, and iterating through results. Requires Ebean library import.

```groovy
package test

import com.avaje.ebean.*

public class MainEbean{
  public static void main(String[] args) {

    PersonG g = Ebean.getReference(PersonG.class, 1);

    String name = g.getName();

    List<PersonG> list = Ebean
      .find(PersonG.class)
      .fetch("topics")
      .findList()

    println "Got list "+list

    list.each() {
      print " $\{it.id} $\{it.name} 
"
      print " GOT DETAILS: "+it.topics
    };

    println "done";
  }
}

```

--------------------------------

### Programmatic Ignite Configuration with ServerConfigStartup

Source: https://ebean.io/docs/features/l2cache/apache-ignite

Implement ServerConfigStartup to programmatically configure Ignite at Ebean startup. This example sets up client mode and specifies discovery addresses.

```java
package models;

import io.ebean.DatabaseBuilder;
import io.ebean.event.ServerConfigStartup;
import org.apache.ignite.configuration.IgniteConfiguration;
import org.apache.ignite.spi.discovery.tcp.TcpDiscoverySpi;
import org.apache.ignite.spi.discovery.tcp.ipfinder.vm.TcpDiscoveryVmIpFinder;

import java.util.Arrays;

public class MyServerConfigStartup implements ServerConfigStartup {

    @Override
    public void onStart(DatabaseBuilder serverConfig) {

        IgniteConfiguration igniteCfg = new IgniteConfiguration();
        igniteCfg.setClientMode(true);

        TcpDiscoveryVmIpFinder finder = new TcpDiscoveryVmIpFinder();
        finder.setAddresses(Arrays.asList("172.30.1.1"));

        TcpDiscoverySpi discoverySpi = new TcpDiscoverySpi();
        discoverySpi.setIpFinder(finder);

        igniteCfg.setDiscoverySpi(discoverySpi);
        serverConfig.putServiceObject("igniteConfiguration", igniteCfg);
    }
}
```

--------------------------------

### FetchGroup Example (Orders with Related Entities)

Source: https://ebean.io/docs/query/fetchgroup

An extensive FetchGroup example demonstrating fetching orders with related lines, shipments, customer details, and customer contacts. It uses fetchQuery for ToMany paths to control SQL query generation.

```java
static final QOrder ORD = QOrder.alias();
static final QCustomer CUST = QCustomer.alias();
static final QContact CONT = QContact.alias();

static final FetchGroup<Order> fetch = QOrder.forFetchGroup()
    .customer.fetch(CUST.name, CUST.version, CUST.whenCreated)
    .customer.shippingAddress.fetch()
    .customer.contacts.fetch(CONT.email)                        // a ToMany path
    .lines.fetchQuery()                                         // a ToMany path
    .shipments.fetchQuery()                                     // a ToMany path
    .buildFetchGroup();

List<Order> orders =
  new QOrder()
    .select(fetch)
    .status.eq(Order.Status.NEW)
    .findList();
```

--------------------------------

### Example POM for Postgres Application

Source: https://ebean.io/docs/getting-started/maven

A complete example POM file for an application using Ebean with Postgres, including JDBC driver, Ebean Postgres artifact, test dependencies, and build plugin configurations.

```xml
<?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>

    <groupId>org.example</groupId>
    <artifactId>hello-ebean</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
      <maven.compiler.release>25</maven.compiler.release> <!-- Prefer release -->
      <maven.compiler.source>25</maven.compiler.source> <!-- fallback -->
      <maven.compiler.target>25</maven.compiler.target> <!-- fallback -->
      <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
      <dependency> <!-- JDBC Driver(s) -->
        <groupId>org.postgresql</groupId>
        <artifactId>postgresql</artifactId>
        <version>42.7.8</version>
      </dependency>

      <dependency> <!-- ebean postgres, add more platforms as needed -->
        <groupId>io.ebean</groupId>
        <artifactId>ebean-postgres</artifactId>
        <version>17.2.0</version>
      </dependency>

      <!-- test dependencies -->
      <dependency>
        <groupId>io.ebean</groupId>
        <artifactId>ebean-test</artifactId>
        <version>17.2.0</version>
        <scope>test</scope>
      </dependency>

      <dependency> <!-- Optional extra: JUnit5 + AssertJ + Mockito -->
        <groupId>io.avaje</groupId>
        <artifactId>junit</artifactId>
        <version>1.7</version>
        <scope>test</scope>
      </dependency>

    </dependencies>

    <build>
      <plugins>

        <plugin> <!-- perform ebean enhancement -->
          <groupId>io.ebean</groupId>
          <artifactId>ebean-maven-plugin</artifactId>
          <version>17.2.0</version>
          <extensions>true</extensions>
        </plugin>

        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-compiler-plugin</artifactId>
          <version>3.14.1</version>
          <configuration>
            <annotationProcessorPaths>
               <path> <!-- generate ebean query beans -->
                  <groupId>io.ebean</groupId>
                  <artifactId>querybean-generator</artifactId>
                  <version>17.2.0</version>
              </path>
            </annotationProcessorPaths>
          </configuration>
        </plugin>

      </plugins>
    </build>
</project>
```

--------------------------------

### Multiple Databases Configuration Example

Source: https://ebean.io/docs/intro/configuration

Configuration for multiple databases, specifying distinct datasource properties for each. System properties are used for sensitive values.

```yaml
ebean:
  dbSchema: my_app  # use this schema rather than public
  migration:
    run: true       # run database migrations on startup

datasource:
  db:
    username: my_app
    password: ${myPassword2}
    url: jdbc:postgresql://${myDatabaseHost2}:5432/my_app

  other:
    username: other_username
    password: ${otherPassword}
    url: jdbc:postgresql://${otherDatabaseHost}:5432/other_dbname
```

--------------------------------

### Start SAP Hana Docker Container Programmatically

Source: https://ebean.io/docs/database/hana

Use HanaContainer.Builder to programmatically start a Docker container for SAP Hana. Ensure the ebean-test-docker dependency is included.

```java
package main;

import io.ebean.docker.commands.HanaContainer;
import java.net.URL;
import java.net.MalformedURLException;

public class Main {

  public static void main(String[] args) {

    HanaContainer.Builder builder = HanaContainer.newBuilder("2.00.033.00.20180925.2");
    builder.port(39117);
    builder.instanceNumber("91");
    try {
      // Assuming passwordsFile and tempDir are accessible within this scope
      // For a real scenario, these would need to be properly defined or passed.
      // Example placeholder:
      // File passwordsFile = new File("path/to/passwords.txt");
      // Path tempDir = Paths.get("path/to/temp");
      // builder.passwordsUrl(new URL("file://" + passwordsFile.getAbsolutePath()));
      // builder.mountsDirectory(tempDir.toString());
      
      // The original code had 'this.passwordsFile.getFileName()' and 'this.tempDir.toString()'
      // which are not standard Java in this context. Replacing with placeholders.
      builder.passwordsUrl(new URL("file:///hana/mounts/passwords.txt"));
      builder.mountsDirectory("/hana/mounts");

    } catch (MalformedURLException e) {
      // In a real application, handle this exception appropriately.
      // For demonstration, printing stack trace.
      e.printStackTrace();
      // fail(e.getMessage()); // 'fail' is not a standard method here, likely from a testing framework.
    }
    builder.agreeToSapLicense(false);

    HanaContainer container = builder.build();

    container.start();
  }
}

```

--------------------------------

### Start PostgreSQL Docker Container Programmatically

Source: https://ebean.io/docs/database/postgres

Use ebean-test-docker to start a PostgreSQL container for local development. This includes setting database name, user, password, container name, and extensions.

```java
package main;

import io.ebean.docker.commands.PostgresContainer;

public class StartPostgres {

  public static void main(String[] args) {

    PostgresContainer container = PostgresContainer.newBuilder("14")
      // .port(5432) // Note: defaults to 6432
      .dbName("my_app")
      .user("my_app")
      .password("silly")
      .containerName("pg14x")
      .extensions("hstore,pgcrypto")
      .build();

    container.start();
  }
}

```

--------------------------------

### Example Gradle Build Output

Source: https://ebean.io/docs/getting-started/gradle

Demonstrates typical output from `./gradlew clean test`, showing class enhancement, DDL execution, SQL statements, and transaction logging.

```bash
$ ./gradlew clean test

> Task :compileJava
ebean-enhance> cls: org/example/domain/BaseDomain  msg: enhanced
ebean-enhance> cls: org/example/domain/Customer  msg: enhanced

> Task :test
enhancement prior to running tests

Gradle suite > Gradle test > org.example.domain.CustomerTest.saveAndFind STANDARD_OUT
14:48:49.900 [Test worker] INFO  io.ebean.internal.DefaultContainer - DatabasePlatform name:db platform:h2
14:48:50.063 [Test worker] TRACE io.ebean.TXN - txn[1001] Begin
14:48:50.064 [Test worker] INFO  io.ebean.DDL - Executing db-create-all.sql - 1 statements
14:48:50.064 [Test worker] DEBUG io.ebean.DDL - executing 1 of 1 create table customer ( id                            bigint auto_increment not...
14:48:50.076 [Test worker] DEBUG io.ebean.TXN - txn[1001] Commit
14:48:50.086 [Test worker] DEBUG io.ebean.SQL - txn[1002] insert into customer (name, start_date, comments, version) values (?,?,?,?); --bind(Hello Rob,2018-01-30,[LOB],1)
14:48:50.098 [Test worker] DEBUG io.ebean.SUM - txn[1002] Inserted [Customer] [1]
14:48:50.098 [Test worker] DEBUG io.ebean.TXN - txn[1002] Commit
14:48:50.122 [Test worker] DEBUG io.ebean.SQL - txn[1003] select t0.id, t0.name, t0.start_date, t0.version from customer t0 where t0.id = ?  ; --bind(1, )
14:48:50.124 [Test worker] DEBUG io.ebean.SUM - txn[1003] FindBean type[Customer] origin[D88YBi.A.A] exeMicros[3052] rows[1] bind[1, ]
hello Hello Rob
.. started on: 2018-01-30
14:48:50.136 [Test worker] DEBUG io.ebean.SQL - txn[1005] select t0.id, t0.name, t0.start_date, t0.version from customer t0 where t0.name like ?  and t0.id > ? ; --bind(BatOutOfHell%,1)
14:48:50.136 [Test worker] DEBUG io.ebean.SUM - txn[1005] FindMany type[Customer] origin[D88YBj.A.A] exeMicros[1619] rows[0] predicates[t0.name like ?  and t0.id > ? ] bind[BatOutOfHell%,1]
bats:BeanList size[0] list[]


BUILD SUCCESSFUL in 1s

```

--------------------------------

### Start DB2 Docker Container Programmatically

Source: https://ebean.io/docs/database/db2

Use the ebean-test-docker dependency to programmatically start a DB2 container. Specify the DB2 version, database name, and port.

```java
package main;

import io.ebean.docker.commands.Db2Container;

public class Main {

  public static void main(String[] args) {

    Db2Container container = Db2Container.newBuilder("11.5.4.0")
      .dbName("my_app")
      .port(50050)
      .build();

    container.start();
  }
}

```

--------------------------------

### Start Oracle Docker Container Programmatically

Source: https://ebean.io/docs/database/oracle

Use the ebean-test-docker dependency to programmatically start an Oracle Docker container. Specify the image tag and user credentials.

```java
package main;

import io.ebean.docker.commands.OracleContainer;

public class Main {

  public static void main(String[] args) {

    OracleContainer container = OracleContainer.newBuilder("latest")
      .user("my_user")
      .build();

    container.start();
  }
}

```

--------------------------------

### Programmatically Start MySQL Docker Container

Source: https://ebean.io/docs/database/mysql

Use the Ebean test Docker API to programmatically start a MySQL Docker container with specified configurations. This is useful for local development and testing.

```java
package main;

import io.ebean.docker.commands.MySqlContainer;

public class Main {

  public static void main(String[] args) {

    MySqlContainer container = MySqlContainer.newBuilder("8.0")
      .dbName("my_db")
      .user("my_user")
      .password("my_pass")
      .build();

    // by default this mysql docker collation is case sensitive using utf8mb4_bin
    // builder.collation("default");
    // builder.collation("utf8mb4_unicode_ci");
    // builder.characterSet("utf8mb4");

    container.start();
  }
}
```

--------------------------------

### Basic EncryptKeyManager Implementation

Source: https://ebean.io/docs/features/encryption

An example implementation of the EncryptKeyManager interface for managing encryption keys.

```java
package org.example.encrypt;

import io.ebean.config.EncryptKey;
import io.ebean.config.EncryptKeyManager;

public class BasicEncyptKeyManager implements EncryptKeyManager {

  public void initialise() {
    // can load keys or initialise source resources ...
  }

  public EncryptKey getEncryptKey(String tableName, String columnName) {
    // get the key for the given table and column
    String keyValue = ...;
    return new BasicEncryptKey(keyValue);
  }

}

```

--------------------------------

### Start NuoDB Docker Container Programmatically

Source: https://ebean.io/docs/database/nuodb

Use the ebean-test-docker dependency to programmatically start a NuoDB Docker container. Configure the container with a specific version, schema, user, and password.

```java
package main;

import io.ebean.docker.commands.NuoDBContainer;

public class Main {

  public static void main(String[] args) {

    NuoDBContainer container = NuoDBContainer.newBuilder("4.0")
      .schema("my_app")
      .user("my_app")
      .password("test")
      .build();

    container.start();
  }
}
```

--------------------------------

### EQL to Query Beans Migration Example (17.x)

Source: https://ebean.io/docs/query/eql

Compares an EQL query from Ebean 16.x with its equivalent using Query Beans in Ebean 17.x.

```java
String eql = "where customer.name like :custName and orderDate > :minOrderDate " +
             "order by id desc limit 50";

List<Order> orders = DB.createQuery(Order.class, eql)
  .setParameter("custName", "Rob%")
  .setParameter("minOrderDate", lastWeek)
  .findList();
```

```java
List<Order> orders = new QOrder()
  .customer.name.contains("Rob")
  .orderDate.greaterThan(lastWeek)
  .orderBy().id.desc()
  .setMaxRows(50)
  .findList();
```

--------------------------------

### Programmatically Start YugabyteDB Docker Container

Source: https://ebean.io/docs/database/yugabyte

Use the YugabyteContainer class from ebean-test-docker to programmatically start a YugabyteDB instance. Specify the version, database name, and any necessary extensions.

```java
package main;

import io.ebean.docker.commands.YugabyteContainer;

public class Main {

  public static void main(String[] args) {

    YugabyteContainer container = YugabyteContainer.newBuilder("2.11.2.0-b89")
      //.port(6433)
      .dbName("my_app")
      .extensions("pgcrypto")
      .build();

    container.start();
  }
}

```

--------------------------------

### Find Map Keyed by SKU

Source: https://ebean.io/docs/query/findMap

Use `asMapKey()` to specify the property to be used as keys on the map. This example keys the map by the 'sku' property.

```java
// map keyed by sku

Map<String, Product> map = 
    new QProduct() 
     .sku.asMapKey() 
     .findMap();

```

--------------------------------

### EQL to Standard Query API Migration Example (17.x)

Source: https://ebean.io/docs/query/eql

Compares an EQL query from Ebean 16.x with its equivalent using the standard Query API in Ebean 17.x.

```java
String eql = "where customer.name like :custName and orderDate > :minOrderDate " +
             "order by id desc limit 50";

List<Order> orders = DB.createQuery(Order.class, eql)
  .setParameter("custName", "Rob%")
  .setParameter("minOrderDate", lastWeek)
  .findList();
```

```java
List<Order> orders = DB.find(Order.class)
  .where()
    .contains("customer.name", "Rob")
    .gt("orderDate", lastWeek)
  .order().desc("id")
  .setMaxRows(50)
  .findList();
```

--------------------------------

### Verify Ebean Agent Skill Installation

Source: https://ebean.io/docs/agents/skills

Command to check if the 'ebean-orm' skill is recognized by the 'pi' tool.

```bash
/skills
```

--------------------------------

### Enable Ebean Migration Runner

Source: https://ebean.io/docs/setup/dbmigration

Set `ebean.migration.run=true` to automatically run migrations when Ebean starts. Optionally, specify DB credentials for migration ownership.

```properties
ebean.migration.run=true

datasource.db.adminusername=myDbTableOwner
datasource.db.adminpassword=secret
```

--------------------------------

### FilterMany Example: Filtering Contacts by First Name

Source: https://ebean.io/docs/query/filterMany

This example demonstrates filtering contacts associated with customers, specifically selecting contacts whose first name starts with 'Rob'.

```java
List<Customer> customers =
    new QCustomer()
    .status.eq(Status.NEW)
    .contacts.filterMany("firstName istartsWith ?", "Rob")
    .findList();
```

--------------------------------

### Add Columns to Customer Table

Source: https://ebean.io/docs/setup/dbmigration

Example migration XML showing the addition of 'registered' (date) and 'comments' (varchar) columns to the 'customer' table.

```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="registered" type="date"/>
      <column name="comments" type="varchar(1000)"/>
    </addColumn>
  </changeSet>
</migration>

```

--------------------------------

### Configure Redis for Testing

Source: https://ebean.io/docs/database/redis

Use `ebean.test.redis` in `test/resources/application-test.yaml` to automatically start a Redis Docker container for testing purposes.

```yaml
ebean:
  test:
    redis: latest
    platform: h2 # h2, postgres, mysql, oracle, sqlserver, sqlite
    ddlMode: dropCreate # none | dropCreate | migrations | create
    dbName: my_app

```

--------------------------------

### Kotlin Operations with Constructor-Set Properties

Source: https://ebean.io/docs/mapping/constructors

Shows how to save a new country, get a reference bean, and perform queries using the Kotlin Country entity.

```kotlin
Country("NZ", "New Zealand").save()

// reference bean
val nzRef = Country.ref("NZ")

// finder & query bean use
val nz = Country.where()
    .code.equalTo("NZ")
    .findOne()
```

--------------------------------

### Example of REQUIRES_NEW Transaction Scope with @Transactional

Source: https://ebean.io/docs/transactions/scopes

Use this scope to always start a new transaction, suspending any existing one. This is applied to methods annotated with @Transactional.

```java
import io.ebean.TxType;

@Transactional(type = TxType.REQUIRES_NEW)
public void doInner() {
  // execute using a new transaction ...

}
```

--------------------------------

### Class-level @Identity Annotation

Source: https://ebean.io/docs/mapping/extensions/identity

Use @Identity on the class level when the @Id property is inherited, for example, with @MappedBy. Specifies start value, cache, and generation type.

```java
@Identity(generated = BY_DEFAULT, start = 1000, cache = 100)
@Entity
public class AuditLog {
  ...

}
```

--------------------------------

### Programmatic Database Startup with Builder in Java

Source: https://ebean.io/docs/intro/database

Shows how to programmatically configure and build a Database instance using the Database.builder() API. This instance should be created once during application startup.

```java
Database database = Database.builder()
  .name("db")
  .loadFromProperties()
  .build();


```

--------------------------------

### Property-level @Identity Annotation

Source: https://ebean.io/docs/mapping/extensions/identity

Apply @Identity directly to the @Id property to configure identity generation. This example sets a specific start value and cache size for the ID.

```java
@Entity
public class AuditLog {

  @Id
  @Identity(generated = BY_DEFAULT, start = 10000, cache = 1000)
  long id;
  ...

}
```

--------------------------------

### Creating Partitions with Helper Function

Source: https://ebean.io/docs/mapping/extensions/dbpartition

Use the 'partition' helper function to create partitions for a specified table. This example creates 'Week' partitions and ensures unique and regular indexes.

```sql
select partition('week','event','id','when_occurred',3)
```

--------------------------------

### Bind Database Provider in Guice Module

Source: https://ebean.io/docs/setup/guice

Bind the custom Database provider in your Guice module. Use `asEagerSingleton()` to ensure the Database instance is created when the application starts.

```java
bind(Database.class).toProvider(DatabaseProvider.class).asEagerSingleton()
```

--------------------------------

### Docker Test Container Logging

Source: https://ebean.io/docs/intro/logging

Log Docker commands used by ebean-test when starting test containers. This helps in diagnosing issues related to test environment setup.

```xml
<!-- Docker commands for starting test containers  -->
<logger name="io.ebean.docker" level="TRACE"/>

```

--------------------------------

### Group By Aggregation Query

Source: https://ebean.io/docs/query/select

Perform aggregation with grouping on multiple columns. This example finds the maximum rate per machine and date, filtering by date and having a minimum rate.

```java
List<MachineStats> result =
  new QMachineStats()
  .select("machine, date, max(rate)")
  .date.gt(LocalDate.now().minusDays(10))
  .query().having().gt("max(rate)", 4)
  .findList();
```

--------------------------------

### Programmatic Database Configuration (Java)

Source: https://ebean.io/docs/intro/configuration

Configure a DataSource and build a Database instance programmatically. This approach makes startup explicit and avoids global lookups.

```java
var dataSource = DataSourceBuilder.create()
  .username("sa")
  .password("")
  .url("jdbc:h2:mem:myapp");

Database database = Database.builder()
  .name("db")
  .dataSourceBuilder(dataSource)
  .build();
```

--------------------------------

### Programmatically Start Elasticsearch Docker Container

Source: https://ebean.io/docs/database/elasticsearch

Use the ElasticContainer class to programmatically start an Elasticsearch Docker container. This is helpful for integration testing.

```java
package main;

import io.ebean.docker.commands.ElasticContainer;

public class Main {

  public static void main(String[] args) {

    ElasticContainer container = ElasticContainer.newBuilder("5.6.0")
      .build();

      container.start();
  }
}

```

--------------------------------

### Load Configuration from Properties (Java)

Source: https://ebean.io/docs/intro/configuration

Build a Database instance and load its configuration from properties files. The default database name is 'db'.

```java
Database database = Database.builder()
  .name("db")
  .loadFromProperties()
  .build();
```

--------------------------------

### Programmatic CockroachDB Docker Container Start

Source: https://ebean.io/docs/database/cockroach

Start a CockroachDB Docker container programmatically using the CockroachContainer class from ebean-test-docker. This is useful for integration testing.

```java
package main;

import io.ebean.docker.commands.CockroachContainer;

public class Main {

  public static void main(String[] args) {

    CockroachContainer container = CockroachContainer.newBuilder("v21.2.9")
      .dbName("unit")
      //.user("test_roach");
      .build();

    container.start();
  }
}

```

--------------------------------

### Programmatic Database Configuration (Kotlin)

Source: https://ebean.io/docs/intro/configuration

Configure a DataSource and build a Database instance programmatically in Kotlin. This approach makes startup explicit and avoids global lookups.

```kotlin
val dataSource = DataSourceBuilder.create()
  .username("sa")
  .password("")
  .url("jdbc:h2:mem:myapp")

val database = Database.builder()
  .name("db")
  .dataSourceBuilder(dataSource)
  .build()
```

--------------------------------

### Load Configuration from Properties (Kotlin)

Source: https://ebean.io/docs/intro/configuration

Build a Database instance and load its configuration from properties files in Kotlin. The default database name is 'db'.

```kotlin
val database = Database.builder()
  .name("db")
  .loadFromProperties()
  .build()
```

--------------------------------

### Configure application-test.yaml

Source: https://ebean.io/docs/testing

Set up the application-test.yaml file in src/test/resources to define test database platform, DDL mode, and database name.

```yaml
ebean:
  test:
    platform: h2 #, h2, postgres, mysql, oracle, sqlserver, hana, clickhouse, sqlite
    ddlMode: dropCreate # none | dropCreate | migrations | create
    dbName: my_app
```

--------------------------------

### Manual columnMapping with RawSqlBuilder

Source: https://ebean.io/docs/query/rawSql

Illustrates the alternative approach of manually mapping each column using `columnMapping` when constructing Raw SQL. This is more verbose than `tableAliasMapping`.

```java
static final RawSql rawSql = RawSqlBuilder.parse(rs)
    .columnMapping("t0.id", "id")
    .columnMapping("t0.status", "status")
    .columnMapping("t1.id", "customer.id")
    .columnMapping("t1.name", "customer.name")
    .columnMapping("t2.id", "details.id")
    .columnMapping("t2.order_qty", "details.orderQty")
    .columnMapping("t3.id", "details.product.id")
    .columnMapping("t3.name", "details.product.name")
    .create();
```

--------------------------------

### Persist, Fetch, and Transaction Management in Java

Source: https://ebean.io/docs/intro/database

Demonstrates basic database operations including saving an entity, fetching a list of entities, and managing transactions using try-with-resources.

```java
// persist ...
Customer customer  = ...
database.save(customer);


// fetch ...
List<Customer> customers =
  database.find(Customer.class)
  .findList();


// transactions ...
try (Transaction transaction = database.beginTransaction()) {

  // fetch and persist beans etc ...

  transaction.commit();
}
  
```

--------------------------------

### Initializing Partitions with XML DDL

Source: https://ebean.io/docs/mapping/extensions/dbpartition

Define initial partitions using the 'partition_init' helper function within an XML extra-ddl script. This allows for explicit control over initial partition creation.

```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<extra-ddl xmlns="http://ebean-orm.github.io/xml/ns/extraddl">

  <ddl-script name="1 initial partitions" >
select partition_init(date '2015-01-01', 'week', 'event', 'id', 'when_occurred', 3);
select partition_init(date '2015-01-01', 'month', 'event_log', 'id', '', 2);
  </ddl-script>

</extra-ddl>
```
Tokens:
Raw