From bbc0ac85009dd5e01bb564fc1aaa837eef14fc80 Mon Sep 17 00:00:00 2001 From: Sean Corfield Date: Sun, 11 Apr 2021 11:39:06 -0700 Subject: [PATCH] Documentation updates --- CHANGELOG.md | 1 + README.md | 16 +++++++++++++--- doc/clause-reference.md | 3 ++- doc/general-reference.md | 6 +++++- doc/getting-started.md | 19 ++++++++++++++----- src/honey/sql.cljc | 7 ++++++- 6 files changed, 41 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d71e514..53fee80 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,7 @@ # Changes * 2.0.next in progress + * The documentation continues to be expanded and clarified in respond to feedback! * Tentative fix for #315 by expanding `:in` handling to deal with `nil` values. * 2.0.0-beta1 (for testing; 2021-04-09) diff --git a/README.md b/README.md index 8ebb10a..c000d83 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,8 @@ to a JDBC library, such as [`next.jdbc`](https://github.com/seancorfield/next-jd (jdbc/execute! conn (sql/format sqlmap)) ``` +> Note: you'll need to add your preferred JDBC library as a dependency in your project -- HoneySQL deliberately does not make that choice for you. + If you want to format the query as a string with no parameters (e.g. to use the SQL statement in a SQL console), pass `:inline true` as an option to `sql/format`: ```clojure @@ -73,9 +75,7 @@ If you want to format the query as a string with no parameters (e.g. to use the => ["SELECT a, b, c FROM foo WHERE f.a = 'baz'"] ``` -> Note: you'll need to add your preferred JDBC library as a dependency in your project -- HoneySQL deliberately does not make that choice for you. - -Namespace-qualified keywords are generally treated as table-qualified columns: `:foo/bar` becomes `foo.bar`, except in contexts where that would be illegal (such as the list of columns in an `INSERT` statement). This approach is likely to be more compatible with code that uses libraries like [`next.jdbc`](https://github.com/seancorfield/next-jdbc) and [`seql`](https://github.com/exoscale/seql), as well as being more convenient in a world of namespace-qualified keywords, following the example of `clojure.spec` etc. +Namespace-qualified keywords (and symbols) are generally treated as table-qualified columns: `:foo/bar` becomes `foo.bar`, except in contexts where that would be illegal (such as the list of columns in an `INSERT` statement). This approach is likely to be more compatible with code that uses libraries like [`next.jdbc`](https://github.com/seancorfield/next-jdbc) and [`seql`](https://github.com/exoscale/seql), as well as being more convenient in a world of namespace-qualified keywords, following the example of `clojure.spec` etc. ```clojure (def q-sqlmap {:select [:foo/a :foo/b :foo/c] @@ -91,6 +91,11 @@ Namespace-qualified keywords are generally treated as table-qualified columns: ` => ["SELECT foo.a, foo.b, foo.c FROM foo WHERE foo.a = ?" "baz"] ``` +Documentation for the entire data DSL can be found in the +[Clause Reference](doc/clause-reference.md), the +[Operator Reference](doc/operator-reference.md)], and the +[Special Syntax referenc](doc/special-syntax.md). + ### Vanilla SQL clause helpers For every single SQL clause supported by HoneySQL (as keywords or symbols @@ -130,6 +135,8 @@ If you want to replace a clause, you can `dissoc` the existing clause first, sin => ["SELECT * FROM foo WHERE (f.a = ?) AND (b > ?)" "baz" 10] ``` +> Note: the helpers always produce keywords so you can rely on `dissoc` with the desired keyword to remove. If you are building the data DSL "manually" and using symbols instead of keywords, you'll need to `dissoc` the symbol form instead. + `where` will combine multiple clauses together using SQL's `AND`: ```clojure @@ -160,6 +167,9 @@ functions interchangably. For any example using the helpers, you could evaluate it (without the call to `sql/format`) to see what the equivalent data structure would be. +Documentation for all the helpers can be found in the +[`honey.sql.helpers` API reference](https://cljdoc.org/d/com.github.seancorfield/honeysql/CURRENT/api/honey.sql.helpers). + ### Inserts Inserts are supported in two patterns. diff --git a/doc/clause-reference.md b/doc/clause-reference.md index 1edc6fb..0e91e49 100644 --- a/doc/clause-reference.md +++ b/doc/clause-reference.md @@ -2,7 +2,8 @@ This section lists all the SQL clauses that HoneySQL supports out of the box, in the order that they are -processed for formatting. +processed for formatting (except for some natural +grouping of related clauses). Clauses can be specified as keywords or symbols. Use `-` in the clause name where the formatted SQL would have diff --git a/doc/general-reference.md b/doc/general-reference.md index d331076..856f9ad 100644 --- a/doc/general-reference.md +++ b/doc/general-reference.md @@ -57,7 +57,7 @@ when quoting is in effect: ``` Finally, there are some contexts where only a SQL entity is accepted, rather than an -arbitrary SQL expression, so a string will be treated as a SQL entity and in such cases +arbitrary SQL expression, so a string will also be treated as a SQL entity and in such cases the entity name will always be quoted, dashes (`-`) will not be converted to underscores (`_`), and a slash (`/`) is not treated as separating a qualifier from the name, regardless of the `:dialect` or `:quoted` settings: @@ -98,8 +98,12 @@ these tuples: ;;=> ["(?, ?, ?)" 13 42 "foo"] ``` +There is also a `composite` helper function. + ## Other Sections Will Be Added! +As questions arise about the use of HoneySQL 2.x, I will add new sections here. + ## Other Reference Documentation The full list of supported SQL clauses is documented in the diff --git a/doc/getting-started.md b/doc/getting-started.md index 2ad2ce8..86ad0a2 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -169,9 +169,9 @@ call as the `:params` key of the options hash map. ## Functional Helpers 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: +SQL queries with raw Clojure data structures, a +[namespace full of helper functions](https://cljdoc.org/d/com.github.seancorfield/honeysql/CURRENT/api/honey.sql.helpers) +is also available. These functions are generally variadic and threadable: ```clojure (ns my.example @@ -189,7 +189,7 @@ 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`, `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), +parts of the SQL DSL (examples of `composite` appear in the [README](/README.md), examples of `over` appear in the [Clause Reference](clause-reference.md)) In addition to being variadic -- which often lets you omit one @@ -231,7 +231,8 @@ you need to consider this when referring symbols in from the ## DDL Statements 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) +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 (up to 0.3.104) has been incorporated @@ -239,6 +240,9 @@ 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!). +See also the [DDL Clauses section](clause-reference.md#ddl-clauses) of +the Clause Reference for documentation about supported DDL. + ## Dialects By default, HoneySQL operates in ANSI SQL mode but it supports @@ -308,6 +312,11 @@ was wrapped in `[:inline `..`]`: * keywords and symbols become SQL keywords (uppercase, with `-` replaced by a space), * everything else is just turned into a string (by calling `str`) and added to the SQL string. +`format` accepts options as either a single hash map argument or +as named arguments (alternating keys and values). If you are using +Clojure 1.11 (or later) you can mix'n'match, providing some options +as named arguments followed by other options in a hash map. + ## Reference Documentation The full list of supported SQL clauses is documented in the diff --git a/src/honey/sql.cljc b/src/honey/sql.cljc index 12b951e..1e396d3 100644 --- a/src/honey/sql.cljc +++ b/src/honey/sql.cljc @@ -1206,7 +1206,12 @@ any parameter values that were encountered in the DSL structure. This is the primary API for HoneySQL and handles dialects, quoting, - and named parameters." + and named parameters. + + `format` accepts options as either a single hash map argument or + as named arguments (alternating keys and values). If you are using + Clojure 1.11 (or later) you can mix'n'match, providing some options + as named arguments followed by other options in a hash map." ([data] (format data {})) ([data opts] (let [dialect? (contains? opts :dialect)