You are viewing the documentation for the 2.6.x release series. 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:
# 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
# - 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
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. Have questions or advice to share? Go to our community forums to start a conversation with the community.