1. Home
2. Working with Play
3. Common topics
4. Configuration

§Configuring the JDBC pool

The Play JDBC datasource is managed by HikariCP.

§Special URLs

Play supports special url format for both MySQL and PostgreSQL:

# To configure MySQL
db.default.url="mysql://user:password@localhost/database"

# To configure PostgreSQL
db.default.url="postgres://user:password@localhost/database"

A non-standard port of the database service can be specified:

# To configure MySQL running in Docker
db.default.url="mysql://user:password@localhost:port/database"

# To configure PostgreSQL running in Docker
db.default.url="postgres://user:password@localhost:port/database"

§Reference

In addition to the classical driver, url, username, password configuration properties, it also supports additional tuning parameters if you need them. The play.db.prototype configuration from the Play JDBC reference.conf is used as the prototype for the configuration for all database connections. The defaults for all the available configuration options can be seen here:

# Copyright (C) Lightbend Inc. <https://www.lightbend.com>

play {

  modules {
    enabled += "play.api.db.DBModule"
    enabled += "play.api.db.HikariCPModule"
  }

  # Database configuration
  db {
    # The name of the configuration item from which to read database config.
    # So, if set to db, means that db.default is where the configuration for the
    # database named default is found.
    config = "db"

    # The name of the default database, used when no database name is explicitly
    # specified.
    default = "default"

    # The default connection pool.
    # Valid values are:
    #  - default - Use the default connection pool provided by the platform (HikariCP)
    #  - hikaricp - Use HikariCP
    #  - A FQCN to a class that implements play.api.db.ConnectionPool
    pool = "default"

    # The prototype for database configuration
    prototype = {

      # The connection pool for this database.
      # Valid values are:
      #  - default - Delegate to play.db.pool
      #  - hikaricp - Use HikariCP
      #  - A FQCN to a class that implements play.api.db.ConnectionPool
      pool = "default"

      # The database driver
      driver = null

      # The database url
      url = null

      # The username
      username = null

      # The password
      password = null

      # If non null, binds the JNDI name to this data source to the given JNDI name.
      jndiName = null

      # If it should log sql statements
      logSql = false

      # HikariCP configuration options
      hikaricp {

        # The datasource class name, if not using a URL
        dataSourceClassName = null

        # Data source configuration options
        dataSource {
        }

        # Whether autocommit should be used
        autoCommit = true

        # The connection timeout
        connectionTimeout = 30 seconds

        # The idle timeout
        idleTimeout = 10 minutes

        # The max lifetime of a connection
        maxLifetime = 30 minutes

        # If non null, the query that should be used to test connections
        connectionTestQuery = null

        # If non null, sets the minimum number of idle connections to maintain.
        minimumIdle = null

        # The maximum number of connections to make.
        maximumPoolSize = 10

        # If non null, sets the name of the connection pool. Primarily used for stats reporting.
        poolName = null

        # This property controls whether the pool will "fail fast" if the pool cannot be seeded with
        # an initial connection successfully.
        # 1. Any positive number is taken to be the number of milliseconds to attempt to acquire an initial connection;
        #    the application thread will be blocked during this period. If a connection cannot be acquired before this
        #    timeout occurs, an exception will be thrown. This timeout is applied after the connectionTimeout period.
        # 2. If the value is zero (0), HikariCP will attempt to obtain and validate a connection. If a connection
        #    is obtained, but fails validation, an exception will be thrown and the pool not started. However, if
        #    a connection cannot be obtained, the pool will start, but later efforts to obtain a connection may fail.
        # 3. A value less than zero will bypass any initial connection attempt, and the pool will start immediately
        #    while trying to obtain connections in the background. Consequently, later efforts to obtain a connection
        #    may fail.
        initializationFailTimeout = -1

        # Sets whether internal queries should be isolated
        isolateInternalQueries = false

        # Sets whether pool suspension is allowed.  There is a performance impact to enabling it.
        allowPoolSuspension = false

        # Sets whether connections should be read only
        readOnly = false

        # Sets whether mbeans should be registered
        registerMbeans = false

        # If non null, sets the catalog that should be used on connections
        catalog = null

        # A SQL statement that will be executed after every new connection creation before adding it to the pool
        connectionInitSql = null

        # If non null, sets the transaction isolation level
        transactionIsolation = null

        # The user-supplied SQLExceptionOverride class name.
        exceptionOverrideClassName = null

        # The validation timeout to use
        validationTimeout = 5 seconds

        # If non null, sets the threshold for the amount of time that a connection has been out of the pool before it is
        # considered to have leaked
        leakDetectionThreshold = null
      }
    }
  }
}

When you need to specify some settings for a connection pool, you can override the prototype settings. For example, to set maximumPoolSize for HikariCP, you would set the following in your application.conf file:

db.default.hikaricp.maximumPoolSize = 15

In case you need to specify some driver-specific properties for connections in the pool, you can set them in the dataSource configuration. For example, to set queryTimeout of the jdbc SQLServerDriver using HikariCP, you would set the following in your application.conf file:

db.default.hikaricp.dataSource.queryTimeout = 15

Next: Configuring Play's thread pools