Database

io.ebean.Database is the main API and the preferred type to use in application code. It provides queries, persisting, deleting and transaction management. 

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

Programmatic startup

Prefer explicit programmatic startup via Database.builder(). Create the Database once during application startup and inject or otherwise pass the resulting instance where it is needed. 

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

javax.sql.DataSource

A Database instance has a 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.

Model and query beans

Model and query bean APIs often operate against the default registered database. If you use those APIs, register a default database at startup. Even then, for service and repository code prefer injecting and using the Database instance directly. 

// explicit Database usage remains the preferred style
List<Customer> customers = database.find(Customer.class)
  .where().eq("status", Status.NEW)
  .findList();

// explicit Database usage remains the preferred style
val customers = database.find(Customer::class.java)
  .where().eq("status", Status.NEW)
  .findList()

Configuration

Details for configuration of Database instances using Database.builder() and explicit startup are in the next section.

 

Default database

A Database can be registered as the default database for compatibility with APIs that expect a default registered instance.

DB (optional / compatibility)

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

DB remains available for convenience and backwards compatibility, but the recommended approach for new applications is to keep and inject the Database instance returned from Database.builder() and call methods on that instance directly.

In practice it is still common to register databases when building them, because query beans, Model, and older convenience APIs resolve through the registry under the hood. The key point is that application code should prefer injected Database instances over direct use of DB convenience methods.

EbeanServer

io.ebean.EbeanServer is the older original name for io.ebean.Database.

For new code, prefer io.ebean.Database.

Ebean

io.ebean.Ebean is the older original name for io.ebean.DB.

For new code, prefer explicit Database usage and only use DB when you intentionally want global lookup or convenience methods.