diff --git a/CHANGELOG.md b/CHANGELOG.md index efd214b..afd7470 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,7 @@ # Changes * 2.6.next in progress + * Address [#547](https://github.com/seancorfield/honeysql/issues/547) by adding examples of conditional SQL building with the helpers to the README and the `honey.sql.helpers` ns docstring. * Performance optimizations via PRs [#545](https://github.com/seancorfield/honeysql/pull/545) and [#546](https://github.com/seancorfield/honeysql/pull/546) [@alexander-yakushev](https://github.com/alexander-yakushev). * Address [#544](https://github.com/seancorfield/honeysql/issues/544) by adding support for MySQL's `VALUES ROW(..)` syntax. * Fix [#543](https://github.com/seancorfield/honeysql/issues/543) by supporting both symbols and keywords in named parameters. diff --git a/README.md b/README.md index 64c24a1..fcf1109 100644 --- a/README.md +++ b/README.md @@ -215,6 +215,24 @@ If you want to replace a clause, you can `dissoc` the existing clause first, sin => ["SELECT * FROM foo WHERE (a = ?) AND (b < ?)" 1 100] ``` +The power of this approach comes from the abiliity to programmatically and +conditionally build up queries: + + +```clojure +(defn fetch-user [& {:keys [id name]}] + (-> (select :*) + (from :users) + (cond-> + id (where [:= :id id]) + name (where [:= :name name])) + sql/format)) +``` + +You can call `fetch-user` with either `:id` or `:name` _or both_ and get back +a query with the appropriate `WHERE` clause, since the helpers will merge the +conditions into the query DSL. + Column and table names may be aliased by using a vector pair of the original name and the desired alias: @@ -226,6 +244,21 @@ name and the desired alias: => ["SELECT a, b AS bar, c, d AS x FROM foo AS quux WHERE (quux.a = ?) AND (bar < ?)" 1 100] ``` +or conditionally: + + +```clojure +(-> (select :a [:b :bar]) + (cond-> + need-c (select :c) + x-val (select [:d :x])) + (from [:foo :quux]) + (where [:= :quux.a 1] [:< :bar 100]) + (cond-> + x-val (where [:> :x x-val])) + sql/format) +``` + In particular, note that `(select [:a :b])` means `SELECT a AS b` rather than `SELECT a, b` -- helpers like `select` are generally variadic and do not take a collection of column names. diff --git a/src/honey/sql/helpers.cljc b/src/honey/sql/helpers.cljc index 5654813..3538ef4 100644 --- a/src/honey/sql/helpers.cljc +++ b/src/honey/sql/helpers.cljc @@ -17,6 +17,16 @@ (sql/format)) ``` + or conditionally like this: + +``` + (-> (select :a :b :c) + (from :table) + (cond-> + id (where [:= :id id])) + (sql/format)) +``` + Therefore all helpers can take an existing DSL expression as their first argument or, if the first argument is not a hash map, an empty DSL is assumed -- an empty hash map.