From dbecb152a164742ff4c56dca270598f094dbd5be Mon Sep 17 00:00:00 2001 From: Sean Corfield Date: Thu, 8 Apr 2021 23:06:07 -0700 Subject: [PATCH] Documentation updates and clarifications This adds placeholders for reference documentation. --- doc/cljdoc.edn | 1 + doc/differences-from-1-x.md | 22 ++++++++++++++-------- doc/general-reference.md | 28 ++++++++++++++++++++++++++++ doc/getting-started.md | 24 +++++++++++++----------- 4 files changed, 56 insertions(+), 19 deletions(-) create mode 100644 doc/general-reference.md diff --git a/doc/cljdoc.edn b/doc/cljdoc.edn index 024ed98..366b459 100644 --- a/doc/cljdoc.edn +++ b/doc/cljdoc.edn @@ -2,6 +2,7 @@ [["Readme" {:file "README.md"}] ["Changes" {:file "CHANGELOG.md"}] ["Getting Started" {:file "doc/getting-started.md"} + ["General Reference" {:file "doc/general-reference.md"}] ["SQL Clause Reference" {:file "doc/clause-reference.md"}] ["SQL Operator Reference" {:file "doc/operator-reference.md"}] ["SQL 'Special Syntax'" {:file "doc/special-syntax.md"}] diff --git a/doc/differences-from-1-x.md b/doc/differences-from-1-x.md index e42c5d1..bb8cd50 100644 --- a/doc/differences-from-1-x.md +++ b/doc/differences-from-1-x.md @@ -10,7 +10,7 @@ HoneySQL 1.x supported Clojure 1.7 and later. HoneySQL 2.x requires Clojure 1.9 ## Group, Artifact, and Namespaces -HoneySQL 2.x uses the group ID `com.github.seancorfield` with the original artifact ID of `honeysql`, in line with the recommendations in Inside Clojure's post about the changes in the Clojure CLI: [Deprecated unqualified lib names](https://insideclojure.org/2020/07/28/clj-exec/). +HoneySQL 2.x uses the group ID `com.github.seancorfield` with the original artifact ID of `honeysql`, in line with the recommendations in Inside Clojure's post about the changes in the Clojure CLI: [Deprecated unqualified lib names](https://insideclojure.org/2020/07/28/clj-exec/); also Clojars [Verified Group Names policy](https://github.com/clojars/clojars-web/wiki/Verified-Group-Names). In addition, HoneySQL 2.x contains different namespaces so you can have both versions on your classpath without introducing any conflicts. The primary API is now in `honey.sql` and the helpers are in `honey.sql.helpers`. A Spec for the DSL data structure will be available in `honey.specs` at some point (work in progress). @@ -80,7 +80,7 @@ You can now select a non-ANSI dialect of SQL using the new `honey.sql/set-dialec As noted above, the variadic options for `format` have been replaced by a single hash map as the optional second argument to `format`. -The `:quoting ` option has superseded by the new dialect machinery and a new `:quoted` option that turns quoting on or off. You either use `:dialect ` instead or set a default dialect (via `set-dialect!`) and then use `{:quoted true}` in `format` calls where you want quoting. +The `:quoting ` option has superseded by the new dialect machinery and a new `:quoted` option that turns quoting on or off. You either use `:dialect ` instead or set a default dialect (via `set-dialect!`) and then use `:quoted true` in `format` calls where you want quoting. Identifiers are automatically quoted if you specify a `:dialect` option to `format`, unless you also specify `:quoted false`. @@ -105,11 +105,14 @@ The following new syntax has been added: * `: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) and for declaring column defaults in table definitions, +* `:escape` -- used to wrap a regular expression so that non-standard escape characters can be provided, * `: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]`. +* `:interval` -- used as a function to support `INTERVAL `, e.g., `[:interval 30 :days]`, +* `:lateral` -- used to wrap a statement or expression, to provide a `LATERAL` join, * `: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) -- this should mostly be a replacement for `honeysql.format/value`, * `:nest` -- used as a function to add an extra level of nesting (parentheses) around an expression, * `:not` -- this is now explicit syntax, +* `:over` -- the function-like part of a T-SQL window clause, * `:param` -- used as a function to replace the `sql/param` / `#sql/param` machinery, * `:raw` -- used as a function to replace the `sql/raw` / `#sql/raw` machinery. Vector subexpressions inside a `[:raw ..]` expression are formatted to SQL and parameters. Other subexpressions are just turned into strings and concatenated. This is different to the v1 behavior but should be more flexible, since you can now embed `:inline`, `:param`, and `:lift` inside a `:raw` expression. @@ -117,8 +120,10 @@ The following new syntax has been added: 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`. +construction: + +* `:constraint`, `:default`, `:foreign-key`, `:index`, `:primary-key`, `:references`, `:unique`, +* `:entity` -- used to force an expression to be rendered as a SQL entity (instead of a SQL keyword). ### select and function calls @@ -174,6 +179,7 @@ And, finally, you can register new operators that will be recognized in expressi The `honey.sql.helpers` namespace includes a helper function that corresponds to every supported piece of the data DSL understood by HoneySQL (v1 only had a limited set of helper functions). Unlike v1 helpers which sometimes had both a regular helper and a `merge-` helper, v2 helpers will all merge clauses by default (if that makes sense for the underlying DSL): use `:dissoc` if you want to force an overwrite. The only helpers that have non-merging behavior are: -* `intersect`, `union`, `union-all`, `except`, and `except-all` which always wrap around their arguments, -* `delete`, `set`, `limit`, `offset`, `for`, and `values` which overwrite, rather than merge, -* `composite` which is a convenience for the `:composite` syntax mentioned above: `(composite :a :b)` is the same as `[:composite :a :b]` which produces `(a, b)`. +* The SQL set operations `intersect`, `union`, `union-all`, `except`, and `except-all` which always wrap around their arguments, +* The SQL clauses `delete`, `fetch`, `for`, `limit`, `lock`, `offset`, `on-constraint`, `set`, `truncate`, `update`, and `values` which overwrite, rather than merge, +* The DDL helpers `drop-column`, `drop-index`, `rename-table`, and `with-data`, +* The function helper `composite` which is a convenience for the `:composite` syntax mentioned above: `(composite :a :b)` is the same as `[:composite :a :b]` which produces `(a, b)`. diff --git a/doc/general-reference.md b/doc/general-reference.md new file mode 100644 index 0000000..c1c2cf2 --- /dev/null +++ b/doc/general-reference.md @@ -0,0 +1,28 @@ +# General Reference Documentation + +This section provides more details about specific behavior in HoneySQL and +how to generate certain SQL constructs. + +## SQL Entity Generation + +See #313 + +## Tuples and Composite Values + +See #314 + +## Other Sections Will Be Added! + +## Other Reference Documentation + +The full list of supported SQL clauses is documented in the +[Clause Reference](clause-reference.md). The full list +of operators supported (as prefix-form "functions") is +documented in the [Operator Reference](operator-reference.md) +section. The full list +of "special syntax" functions is documented in the +[Special Syntax](special-syntax.md) section. The best +documentation for the helper functions is in the +[honey.sql.helpers](https://cljdoc.org/d/com.github.seancorfield/honeysql/2.0.0-alpha3/api/honey.sql.helpers) namespace. +If you're migrating to HoneySQL 2.0, this [overview of differences +between 1.0 and 2.0](differences-from-1-x.md) should help. diff --git a/doc/getting-started.md b/doc/getting-started.md index 50a8741..05f4326 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -26,7 +26,7 @@ To execute SQL statements, you will also need a JDBC wrapper like SQL statements are represented as hash maps, with keys that represent clauses in SQL. SQL expressions are generally -represented as vectors, where the first element identifies +represented as sequences, where the first element identifies the function or operator and the remaining elements are the arguments or operands. @@ -50,10 +50,10 @@ 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`. -Most clauses expect a vector as their value, containing +Most clauses expect a sequence as their value, containing either a list of SQL entities or the representation of a SQL expression. Some clauses accept a single SQL entity. A few -accept a most specialized form (such as `:set` accepting a +accept a more 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 @@ -97,7 +97,7 @@ the table name, i.e., `:foo/bar` instead of `:foo.bar`: ## SQL Expressions In addition to using hash maps to describe SQL clauses, -HoneySQL uses vectors to describe SQL expressions. Any +HoneySQL uses sequences to describe SQL expressions. Any sequence that begins with a keyword (or symbol) is considered to be a kind of function invocation. Certain "functions" are considered to be "special syntax" and have custom rendering. @@ -168,7 +168,7 @@ call as the `:params` key of the options hash map. ## Functional Helpers -In addition to the hash map (and vectors) approach of building +In addition to the hash map (and sequences) approach of building SQL queries with raw Clojure data structures, a namespace full of helper functions is also available. These functions are generally variadic and threadable: @@ -188,9 +188,9 @@ generally variadic and threadable: 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](README.md), -examples of the latter appear in the [Clause Reference](docs/clause-reference.md)) +`composite`, `lateral`, `over`, and `upsert` that make it easier to construct those +parts of the SQL DSL (examples of `composite` appear in the [README](README.md), +examples of `over` appear in the [Clause Reference](docs/clause-reference.md)) In addition to being variadic -- which often lets you omit one level of `[`..`]` -- the helper functions merge clauses, which @@ -225,7 +225,7 @@ 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`, +`honey.sql.helpers` namespace: `for`, `group-by`, `into`, `partition-by`, `set`, and `update`. ## DDL Statements @@ -234,7 +234,7 @@ HoneySQL 1.x did not support any DDL statements. It was fairly common for people to use the [nilenso/honeysql-postgres library](https://github.com/nilenso/honeysql-postgres) to get DDL support, even if they didn't need the PostgreSQL-specific extensions. That library does not work with HoneySQL 2.x but all -of the functionality from it has been incorporated +of the functionality from it (up to 0.3.104) has been incorporated into HoneySQL now and is described in the [PostgreSQL](postgresql.md) section (because that covers all of the things that the nilenso library supported and much of it was PostgreSQL-specific!). @@ -288,7 +288,7 @@ specify a dialect in the `format` call, you can specify Out of the box, as part of the extended ANSI SQL support, HoneySQL supports quite a few [PostgreSQL extensions](postgresql.md). -> Note: the [nilenso/honeysql-postgres library](https://github.com/nilenso/honeysql-postgres) which provided PostgreSQL support for HoneySQL 1.x does not work with HoneySQL 2.x. However, HoneySQL 2.x includes all of the functionality from that library out of the box! +> Note: the [nilenso/honeysql-postgres library](https://github.com/nilenso/honeysql-postgres) which provided PostgreSQL support for HoneySQL 1.x does not work with HoneySQL 2.x. However, HoneySQL 2.x includes all of the functionality from that library (up to 0.3.104) out of the box! ## Format Options @@ -319,5 +319,7 @@ of "special syntax" functions is documented in the [Special Syntax](special-syntax.md) section. The best documentation for the helper functions is in the [honey.sql.helpers](https://cljdoc.org/d/com.github.seancorfield/honeysql/2.0.0-alpha3/api/honey.sql.helpers) namespace. +More detail about certain core HoneySQL functionality can be found in the +[Reference documentation](general-reference.md). If you're migrating to HoneySQL 2.0, this [overview of differences between 1.0 and 2.0](differences-from-1-x.md) should help.