diff --git a/CHANGELOG.md b/CHANGELOG.md index b59ab05..2c2975f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ Only accretive/fixative changes will be made from now on. -* 1.3.next in progress +* 1.3.894 -- 2023-09-24 * Fix [#257](https://github.com/seancorfield/next-jdbc/issues/257) by making the `fdef` spec for `with-transaction` more permissive. Also add specs for `on-connection` and the `+options` variants of both macros. * Address [#256](https://github.com/seancorfield/next-jdbc/issues/256) by adding `with-transaction+options` and `on-connection+options`. * Update `tools.build` to 0.9.5 (and remove `:java-opts` from `build/test`) diff --git a/README.md b/README.md index 3d85895..be34d08 100644 --- a/README.md +++ b/README.md @@ -8,8 +8,8 @@ The next generation of `clojure.java.jdbc`: a new low-level Clojure wrapper for The latest versions on Clojars and on cljdoc: -[![Clojars](https://img.shields.io/badge/clojars-com.github.seancorfield/next.jdbc_1.3.883-blue.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAMAAABEpIrGAAAABGdBTUEAALGPC/xhBQAAACBjSFJNAAB6JgAAgIQAAPoAAACA6AAAdTAAAOpgAAA6mAAAF3CculE8AAABjFBMVEUAAAAdCh0qDikdChwAAAAnDSY0EjM2FjUnDiYnDSYnDSYpDigyEDEEAQRGNUb///////8mDSYAAAAAAAAAAAAFAgUqEyoAAAAAAAAAAAAFAgUAAABXU1c2FjVMx+dQx+f///////9Nx+b////4/f6y4vRPt+RQtOT///9Qt+P///8oDSey4vRQr9/////3/P5hzelNx+dNx+dNx+f///8AAAAuDy0zETIAAAAoDScAAAAAAAARBREAAAAvDy40ETMwEC9gSF+Ne42ilKKuoK6Rg5B5ZXlaP1o4Gzf///9nTWZ4YncyEDF/bn/8/Pz9/P339/c1FTUlDCRRM1AbCRtlS2QyEDEuDy1gRWAxEDAzETIwEC/g4OAvDy40EjOaiZorDiq9sbzNyM3UzdQyEDE0ETMzETKflZ/UzdQ5Fzmu4fNYyuhNx+dPt+RLu9xQyOhBbo81GTuW2vCo4PJNx+c4MFE5N1lHiLFEhKQyEDGDboMzETI5Fjh5bXje2d57aHrIw8jc2NyWhJUrDioxe9o4AAAAPnRSTlMAkf+IAQj9+e7n6e31RtqAD/QAAAED+A0ZEQ8DwvkLBsmcR4aG8+cdAD6C8/MC94eP+qoTrgH+/wj1HA8eEvpXOCUAAAABYktHRA8YugDZAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH3wcHFjou4Z/shwAAAUpJREFUOMul0/VTwzAUB/AAwyW4y3B3h8EDNuTh7u6UDHcd8I+TbHSjWdrjju/1h77kc+3Lu5aQvyakF/r6B5wu1+DQMEBomLRtG0EpozYDCEccA4iIjIqOiY0bB5iYxHgZ4FQCpYneKmmal0aQPMOXZnUAvJhLkbpInf8NFtKCTrGImK6DJcTlDGl/BXGV6oCsrSNIYAM3aQDwl2xJYBtBB5lZAuyYgWzY3YMcNcjN2wc4EGMEFTg8+hlyfgEenygAj71Q9FBExH0wKC4p1bRTJlJWXqEAVNM05ovbXfkPAHBmAUQPAGaAsXMBLiwA8z3h0gRcsWsObuAWLJu8Awb3ZoB5T8EvS/CgBo9Y5Z8TPwXBJwlUI9Ia/yRrEZ8lID71Olrf0MiamkkL4kurDEjba+C/e2sninR0wrsH8eMTvrqIWbodjh7jyjdtCY3Aniz4jwAAACV0RVh0ZGF0ZTpjcmVhdGUAMjAxNS0wNy0wN1QyMjo1ODo0NiswMjowMCgWtSoAAAAldEVYdGRhdGU6bW9kaWZ5ADIwMTUtMDctMDdUMjI6NTg6NDYrMDI6MDBZSw2WAAAAAElFTkSuQmCC)](https://clojars.org/com.github.seancorfield/next.jdbc) -[![cljdoc](https://cljdoc.org/badge/com.github.seancorfield/next.jdbc?1.3.883)](https://cljdoc.org/d/com.github.seancorfield/next.jdbc/CURRENT) +[![Clojars](https://img.shields.io/badge/clojars-com.github.seancorfield/next.jdbc_1.3.894-blue.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAMAAABEpIrGAAAABGdBTUEAALGPC/xhBQAAACBjSFJNAAB6JgAAgIQAAPoAAACA6AAAdTAAAOpgAAA6mAAAF3CculE8AAABjFBMVEUAAAAdCh0qDikdChwAAAAnDSY0EjM2FjUnDiYnDSYnDSYpDigyEDEEAQRGNUb///////8mDSYAAAAAAAAAAAAFAgUqEyoAAAAAAAAAAAAFAgUAAABXU1c2FjVMx+dQx+f///////9Nx+b////4/f6y4vRPt+RQtOT///9Qt+P///8oDSey4vRQr9/////3/P5hzelNx+dNx+dNx+f///8AAAAuDy0zETIAAAAoDScAAAAAAAARBREAAAAvDy40ETMwEC9gSF+Ne42ilKKuoK6Rg5B5ZXlaP1o4Gzf///9nTWZ4YncyEDF/bn/8/Pz9/P339/c1FTUlDCRRM1AbCRtlS2QyEDEuDy1gRWAxEDAzETIwEC/g4OAvDy40EjOaiZorDiq9sbzNyM3UzdQyEDE0ETMzETKflZ/UzdQ5Fzmu4fNYyuhNx+dPt+RLu9xQyOhBbo81GTuW2vCo4PJNx+c4MFE5N1lHiLFEhKQyEDGDboMzETI5Fjh5bXje2d57aHrIw8jc2NyWhJUrDioxe9o4AAAAPnRSTlMAkf+IAQj9+e7n6e31RtqAD/QAAAED+A0ZEQ8DwvkLBsmcR4aG8+cdAD6C8/MC94eP+qoTrgH+/wj1HA8eEvpXOCUAAAABYktHRA8YugDZAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH3wcHFjou4Z/shwAAAUpJREFUOMul0/VTwzAUB/AAwyW4y3B3h8EDNuTh7u6UDHcd8I+TbHSjWdrjju/1h77kc+3Lu5aQvyakF/r6B5wu1+DQMEBomLRtG0EpozYDCEccA4iIjIqOiY0bB5iYxHgZ4FQCpYneKmmal0aQPMOXZnUAvJhLkbpInf8NFtKCTrGImK6DJcTlDGl/BXGV6oCsrSNIYAM3aQDwl2xJYBtBB5lZAuyYgWzY3YMcNcjN2wc4EGMEFTg8+hlyfgEenygAj71Q9FBExH0wKC4p1bRTJlJWXqEAVNM05ovbXfkPAHBmAUQPAGaAsXMBLiwA8z3h0gRcsWsObuAWLJu8Awb3ZoB5T8EvS/CgBo9Y5Z8TPwXBJwlUI9Ia/yRrEZ8lID71Olrf0MiamkkL4kurDEjba+C/e2sninR0wrsH8eMTvrqIWbodjh7jyjdtCY3Aniz4jwAAACV0RVh0ZGF0ZTpjcmVhdGUAMjAxNS0wNy0wN1QyMjo1ODo0NiswMjowMCgWtSoAAAAldEVYdGRhdGU6bW9kaWZ5ADIwMTUtMDctMDdUMjI6NTg6NDYrMDI6MDBZSw2WAAAAAElFTkSuQmCC)](https://clojars.org/com.github.seancorfield/next.jdbc) +[![cljdoc](https://cljdoc.org/badge/com.github.seancorfield/next.jdbc?1.3.894)](https://cljdoc.org/d/com.github.seancorfield/next.jdbc/CURRENT) [![Slack](https://img.shields.io/badge/slack-next.jdbc-orange.svg?logo=slack)](https://clojurians.slack.com/app_redirect?channel=sql) [![Join Slack](https://img.shields.io/badge/slack-join_clojurians-orange.svg?logo=slack)](http://clojurians.net) @@ -20,7 +20,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.3.883 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.3.894 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/doc/all-the-options.md b/doc/all-the-options.md index f04f1f9..f664dca 100644 --- a/doc/all-the-options.md +++ b/doc/all-the-options.md @@ -42,7 +42,11 @@ Except for `query` (which is simply an alias for `execute!`), all the "friendly" * `:table-fn` -- the quoting function to be used on the string that identifies the table name, if provided; this also applies to assumed table names when `nav`igating schemas, * `:column-fn` -- the quoting function to be used on any string that identifies a column name, if provided; this also applies to the reducing function context over `plan` and to assumed foreign key column names when `nav`igating schemas. -They also support a `:suffix` argument which can be used to specify a SQL string that should be appended to the generated SQL string before executing it, e.g., `:suffix "FOR UPDATE"`. +They also support a `:suffix` argument which can be used to specify a SQL string that should be appended to the generated SQL string before executing it, e.g., `:suffix "FOR UPDATE"` or, for an `insert!` call `:suffix "RETURNING *"`. +The latter is particularly useful for databases, such as SQLite these days, +which do not support calling `.getGeneratedKeys()` on `PreparedStatement` objects, +so you cannot use `:return-generated-keys` to get back the keys -- you must +use `RETURNING *`. In addition, `find-by-keys` accepts the following options (see its docstring for more details): diff --git a/doc/getting-started.md b/doc/getting-started.md index b6972a6..7b3630e 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.3.883"} +com.github.seancorfield/next.jdbc {:mvn/version "1.3.894"} ``` for `deps.edn` or: ```clojure -[com.github.seancorfield/next.jdbc "1.3.883"] +[com.github.seancorfield/next.jdbc "1.3.894"] ``` for `project.clj` or `build.boot`. @@ -38,7 +38,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.3.883"} + com.github.seancorfield/next.jdbc {:mvn/version "1.3.894"} com.h2database/h2 {:mvn/version "1.4.199"}}} ``` @@ -453,7 +453,7 @@ You can read more about [working with transactions](/doc/transactions.md) furthe (jdbc/execute! con-opts ...))) ; auto-committed ``` -As of 1.3.next, you can use `next.jdbc/with-transaction+options` instead, +As of 1.3.894, you can use `next.jdbc/with-transaction+options` instead, which will automatically rewrap the `Connection` with the options from the initial transactable. Be aware that means you cannot use Java interop on the new connectable because it is no longer a plain Java `java.sql.Connection` object. @@ -634,7 +634,7 @@ if one is passed or create a new one if needed (and automatically close it after > Note: to avoid confusion and/or incorrect usage, you cannot pass options to `on-connection` because they would be ignored in some cases (existing `Connection` or a wrapped `Connection`). -As of 1.3.next, if you want the options from a wrapped connectable to flow +As of 1.3.894, if you want the options from a wrapped connectable to flow through to the new connectable inside `on-connection`, you can use the `on-connection+options` variant of the macro. This will automatically rewrap the connectable produced with the options from the initial connectable. diff --git a/doc/transactions.md b/doc/transactions.md index cfb40c1..e32318c 100644 --- a/doc/transactions.md +++ b/doc/transactions.md @@ -116,7 +116,7 @@ it's important to be aware that `with-transaction` produces a bare Java `java.sql.Connection` object that cannot have options -- but does allow direct interop. If you want to use `with-options` with `with-transaction`, you must either rewrap the `Connection` with a nested call to `with-options` or, -as of 1.3.next, you can use `with-transaction+options` which will automatically +as of 1.3.894, you can use `with-transaction+options` which will automatically rewrap the `Connection` in a new connectable along with the options from the original transactable. Be aware that you cannot use Java interop on this wrapped connectable.