Fixes #95 by adding notes about/links to next.jdbc.date-time

CHANGELOG.md

@@ -6,6 +6,7 @@ Only accretive/fixative changes will be made from now on.
 
 The following changes have been committed to the **master** branch since the 1.0.384 release:
 
+* Specifically call out PostgreSQL as needing `next.jdbc.date-time` to enable automatic conversion of `java.util.Date` objects to SQL timestamps for prepared statements (#95).
 * Split **Tips & Tricks** into its own page, with a whole new section on using JSON data types with PostgreSQL (#94 -- thank you @vharmain).
 * Bump dependencies to latest.
 

doc/getting-started.md

@@ -294,7 +294,13 @@ If you are using [Component](https://github.com/stuartsierra/component), a conne
 
 ## Working with Additional Data Types
 
-By default, `next.jdbc` relies on the JDBC driver to handle all data type conversions when reading from a result set (to produce Clojure values from SQL values) or setting parameters (to produce SQL values from Clojure values). Sometimes that means that you will get back a database-specific Java object that would need to be manually converted to a Clojure data structure, or that certain database column types require you to manually construct the appropriate database-specific Java object to pass into a SQL operation. You can usually automate those conversions using either the [ReadableColumn protocol](/doc/result-set-builders.md#readablecolumn) (for converting database-specific types to Clojure values) or the [SettableParameter protocol](/doc/prepared-statements.md#prepared-statement-parameters) (for converting Clojure values to database-specific types).
+By default, `next.jdbc` relies on the JDBC driver to handle all data type conversions when reading from a result set (to produce Clojure values from SQL values) or setting parameters (to produce SQL values from Clojure values). Sometimes that means that you will get back a database-specific Java object that would need to be manually converted to a Clojure data structure, or that certain database column types require you to manually construct the appropriate database-specific Java object to pass into a SQL operation. You can usually automate those conversions using either the [`ReadableColumn` protocol](/doc/result-set-builders.md#readablecolumn) (for converting database-specific types to Clojure values) or the [`SettableParameter` protocol](/doc/prepared-statements.md#prepared-statement-parameters) (for converting Clojure values to database-specific types).
+
+In particular, PostgreSQL does not seem to perform a conversion from `java.util.Date` to a SQL data type automatically. You must `require` the [`next.jdbc.date-time` namespace](https://cljdoc.org/d/seancorfield/next.jdbc/CURRENT/api/next.jdbc.date-time) to enable that conversion.
+
+If you are working with Java Time, some JDBC drivers will automatically convert `java.time.Instant` (and `java.time.LocalDate` and `java.time.LocalDateTime`) to a SQL data type automatically, but others will not. Requiring `next.jdbc.date-time` will enable those automatic conversions for all databases.
+
+> Note: `next.jdbc.date-time` does **not** provide automatic conversion of SQL data types to Clojure data types when reading result sets. If you want specific conversions to happen automatically, consider extending the `ReadableColumn` protocol, mentioned above.
 
 ## Support from Specs
 

doc/prepared-statements.md

@@ -46,7 +46,9 @@ This can be extended to any Clojure data type, to provide a customized way to ad
     (.setTimestamp ps i (java.sql.Timestamp/valueOf v))))
 ```
 
-Note that you can extend this protocol via metadata so you can do it on a per-object basis if you need:
+> Note: those conversions can also be enabled by requiring the [`next.jdbc.date-time` namespace](https://cljdoc.org/d/seancorfield/next.jdbc/CURRENT/api/next.jdbc.date-time).
+
+You can also extend this protocol via metadata so you can do it on a per-object basis if you need:
 
 ```clojure
 (with-meta obj {'next.jdbc.prepare/set-parameter (fn [v ps i]...)})

src/next/jdbc/prepare.clj

@@ -11,7 +11,11 @@
   `PreparedStatement` and then execute it in batch mode (via `.executeBatch`).
 
   Defines the `SettableParameter` protocol for converting Clojure values
-  to database-specific values."
+  to database-specific values.
+
+  See also https://cljdoc.org/d/seancorfield/next.jdbc/CURRENT/api/next.jdbc.date-time
+  for implementations of `SettableParameter` that provide automatic
+  conversion of Java Time objects to SQL data types."
   (:require [clojure.java.data :as j]
             [next.jdbc.protocols :as p])
   (:import (java.sql Connection