Programmatic configuration (recommended)

The preferred approach is to programmatically create a Database using Database.builder() and then inject or otherwise pass that instance where it is needed.

This makes startup explicit and avoids relying on global lookup via DB.

• java
• kotlin

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

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

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

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

Load configuration from application.yaml / properties

If the datasource settings live in application.yaml, application.properties and similar configuration sources, still create the Database explicitly and call loadFromProperties().

The default database name is db so the minimal configuration looks like:

H2 - In memory

## H2 setup - In memory
datasource:
  db:
    username: sa
    password: sa
    url: jdbc:h2:mem:myapp

Postgres

datasource:
  db:
    username: my_app
    password: my_password
    url: jdbc:postgresql://localhost:5432/my_app

• java
• kotlin

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

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

ebean.migration.run

Generally we want Ebean to run migrations on startup and we have ebean.migration.run set to true.

Postgres - ebean.dbSchema

Generally for Postgres we set ebean.dbSchema to match the database username when we want database tables etc to be in that named schema rather than the public schema.

Example Postgres typical configuration

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

Multiple databases

When using multiple databases, keep the startup explicit and create each Database using its configured name.

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

Create the named database explicitly:

Database otherDatabase = Database.builder()
  .name("other")
  .loadFromProperties()
  .build();
  

val otherDatabase = Database.builder()
  .name("other")
  .loadFromProperties()
  .build()
  

Goto docs / multi-database for more details on working with multiple databases.

For Testing with ddl.generation

We can set ddl.generation and ddl.run true for simple testing against in memory H2 or a provided database instance (especially if our application is read only).

ebean:
  ddl:
    generate: true
    run: true
#   initSql: test-init.sql
#   seedSql: test-seed.sql

datasource:
  db:
    username: sa
    password: sa
    url: jdbc:h2:mem:myapp

For Testing with ebean-test

ebean-test was built to help with testing against the target database (Postgres, MySql, MariaDB, SQLServer, Oracle ...). Docker especially can be used to programmatically setup and initialise the database for testing purposes.

Testing against the full featured target database(s) comes with a number of advantages in terms of testing and coverage that we talk about at docs / testing.

ebean-test reads the configuration in src/test/resources/application-test.yaml. See the example below:

ebean:
  test:
    platform: postgres # h2, postgres, mysql, ...
    ddlMode: dropCreate # none | dropCreate | migration
    dbName: my_app

ebean-test hooks into the Ebean startup and configures the datasource based on ebean.test.platform and configures the DDL generation and execution based on ebean.test.ddlMode (plus start, setup and wait for docker container(s) as necessary when using docker test containers).

Using ebean-test is the recommended approach for testing as it puts us in a position where we can easily change the database used for testing. For example, changing from testing against H2 to testing against Postgres docker container is as simple as changing ebean.test.platform to postgres.

Refer to docs / testing for more details.