The Database API provides almost all of the functionality including queries, saving, deleting and transactions.

// persist ...
Customer customer  = ...;

// fetch ...
List<Customer> customers =

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

  // fetch and persist beans etc ...



A Database instance has an JDBC DataSource associating it one to one to an actual database.

Note that a Database can have a second read only DataSource that can be used for performance reasons (for read only queries) and potentially connect to database read replicas.

Default database

One database can be specified as the default database. The default Database instance is registered with DB and then can be obtained via DB.getDefault().

// obtain the "default" database
Database database = DB.getDefault();

Named database

Each Database instance has a name and can be registered with DB and then obtained by it's name via DB.byName()

// obtain a database by it's name
Database hrDatabase = DB.byName("hr");

Create database

We can programmatically create a Database instance using DatabaseFactory and DatabaseConfig or it can be created automatically from properties file configuration (for testing we often use application-test.yaml and have the database instance created automatically).

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

// create database instance
Database database = DatabaseFactory.create(config);

Refer to DatabaseFactory for more details.


DB (io.ebean.DB)

  • DB holds a registry of database instances (keyed by name)
  • DB holds one Database instance known as the default database
  • DB has convenience methods to operate on the default database


Obtain default or named database instance

When an Database instance is created it can be registered with DB. We can then use DB to obtain those Database instances by name and we can obtain the default database via DB.getDefault().

// obtain the "default" database
Database server = DB.getDefault();

// obtain the HR database by name
Database hrDB = DB.byName("hr");

DB convenience methods

DB has convenience methods that effectively proxy through to the default database. This is useful and convenient as many applications only use a single database.

Customer customer  = ...

// save using the 'default' database;

// which is the same as
Database defaultDatabase = DB.getDefault();

DB is optional

Note that you don't have to use the DB singleton in your application at all - it's use is completely optional. Instead we can create the Database instance(s) and inject them where needed. We typically do this using Spring or Guice or a similar DI framework.

When we do this (inject Database and don't use the DB singleton) we will likely have the application code following a DI / Repository pattern convention.



Database and EbeanServer are the same thing.

io.ebean.EbeanServer is the older original name for io.ebean.Database. They can be used interchangably. In time EbeanServer will be deprecated and code should migrate to use io.ebean.Database.



DB and Ebean are the same thing.

io.ebean.Ebean is the older original name for io.ebean.DB. They can be used interchangably. In time use of Ebean will be deprecated and code should migrate to use io.ebean.DB.

Edit Page