diff --git a/CHANGELOG.md b/CHANGELOG.md index 215b837..ea01e95 100644 --- a/CHANGELOG.md +++ b/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. diff --git a/README.md b/README.md index 6942cee..dfb2d72 100644 --- a/README.md +++ b/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 diff --git a/build.clj b/build.clj index 039d4ac..b3416b7 100644 --- a/build.clj +++ b/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")) diff --git a/doc/clause-reference.md b/doc/clause-reference.md index 415c861..fa07044 100644 --- a/doc/clause-reference.md +++ b/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 diff --git a/doc/differences-from-1-x.md b/doc/differences-from-1-x.md index 5aef173..7cba1e3 100644 --- a/doc/differences-from-1-x.md +++ b/doc/differences-from-1-x.md @@ -63,7 +63,7 @@ Supported Clojure versions: 1.7 and later. In `deps.edn`: ```clojure -com.github.seancorfield/honeysql {:mvn/version "2.0.813"} +com.github.seancorfield/honeysql {:mvn/version "2.1.818"} ``` Required as: diff --git a/doc/getting-started.md b/doc/getting-started.md index 0173107..e8b3499 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -10,14 +10,14 @@ For the Clojure CLI, add the following dependency to your `deps.edn` file: ```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: ```clojure - [com.github.seancorfield/honeysql "2.0.813"] + [com.github.seancorfield/honeysql "2.1.818"] ``` HoneySQL produces SQL statements but does not execute them.