From 9cd75dc4b287645fe4ff08b510e4c47d4f30e5b1 Mon Sep 17 00:00:00 2001 From: Sean Corfield Date: Thu, 15 Jul 2021 20:06:19 -0700 Subject: [PATCH] fixes #169 by expanding with-transaction docs --- CHANGELOG.md | 3 +++ README.md | 2 +- deps.edn | 2 +- doc/getting-started.md | 23 ++++++++++++++++++----- src/next/jdbc.clj | 3 +++ 5 files changed, 26 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8eb712f..844122f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,9 @@ Only accretive/fixative changes will be made from now on. +* 1.2.next in progress + * Address #169 by expanding the description of `with-transaction` in **Getting Started**. + * 1.2.674 -- 2021-06-16 * Fix #167 by adding `:property-separator` to `next.jdbc.connection/dbtypes` and using it in `jdbc-url`. * Address #166 by adding `next.jdbc/with-logging` to create a wrapped connectable that will invoke logging functions with the SQL/parameters and optionally the result or exception for each operation. diff --git a/README.md b/README.md index 97e5df0..dcc7ba3 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ The documentation on [cljdoc.org](https://cljdoc.org/d/com.github.seancorfield/n * [Getting Started](https://cljdoc.org/d/com.github.seancorfield/next.jdbc/CURRENT/doc/getting-started) * [API Reference](https://cljdoc.org/d/com.github.seancorfield/next.jdbc/CURRENT/api/next) * [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/details/) or the [`#sql` stream on the Clojurians Zulip](https://clojurians.zulipchat.com/#narrow/stream/152063-sql). +* 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.674 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). diff --git a/deps.edn b/deps.edn index 54445e8..1c38478 100644 --- a/deps.edn +++ b/deps.edn @@ -41,7 +41,7 @@ :jvm-opts ["-Dlog4j2.configurationFile=log4j2-info.properties"] :exec-fn cognitect.test-runner.api/test} :jar - {:replace-deps {com.github.seancorfield/depstar {:mvn/version "2.0.216"}} + {:replace-deps {com.github.seancorfield/depstar {:mvn/version "2.1.267"}} :exec-fn hf.depstar/jar :exec-args {:jar "next-jdbc.jar" :sync-pom true}} :deploy diff --git a/doc/getting-started.md b/doc/getting-started.md index aaf3fc8..e9549ce 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -394,16 +394,27 @@ If any of these operations throws an exception, the connection will still be clo (into [] (map :column) (jdbc/plan tx ...))) ``` -If `with-transaction` is given a datasource, it will create and close the connection for you. If you pass in an existing connection, `with-transaction` will set up a transaction on that connection and, after either committing or rolling back the transaction, will restore the state of the connection and leave it open: +`with-transaction` behaves somewhat like Clojure's `with-open` macro: it will (generally) create a new `Connection` for you (from `ds`) and set up a transaction on it and bind it to `tx`; if the code in the body executes successfully, it will commit the transaction and close the `Connection`; if the code in the body throws an exception, it will rollback the transaction, but still close the `Connection`. + +If `ds` is a `Connection`, `with-transaction` will just bind `tx` to that but will set up a transaction on that `Connection`; run the code in the body and either commit or rollback the transaction; it will leave the `Connection` open (but try to restore the state of the `Connection`). + +If `ds` is a datasource, `with-transaction` will call `get-connection` on it, bind `tx` to that `Connection` and set up a transaction; run the code in the body and either commit or rollback the transaction; close the `Connection`. + +If `ds` is something else, `with-transaction` will call `get-datasource` on it first and then proceed as above. + +Here's what will happen in the case where `with-transaction` is given a `Connection`: ```clojure (with-open [con (jdbc/get-connection ds)] - (jdbc/execute! con ...) ; committed + (jdbc/execute! con ...) ; auto-committed + (jdbc/with-transaction [tx con] ; will commit or rollback this group: + ;; note: tx is bound to the same Connection object as con (jdbc/execute! tx ...) (jdbc/execute! tx ...) (into [] (map :column) (jdbc/plan tx ...))) - (jdbc/execute! con ...)) ; committed + + (jdbc/execute! con ...)) ; auto-committed ``` You can read more about [working with transactions](/doc/transactions.md) further on in the documentation. @@ -413,13 +424,15 @@ You can read more about [working with transactions](/doc/transactions.md) furthe ```clojure (with-open [con (jdbc/get-connection ds)] (let [con-opts (jdbc/with-options con some-options)] - (jdbc/execute! con-opts ...) ; committed + (jdbc/execute! con-opts ...) ; auto-committed + (jdbc/with-transaction [tx con-opts] ; will commit or rollback this group: (let [tx-opts (jdbc/with-options tx (:options con-opts)] (jdbc/execute! tx-opts ...) (jdbc/execute! tx-opts ...) (into [] (map :column) (jdbc/plan tx-opts ...)))) - (jdbc/execute! con-opts ...))) ; committed + + (jdbc/execute! con-opts ...))) ; auto-committed ``` ### Prepared Statement Caveat diff --git a/src/next/jdbc.clj b/src/next/jdbc.clj index fa098d1..8a7d897 100644 --- a/src/next/jdbc.clj +++ b/src/next/jdbc.clj @@ -352,6 +352,9 @@ then executes the `body` in that context, committing any changes if the body completes successfully, otherwise rolling back any changes made. + Like `with-open`, if `with-transaction` creates a new `Connection` object, + it will automatically close it for you. + The options map supports: * `:isolation` -- `:none`, `:read-committed`, `:read-uncommitted`, `:repeatable-read`, `:serializable`,