fixes #169 by expanding with-transaction docs

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.

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).
 

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

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

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`,