diff --git a/CHANGELOG.md b/CHANGELOG.md index 8be3c54..c4e4892 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,8 @@ Only accretive/fixative changes will be made from now on. -* 1.2.next in progress +* 1.2.737 -- 2021-10-17 + * Address #186 by updating `java.data` to 1.0.92 and documenting HikariCP's `:dataSourceProperties`. * Address #184 by improving documentation about `:jdbcUrl`. * 1.2.731 -- 2021-10-04 diff --git a/README.md b/README.md index 6c76bd2..100a0e2 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ The next generation of `clojure.java.jdbc`: a new low-level Clojure wrapper for The latest versions on Clojars and on cljdoc: -[![Clojars Project](https://clojars.org/com.github.seancorfield/next.jdbc/latest-version.svg)](https://clojars.org/com.github.seancorfield/next.jdbc) [![cljdoc badge](https://cljdoc.org/badge/com.github.seancorfield/next.jdbc?1.2.731)](https://cljdoc.org/d/com.github.seancorfield/next.jdbc/CURRENT) +[![Clojars Project](https://clojars.org/com.github.seancorfield/next.jdbc/latest-version.svg)](https://clojars.org/com.github.seancorfield/next.jdbc) [![cljdoc badge](https://cljdoc.org/badge/com.github.seancorfield/next.jdbc?1.2.737)](https://cljdoc.org/d/com.github.seancorfield/next.jdbc/CURRENT) The documentation on [cljdoc.org](https://cljdoc.org/d/com.github.seancorfield/next.jdbc/CURRENT) is for the current version of `next.jdbc`: @@ -17,7 +17,7 @@ The documentation on [cljdoc.org](https://cljdoc.org/d/com.github.seancorfield/n * [Migrating from `clojure.java.jdbc`](https://cljdoc.org/d/com.github.seancorfield/next.jdbc/CURRENT/doc/migration-from-clojure-java-jdbc) * Feedback via [issues](https://github.com/seancorfield/next-jdbc/issues) or in the [`#sql` channel on the Clojurians Slack](https://clojurians.slack.com/messages/C1Q164V29/) or the [`#sql` stream on the Clojurians Zulip](https://clojurians.zulipchat.com/#narrow/stream/152063-sql). -The documentation on GitHub is for **develop** since the 1.2.731 release -- [see the CHANGELOG](https://github.com/seancorfield/next-jdbc/blob/develop/CHANGELOG.md) and then read the [corresponding updated documentation](https://github.com/seancorfield/next-jdbc/tree/develop/doc) on GitHub if you want. Older versions of `next.jdbc` were published under the `seancorfield` group ID and you can find [older seancorfield/next.jdbc documentation on cljdoc.org](https://cljdoc.org/versions/seancorfield/next.jdbc). +The documentation on GitHub is for **develop** since the 1.2.737 release -- [see the CHANGELOG](https://github.com/seancorfield/next-jdbc/blob/develop/CHANGELOG.md) and then read the [corresponding updated documentation](https://github.com/seancorfield/next-jdbc/tree/develop/doc) on GitHub if you want. Older versions of `next.jdbc` were published under the `seancorfield` group ID and you can find [older seancorfield/next.jdbc documentation on cljdoc.org](https://cljdoc.org/versions/seancorfield/next.jdbc). This project follows the version scheme MAJOR.MINOR.COMMITS where MAJOR and MINOR provide some relative indication of the size of the change, but do not follow semantic versioning. In general, all changes endeavor to be non-breaking (by moving to new names rather than by breaking existing names). COMMITS is an ever-increasing counter of commits since the beginning of this repository. diff --git a/deps.edn b/deps.edn index 30cb246..bdbbdad 100644 --- a/deps.edn +++ b/deps.edn @@ -1,7 +1,7 @@ {:mvn/repos {"sonatype" {:url "https://oss.sonatype.org/content/repositories/snapshots/"}} :paths ["src" "resources"] :deps {org.clojure/clojure {:mvn/version "1.10.3"} - org.clojure/java.data {:mvn/version "1.0.86"} + org.clojure/java.data {:mvn/version "1.0.92"} camel-snake-kebab/camel-snake-kebab {:mvn/version "0.4.2"}} :aliases diff --git a/doc/getting-started.md b/doc/getting-started.md index 5e1b8fd..0ceab80 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -11,12 +11,12 @@ It is designed to work with Clojure 1.10 or later, supports `datafy`/`nav`, and You can add `next.jdbc` to your project with either: ```clojure -com.github.seancorfield/next.jdbc {:mvn/version "1.2.731"} +com.github.seancorfield/next.jdbc {:mvn/version "1.2.737"} ``` for `deps.edn` or: ```clojure -[com.github.seancorfield/next.jdbc "1.2.731"] +[com.github.seancorfield/next.jdbc "1.2.737"] ``` for `project.clj` or `build.boot`. @@ -37,7 +37,7 @@ For the examples in this documentation, we will use a local H2 database on disk, ```clojure ;; deps.edn {:deps {org.clojure/clojure {:mvn/version "1.10.3"} - com.github.seancorfield/next.jdbc {:mvn/version "1.2.731"} + com.github.seancorfield/next.jdbc {:mvn/version "1.2.737"} com.h2database/h2 {:mvn/version "1.4.199"}}} ``` @@ -475,6 +475,17 @@ Then import the appropriate classes into your code: Finally, create the connection pooled datasource. `db-spec` here contains the regular `next.jdbc` options (`:dbtype`, `:dbname`, and maybe `:host`, `:port`, `:classname` etc -- or the `:jdbcUrl` format mentioned above). Those are used to construct the JDBC URL that is passed into the datasource object (by calling `.setJdbcUrl` on it). You can also specify any of the connection pooling library's options, as mixed case keywords corresponding to any simple setter methods on the class being passed in, e.g., `:connectionTestQuery`, `:maximumPoolSize` (HikariCP), `:maxPoolSize`, `:preferredTestQuery` (c3p0). +In addition, for HikariCP, you can specify properties to be applied to the underlying `DataSource` itself by passing `:dataSourceProperties` with a value of `java.util.Properties` containing those properties, such as `:socketTimeout`. Using `java.data` makes this easier: + +```clojure +;; assumes next.jdbc.connection has been required as connection +;; assumes clojure.java.data has been required as j +(connection/->pool com.zaxxer.hikari.HikariConfig + {:dbtype "postgres" :dbname "thedb" :username "dbuser" :password "secret" + :dataSourceProperties + (j/to-java java.util.Properties {:socketTimeout 30})}) +``` + > Note: both HikariCP and c3p0 defer validation of the settings until a connection is requested. If you want to ensure that your datasource is set up correctly, and the database is reachable, when you first create the connection pool, you will need to call `jdbc/get-connection` on it (and then close that connection and return it to the pool). This will also ensure that the pool is fully initialized. See the examples below. Some important notes regarding HikariCP: