via Properties / yaml

io.ebean.Database can automatically be configured via properties in application.yaml, application.properties etc.

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
    driver: org.h2.Driver

Postgres

datasource:
  db:
    username: my_app
    password: my_password
    url: jdbc:postgresql://localhost:5432/my_app
    driver: org.postgresql.Driver

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
    driver: org.postgresql.Driver

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

Multiple databases

When using multiple databases we set multiple datasource configurations. The non-default databases have a name. For example, if we have a second database called "other" we configure a second datasource like below:

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
    driver: org.postgresql.Driver

  other:
    username: other_username
    password: ${otherPassword}
    url: jdbc:postgresql://${otherDatabaseHost}:5432/other_dbname
    driver: org.postgresql.Driver

We can obtain the "other" database instance by it's name:

// obtain "other" database by its name
Database otherDatabase = DB.byName("other");
  
// obtain "other" database by its name
val otherDatabase = DB.byName("other");
  

Goto docs / multi-database for more details on using multiple databases with @DbName, Model and Finder.

Programmatically creating database

We can programmatically create a Database instance using DatabaseFactory and DatabaseConfig.

// datasource
DataSourceConfig dataSourceConfig = new DataSourceConfig();
dataSourceConfig.setUsername("sa");
dataSourceConfig.setPassword("");
dataSourceConfig.setUrl("jdbc:h2:mem:myapp;");
dataSourceConfig.setDriver("org.h2.Driver");


// configuration ...
DatabaseConfig config = new DatabaseConfig();
config.setDataSourceConfig(dataSourceConfig);
...

// create database instance
Database database = DatabaseFactory.create(config);
  
// datasource
val dataSourceConfig = new DataSourceConfig()
dataSourceConfig.setUsername("sa")
dataSourceConfig.setPassword("")
dataSourceConfig.setUrl("jdbc:h2:mem:myapp;")
dataSourceConfig.setDriver("org.h2.Driver")


// configuration ...
val config = new DatabaseConfig();
config.setDataSourceConfig(dataSourceConfig)
...

// create database instance
val database = DatabaseFactory.create(config)
  

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
    driver: org.h2.Driver

For Testing with ebean-test

ebean-test was built to help with testing against 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.