diff --git a/CHANGELOG.md b/CHANGELOG.md index 10b7344..13d6bc4 100644 --- a/CHANGELOG.md +++ b/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. diff --git a/doc/getting-started.md b/doc/getting-started.md index c28e1dd..908e6c9 100644 --- a/doc/getting-started.md +++ b/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 diff --git a/doc/prepared-statements.md b/doc/prepared-statements.md index 26dba09..5051c80 100644 --- a/doc/prepared-statements.md +++ b/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]...)}) diff --git a/src/next/jdbc/prepare.clj b/src/next/jdbc/prepare.clj index c8c3bb2..5ba66df 100644 --- a/src/next/jdbc/prepare.clj +++ b/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