DatabaseFactoryDef
Related Doc:
package JdbcBackend
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:
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).jdbcUrl or url (String, required): JDBC URLusername or user (String, optional): User namepassword (String, optional): PasswordautoCommit (Boolean, optional, default: true): controls the default auto-commit
behavior of connections returned from the pool.connectionTimeout (Duration, optional, default: 30s): The maximum number of milliseconds that a
client (that's you) will wait for a connection from the pool. If this time is exceeded without a
connection becoming available, a SQLException will be thrown. Lowest acceptable connection timeout is 250 msidleTimeout (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.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).minimumIdle or minConnections (Int, optional, default: same as numThreads): The minimum number
of connections to keep in the pool.maximumPoolSize or maxConnections (Int, optional, default: numThreads): The maximum number of
connections in the pool.initializationFailTimeout (Long, optional, default: 1): controls whether the pool will
"fail fast" if the pool cannot be seeded with an initial connection successfully. 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. 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. 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.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.isolateInternalQueries (Boolean, optional, default: false): determines whether HikariCP
isolates internal pool queries, such as the connection alive test, in their own transaction.
Since these are typically read-only queries, it is rarely necessary to encapsulate them in their
own transaction. This property only applies if autoCommit is disabled.allowPoolSuspension (Boolean, optional, default: false): controls whether the pool can be
suspended and resumed through JMX. This is useful for certain failover automation scenarios.
When the pool is suspended, calls to getConnection() will not timeout and will be held until
the pool is resumed.readOnly (Boolean, optional): Read Only flag for new connections.catalog (String, optional): Default catalog for new connections.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.driver or driverClassName (String, optional): JDBC driver class to loadtransactionIsolation or isolation (String, optional): Transaction isolation level for new connections.
Allowed values are: NONE, READ_COMMITTED, READ_UNCOMMITTED, REPEATABLE_READ,
SERIALIZABLE.validationTimeout (Duration, optional, default: 5s): The maximum amount of time that a connection will
be tested for aliveness. This value must be less than the connectionTimeout.
Lowest acceptable validation timeout is 250 ms.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.schema (String, optional): Default catalog for new connections.properties (Map, optional): Properties to pass to the driver or DataSource.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 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 maximum number of connections that the DataSource can provide. This is necessary to
prevent deadlocks when scheduling database actions. Use None if there is no hard limit.
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.
NOTE: this method will return a Slick DatabaseDef configured to use the named DataSource and the passed AsyncExecutor. Calling this method more then once for the same DataSource name, will result in different DatabaseDefs configured with different AsyncExecutors but backed by the same DataSource. This is probably not what you want. Therefore, it's recommended to call it only once and re-use the returned DatabaseDef whenever needed. Each DataSource should be associated with only one AsyncExecutor.
The name of the DataSource to use.
The maximum number of connections that the DataSource can provide. This is necessary to
prevent deadlocks when scheduling database actions. Use None if there is no hard limit.
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.