You are viewing the documentation for the 2.4.x release series. The latest stable release series is 2.5.x.

§Accessing an SQL database

§Configuring JDBC connection pools

Play provides a plug-in for managing JDBC connection pools. You can configure as many databases as you need.

To enable the database plug-in, add jdbc in your build dependencies :

libraryDependencies += jdbc

Then you must configure a connection pool in the conf/application.conf file. By convention, the default JDBC data source must be called default and the corresponding configuration properties are db.default.driver and db.default.url.

If something isn’t properly configured you will be notified directly in your browser:

Note: You likely need to enclose the JDBC URL configuration value with double quotes, since ‘:’ is a reserved character in the configuration syntax.

§H2 database engine connection properties

In memory database:

# Default database configuration using H2 database engine in an in-memory mode

File based database:

# Default database configuration using H2 database engine in a persistent mode

The details of the H2 database URLs are found from H2 Database Engine Cheat Sheet.

§SQLite database engine connection properties

# Default database configuration using SQLite database engine

§PostgreSQL database engine connection properties

# Default database configuration using PostgreSQL database engine

§MySQL database engine connection properties

# Default database configuration using MySQL database engine
# Connect to playdb as playdbuser
db.default.password="a strong password"

§How to configure several data sources

# Orders database

# Customers database

§Configuring the JDBC Driver

Play is bundled only with an H2 database driver. Consequently, to deploy in production you will need to add your database driver as a dependency.

For example, if you use MySQL5, you need to add a dependency for the connector:

libraryDependencies += "mysql" % "mysql-connector-java" % "5.1.34"

Or if the driver can’t be found from repositories you can drop the driver into your project’s unmanaged dependencies lib directory.

§Accessing the JDBC datasource

The play.api.db package provides access to the configured data sources:

import play.api.db._

val ds = DB.getDataSource()

§Obtaining a JDBC connection

There are several ways to retrieve a JDBC connection. The simplest way is:

val connection = DB.getConnection()

Following code show you a JDBC example very simple, working with MySQL 5.*:

package controllers
import play.api.Play.current
import play.api.mvc._
import play.api.db._

object Application extends Controller {

  def index = Action {
    var outString = "Number is "
    val conn = DB.getConnection()
    try {
      val stmt = conn.createStatement
      val rs = stmt.executeQuery("SELECT 9 as testkey ")
      while ( {
        outString += rs.getString("testkey")
    } finally {


But of course you need to call close() at some point on the opened connection to return it to the connection pool. Another way is to let Play manage closing the connection for you:

// access "default" database
DB.withConnection { conn =>
  // do whatever you need with the connection

For a database other than the default:

// access "orders" database instead of "default"
DB.withConnection("orders") { conn =>
  // do whatever you need with the connection

The connection will be automatically closed at the end of the block.

Tip: Each Statement and ResultSet created with this connection will be closed as well.

A variant is to set the connection’s auto-commit to false and to manage a transaction for the block:

DB.withTransaction { conn =>
  // do whatever you need with the connection

§Selecting and configuring the connection pool

Out of the box, Play provides two database connection pool implementations, HikariCP and BoneCP. The default is HikariCP, but this can be changed by setting the play.db.pool property:


The full range of configuration options for connection pools can be found by inspecting the play.db.prototype property in Play’s JDBC reference.conf.


For information on testing with databases, including how to setup in-memory databases and, see Testing With Databases.

§Enabling Play database evolutions

Read Evolutions to find out what Play database evolutions are useful for, and follow the setup instructions for using it.

Next: Using Slick to access your database

Found an error in this documentation? The source code for this page can be found here. After reading the documentation guidelines, please feel free to contribute a pull request.