Load a database configuration through Typesafe Config.
Load a database configuration through Typesafe Config.
The main config key to set is connectionPool
. It determines the connection pool
implementation to use. The default is HikariCP
(a.k.a. slick.jdbc.hikaricp.HikariCPJdbcDataSource$
)
for HikariCP). This requires the "slick-hikaricp"
dependency to be added to your project, in addition to "slick" itself. Use disabled
(a.k.a.
slick.jdbc.DataSourceJdbcDataSource$
) to disable connection pooling and use a DataSource or
the DriverManager directly. A third-party connection pool implementation can be selected by
specifying the fully qualified name of an object implementing JdbcDataSourceFactory.
The following config keys are supported for all connection pools, both built-in and third-party:
numThreads
(Int, optional, default: 20): The number of concurrent threads in the
thread pool for asynchronous execution of database actions. See the
HikariCP wiki
for more information about sizing the thread pool correctly. Note that for asynchronous
execution in Slick you should tune the thread pool size (this parameter) accordingly
instead of the maximum connection pool size.queueSize
(Int, optional, default: 1000): The size of the queue for database
actions which cannot be executed immediately when all threads are busy. Beyond this
limit new actions fail immediately. Set to 0 for no queue (direct hand-off) or to -1
for an unlimited queue size (not recommended).registerMbeans
(Boolean, optional, default: false): Whether or not JMX Management
Beans ("MBeans") are registered. Slick supports an MBean of its own for monitoring the
AsyncExecutor
with the thread pool and queue, but connection pool implementations
may register additional MBeans. In particular, HikariCP does this.poolName
(String, optional): A user-defined name for the connection pool in logging
and JMX management consoles to identify pools and pool configurations. This defaults to
the config path.The pool is tuned for asynchronous execution by default. Apart from the connection
parameters you should only have to set numThreads
and queueSize
in most cases. In this
scenario there is contention over the thread pool (via its queue), not over the
connections, so you can have a rather large limit on the maximum number of connections
(based on what the database server can still handle, not what is most efficient). Slick
will use more connections than there are threads in the pool when sequencing non-database
actions inside a transaction.
The following config keys are supported for HikariCP:
url
(String, required): JDBC URLdriver
or driverClassName
(String, optional): JDBC driver class to loaduser
(String, optional): User namepassword
(String, optional): Passwordisolation
(String, optional): Transaction isolation level for new connections.
Allowed values are: NONE
, READ_COMMITTED
, READ_UNCOMMITTED
, REPEATABLE_READ
,
SERIALIZABLE
.catalog
(String, optional): Default catalog for new connections.readOnly
(Boolean, optional): Read Only flag for new connections.properties
(Map, optional): Properties to pass to the driver or DataSource.dataSourceClass
(String, optional): The name of the DataSource class provided by
the JDBC driver. This is preferred over using driver
. Note that url
is ignored when
this key is set (You have to use properties
to configure the database
connection instead).maxConnections
(Int, optional, default: numThreads
* 5): The maximum number of
connections in the pool.minConnections
(Int, optional, default: same as numThreads
): The minimum number
of connections to keep in the pool.connectionTimeout
(Duration, optional, default: 1s): The maximum time to wait
before a call to getConnection is timed out. If this time is exceeded without a
connection becoming available, a SQLException will be thrown. 1000ms is the minimum
value.validationTimeout
(Duration, optional, default: 1s): The maximum amount of time
that a connection will be tested for aliveness. 1000ms is the minimum value.idleTimeout
(Duration, optional, default: 10min): The maximum amount
of time that a connection is allowed to sit idle in the pool. A value of 0 means that
idle connections are never removed from the pool.maxLifetime
(Duration, optional, default: 30min): The maximum lifetime of a
connection in the pool. When an idle connection reaches this timeout, even if recently
used, it will be retired from the pool. A value of 0 indicates no maximum
lifetime.connectionInitSql
(String, optional): A SQL statement that will be
executed after every new connection creation before adding it to the pool. If this SQL
is not valid or throws an exception, it will be treated as a connection failure and the
standard retry logic will be followed.initializationFailFast
(Boolean, optional, default: false): Controls whether the
pool will "fail fast" if the pool cannot be seeded with initial connections
successfully. If connections cannot be created at pool startup time, a RuntimeException
will be thrown. This property has no effect if minConnections
is 0.leakDetectionThreshold
(Duration, optional, default: 0): The amount of time that a
connection can be out of the pool before a message is logged indicating a possible
connection leak. A value of 0 means leak detection is disabled. Lowest acceptable value
for enabling leak detection is 10s.connectionTestQuery
(String, optional): A statement that will be executed just
before a connection is obtained from the pool to validate that the connection to the
database is still alive. It is database dependent and should be a query that takes very
little processing by the database (e.g. "VALUES 1"). When not set, the JDBC4
Connection.isValid()
method is used instead (which is usually preferable).Direct connections are based on a java.sql.DataSource
or a java.sql.Driver
. This is
determined by the presence or absence of the dataSourceClass
config key. The following
keys are supported for direct connections in DataSource mode:
dataSourceClass
(String): The name of the DataSource class provided by
the JDBC driver.properties
(Map, optional): Java Bean properties to set on the DataSource.The following keys are supported for direct connections in Driver mode:
url
(String, required): JDBC URLdriver
or driverClassName
(String, optional): JDBC driver class to load. If not
specified, the DriverManager is expected to already know how to handle the URL. Slick
will check if the driver class is already registered before loading a new copy.user
(String, optional): User namepassword
(String, optional): Passwordproperties
(Map, optional): Connection properties to pass to the driver.deregisterDriver
(Boolean, optional, default: false): If this is set to true and
Slick loaded a JDBC driver when creating the Database object, it attempts to deregister
that driver from the DriverManager when close()
is called. Note that this may
prevent the same driver from being registered again within the same ClassLoader through
the usual automatic registration process.The following additional keys are supported for all direct connections:
isolation
(String, optional): Transaction isolation level for new connections.
Allowed values are: NONE
, READ_COMMITTED
, READ_UNCOMMITTED
, REPEATABLE_READ
,
SERIALIZABLE
.catalog
(String, optional): Default catalog for new connections.readOnly
(Boolean, optional): Read Only flag for new connections.keepAliveConnection
(Boolean, optional, default: false): If this is set to true,
one extra connection will be opened as soon as the database is accessed for the first
time, and kept open until close()
is called. This is useful for named in-memory
databases in test environments.Note that Driver mode is equivalent to using DataSource mode with a DriverDataSource
and moving the config keys url
, user
, password
, properties
and driver
/
driverClassName
down into the DataSource properties
, except that DataSource mode
always uses the default ClassLoader whereas Driver mode can be used with alternate
ClassLoaders.
Unknown keys are ignored. Invalid values or missing mandatory keys will trigger a SlickException.
The path in the configuration file for the database configuration (e.g. foo.bar
would find a database URL at config key foo.bar.url
) or an empty string for
the top level of the Config
object.
The Config
object to read from. This defaults to the global app config
(e.g. in application.conf
at the root of the class path) if not specified.
An optional JDBC driver to call directly. If this is set to a non-null value,
the driver
key from the configuration is ignored. The default is to use the
standard lookup mechanism. The explicit driver may not be supported by all
connection pools (in particular, the default HikariCPJdbcDataSource).
The ClassLoader to use to load any custom classes from. The default is to try the context ClassLoader first and fall back to Slick's ClassLoader.
Create a Database based on a DataSource.
Create a Database based on a DataSource.
The DataSource to use.
The AsyncExecutor for scheduling database actions.
If this is set to true, one extra connection will be opened as soon as the database
is accessed for the first time, and kept open until close()
is called. This is
useful for named in-memory databases in test environments.
Create a Database that directly uses a Driver to open new connections.
Create a Database that directly uses a Driver to open new connections. This is needed to open a JDBC URL with a driver that was not loaded by the system ClassLoader.
Create a Database based on the JNDI name of a DataSource.
Create a Database based on the JNDI name of a DataSource.
The AsyncExecutor for scheduling database actions.
Create a Database based on a JdbcDataSource.
Create a Database that uses the DriverManager to open new connections.
Create a Database that uses the DriverManager to open new connections.