API - DB and Database
The Database API provides almost all of the functionality including
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.
One database can be specified as the
default database. The default Database
instance is registered with
DB and then can be obtained via
Each Database instance has a name and can be registered with
DB and then obtained by
it's name via
Model uses default database
When our entity beans extend Model and we use save() that is actually using the default database.
Customer customer = new Customer("Roberto") // use the default database customer.save()
val customer = Customer("Roberto") // use the default database customer.save()
Query beans use default database
When we create a Query bean and execute the query that also is actually using the default database.
// use the default database List<Customer> customers = new QCustomer() .status.equalTo(Status.NEW) .billingAddress.city.equalTo("Auckland") .findList();
// use the default database val customers = QCustomer() .status.equalTo(Status.NEW) .billingAddress.city.equalTo("Auckland") .findList()
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(); config.addClass(MyEntityBean.class); ... // create database instance Database database = DatabaseFactory.create(config);
Refer to DatabaseFactory for more details.
- 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
DB to obtain those Database instances by name and we can obtain
the default database via
// 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 DB.save(customer); // which is the same as Database defaultDatabase = DB.getDefault() defaultDatabase.save(customer);
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
them where needed. We typically do this using
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
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
They can be used interchangably. In time use of Ebean will be deprecated and code should migrate
to use io.ebean.DB.