Play Framework JDBC support library providing database access, connection pooling, and database configuration management for Play applications.
—
API for managing multiple database configurations in a single application, with named database support and lifecycle management.
Primary interface for managing multiple databases in Scala.
trait DBApi {
/** All configured databases */
def databases(): Seq[Database]
/** Get database with given configuration name */
def database(name: String): Database
/** Shutdown all databases, releasing resources */
def shutdown(): Unit
}Usage Examples:
import play.api.db._
import javax.inject.Inject
class MultiDbController @Inject()(dbApi: DBApi) {
// Access specific databases by name
def getUserData(userId: Long) = {
val userDb = dbApi.database("users")
val profileDb = dbApi.database("profiles")
userDb.withConnection { implicit conn =>
// Query user data
val stmt = conn.prepareStatement("SELECT name FROM users WHERE id = ?")
stmt.setLong(1, userId)
val rs = stmt.executeQuery()
// ... process results
}
}
// Iterate over all databases
def performMaintenance() = {
dbApi.databases().foreach { db =>
println(s"Performing maintenance on database: ${db.name}")
db.withConnection { implicit conn =>
// Maintenance operations
conn.prepareStatement("ANALYZE").execute()
}
}
}
// Graceful shutdown
def cleanup() = {
dbApi.shutdown()
}
}Primary interface for managing multiple databases in Java.
public interface DBApi {
/** @return all configured databases */
List<Database> getDatabases();
/** Get database with given configuration name */
Database getDatabase(String name);
/** Shutdown all databases, releasing resources */
void shutdown();
}Usage Examples:
import play.db.*;
import javax.inject.Inject;
import java.util.List;
public class MultiDbController {
private final DBApi dbApi;
@Inject
public MultiDbController(DBApi dbApi) {
this.dbApi = dbApi;
}
// Access specific databases by name
public void processUserData(long userId) {
Database userDb = dbApi.getDatabase("users");
Database logDb = dbApi.getDatabase("logs");
userDb.withConnection(connection -> {
PreparedStatement stmt = connection.prepareStatement("SELECT email FROM users WHERE id = ?");
stmt.setLong(1, userId);
ResultSet rs = stmt.executeQuery();
// ... process results
});
logDb.withConnection(connection -> {
PreparedStatement stmt = connection.prepareStatement("INSERT INTO access_log (user_id, timestamp) VALUES (?, ?)");
stmt.setLong(1, userId);
stmt.setTimestamp(2, new Timestamp(System.currentTimeMillis()));
stmt.executeUpdate();
});
}
// Iterate over all databases
public void performHealthCheck() {
List<Database> databases = dbApi.getDatabases();
for (Database db : databases) {
try {
db.withConnection(connection -> {
PreparedStatement stmt = connection.prepareStatement("SELECT 1");
stmt.executeQuery();
});
System.out.println("Database " + db.getName() + " is healthy");
} catch (Exception e) {
System.err.println("Database " + db.getName() + " failed health check: " + e.getMessage());
}
}
}
}Default implementation of the DBApi interface.
class DefaultDBApi(
configuration: Map[String, Config],
defaultConnectionPool: ConnectionPool = new HikariCPConnectionPool(Environment.simple()),
environment: Environment = Environment.simple(),
injector: Injector = NewInstanceInjector
) extends DBApi {
/** Try to initialize all the configured databases */
def initialize(logInitialization: Boolean): Unit
/** @deprecated Use initialize instead */
@deprecated("Use initialize instead, which does not try to connect to the database", "2.7.0")
def connect(logConnection: Boolean = false): Unit
}Usage Examples:
import play.api.db._
import play.api.{Configuration, Environment}
import com.typesafe.config.ConfigFactory
// Create DBApi manually for testing
val config = Map(
"default" -> ConfigFactory.parseString("""
driver = "org.h2.Driver"
url = "jdbc:h2:mem:test"
"""),
"cache" -> ConfigFactory.parseString("""
driver = "org.h2.Driver"
url = "jdbc:h2:mem:cache"
""")
)
val dbApi = new DefaultDBApi(config)
dbApi.initialize(logInitialization = true)
try {
val defaultDb = dbApi.database("default")
val cacheDb = dbApi.database("cache")
// Use databases...
} finally {
dbApi.shutdown()
}Support for injecting specific databases by name using dependency injection.
/** Qualifier annotation for dependency injection of named databases */
@Qualifier
@Retention(RetentionPolicy.RUNTIME)
public @interface NamedDatabase {
String value();
}
/** Implementation class for NamedDatabase annotation */
public class NamedDatabaseImpl implements NamedDatabase, Serializable {
public NamedDatabaseImpl(String value);
public String value();
}Usage Examples:
import play.db.*;
import javax.inject.Inject;
public class UserService {
private final Database userDb;
private final Database sessionDb;
@Inject
public UserService(
@NamedDatabase("users") Database userDb,
@NamedDatabase("sessions") Database sessionDb
) {
this.userDb = userDb;
this.sessionDb = sessionDb;
}
public void authenticateUser(String username, String password) {
// Use userDb for user lookup
Optional<User> user = userDb.withConnection(connection -> {
// User authentication logic
return findUser(username, password, connection);
});
if (user.isPresent()) {
// Use sessionDb for session management
sessionDb.withConnection(connection -> {
PreparedStatement stmt = connection.prepareStatement(
"INSERT INTO sessions (user_id, session_token, created_at) VALUES (?, ?, ?)"
);
stmt.setLong(1, user.get().getId());
stmt.setString(2, generateSessionToken());
stmt.setTimestamp(3, new Timestamp(System.currentTimeMillis()));
stmt.executeUpdate();
});
}
}
}Type alias for compatibility between Scala and Java APIs.
package object db {
type NamedDatabase = play.db.NamedDatabase
}Multiple databases are configured in application.conf:
# Database configuration key (default: "db")
play.db.config = "db"
# Default database name (default: "default")
play.db.default = "default"
# Multiple database configurations
db {
default {
driver = "org.postgresql.Driver"
url = "jdbc:postgresql://localhost/myapp"
username = "dbuser"
password = "dbpass"
}
cache {
driver = "org.h2.Driver"
url = "jdbc:h2:mem:cache"
}
analytics {
driver = "org.postgresql.Driver"
url = "jdbc:postgresql://analytics-server/warehouse"
username = "analyst"
password = "secret"
pool = "hikaricp"
}
}initialize() to set up all configured databasesshutdown() to gracefully close all database connections and connection poolsApplicationLifecycleInstall with Tessl CLI
npx tessl i tessl/maven-com-typesafe-play--play-jdbc-2-11