From 267eef778a197eb92c174002cc7986d658aa259f Mon Sep 17 00:00:00 2001 From: Sean Corfield Date: Sat, 13 Feb 2021 17:30:16 -0800 Subject: [PATCH] Some more documentation! --- doc/differences-from-1-x.md | 9 +++++-- doc/getting-started.md | 49 ++++++++++++++++++++++++++++++++++--- 2 files changed, 53 insertions(+), 5 deletions(-) diff --git a/doc/differences-from-1-x.md b/doc/differences-from-1-x.md index 91f8728..591a94e 100644 --- a/doc/differences-from-1-x.md +++ b/doc/differences-from-1-x.md @@ -83,7 +83,7 @@ The `:quoting ` option has superseded by the new dialect machinery and Identifiers are automatically quoted if you specify a `:dialect` option to `format`, unless you also specify `:quoted false`. The following options are no longer supported: -* `:allow-dashed-names?` -- if you provide dashed-names in v2, they will be left as-is if quoting is enabled, else they will be converted to snake_case (so you will either get `"dashed-names"` with quoting or `dashed_names` without); v1 treated names specified as keywords and names specified as strings differently. +* `:allow-dashed-names?` -- if you provide dashed-names in v2, they will be left as-is if quoting is enabled, else they will be converted to snake_case (so you will either get `"dashed-names"` with quoting or `dashed_names` without). * `:allow-namespaced-names?` -- this supported `foo/bar` column names in SQL which I'd like to discourage. * `:namespace-as-table?` -- this is the default in v2: `:foo/bar` will be treated as `foo.bar` which is more in keeping with `next.jdbc`. * `:parameterizer` -- this would add a lot of complexity to the formatting engine and I do not know how widely it was used (especially in its arbitrarily extensible form). @@ -102,7 +102,7 @@ The following new syntax has been added: * `:case` -- this is now explicit syntax, * `:cast` -- `[:cast expr :type]` => `CAST( expr AS type )`, * `:composite` -- explicit syntax to produce a comma-separated list of expressions, wrapped in parentheses, -* `:default` -- for `DEFAULT` values (in inserts), +* `:default` -- for `DEFAULT` values (in inserts) and for declaring column defaults in table definitions, * `:inline` -- used as a function to replace the `sql/inline` / `#sql/inline` machinery, * `:interval` -- used as a function to support `INTERVAL `, e.g., `[:interval 30 :days]`. * `:lift` -- used as a function to prevent interpretation of a Clojure data structure as DSL syntax (e.g., when passing a vector or hash map as a parameter value), @@ -113,6 +113,11 @@ The following new syntax has been added: > Note 1: in 1.x, inlining a string `"foo"` produced `foo` but in 2.x it produces `'foo'`, i.e., string literals become SQL strings without needing internal quotes (1.x required `"'foo'"`). +Several additional pieces of syntax have also been added to support column +definitions in `CREATE TABLE` clauses, now that v2 supports DDL statement +construction: `:constraint`, `:foreign-key`, `:index`, `:primary-key`, +`:references`, `:unique`, and -- as noted above -- `:default`. + You can now `SELECT` a function call more easily, using `[[...]]`. This was previously an error -- missing an alias -- but it was a commonly requested change, to avoid using `(sql/call ...)`: ```clojure diff --git a/doc/getting-started.md b/doc/getting-started.md index e8b986e..0233b8e 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -52,12 +52,14 @@ or symbols, are treated as positional parameters and replaced by `?` in the SQL string and lifted out into the vector that is returned from `format`. -Nearly all clauses expect a vector as their value, containing +Most clauses expect a vector as their value, containing either a list of SQL entities or the representation of a SQL -expression. +expression. Some clauses accept a single SQL entity. A few +accept a most specialized form (such as `:set` accepting a +hash map of SQL entities and SQL expressions). A SQL entity can be a simple keyword (or symbol) or a pair -that represents a SQL entity and its alias: +that represents a SQL entity and its alias (where aliases are allowed): ```clojure (sql/format {:select [:t.id [:name :item]], :from [[:table :t]], :where [:= :id 1]}) @@ -76,6 +78,8 @@ avoid evaluation: ```clojure (sql/format '{select [t.id [name item]], from [[table t]], where [= id 1]}) +;; or you can use (..) instead of [..] when quoted: +(sql/format '{select (t.id (name item)), from ((table t)), where (= id 1)}) ;; also produces: ;;=> ["SELECT t.id, name AS item FROM table AS t WHERE id = ?" 1] ``` @@ -110,6 +114,12 @@ generally variadic and threadable: ;;=> ["SELECT t.id, name AS item FROM table AS t WHERE id = ?" 1] ``` +There is a helper function for every single clause that HoneySQL +supports out of the box. In addition, there are helpers for +`composite` and `over` that make it easier to construct those +parts of the SQL DSL (examples of the former appear in the [README.md](README), +examples of the latter appear in the [docs/clause-reference.md](Clause Reference)) + In addition to being variadic -- which often lets you omit one level of `[`..`]` -- the helper functions merge clauses, which can make it easier to build queries programmatically: @@ -123,3 +133,36 @@ can make it easier to build queries programmatically: ;; produces: ;;=> ["SELECT t.id, name AS item FROM table AS t WHERE id = ?" 1] ``` + +If you want to replace a clause with a subsequent helper call, +you need to explicitly remove the prior value: + +```clojure +(-> (select :t/id) + (from [:table :t]) + (where [:= :id 1]) + (dissoc :select) + (select [:name :item]) + (sql/format)) +;; produces: +;;=> ["SELECT name AS item FROM table AS t WHERE id = ?" 1] +``` + +Helpers always use keywords when constructing clauses so you +can rely on using keywords in `dissoc`. + +The following helpers shadow functions in `clojure.core` so +you need to consider this when referring symbols in from the +`honey.sql.helpers` namespace: `for`, `group-by`, `partition-by`, +`set`, and `update`. + +## Reference Documentation + +The full list of supported SQL clauses is documented in the +[docs/clause-reference.md](Clause Reference). The full list +of "special syntax" functions is documented in the +[docs/special-syntax.md](Special Syntax) section. The best +documentation for the helper functions is the +[honey.sql.helpers](https://cljdoc.org/d/seancorfield/honeysql/CURRENT/api/honey.sql.helpers). +If you're migrating to HoneySQL 2.0, this [overview of differences +between 1.0 and 2.0](docs/differences-from-1-x.md) should help.