diff --git a/CHANGELOG.md b/CHANGELOG.md index 340cba2..ba12de0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,7 @@ Only accretive/fixative changes will be made from now on. * 1.2.next in progress + * Address [#218](https://github.com/seancorfield/next-jdbc/issues/218) by moving `:extend-via-metadata true` after the protocols' docstrings. * Document `:useBulkCopyForBatchInsert` for Microsoft SQL Server via PR [#216](https://github.com/seancorfield/next-jdbc/issues/216) -- [danskarda](https://github.com/danskarda). * Address [#214](https://github.com/seancorfield/next-jdbc/issues/214) by updating test/CI versions. * Address [#212](https://github.com/seancorfield/next-jdbc/issues/212) by documenting the problem with SQLite's JDBC driver. diff --git a/src/next/jdbc/prepare.clj b/src/next/jdbc/prepare.clj index dcd0136..b424af6 100644 --- a/src/next/jdbc/prepare.clj +++ b/src/next/jdbc/prepare.clj @@ -26,12 +26,13 @@ (set! *warn-on-reflection* true) -(defprotocol SettableParameter :extend-via-metadata true +(defprotocol SettableParameter "Protocol for setting SQL parameters in statement objects, which can convert from Clojure values. The default implementation just calls `.setObject` on the parameter value. It can be extended to use other methods of `PreparedStatement` to convert and set parameter values. Extension via metadata is supported." + :extend-via-metadata true (set-parameter [val stmt ix] "Convert a Clojure value into a SQL value and store it as the ix'th parameter in the given SQL statement object.")) diff --git a/src/next/jdbc/protocols.clj b/src/next/jdbc/protocols.clj index cc4e71f..5e8a622 100644 --- a/src/next/jdbc/protocols.clj +++ b/src/next/jdbc/protocols.clj @@ -11,15 +11,16 @@ (set! *warn-on-reflection* true) -(defprotocol Sourceable :extend-via-metadata true +(defprotocol Sourceable "Protocol for producing a `javax.sql.DataSource`. Implementations are provided for strings, hash maps (`db-spec` structures), and also a `DataSource` (which just returns itself). Extension via metadata is supported." + :extend-via-metadata true (get-datasource ^javax.sql.DataSource [this] - "Produce a `javax.sql.DataSource`.")) + "Produce a `javax.sql.DataSource`.")) (defprotocol Connectable "Protocol for producing a new JDBC connection that should be closed when you @@ -54,10 +55,11 @@ (prepare ^java.sql.PreparedStatement [this sql-params opts] "Produce a new `java.sql.PreparedStatement` for use with `with-open`.")) -(defprotocol Transactable :extend-via-metadata true +(defprotocol Transactable "Protocol for running SQL operations in a transaction. Implementations are provided for `Connection`, `DataSource`, and `Object` (on the assumption that an `Object` can be turned into a `DataSource`)." + :extend-via-metadata true (-transact [this body-fn opts] "Run the `body-fn` inside a transaction.")) diff --git a/src/next/jdbc/result_set.clj b/src/next/jdbc/result_set.clj index 0fa0d6f..75cc1c5 100644 --- a/src/next/jdbc/result_set.clj +++ b/src/next/jdbc/result_set.clj @@ -106,12 +106,13 @@ (get-unqualified-modified-column-names rsmeta (assoc opts :label-fn lower-case))) -(defprotocol ReadableColumn :extend-via-metadata true +(defprotocol ReadableColumn "Protocol for reading objects from the `java.sql.ResultSet`. Default implementations (for `Object` and `nil`) return the argument, and the `Boolean` implementation ensures a canonicalized `true`/`false` value, but it can be extended to provide custom behavior for special types. Extension via metadata is supported." + :extend-via-metadata true (read-column-by-label [val label] "Function for transforming values after reading them via a column label.") (read-column-by-index [val rsmeta idx] @@ -443,7 +444,7 @@ (definterface MapifiedResultSet) -(defprotocol InspectableMapifiedResultSet :extend-via-metadata true +(defprotocol InspectableMapifiedResultSet "Protocol for exposing aspects of the (current) result set via functions. The intent here is to expose information that is associated with either @@ -452,6 +453,7 @@ `next.jdbc/plan`, including situations where the reducing function has to realize a row by calling `datafiable-row` but still wants to call these functions on the (realized) row." + :extend-via-metadata true (row-number [this] "Return the current 1-based row number, if available. diff --git a/test/next/jdbc/connection_test.clj b/test/next/jdbc/connection_test.clj index 7af6b04..9f6cf6f 100644 --- a/test/next/jdbc/connection_test.clj +++ b/test/next/jdbc/connection_test.clj @@ -129,6 +129,12 @@ (= "derby" db) (assoc :create true)))) +(deftest test-sourceable-via-metadata + (doseq [db test-dbs] + (let [ds (p/get-datasource + ^{`p/get-datasource (fn [v] (p/get-datasource (first v)))} [db])] + (is (instance? javax.sql.DataSource ds))))) + (deftest test-get-connection (doseq [db test-dbs] (println 'test-get-connection (:dbtype db))