Documentation

You are viewing the documentation for the 2.6.6 release in the 2.6.x series of releases. The latest stable release series is 3.0.x.

§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:

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
    #  - bonecp - Use BoneCP
    #  - 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
      #  - bonecp - Use BoneCP
      #  - 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 or not construction of the pool should fail if the minimum number of connections
        # couldn't be created.
        # Deprecated value in HikariCP, initializationFailTimeout should be used instead.
        # This configuration value is optional, so commenting it out removes the runtime warning from HikariCP.
        #initializationFailFast = true

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

      # BoneCP configuration options
      bonecp {

        # Whether autocommit should be used
        autoCommit = true

        # If non null, the transaction isolation level to use.
        isolation = null

        # If non null, sets the catolog to use
        defaultCatalog = null

        # Whether the database should be treated as read only
        readOnly = false

        # Whether opened statements should be automatically closed
        closeOpenStatements = true

        # The pool partition count
        partitionCount = 1

        # The maximum number of connections per partition
        maxConnectionsPerPartition = 30

        # The minimum number of connections per partition
        minConnectionsPerPartition = 5

        # The increment to acquire connections in
        acquireIncrement = 1

        # The acquire retry attempts
        acquireRetryAttempts = 10

        # The delay to wait before retrying to acquire a connection
        acquireRetryDelay = 1 second

        # The connection timeout
        connectionTimeout = 1 second

        # The idle age to expire connections
        idleMaxAge = 10 minutes

        # The maximum a connection should live for
        maxConnectionAge = 1 hour

        # Whether JMX reporting should be disabled
        disableJMX = true

        # Whether statistics should be kept
        statisticsEnabled = false

        # How frequently idle connections should be tested
        idleConnectionTestPeriod = 1 minute

        # Disable connection tracking
        disableConnectionTracking = true

        # The time limit for executing queries. 0 means no time limit.
        queryExecuteTimeLimit = 0

        # Whether the connection should be reset when closed
        resetConnectionOnClose = false

        # Whether unresolved transactions should be detected
        detectUnresolvedTransactions = false

        # An SQL statement to execute to test if a connection is ok after it is created.
        # Null turns this feature off.
        initSQL = null

        # An SQL statement to execute to test if a connection is ok before giving it out of the pool.
        # Null turns this feature off.
        connectionTestStatement = null

        # Whether SQL statements should be logged
        logStatements = false
      }
    }
  }
}

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

play.db.pool=bonecp
play.db.prototype.bonecp.maxConnectionsPerPartition = 50

Next: Configuring Play's thread pools