0
# Slick-HikariCP
1

2
Slick-HikariCP provides HikariCP connection pool integration for Slick, the Scala Language-Integrated Connection Kit. It enables high-performance database connection management with comprehensive configuration options, automatic pool lifecycle management, and seamless integration with Slick's asynchronous database access layer.
3

4
## Package Information
5

6
- **Package Name**: slick-hikaricp
7
- **Package Type**: maven
8
- **Language**: Scala
9
- **Installation**: Add to your `build.sbt`:
10
  ```scala
11
  libraryDependencies += "com.typesafe.slick" %% "slick-hikaricp" % "3.6.1"
12
  ```
13

14
## Core Imports
15

16
```scala
17
import slick.jdbc.hikaricp.HikariCPJdbcDataSource
18
```
19

20
For using with Slick databases:
21

22
```scala
23
import slick.jdbc.JdbcBackend.Database
24
```
25

26
## Basic Usage
27

28
```scala
29
import slick.jdbc.JdbcBackend.Database
30
import slick.jdbc.hikaricp.HikariCPJdbcDataSource
31
import com.typesafe.config.ConfigFactory
32

33
// Using Database.forConfig with HikariCP
34
val config = ConfigFactory.parseString("""
35
  mydb {
36
    profile = "slick.jdbc.H2Profile$"
37
    db {
38
      connectionPool = "slick.jdbc.hikaricp.HikariCPJdbcDataSource$"
39
      dataSourceClass = "slick.jdbc.DriverDataSource"
40
      properties = {
41
        driver = "org.h2.Driver"
42
        url = "jdbc:h2:mem:test"
43
      }
44
      numThreads = 10
45
      maximumPoolSize = 20
46
      minimumIdle = 5
47
      connectionTimeout = 30000
48
    }
49
  }
50
""")
51

52
val db = Database.forConfig("mydb.db", config)
53

54
// Use the database for queries
55
// db.run(...)
56

57
// Clean up when done
58
db.close()
59
```
60

61
## Capabilities
62

63
### HikariCP Data Source
64

65
A JdbcDataSource implementation that wraps HikariCP's connection pooling capabilities.
66

67
```scala { .api }
68
class HikariCPJdbcDataSource(
69
  val ds: com.zaxxer.hikari.HikariDataSource, 
70
  val hconf: com.zaxxer.hikari.HikariConfig
71
) extends JdbcDataSource {
72
  def createConnection(): java.sql.Connection
73
  def close(): Unit
74
  override val maxConnections: Option[Int]
75
}
76
```
77

78
**Parameters:**
79
- `ds`: The underlying HikariCP data source instance
80
- `hconf`: The HikariCP configuration used to create the data source
81

82
**Methods:**
83
- `createConnection()`: Creates a new database connection from the pool
84
- `close()`: Closes the data source and releases all connections in the pool
85
- `maxConnections`: Returns `Some(maximumPoolSize)` from the HikariCP configuration
86

87
### Data Source Factory
88

89
Factory object for creating HikariCPJdbcDataSource instances from Typesafe Config.
90

91
```scala { .api }
92
object HikariCPJdbcDataSource extends JdbcDataSourceFactory {
93
  def forConfig(
94
    c: com.typesafe.config.Config, 
95
    driver: java.sql.Driver, 
96
    name: String, 
97
    classLoader: ClassLoader
98
  ): HikariCPJdbcDataSource
99
}
100
```
101

102
**Parameters:**
103
- `c`: Typesafe Config object containing HikariCP configuration
104
- `driver`: JDBC driver instance (may be null if using dataSourceClassName)
105
- `name`: Name for the connection pool
106
- `classLoader`: ClassLoader for loading driver classes
107

108
**Returns:** A new `HikariCPJdbcDataSource` instance configured according to the provided config
109

110
### Configuration Options
111

112
The `forConfig` method supports extensive HikariCP configuration through Typesafe Config:
113

114
#### Essential Connection Settings
115

116
```scala { .api }
117
// Data source configuration (choose one approach)
118
dataSourceClassName: String     // Preferred: HikariCP data source class name
119
dataSourceClass: String         // Alternative name for dataSourceClassName  
120
driverClassName: String         // Fallback: JDBC driver class name
121
driver: String                  // Alternative name for driverClassName
122

123
// Connection details
124
jdbcUrl: String                 // JDBC URL (use with old drivers)
125
url: String                     // Alternative name for jdbcUrl
126
username: String                // Database username
127
user: String                    // Alternative name for username  
128
password: String                // Database password
129
properties: Map[String, String] // Additional data source properties
130
```
131

132
#### Pool Sizing and Threading
133

134
```scala { .api }
135
numThreads: Int                 // Base thread count (default: 20)
136
maximumPoolSize: Int            // Maximum pool size (default: numThreads)
137
maxConnections: Int             // Alternative name for maximumPoolSize
138
minimumIdle: Int                // Minimum idle connections (default: numThreads)
139
minConnections: Int             // Alternative name for minimumIdle
140
```
141

142
#### Timeout Configuration
143

144
```scala { .api }
145
connectionTimeout: Long         // Connection timeout in milliseconds (default: 30000)
146
idleTimeout: Long               // Idle timeout in milliseconds (default: 600000)
147
maxLifetime: Long               // Maximum connection lifetime in milliseconds (default: 1800000)
148
validationTimeout: Long         // Connection validation timeout in milliseconds (default: 5000)
149
initializationFailTimeout: Long // Pool initialization timeout in milliseconds (default: -1)
150
leakDetectionThreshold: Long    // Connection leak detection threshold in milliseconds (default: 0)
151
keepAliveTime: Long             // Connection keep-alive time in milliseconds
152
```
153

154
#### Connection Behavior
155

156
```scala { .api }
157
autoCommit: Boolean             // Auto-commit behavior
158
readOnly: Boolean               // Mark connections as read-only
159
isolateInternalQueries: Boolean // Isolate internal HikariCP queries
160
allowPoolSuspension: Boolean    // Allow pool suspension
161
```
162

163
#### Connection Testing and Initialization
164

165
```scala { .api }
166
connectionTestQuery: String     // Query to validate connections
167
connectionInitSql: String       // SQL to execute when creating connections
168
exceptionOverrideClassName: String // Custom exception override class name
169
```
170

171
#### Metadata and Monitoring
172

173
```scala { .api }
174
poolName: String                // Connection pool name (default: provided name)
175
catalog: String                 // Database catalog
176
schema: String                  // Database schema  
177
registerMbeans: Boolean         // Register JMX MBeans for monitoring
178
```
179

180
#### Transaction Configuration
181

182
```scala { .api }
183
transactionIsolation: String    // Transaction isolation level
184
isolation: String               // Alternative name for transactionIsolation
185
```
186

187
**Transaction Isolation Levels:**
188
- `"READ_UNCOMMITTED"` → `TRANSACTION_READ_UNCOMMITTED`
189
- `"READ_COMMITTED"` → `TRANSACTION_READ_COMMITTED`  
190
- `"REPEATABLE_READ"` → `TRANSACTION_REPEATABLE_READ`
191
- `"SERIALIZABLE"` → `TRANSACTION_SERIALIZABLE`
192

193
#### Legacy Configuration
194

195
```scala { .api }
196
initializationFailFast: Boolean // Deprecated: Use initializationFailTimeout instead
197
```
198

199
**Note:** `initializationFailFast` is deprecated. Use `initializationFailTimeout` with `-1` for no timeout, `0` for fail immediately, or positive milliseconds for timeout duration.
200

201
## Types
202

203
```scala { .api }
204
// External dependencies
205
import com.zaxxer.hikari.{HikariConfig, HikariDataSource}
206
import com.typesafe.config.Config
207
import java.sql.{Connection, Driver}
208
import slick.jdbc.{JdbcDataSource, JdbcDataSourceFactory}
209
```
210

211
## Usage Examples
212

213
### Simple Database Configuration
214

215
```scala
216
// application.conf
217
myapp {
218
  db {
219
    connectionPool = "slick.jdbc.hikaricp.HikariCPJdbcDataSource$"
220
    dataSourceClass = "slick.jdbc.DriverDataSource"
221
    properties = {
222
      driver = "org.postgresql.Driver"
223
      url = "jdbc:postgresql://localhost/mydb"
224
      user = "dbuser"
225
      password = "dbpass"
226
    }
227
    numThreads = 10
228
    maximumPoolSize = 20
229
  }
230
}
231
```
232

233
### Advanced HikariCP Configuration
234

235
```scala
236
// application.conf with advanced settings
237
production {
238
  db {
239
    connectionPool = "slick.jdbc.hikaricp.HikariCPJdbcDataSource$"
240
    dataSourceClassName = "org.postgresql.ds.PGSimpleDataSource"
241
    properties = {
242
      serverName = "localhost"
243
      portNumber = "5432"
244
      databaseName = "mydb"
245
      user = "dbuser"
246
      password = "dbpass"
247
    }
248
    
249
    # Pool sizing
250
    maximumPoolSize = 50
251
    minimumIdle = 10
252
    
253
    # Timeouts (in milliseconds)
254
    connectionTimeout = 30000
255
    idleTimeout = 600000
256
    maxLifetime = 1800000
257
    validationTimeout = 5000
258
    
259
    # Connection testing
260
    connectionTestQuery = "SELECT 1"
261
    
262
    # Monitoring
263
    poolName = "ProductionPool"
264
    registerMbeans = true
265
    leakDetectionThreshold = 60000
266
    
267
    # Connection behavior
268
    autoCommit = false
269
    transactionIsolation = "READ_COMMITTED"
270
  }
271
}
272
```
273

274
### Direct API Usage
275

276
```scala
277
import com.zaxxer.hikari.{HikariConfig, HikariDataSource}
278
import slick.jdbc.hikaricp.HikariCPJdbcDataSource
279
import com.typesafe.config.ConfigFactory
280

281
// Create HikariCP configuration directly
282
val hconfig = new HikariConfig()
283
hconfig.setJdbcUrl("jdbc:h2:mem:test")
284
hconfig.setUsername("sa")
285
hconfig.setPassword("")
286
hconfig.setMaximumPoolSize(20)
287
hconfig.setMinimumIdle(5)
288

289
// Create HikariCP data source
290
val hikariDS = new HikariDataSource(hconfig)
291

292
// Wrap in Slick data source
293
val slickDS = new HikariCPJdbcDataSource(hikariDS, hconfig)
294

295
// Use with Slick database
296
val db = Database.forDataSource(slickDS, Some(20))
297

298
// Clean up
299
db.close()
300
slickDS.close()
301
```