prep for 2.1.818; document :values-default-columns

Author: seancorfield

CHANGELOG.md

@@ -1,8 +1,8 @@
 # Changes
 
-* 2.0.next in progress
+* 2.1.818 -- 2021-10-04
   * Fix #367 by supporting parameters in subexpressions around `IS NULL` / `IS NOT NULL` tests.
-  * Address #366 by introducing `:values-default-columns` option to control whether missing columns are treated as `NULL` or `DEFAULT` in `:values` clauses with sequences of hash maps. TODO: NEEDS DOCUMENTATION UPDATES INCLUDING EXAMPLE USAGE!
+  * Address #366 by introducing `:values-default-columns` option to control whether missing columns are treated as `NULL` or `DEFAULT` in `:values` clauses with sequences of hash maps.
   * Fix #365 -- a regression from 1.x -- where subclauses for `UNION`, `EXCEPT`, etc were incorrectly parenthesized.
   * Update `build-clj` to v0.5.0.
 

README.md

@@ -4,7 +4,7 @@ SQL as Clojure data structures. Build queries programmatically -- even at runtim
 
 ## Build
 
-[![Clojars Project](https://clojars.org/com.github.seancorfield/honeysql/latest-version.svg)](https://clojars.org/com.github.seancorfield/honeysql) [![cljdoc badge](https://cljdoc.org/badge/com.github.seancorfield/honeysql?2.0.813)](https://cljdoc.org/d/com.github.seancorfield/honeysql/CURRENT)
+[![Clojars Project](https://clojars.org/com.github.seancorfield/honeysql/latest-version.svg)](https://clojars.org/com.github.seancorfield/honeysql) [![cljdoc badge](https://cljdoc.org/badge/com.github.seancorfield/honeysql?2.1.818)](https://cljdoc.org/d/com.github.seancorfield/honeysql/CURRENT)
 
 This project follows the version scheme MAJOR.MINOR.COMMITS where MAJOR and MINOR provide some relative indication of the size of the change, but do not follow semantic versioning. In general, all changes endeavor to be non-breaking (by moving to new names rather than by breaking existing names). COMMITS is an ever-increasing counter of commits since the beginning of this repository.
 
@@ -273,7 +273,37 @@ INSERT INTO properties
 ```
 
 The set of columns used in the insert will be the union of all column names from all
-the hash maps: columns that are missing from any rows will have `NULL` as their value.
+the hash maps: columns that are missing from any rows will have `NULL` as their value
+unless you specify those columns in the `:values-default-columns` option, which takes
+a set of column names that should get the value `DEFAULT` instead of `NULL`:
+
+
+```clojure
+(-> (insert-into :properties)
+    (values [{:name "John" :surname "Smith" :age 34}
+             {:name "Andrew" :age 12}
+             {:name "Jane" :surname "Daniels"}])
+    (sql/format {:pretty true}))
+=> ["
+INSERT INTO properties
+(name, surname, age) VALUES (?, ?, ?), (?, NULL, ?), (?, ?, NULL)
+"
+"John" "Smith" 34
+"Andrew" 12
+"Jane" "Daniels"]
+(-> (insert-into :properties)
+    (values [{:name "John" :surname "Smith" :age 34}
+             {:name "Andrew" :age 12}
+             {:name "Jane" :surname "Daniels"}])
+    (sql/format {:pretty true :values-default-columns #{:age}}))
+=> ["
+INSERT INTO properties
+(name, surname, age) VALUES (?, ?, ?), (?, NULL, ?), (?, ?, DEFAULT)
+"
+"John" "Smith" 34
+"Andrew" 12
+"Jane" "Daniels"]
+```
 
 ### Nested subqueries
 

build.clj

@@ -17,7 +17,7 @@
             [org.corfield.build :as bb]))
 
 (def lib 'com.github.seancorfield/honeysql)
-(defn- the-version [patch] (format "2.0.%s" patch))
+(defn- the-version [patch] (format "2.1.%s" patch))
 (def version (the-version (b/git-count-revs nil)))
 (def snapshot (the-version "999-SNAPSHOT"))
 

doc/clause-reference.md

@@ -842,9 +842,13 @@ row values or a sequence of sequences, also representing row
 values.
 
 In the former case, all of the rows are augmented to have
-`nil` values for any missing keys (columns). In the latter,
+either `NULL` or `DEFAULT` values for any missing keys (columns).
+By default, `NULL` is used but you can specify a set of columns
+to get `DEFAULT` values, via the `:values-default-columns` option.
+In the latter case -- a sequence of sequences --
 all of the rows are padded to the same length by adding `nil`
-values if needed.
+values if needed (since `:values` does not know how or if column
+names are being used in this case).
 
 ```clojure
 user=> (sql/format {:insert-into :table
@@ -855,8 +859,16 @@ user=> (sql/format '{insert-into table
                              {id 2}
                              {name "Extra"})})
 ["INSERT INTO table (id, name) VALUES (?, ?), (?, NULL), (NULL, ?)" 1 "Sean" 2 "Extra"]
+user=> (sql/format '{insert-into table
+                     values ({id 1 name "Sean"}
+                             {id 2}
+                             {name "Extra"})}
+                   {:values-default-columns #{'id}})
+["INSERT INTO table (id, name) VALUES (?, ?), (?, NULL), (DEFAULT, ?)" 1 "Sean" 2 "Extra"]
 ```
 
+> Note: the `:values-default-columns` option must match how the columns are specified, i.e., as symbols or keywords.
+
 ## on-conflict, on-constraint, do-nothing, do-update-set
 
 These are grouped together because they are handled

doc/differences-from-1-x.md

@@ -63,7 +63,7 @@ Supported Clojure versions: 1.7 and later.
 In `deps.edn`:
 <!-- :test-doc-blocks/skip -->
 ```clojure
-com.github.seancorfield/honeysql {:mvn/version "2.0.813"}
+com.github.seancorfield/honeysql {:mvn/version "2.1.818"}
 ```
 
 Required as:

doc/getting-started.md

@@ -10,14 +10,14 @@ For the Clojure CLI, add the following dependency to your `deps.edn` file:
 
 <!-- :test-doc-blocks/skip -->
 ```clojure
-    com.github.seancorfield/honeysql {:mvn/version "2.0.813"}
+    com.github.seancorfield/honeysql {:mvn/version "2.1.818"}
 ```
 
 For Leiningen, add the following dependency to your `project.clj` file:
 
 <!-- :test-doc-blocks/skip -->
 ```clojure
-    [com.github.seancorfield/honeysql "2.0.813"]
+    [com.github.seancorfield/honeysql "2.1.818"]
 ```
 
 HoneySQL produces SQL statements but does not execute them.