luciano/honeysql
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Some more documentation!

Browse source
This commit is contained in:
Sean Corfield 2021-02-13 17:30:16 -08:00
parent 6355452102
commit 267eef778a
2 changed files with 53 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

9
doc/differences-from-1-x.md
View file

@ -83,7 +83,7 @@ The `:quoting <dialect>` 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 <n> <units>`, 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

49
doc/getting-started.md
View file

@ -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.