hikari-cp

A Clojure wrapper to HikariCP - "zero-overhead" production ready JDBC connection pool.

Installation

Add the following dependency to your project.clj file:

[hikari-cp "3.2.0"]

hikari-cp version 3.x targets Clojure 1.11. Version 2.14.3 was the last release for Clojure 1.9. Version 1.8.3 was the last release for Clojure 1.8.

Note that hikari-cp requires Java 11 or newer. Version 2.14.3 was the last release for Java 8.

You'll also need to add the JDBC driver needed for your database.

Configuration options

¹ :adapter and :jdbc-url are mutually exclusive.

You can also add other datasource-specific configuration options. By default, keywords will be converted to the camelCase format add added as a datasource property, unless a special translation is defined:

;; {:tcp-keep-alive true} will be:
(.addDataSourceProperty config "tcpKeepAlive" true)

;; {:use-ssl false} has a custom translation, so it will be:
(.addDataSourceProperty config "useSSL" false)

;; {:tinyInt1isBit false} also has a custom translation to support
;; the incorrect property casing in the original java class.

Custom translations of properties can be added by extending the translate-property multimethod.

Please note: All time values are specified in milliseconds.

Adapters and corresponding datasource class names

Usage

PostgreSQL example

(ns hikari-cp.example
  (:require [hikari-cp.core :refer :all]
            [clojure.java.jdbc :as jdbc]))

(def datasource-options {:auto-commit        true
                         :read-only          false
                         :connection-timeout 30000
                         :validation-timeout 5000
                         :idle-timeout       600000
                         :max-lifetime       1800000
                         :minimum-idle       10
                         :maximum-pool-size  10
                         :pool-name          "db-pool"
                         :adapter            "postgresql"
                         :username           "username"
                         :password           "password"
                         :database-name      "database"
                         :server-name        "localhost"
                         :port-number        5432
                         :register-mbeans    false})

(defonce datasource
  (delay (make-datasource datasource-options)))

(defn -main [& args]
  (jdbc/with-db-connection [conn {:datasource @datasource}]
    (let [rows (jdbc/query conn "SELECT 0")]
      (println rows)))
  (close-datasource @datasource))

Neo4j

(ns hikari-cp.example
  (:require [hikari-cp.core :refer :all]
            [clojure.java.jdbc :as jdbc]))

(def datasource-options {:jdbc-url "jdbc:neo4j:bolt://host:port/?username=neo4j&password=xxxx&debug=true"})

(defonce datasource
  (delay (make-datasource datasource-options)))

(defn -main [& args]
  (jdbc/with-db-connection [conn {:datasource @datasource}]
    (let [rows (jdbc/query conn ["MATCH (n:Foo) WHERE n.name = ? RETURN n" "john"])]
      (println rows)))
  (close-datasource @datasource))

H2 minimal config example

(def datasource-options {:adapter "h2"
                         :url     "jdbc:h2:~/test"})

Oracle example

(ns hikari-cp.example
  (:require [hikari-cp.core :refer :all]
            [clojure.java.jdbc :as jdbc]))

(def datasource-options {:username      "username"
                         :password      "password"
                         :database-name "database"
                         :server-name   "localhost"
                         :port-number   1521
                         :driverType    "thin"       ; Other options are oci8, oci or kprb. See jdbc.pool.OracleDataSource.makeURL()
                         :adapter       "oracle"})

(defonce datasource
  (delay (make-datasource datasource-options)))

(defn -main [& args]
  (jdbc/with-db-connection [conn {:datasource @datasource}]
    (let [rows (jdbc/query conn "SELECT 0 FROM dual")]
      (println rows)))
  (close-datasource @datasource))

Sybase example

(ns hikari-cp.example
  (:require [hikari-cp.core :refer :all]
            [clojure.java.jdbc :as jdbc]))

(def datasource-options {:username      "username"
                         :password      "password"
                         :database-name "database"
                         :server-name   "localhost"
                         :port-number   5900
                         :adapter       "sybase"}) ; assumes jconn4.jar (com.sybase.jdbc4.jdbc.SybDataSource)

; if you're using jconn2.jar or jconn3.jar replace :adapter "sybase" with the following
; :datasource-class-name "com.sybase.jdbc3.jdbc.SybDataSource"
; or
; :datasource-class-name "com.sybase.jdbc2.jdbc.SybDataSource"

(defonce datasource
  (delay (make-datasource datasource-options)))

(defn -main [& args]
  (jdbc/with-db-connection [conn {:datasource @datasource}]
    (let [rows (jdbc/query conn "SELECT 0")]
      (println rows)))
  (close-datasource @datasource))

SQLite example

(def datasource-options {:jdbc-url "jdbc:sqlite:db/database.db"})

ClickHouse example

hikari-cp can be used with official ClickHouse driver in following two ways:

1. Using :datasource property:

• Official ClickHouse JDBC driver's ClickHouseDataSource does not have a zero arity constructor.
• This mandates creating ClickHouseDataSource separately and setting :datasource property in datasource-options

(ns hikari-cp.example
  (:require
    [hikari-cp.core :refer :all]
    [next.jdbc :as jdbc])
  (:import
    [java.util Properties]
    [com.clickhouse.jdbc ClickHouseDataSource]))

(defonce clickhouse-datasource
  (let [jdbc-url "jdbc:ch://localhost:8123/test_db"
        properties (doto
                     (Properties.)
                     (.setProperty "user" "username")
                     (.setProperty "password" "password")
                     (.setProperty "client_name" "test_client")
                     (.setProperty "custom_http_params" "max_query_size=1000000"))]
    (ClickHouseDataSource. jdbc-url properties)))

(def datasource-options
  {:datasource clickhouse-datasource
   :connection-timeout 5000
   :maximum-pool-size 20
   :max-lifetime 300000
   :pool-name "clickhouse-conn-pool"})

(defonce datasource 
  (delay (make-datasource datasource-options)))

(defn -main
  [& args]
  (with-open [conn (jdbc/get-connection {:datasource @datasource})]
    (let [rows (jdbc/execute! conn ["SELECT 0"])]
      (println rows)))
  (close-datasource @datasource))

2. Using :jdbc-url and :driver-class-name properties:

(ns hikari-cp.example
  (:require
    [hikari-cp.core :refer :all]
    [next.jdbc :as jdbc]))

(def datasource-options-2
  {:jdbc-url "jdbc:ch://localhost:8123/test_db"
   :username "username"
   :password "password"
   :driver-class-name "com.clickhouse.jdbc.ClickHouseDriver"
   :connection-timeout 5000
   :maximum-pool-size 20
   :max-lifetime 300000
   :pool-name "clickhouse-conn-pool"})

(defonce datasource
  (delay (make-datasource datasource-options)))

(defn -main
  [& args]
  (with-open [conn (jdbc/get-connection {:datasource @datasource})]
    (let [rows (jdbc/execute! conn ["SELECT 0"])]
      (println rows)))
  (close-datasource @datasource))

Notice

make-datasource will throw IllegalArgumentException when invalid arguments are provided:

(make-datasource (dissoc config :username :database-name))
;; IllegalArgumentException: Invalid configuration options: (:username :database-name)

License

Copyright © 2014 - 2024 Tomek Wałkuski and Jan Stępień

Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.