0
# Play JDBC
1

2
Play JDBC is the database access module for the Play Framework, providing comprehensive database connectivity through both Scala and Java APIs. It offers connection pooling via HikariCP, transaction management, database configuration support, and utilities for database operations in Play applications.
3

4
## Package Information
5

6
- **Package Name**: play-jdbc_2.11
7
- **Package Type**: maven (Scala/SBT)
8
- **Language**: Scala with Java interoperability
9
- **Installation**: `libraryDependencies += "com.typesafe.play" %% "play-jdbc" % "2.7.9"`
10

11
## Core Imports
12

13
**Scala API:**
14

15
```scala
16
import play.api.db._
17
import java.sql.Connection
18
import javax.sql.DataSource
19
import javax.inject.Inject
20
```
21

22
**Java API:**
23

24
```java
25
import play.db.*;
26
import java.sql.Connection;
27
import javax.sql.DataSource;
28
import javax.inject.Inject;
29
```
30

31
## Basic Usage
32

33
### Scala API
34

35
```scala
36
import play.api.db._
37
import java.sql.Connection
38
import javax.inject.Inject
39

40
class UserController @Inject()(db: Database) {
41
  def getUser(id: Long) = {
42
    db.withConnection { implicit connection =>
43
      // Execute SQL queries
44
      val stmt = connection.prepareStatement("SELECT name FROM users WHERE id = ?")
45
      stmt.setLong(1, id)
46
      val rs = stmt.executeQuery()
47
      if (rs.next()) Some(rs.getString("name")) else None
48
    }
49
  }
50
  
51
  def createUser(name: String) = {
52
    db.withTransaction { implicit connection =>
53
      val stmt = connection.prepareStatement("INSERT INTO users (name) VALUES (?)")
54
      stmt.setString(1, name)
55
      stmt.executeUpdate()
56
    }
57
  }
58
}
59
```
60

61
### Java API
62

63
```java
64
import play.db.*;
65
import javax.inject.Inject;
66

67
public class UserController {
68
    private final Database db;
69
    
70
    @Inject
71
    public UserController(Database db) {
72
        this.db = db;
73
    }
74
    
75
    public Optional<String> getUser(long id) {
76
        return db.withConnection(connection -> {
77
            PreparedStatement stmt = connection.prepareStatement("SELECT name FROM users WHERE id = ?");
78
            stmt.setLong(1, id);
79
            ResultSet rs = stmt.executeQuery();
80
            return rs.next() ? Optional.of(rs.getString("name")) : Optional.empty();
81
        });
82
    }
83
    
84
    public void createUser(String name) {
85
        db.withTransaction(connection -> {
86
            PreparedStatement stmt = connection.prepareStatement("INSERT INTO users (name) VALUES (?)");
87
            stmt.setString(1, name);
88
            stmt.executeUpdate();
89
        });
90
    }
91
}
92
```
93

94
## Architecture
95

96
Play JDBC is organized around several key components:
97

98
- **Database Trait/Interface**: Core API for database operations, connection management, and transactions
99
- **DBApi Trait/Interface**: Multi-database management API for applications with multiple data sources
100
- **Connection Pool**: HikariCP-based connection pooling with configurable parameters
101
- **Configuration System**: Type-safe database configuration with support for multiple environments
102
- **Dependency Injection**: Full integration with Play's DI system for both runtime and compile-time injection
103
- **Transaction Management**: Automatic transaction handling with isolation level support
104

105
## Capabilities
106

107
### Database Operations
108

109
Core database connectivity providing connection management, transaction support, and resource handling for both Scala and Java APIs.
110

111
```scala { .api }
112
trait Database {
113
  def name: String
114
  def dataSource: DataSource
115
  def getConnection(): Connection
116
  def withConnection[A](block: Connection => A): A
117
  def withTransaction[A](block: Connection => A): A
118
}
119
```
120

121
```java { .api }
122
public interface Database {
123
  String getName();
124
  DataSource getDataSource();
125
  Connection getConnection();
126
  <A> A withConnection(ConnectionCallable<A> block);
127
  void withTransaction(ConnectionRunnable block);
128
}
129
```
130

131
[Database Operations](./database-operations.md)
132

133
### Multi-Database Management
134

135
API for managing multiple database configurations in a single application, with named database support.
136

137
```scala { .api }
138
trait DBApi {
139
  def databases(): Seq[Database]
140
  def database(name: String): Database
141
  def shutdown(): Unit
142
}
143
```
144

145
```java { .api }
146
public interface DBApi {
147
  List<Database> getDatabases();
148
  Database getDatabase(String name);
149
  void shutdown();
150
}
151
```
152

153
[Multi-Database Management](./database-management.md)
154

155
### Connection Pooling
156

157
HikariCP-based connection pool implementation with comprehensive configuration options and performance monitoring.
158

159
```scala { .api }
160
trait ConnectionPool {
161
  def create(name: String, dbConfig: DatabaseConfig, configuration: Config): DataSource
162
  def close(dataSource: DataSource): Unit
163
}
164
```
165

166
[Connection Pooling](./connection-pooling.md)
167

168
### Database Configuration
169

170
Type-safe configuration system supporting multiple databases, JNDI, and environment-specific settings.
171

172
```scala { .api }
173
case class DatabaseConfig(
174
  driver: Option[String],
175
  url: Option[String], 
176
  username: Option[String],
177
  password: Option[String],
178
  jndiName: Option[String]
179
)
180
```
181

182
[Database Configuration](./database-configuration.md)
183

184
### Dependency Injection
185

186
Runtime and compile-time dependency injection modules with support for named databases and lifecycle management.
187

188
```scala { .api }
189
class DBModule extends SimpleModule
190
trait DBComponents {
191
  def dbApi: DBApi
192
}
193
```
194

195
```java { .api }
196
@NamedDatabase("users")
197
@Inject
198
private Database userDb;
199
```
200

201
[Dependency Injection](./dependency-injection.md)
202

203
## Types
204

205
### Transaction Isolation Levels
206

207
```scala { .api }
208
sealed abstract class TransactionIsolationLevel(val id: Int)
209
object TransactionIsolationLevel {
210
  case object ReadUncommitted extends TransactionIsolationLevel(Connection.TRANSACTION_READ_UNCOMMITTED)
211
  case object ReadCommitted extends TransactionIsolationLevel(Connection.TRANSACTION_READ_COMMITTED)
212
  case object RepeatedRead extends TransactionIsolationLevel(Connection.TRANSACTION_REPEATABLE_READ)
213
  case object Serializable extends TransactionIsolationLevel(Connection.TRANSACTION_SERIALIZABLE)
214
}
215
```
216

217
```java { .api }
218
public enum TransactionIsolationLevel {
219
  ReadUncommitted(Connection.TRANSACTION_READ_UNCOMMITTED),
220
  ReadCommitted(Connection.TRANSACTION_READ_COMMITTED),
221
  RepeatedRead(Connection.TRANSACTION_REPEATABLE_READ),
222
  Serializable(Connection.TRANSACTION_SERIALIZABLE);
223
}
224

225
@FunctionalInterface
226
public interface ConnectionCallable<A> {
227
  A call(Connection connection) throws SQLException;
228
}
229

230
@FunctionalInterface
231
public interface ConnectionRunnable {
232
  void run(Connection connection) throws SQLException;
233
}
234
```