§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) from 2022 The Play Framework Contributors <https://github.com/playframework>, 2011-2021 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
# If non null, controls how frequently HikariCP will attempt to keep a connection alive
keepaliveTime = null
# 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.
# Defaults to the database configuration item name.
# 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
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.