Database

io.ebean.Database provides most of the functionality including queries, saving, deleting and transactions. 

// 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();
}
  

// persist ...
val customer  = ...
database.save(customer)


// fetch ...
val customers =
  database.find(Customer::class.java)
  .findList()


// transactions ...
database.beginTransaction().use { transaction ->

  // fetch and persist beans etc ...

  transaction.commit();
}

javax.sql.DataSource

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();
  

// obtain the "default" database
val 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");
  

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

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()

Note that in practice when using Model for persisting , Query beans for entity queries and @Transactional for transactions then we tend to only use database directly for DTO queries, SQL queries and SQL updates.

Configuration

Details for configuration of database instances programmatically and via properties is in the next section.

 

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
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 inject them where needed. We typically do this using Spring or Guice or a similar DI framework.

We can do both and have Database instances registered with DB and the DI Context and in this way access the database instance(s) either way.

EbeanServer

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.

Ebean

DB and Ebean are the same thing.

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