fix #256 by documenting the new macros

CHANGELOG.md

@@ -4,7 +4,7 @@ Only accretive/fixative changes will be made from now on.
 
 * 1.3.next in progress
   * 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`. Documentation TBD.
+  * 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`)
 
 * 1.3.883 -- 2023-06-25

doc/all-the-options.md

@@ -98,7 +98,7 @@ In addition to the above, `next.jdbc/execute-batch!` (which may create a `Prepar
 
 ## Transactions
 
-The `transact` function and `with-transaction` macro accept the following options:
+The `transact` function and `with-transaction` (`+options`) macro accept the following options:
 
 * `:isolation` -- a keyword that identifies the isolation to be used for this transaction: `:none`, `:read-committed`, `:read-uncommitted`, `:repeatable-read`, or `:serializable`; these represent increasingly strict levels of transaction isolation and may not all be available depending on the database and/or JDBC driver being used,
 * `:read-only` -- a `Boolean` that indicates whether the transaction should be read-only or not (the default),

doc/getting-started.md

@@ -445,7 +445,7 @@ You can read more about [working with transactions](/doc/transactions.md) furthe
     (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)]
+      (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 ...))))
@@ -453,6 +453,11 @@ 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,
+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.
+
 ### Prepared Statement Caveat
 
 Not all databases support using a `PreparedStatement` for every type of SQL operation. You might have to create a `java.sql.Statement` instead, directly from a `java.sql.Connection` and use that, without parameters, in `plan`, `execute!`, or `execute-one!`. See the following example:
@@ -629,6 +634,14 @@ 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
+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.
+Be aware that means you cannot
+use plain Java interop inside the body of the macro because the connectable
+is no longer a plain Java `java.sql.Connection` object.
+
 ## Logging
 
 Sometimes it is convenient to have database operations logged automatically. `next.jdbc/with-logging`

doc/transactions.md

@@ -108,3 +108,15 @@ transactions in the code under test.
 * `(binding [next.jdbc.transaction/*nested-tx* :prohibit] ...)` will cause any attempt to start a nested transaction to throw an exception instead; this could be a useful way to detect the potentially buggy behavior described above (for either `:allow` or `:ignore`).
 
  > Note: this is a **global** setting (per thread) and not related to just a single connection, so you can't use this setting if you are working with multiple databases in the same context.
+
+### `with-options`
+
+If you are using `with-options` to produce wrapped connectables / transactables,
+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
+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.

src/next/jdbc.clj

@@ -392,7 +392,11 @@
 
   Otherwise, creates a new `Connection` object from the connectable,
   wraps that with options, executes the body, and automatically closes
-  the new `Connection` for you."
+  the new `Connection` for you.
+
+  Note: the bound `sym` will be a **wrapped** connectable and not a plain
+  Java object, so you cannot call JDBC methods directly on it like you can
+  with `on-connection`."
   [[sym connectable] & body]
   `(let [con-obj# ~connectable]
      (cond (instance? java.sql.Connection con-obj#)