CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-com-typesafe-play--play-jdbc-2-11

Play Framework JDBC support library providing database access, connection pooling, and database configuration management for Play applications.

Pending
Overview
Eval results
Files

database-management.mddocs/

Multi-Database Management

API for managing multiple database configurations in a single application, with named database support and lifecycle management.

Capabilities

DBApi Interface (Scala)

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

DBApi Interface (Java)

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

DefaultDBApi Implementation

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

Named Database Injection

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

Package Object Type Alias

Type alias for compatibility between Scala and Java APIs.

package object db {
  type NamedDatabase = play.db.NamedDatabase
}

Configuration

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"
  }
}

Error Handling

  • IllegalArgumentException: Thrown when requesting a database that doesn't exist
  • Configuration errors: Thrown during initialization for invalid database configurations
  • Connection errors: Thrown during database initialization if connections cannot be established

Lifecycle Management

  • Initialization: Call initialize() to set up all configured databases
  • Shutdown: Call shutdown() to gracefully close all database connections and connection pools
  • Automatic lifecycle: When using Play's dependency injection, lifecycle is managed automatically through ApplicationLifecycle

Install with Tessl CLI

npx tessl i tessl/maven-com-typesafe-play--play-jdbc-2-11

docs

connection-pooling.md

database-configuration.md

database-management.md

database-operations.md

dependency-injection.md

index.md

tile.json