{"id":19167520,"url":"https://github.com/tomekw/hikari-cp","last_synced_at":"2025-05-14T05:10:25.568Z","repository":{"id":19896055,"uuid":"23160980","full_name":"tomekw/hikari-cp","owner":"tomekw","description":"A Clojure wrapper to HikariCP JDBC connection pool","archived":false,"fork":false,"pushed_at":"2024-12-02T11:05:58.000Z","size":318,"stargazers_count":421,"open_issues_count":3,"forks_count":51,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-05-03T07:45:23.730Z","etag":null,"topics":["clojure","clojure-library","connection-pool","jdbc"],"latest_commit_sha":null,"homepage":null,"language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"epl-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tomekw.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["tomekw"]}},"created_at":"2014-08-20T19:18:24.000Z","updated_at":"2025-04-08T20:16:35.000Z","dependencies_parsed_at":"2024-01-05T21:51:32.841Z","dependency_job_id":"4468ddb0-0905-42e4-b049-7395d1f19a19","html_url":"https://github.com/tomekw/hikari-cp","commit_stats":{"total_commits":293,"total_committers":35,"mean_commits":8.371428571428572,"dds":0.6040955631399317,"last_synced_commit":"02e91ab9d553d46399a4e5809f905af912b7135c"},"previous_names":[],"tags_count":66,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomekw%2Fhikari-cp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomekw%2Fhikari-cp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomekw%2Fhikari-cp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomekw%2Fhikari-cp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tomekw","download_url":"https://codeload.github.com/tomekw/hikari-cp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254076848,"owners_count":22010611,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clojure","clojure-library","connection-pool","jdbc"],"created_at":"2024-11-09T09:38:01.876Z","updated_at":"2025-05-14T05:10:25.535Z","avatar_url":"https://github.com/tomekw.png","language":"Clojure","funding_links":["https://github.com/sponsors/tomekw"],"categories":["Clojure","Connection pools"],"sub_categories":[],"readme":"# hikari-cp ![GitHub Workflow Status](https://img.shields.io/github/workflow/status/tomekw/hikari-cp/Clojure%20CI) [![Clojars Project](https://img.shields.io/clojars/v/hikari-cp.svg)](https://clojars.org/hikari-cp)\n\nA Clojure wrapper to [HikariCP](https://github.com/brettwooldridge/HikariCP) - \"zero-overhead\" production ready JDBC connection pool.\n\n## Installation\n\nAdd the following dependency to your `project.clj` file:\n\n```clojure\n[hikari-cp \"3.2.0\"]\n```\n\n`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`.\n\nNote that `hikari-cp` requires Java 11 or newer. Version `2.14.3` was the last release for Java 8.\n\nYou'll also need to add the JDBC driver needed for your database.\n\n## Configuration options\n\n| Option                      | Required | Default value          | Description                                                                                                                                                                                                                                                                                                                            |\n| --------------------------- | :------: | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `:auto-commit`              | No       | `true`                 | This property controls the default auto-commit behavior of connections returned from the pool. It is a boolean value.                                                                                                                                                                                                                  |\n| `:read-only`                | No       | `false`                | This property controls whether Connections obtained from the pool are in read-only mode by default.                                                                                                                                                                                                                                    |\n| `:connection-timeout`       | No       | `30000`                | This property controls the maximum number of milliseconds that a client will wait for a connection from the pool. If this time is exceeded without a connection becoming available, a SQLException will be thrown. 1000ms is the minimum value.                                                                                        |\n| `:validation-timeout`       | No       | `5000`                 | This property controls the maximum amount of time that a connection will be tested for aliveness. This value must be less than the `:connection-timeout`. The lowest accepted validation timeout is 1000ms (1 second).                                                                                                                 |\n| `:idle-timeout`             | No       | `600000`               | This property controls the maximum amount of time (in milliseconds) that a connection is allowed to sit idle in the pool.                                                                                                                                                                                                              |\n| `:max-lifetime`             | No       | `1800000`              | This property controls the maximum lifetime of a connection in the pool. A value of 0 indicates no maximum lifetime (infinite lifetime).                                                                                                                                                                                               |\n| `:minimum-idle`             | No       | `10`                   | This property controls the minimum number of idle connections that HikariCP tries to maintain in the pool.                                                                                                                                                                                                                             |\n| `:maximum-pool-size`        | No       | `10`                   | This property controls the maximum size that the pool is allowed to reach, including both idle and in-use connections. Basically this value will determine the maximum number of actual connections to the database backend.                                                                                                           |\n| `:pool-name`                | No       | Auto-generated         | This property represents a user-defined name for the connection pool and appears mainly in logging and JMX management consoles to identify pools and pool configurations.                                                                                                                                                              |\n| `:jdbc-url`                 | **Yes¹** | None                   | This property sets the JDBC connection URL. Please note the `h2` adapter expects `:url` instead of `:jdbc-url`.                                                                                                                                                                                                                        |\n| `:driver-class-name`        | No       | None                   | This property sets the JDBC driver class.                                                                                                                                                                                                                                                                                              |\n| `:adapter`                  | **Yes¹** | None                   | This property sets the database adapter. Please check [Adapters and corresponding datasource class names](#adapters-and-corresponding-datasource-class-names) for the full list of supported adapters and their datasource class names. The value should be provided as a string.                                                      |\n| `:username`                 | No       | None                   | This property sets the default authentication username used when obtaining Connections from the underlying driver.                                                                                                                                                                                                                     |\n| `:password`                 | No       | None                   | This property sets the default authentication password used when obtaining Connections from the underlying driver.                                                                                                                                                                                                                     |\n| `:database-name`            | No       | None                   | This property sets the database name.                                                                                                                                                                                                                                                                                                  |\n| `:server-name`              | No       | Depends on the adapter | This property sets the hostname client connects to.                                                                                                                                                                                                                                                                                    |\n| `:port-number`              | No       | Depends on the adapter | This property sets the port clients connects on.                                                                                                                                                                                                                                                                                       |\n| `:connection-test-query`    | No       | None                   | If your driver supports JDBC4 we strongly recommend not setting this property. This is for \"legacy\" databases that do not support the JDBC4 `Connection.isValid()` API. This is the query that will be executed just before a connection is given to you from the pool to validate that the connection to the database is still alive. |\n| `:leak-detection-threshold` | No       | 0                      | This property controls 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, minimum accepted value is 2000 (ms). ( *ps: it's rarely needed option, use only for debugging* )                                   |\n| `:register-mbeans`          | No       | false                  | This property register mbeans which can be used in jmx to monitor hikari-cp.                                                                                                                                                                                                                                                           |\n| `:connection-init-sql`      | No       | None                   | This property sets a SQL statement that will be executed after every new connection creation before adding it to the pool.                                                                                                                                                                                                             |\n| `:datasource`               | No       | None                   | This property allows you to directly set the instance of the DataSource to be wrapped by the pool.                                                                                                                                                                                                                                     |\n| `:datasource-class-name`    | No       | None                   | This is the name of the DataSource class provided by the JDBC driver.                                                                                                                                                                                                                                                                  |\n| `:metric-registry`          | No       | None                   | This is an instance of a Dropwizard metrics MetricsRegistry.                                                                                                                                                                                                                                                                           |\n| `:health-check-registry`    | No       | None                   | This is an instance of a Dropwizard metrics HealthCheckRegistry.                                                                                                                                                                                                                                                                       |\n| `:metrics-tracker-factory`  | No       | None                   | This is an implementation of a `MetricsTrackerFactory` (`CodahaleMetricsTrackerFactory`, `MicrometerMetricsTrackerFactory`, `PrometheusMetricsTrackerFactory`).                                                                                                                                                                        |\n| `:transaction-isolation`    | No       | None                   | Constant name from the [Connection][java.sql.Connection] interface such as `TRANSACTION_READ_COMMITTED`, `TRANSACTION_REPEATABLE_READ`, etc.                                                                                                                                                                                                                      |\n\n**¹** `:adapter` and `:jdbc-url` are mutually exclusive.\n\nYou can also add other datasource-specific configuration options.\nBy default, keywords will be converted to the camelCase format add added\nas a datasource property, unless a special translation is defined:\n\n[java.sql.Connection]: https://docs.oracle.com/javase/8/docs/api/java/sql/Connection.html\n\n```clojure\n;; {:tcp-keep-alive true} will be:\n(.addDataSourceProperty config \"tcpKeepAlive\" true)\n\n;; {:use-ssl false} has a custom translation, so it will be:\n(.addDataSourceProperty config \"useSSL\" false)\n\n;; {:tinyInt1isBit false} also has a custom translation to support\n;; the incorrect property casing in the original java class.\n```\n\nCustom translations of properties can be added by extending the\n`translate-property` multimethod.\n\n**Please note:** All time values are specified in milliseconds.\n\n## Adapters and corresponding datasource class names\n\n| Adapter          | Datasource class name                              | Tested with hikari-cp |\n| ---------------- | -------------------------------------------------- | :-------------------: |\n| `derby`          | `org.apache.derby.jdbc.ClientDataSource`           | No                    |\n| `firebird`       | `org.firebirdsql.pool.FBSimpleDataSource`          | No                    |\n| `db2`            | `com.ibm.db2.jcc.DB2SimpleDataSource`              | No                    |\n| `h2`             | `org.h2.jdbcx.JdbcDataSource`                      | **Yes**               |\n| `hsqldb`         | `org.hsqldb.jdbc.JDBCDataSource`                   | No                    |\n| `mariadb`        | `org.mariadb.jdbc.MySQLDataSource`                 | No                    |\n| `mysql`          | `com.mysql.jdbc.jdbc2.optional.MysqlDataSource`    | **Yes**               |\n| `mysql8`         | `com.mysql.cj.jdbc.MysqlDataSource`                | No                    |\n| `neo4j`          | `org.neo4j.jdbc.DataSource`                        | No                    |\n| `sqlserver-jtds` | `net.sourceforge.jtds.jdbcx.JtdsDataSource`        | **Yes**               |\n| `sqlserver`      | `com.microsoft.sqlserver.jdbc.SQLServerDataSource` | **Yes**               |\n| `oracle`         | `oracle.jdbc.pool.OracleDataSource`                | **Yes**               |\n| `pgjdbc-ng`      | `com.impossibl.postgres.jdbc.PGDataSource`         | No                    |\n| `postgresql`     | `org.postgresql.ds.PGSimpleDataSource`             | **Yes**               |\n| `fdbsql`         | `com.foundationdb.sql.jdbc.ds.FDBSimpleDataSource` | No                    |\n| `sybase`         | `com.sybase.jdbc4.jdbc.SybDataSource`              | Yes                   |\n| `sqlite`         | `org.sqlite.SQLiteDataSource`                      | No                    |\n\n## Usage\n\n### PostgreSQL example\n\n```clojure\n(ns hikari-cp.example\n  (:require [hikari-cp.core :refer :all]\n            [clojure.java.jdbc :as jdbc]))\n\n(def datasource-options {:auto-commit        true\n                         :read-only          false\n                         :connection-timeout 30000\n                         :validation-timeout 5000\n                         :idle-timeout       600000\n                         :max-lifetime       1800000\n                         :minimum-idle       10\n                         :maximum-pool-size  10\n                         :pool-name          \"db-pool\"\n                         :adapter            \"postgresql\"\n                         :username           \"username\"\n                         :password           \"password\"\n                         :database-name      \"database\"\n                         :server-name        \"localhost\"\n                         :port-number        5432\n                         :register-mbeans    false})\n\n(defonce datasource\n  (delay (make-datasource datasource-options)))\n\n(defn -main [\u0026 args]\n  (jdbc/with-db-connection [conn {:datasource @datasource}]\n    (let [rows (jdbc/query conn \"SELECT 0\")]\n      (println rows)))\n  (close-datasource @datasource))\n```\n### Neo4j\n\n```clojure\n(ns hikari-cp.example\n  (:require [hikari-cp.core :refer :all]\n            [clojure.java.jdbc :as jdbc]))\n\n(def datasource-options {:jdbc-url \"jdbc:neo4j:bolt://host:port/?username=neo4j\u0026password=xxxx\u0026debug=true\"})\n\n(defonce datasource\n  (delay (make-datasource datasource-options)))\n\n(defn -main [\u0026 args]\n  (jdbc/with-db-connection [conn {:datasource @datasource}]\n    (let [rows (jdbc/query conn [\"MATCH (n:Foo) WHERE n.name = ? RETURN n\" \"john\"])]\n      (println rows)))\n  (close-datasource @datasource))\n```\n### H2 minimal config example\n\n```clojure\n(def datasource-options {:adapter \"h2\"\n                         :url     \"jdbc:h2:~/test\"})\n```\n\n### Oracle example\n\n```clojure\n(ns hikari-cp.example\n  (:require [hikari-cp.core :refer :all]\n            [clojure.java.jdbc :as jdbc]))\n\n(def datasource-options {:username      \"username\"\n                         :password      \"password\"\n                         :database-name \"database\"\n                         :server-name   \"localhost\"\n                         :port-number   1521\n                         :driverType    \"thin\"       ; Other options are oci8, oci or kprb. See jdbc.pool.OracleDataSource.makeURL()\n                         :adapter       \"oracle\"})\n\n(defonce datasource\n  (delay (make-datasource datasource-options)))\n\n(defn -main [\u0026 args]\n  (jdbc/with-db-connection [conn {:datasource @datasource}]\n    (let [rows (jdbc/query conn \"SELECT 0 FROM dual\")]\n      (println rows)))\n  (close-datasource @datasource))\n```\n\n### Sybase example\n\n```clojure\n(ns hikari-cp.example\n  (:require [hikari-cp.core :refer :all]\n            [clojure.java.jdbc :as jdbc]))\n\n(def datasource-options {:username      \"username\"\n                         :password      \"password\"\n                         :database-name \"database\"\n                         :server-name   \"localhost\"\n                         :port-number   5900\n                         :adapter       \"sybase\"}) ; assumes jconn4.jar (com.sybase.jdbc4.jdbc.SybDataSource)\n\n; if you're using jconn2.jar or jconn3.jar replace :adapter \"sybase\" with the following\n; :datasource-class-name \"com.sybase.jdbc3.jdbc.SybDataSource\"\n; or\n; :datasource-class-name \"com.sybase.jdbc2.jdbc.SybDataSource\"\n\n(defonce datasource\n  (delay (make-datasource datasource-options)))\n\n(defn -main [\u0026 args]\n  (jdbc/with-db-connection [conn {:datasource @datasource}]\n    (let [rows (jdbc/query conn \"SELECT 0\")]\n      (println rows)))\n  (close-datasource @datasource))\n```\n\n### SQLite example\n\n```clojure\n(def datasource-options {:jdbc-url \"jdbc:sqlite:db/database.db\"})\n```\n\n### ClickHouse example\n`hikari-cp` can be used with [official ClickHouse driver](https://github.com/ClickHouse/clickhouse-java) in following two ways:\n1. Using `:datasource` property:\n- Official ClickHouse JDBC driver's `ClickHouseDataSource` does not have a zero arity constructor.\n- This mandates creating `ClickHouseDataSource` separately and setting `:datasource` property in `datasource-options`\n```clojure\n(ns hikari-cp.example\n  (:require\n    [hikari-cp.core :refer :all]\n    [next.jdbc :as jdbc])\n  (:import\n    [java.util Properties]\n    [com.clickhouse.jdbc ClickHouseDataSource]))\n\n(defonce clickhouse-datasource\n  (let [jdbc-url \"jdbc:ch://localhost:8123/test_db\"\n        properties (doto\n                     (Properties.)\n                     (.setProperty \"user\" \"username\")\n                     (.setProperty \"password\" \"password\")\n                     (.setProperty \"client_name\" \"test_client\")\n                     (.setProperty \"custom_http_params\" \"max_query_size=1000000\"))]\n    (ClickHouseDataSource. jdbc-url properties)))\n\n(def datasource-options\n  {:datasource clickhouse-datasource\n   :connection-timeout 5000\n   :maximum-pool-size 20\n   :max-lifetime 300000\n   :pool-name \"clickhouse-conn-pool\"})\n\n(defonce datasource \n  (delay (make-datasource datasource-options)))\n\n(defn -main\n  [\u0026 args]\n  (with-open [conn (jdbc/get-connection {:datasource @datasource})]\n    (let [rows (jdbc/execute! conn [\"SELECT 0\"])]\n      (println rows)))\n  (close-datasource @datasource))\n```\n2. Using `:jdbc-url` and `:driver-class-name` properties:\n```clojure\n(ns hikari-cp.example\n  (:require\n    [hikari-cp.core :refer :all]\n    [next.jdbc :as jdbc]))\n\n(def datasource-options-2\n  {:jdbc-url \"jdbc:ch://localhost:8123/test_db\"\n   :username \"username\"\n   :password \"password\"\n   :driver-class-name \"com.clickhouse.jdbc.ClickHouseDriver\"\n   :connection-timeout 5000\n   :maximum-pool-size 20\n   :max-lifetime 300000\n   :pool-name \"clickhouse-conn-pool\"})\n\n(defonce datasource\n  (delay (make-datasource datasource-options)))\n\n(defn -main\n  [\u0026 args]\n  (with-open [conn (jdbc/get-connection {:datasource @datasource})]\n    (let [rows (jdbc/execute! conn [\"SELECT 0\"])]\n      (println rows)))\n  (close-datasource @datasource))\n```\n\n### Notice\n\n`make-datasource` will throw `IllegalArgumentException` when invalid\narguments are provided:\n\n```clojure\n(make-datasource (dissoc config :username :database-name))\n;; IllegalArgumentException: Invalid configuration options: (:username :database-name)\n```\n\n## License\n\nCopyright © 2014 - 2024 [Tomek Wałkuski](https://github.com/tomekw) and [Jan Stępień](https://github.com/jstepien)\n\nDistributed under the Eclipse Public License either version 1.0 or (at your option) any later version.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomekw%2Fhikari-cp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftomekw%2Fhikari-cp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomekw%2Fhikari-cp/lists"}