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

address #539 by improving getting started

Browse source 
Signed-off-by: Sean Corfield <sean@corfield.org>
This commit is contained in:
Sean Corfield 2024-09-21 18:12:10 -07:00
parent 7fceefbe5c
commit 4efa9a38ef
No known key found for this signature in database
11 changed files with 44 additions and 36 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
CHANGELOG.md
View file

@ -1,6 +1,7 @@
# Changes # Changes
* 2.6.next in progress * 2.6.next in progress
* Getting Started updated based on feedback from Los Angeles Clojure meetup walkthrough [#539](https://github.com/seancorfield/honeysql/issues/539).
* Update Clojure version to 1.12.0. * Update Clojure version to 1.12.0.
* 2.6.1161 -- 2024-08-29 * 2.6.1161 -- 2024-08-29

17
README.md
View file

@ -16,7 +16,7 @@ This project follows the version scheme MAJOR.MINOR.COMMITS where MAJOR and MINO
HoneySQL 2.x requires Clojure 1.9 or later. HoneySQL 2.x requires Clojure 1.9 or later.
Compared to 1.x, HoneySQL 2.x provides a streamlined codebase and a simpler method for extending the DSL. It also supports SQL dialects out-of-the-box and will be extended to support vendor-specific language features over time (unlike 1.x). Compared to the [legacy 1.x version](#1.x), HoneySQL 2.x provides a streamlined codebase and a simpler method for extending the DSL. It also supports SQL dialects out-of-the-box and will be extended to support vendor-specific language features over time (unlike 1.x).
> Note: you can use 1.x and 2.x side-by-side as they use different group IDs and different namespaces. This allows for a piecemeal migration. See this [summary of differences between 1.x and 2.x](doc/differences-from-1-x.md) if you are migrating from 1.x! > Note: you can use 1.x and 2.x side-by-side as they use different group IDs and different namespaces. This allows for a piecemeal migration. See this [summary of differences between 1.x and 2.x](doc/differences-from-1-x.md) if you are migrating from 1.x!
@ -35,12 +35,6 @@ Sample code in this documentation is verified via
Some of these samples show pretty-printed SQL: HoneySQL 2.x supports `:pretty true` which inserts newlines between clauses in the generated SQL strings. Some of these samples show pretty-printed SQL: HoneySQL 2.x supports `:pretty true` which inserts newlines between clauses in the generated SQL strings.
### HoneySQL 1.x (legacy)
[![Clojars](https://img.shields.io/badge/clojars-honeysql_1.0.461-lightblue.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAMAAABEpIrGAAAABGdBTUEAALGPC/xhBQAAACBjSFJNAAB6JgAAgIQAAPoAAACA6AAAdTAAAOpgAAA6mAAAF3CculE8AAABjFBMVEUAAAAdCh0qDikdChwAAAAnDSY0EjM2FjUnDiYnDSYnDSYpDigyEDEEAQRGNUb///////8mDSYAAAAAAAAAAAAFAgUqEyoAAAAAAAAAAAAFAgUAAABXU1c2FjVMx+dQx+f///////9Nx+b////4/f6y4vRPt+RQtOT///9Qt+P///8oDSey4vRQr9/////3/P5hzelNx+dNx+dNx+f///8AAAAuDy0zETIAAAAoDScAAAAAAAARBREAAAAvDy40ETMwEC9gSF+Ne42ilKKuoK6Rg5B5ZXlaP1o4Gzf///9nTWZ4YncyEDF/bn/8/Pz9/P339/c1FTUlDCRRM1AbCRtlS2QyEDEuDy1gRWAxEDAzETIwEC/g4OAvDy40EjOaiZorDiq9sbzNyM3UzdQyEDE0ETMzETKflZ/UzdQ5Fzmu4fNYyuhNx+dPt+RLu9xQyOhBbo81GTuW2vCo4PJNx+c4MFE5N1lHiLFEhKQyEDGDboMzETI5Fjh5bXje2d57aHrIw8jc2NyWhJUrDioxe9o4AAAAPnRSTlMAkf+IAQj9+e7n6e31RtqAD/QAAAED+A0ZEQ8DwvkLBsmcR4aG8+cdAD6C8/MC94eP+qoTrgH+/wj1HA8eEvpXOCUAAAABYktHRA8YugDZAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH3wcHFjou4Z/shwAAAUpJREFUOMul0/VTwzAUB/AAwyW4y3B3h8EDNuTh7u6UDHcd8I+TbHSjWdrjju/1h77kc+3Lu5aQvyakF/r6B5wu1+DQMEBomLRtG0EpozYDCEccA4iIjIqOiY0bB5iYxHgZ4FQCpYneKmmal0aQPMOXZnUAvJhLkbpInf8NFtKCTrGImK6DJcTlDGl/BXGV6oCsrSNIYAM3aQDwl2xJYBtBB5lZAuyYgWzY3YMcNcjN2wc4EGMEFTg8+hlyfgEenygAj71Q9FBExH0wKC4p1bRTJlJWXqEAVNM05ovbXfkPAHBmAUQPAGaAsXMBLiwA8z3h0gRcsWsObuAWLJu8Awb3ZoB5T8EvS/CgBo9Y5Z8TPwXBJwlUI9Ia/yRrEZ8lID71Olrf0MiamkkL4kurDEjba+C/e2sninR0wrsH8eMTvrqIWbodjh7jyjdtCY3Aniz4jwAAACV0RVh0ZGF0ZTpjcmVhdGUAMjAxNS0wNy0wN1QyMjo1ODo0NiswMjowMCgWtSoAAAAldEVYdGRhdGU6bW9kaWZ5ADIwMTUtMDctMDdUMjI6NTg6NDYrMDI6MDBZSw2WAAAAAElFTkSuQmCC)](https://clojars.org/honeysql/honeysql) [![cljdoc badge](https://cljdoc.org/badge/honeysql/honeysql?1.0.461)](https://cljdoc.org/d/honeysql/honeysql/CURRENT)
HoneySQL 1.x will continue to get critical security fixes but otherwise should be considered "legacy" at this point.
## Usage ## Usage
This section includes a number of usage examples but does not dive deep into the This section includes a number of usage examples but does not dive deep into the
@ -1015,8 +1009,15 @@ You can also register SQL clauses, specifying the keyword, the formatting functi
If you find yourself registering an operator, a function (syntax), or a new clause, consider submitting a [pull request to HoneySQL](https://github.com/seancorfield/honeysql/pulls) so others can use it, too. If it is dialect-specific, let me know in the pull request. If you find yourself registering an operator, a function (syntax), or a new clause, consider submitting a [pull request to HoneySQL](https://github.com/seancorfield/honeysql/pulls) so others can use it, too. If it is dialect-specific, let me know in the pull request.
<a name="1.x"/>
## HoneySQL 1.x (legacy)
[![Clojars](https://img.shields.io/badge/clojars-honeysql_1.0.461-lightblue.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAMAAABEpIrGAAAABGdBTUEAALGPC/xhBQAAACBjSFJNAAB6JgAAgIQAAPoAAACA6AAAdTAAAOpgAAA6mAAAF3CculE8AAABjFBMVEUAAAAdCh0qDikdChwAAAAnDSY0EjM2FjUnDiYnDSYnDSYpDigyEDEEAQRGNUb///////8mDSYAAAAAAAAAAAAFAgUqEyoAAAAAAAAAAAAFAgUAAABXU1c2FjVMx+dQx+f///////9Nx+b////4/f6y4vRPt+RQtOT///9Qt+P///8oDSey4vRQr9/////3/P5hzelNx+dNx+dNx+f///8AAAAuDy0zETIAAAAoDScAAAAAAAARBREAAAAvDy40ETMwEC9gSF+Ne42ilKKuoK6Rg5B5ZXlaP1o4Gzf///9nTWZ4YncyEDF/bn/8/Pz9/P339/c1FTUlDCRRM1AbCRtlS2QyEDEuDy1gRWAxEDAzETIwEC/g4OAvDy40EjOaiZorDiq9sbzNyM3UzdQyEDE0ETMzETKflZ/UzdQ5Fzmu4fNYyuhNx+dPt+RLu9xQyOhBbo81GTuW2vCo4PJNx+c4MFE5N1lHiLFEhKQyEDGDboMzETI5Fjh5bXje2d57aHrIw8jc2NyWhJUrDioxe9o4AAAAPnRSTlMAkf+IAQj9+e7n6e31RtqAD/QAAAED+A0ZEQ8DwvkLBsmcR4aG8+cdAD6C8/MC94eP+qoTrgH+/wj1HA8eEvpXOCUAAAABYktHRA8YugDZAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH3wcHFjou4Z/shwAAAUpJREFUOMul0/VTwzAUB/AAwyW4y3B3h8EDNuTh7u6UDHcd8I+TbHSjWdrjju/1h77kc+3Lu5aQvyakF/r6B5wu1+DQMEBomLRtG0EpozYDCEccA4iIjIqOiY0bB5iYxHgZ4FQCpYneKmmal0aQPMOXZnUAvJhLkbpInf8NFtKCTrGImK6DJcTlDGl/BXGV6oCsrSNIYAM3aQDwl2xJYBtBB5lZAuyYgWzY3YMcNcjN2wc4EGMEFTg8+hlyfgEenygAj71Q9FBExH0wKC4p1bRTJlJWXqEAVNM05ovbXfkPAHBmAUQPAGaAsXMBLiwA8z3h0gRcsWsObuAWLJu8Awb3ZoB5T8EvS/CgBo9Y5Z8TPwXBJwlUI9Ia/yRrEZ8lID71Olrf0MiamkkL4kurDEjba+C/e2sninR0wrsH8eMTvrqIWbodjh7jyjdtCY3Aniz4jwAAACV0RVh0ZGF0ZTpjcmVhdGUAMjAxNS0wNy0wN1QyMjo1ODo0NiswMjowMCgWtSoAAAAldEVYdGRhdGU6bW9kaWZ5ADIwMTUtMDctMDdUMjI6NTg6NDYrMDI6MDBZSw2WAAAAAElFTkSuQmCC)](https://clojars.org/honeysql/honeysql) [![cljdoc badge](https://cljdoc.org/badge/honeysql/honeysql?1.0.461)](https://cljdoc.org/d/honeysql/honeysql/CURRENT)
HoneySQL 1.x will continue to get critical security fixes but otherwise should be considered "legacy" at this point.
## License ## License
Copyright (c) 2020-2022 Sean Corfield. HoneySQL 1.x was copyright (c) 2012-2020 Justin Kramer and Sean Corfield. Copyright (c) 2020-2024 Sean Corfield. HoneySQL 1.x was copyright (c) 2012-2020 Justin Kramer and Sean Corfield.
Distributed under the Eclipse Public License, the same as Clojure. Distributed under the Eclipse Public License, the same as Clojure.

36
doc/getting-started.md
View file

@ -32,7 +32,7 @@ required -- using [John Shaffer](https://github.com/john-shaffer)'s awesome
SQL statements are represented as hash maps, with keys that SQL statements are represented as hash maps, with keys that
represent clauses in SQL. SQL expressions are generally represent clauses in SQL. SQL expressions are generally
represented as sequences, where the first element identifies represented as vectors, where the first element identifies
the function or operator and the remaining elements are the the function or operator and the remaining elements are the
arguments or operands. arguments or operands.
@ -54,11 +54,13 @@ or symbols, are treated as positional parameters and replaced
by `?` in the SQL string and lifted out into the vector that by `?` in the SQL string and lifted out into the vector that
is returned from `format`. is returned from `format`.
Most clauses expect a sequence 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 either a list of SQL entities or the representation of a SQL
expression. Some clauses accept a single SQL entity. A few expression. Some clauses accept a single SQL entity. A few
accept a more specialized form (such as `:set` accepting a accept a more specialized form (such as `:set` within an `:update` clause
hash map of SQL entities and SQL expressions). accepting a hash map of SQL entities and SQL expressions).
> Note: clauses can have a list as their value, but literal vectors and keywords are easier to type without quoting.
A SQL entity can be a simple keyword (or symbol) or a pair A SQL entity can be a simple keyword (or symbol) or a pair
that represents a SQL entity and its alias (where aliases are allowed): that represents a SQL entity and its alias (where aliases are allowed):
@ -86,6 +88,8 @@ avoid evaluation:
;;=> ["SELECT t.id, name AS item FROM table AS t WHERE id = ?" 1] ;;=> ["SELECT t.id, name AS item FROM table AS t WHERE id = ?" 1]
``` ```
> Note: these quoted forms may be appealing to users familiar with Datalog-family query languages, and they can be easier to type (and read) in some cases since you do not need to add `:` (shift-`;` on most keyboards) to the start of each SQL entity. The quoted forms do not work well in the [HoneySQL web app](https://john.shaffe.rs/honeysql/) so it's better to stick with vectors and keywords when using that.
If you wish, you can specify SQL entities as namespace-qualified If you wish, you can specify SQL entities as namespace-qualified
keywords (or symbols) and the namespace portion will treated as keywords (or symbols) and the namespace portion will treated as
the table name, i.e., `:foo/bar` instead of `:foo.bar`: the table name, i.e., `:foo/bar` instead of `:foo.bar`:
@ -101,8 +105,8 @@ the table name, i.e., `:foo/bar` instead of `:foo.bar`:
## SQL Expressions ## SQL Expressions
In addition to using hash maps to describe SQL clauses, In addition to using hash maps to describe SQL clauses,
HoneySQL uses sequences to describe SQL expressions. Any HoneySQL uses vectors to describe SQL expressions. Any
sequence that begins with a keyword (or symbol) is considered vector that begins with a keyword (or symbol) is considered
to be a kind of function invocation. Certain "functions" are to be a kind of function invocation. Certain "functions" are
considered to be "special syntax" and have custom rendering. considered to be "special syntax" and have custom rendering.
Some "functions" are considered to be operators. In general, Some "functions" are considered to be operators. In general,
@ -151,22 +155,22 @@ Some examples:
[:now] ;=> "NOW()" [:now] ;=> "NOW()"
[:count :*] ;=> "COUNT(*)" [:count :*] ;=> "COUNT(*)"
[:or [:<> :name nil] [:= :status-id 0]] ;=> "(name IS NOT NULL) OR (status_id = ?)" [:or [:<> :name nil] [:= :status-id 0]] ;=> "(name IS NOT NULL) OR (status_id = ?)"
;; with a parameter of 0 -- the nil value is inlined as NULL ;; the nil value is inlined as NULL but 0 is provided as a parameter
``` ```
`:inline` is an example of "special syntax" and it renders its `:inline` is an example of "special syntax" and it renders its
(single) argument as part of the SQL string generated by `format`. arguments as part of the SQL string generated by `format`.
Another form of special syntax that is treated as function calls Another form of special syntax that is treated as function calls
is keywords or symbols that begin with `%`. Such keywords (or symbols) is keywords or symbols that begin with `%`. Such keywords (or quoted symbols)
are split at `.` and turned into function calls: are split at `.` and turned into function calls:
<!-- :test-doc-blocks/skip --> <!-- :test-doc-blocks/skip -->
```clojure ```clojure
%now ;=> NOW() :%now ;=> NOW()
%count.* ;=> COUNT(*) :%count.* ;=> COUNT(*)
%max.foo ;=> MAX(foo) :%max.foo ;=> MAX(foo)
%f.a.b ;=> F(a,b) :%f.a.b ;=> F(a,b)
``` ```
If you need to reference a table or alias for a column, you can use If you need to reference a table or alias for a column, you can use
@ -200,6 +204,8 @@ expression requires an extra level of nesting:
;;=> ["SELECT x, y AS d, Z(e), Z(f) AS g"] ;;=> ["SELECT x, y AS d, Z(e), Z(f) AS g"]
(sql/format {:select [:x [:y :d] [:%z.e] [:%z.f :g]]}) (sql/format {:select [:x [:y :d] [:%z.e] [:%z.f :g]]})
;;=> ["SELECT x, y AS d, Z(e), Z(f) AS g"] ;;=> ["SELECT x, y AS d, Z(e), Z(f) AS g"]
(sql/format {:select [:x [:y :d] :%z.e [:%z.f :g]]})
;;=> ["SELECT x, y AS d, Z(e), Z(f) AS g"]
``` ```
## SQL Parameters ## SQL Parameters
@ -255,7 +261,7 @@ Or with `:numbered true`:
## Functional Helpers ## Functional Helpers
In addition to the hash map (and sequences) approach of building In addition to the hash map (and vectors) approach of building
SQL queries with raw Clojure data structures, a 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) [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: is also available. These functions are generally variadic and threadable:
@ -348,7 +354,7 @@ The most visible difference between dialects is how SQL entities
should be quoted (if the `:quoted true` option is provided to `format`). should be quoted (if the `:quoted true` option is provided to `format`).
Most databases use `"` for quoting (the `:ansi` and `:oracle` dialects). Most databases use `"` for quoting (the `:ansi` and `:oracle` dialects).
The `:sqlserver` dialect uses `[`..`]` and the `:mysql` dialect uses The `:sqlserver` dialect uses `[`..`]` and the `:mysql` dialect uses
```..```. In addition, the `:oracle` dialect disables `AS` in aliases. ```` .. ````. In addition, the `:oracle` dialect disables `AS` in aliases.
> Note: by default, quoting is **off** which produces cleaner-looking SQL and assumes you control all the symbols/keywords used as table, column, and function names -- the "SQL entities". If you are building any SQL or DDL where the table, column, or function names could be provided by an external source, **you should specify `:quoted true` to ensure all SQL entities are safely quoted**. As of 2.3.928, if you do _not_ specify `:quoted` as an option, HoneySQL will automatically quote any SQL entities that seem unusual, i.e., that contain any characters that are not alphanumeric or underscore. Purely alphanumeric entities will not be quoted (no entities were quoted by default prior to 2.3.928). You can prevent that auto-quoting by explicitly passing `:quoted false` into the `format` call but, from a security point of view, you should think very carefully before you do that: quoting entity names helps protect you from injection attacks! As of 2.4.947, you can change the default setting of `:quoted` from `nil` to `true` (or `false`) via the `set-options!` function. > Note: by default, quoting is **off** which produces cleaner-looking SQL and assumes you control all the symbols/keywords used as table, column, and function names -- the "SQL entities". If you are building any SQL or DDL where the table, column, or function names could be provided by an external source, **you should specify `:quoted true` to ensure all SQL entities are safely quoted**. As of 2.3.928, if you do _not_ specify `:quoted` as an option, HoneySQL will automatically quote any SQL entities that seem unusual, i.e., that contain any characters that are not alphanumeric or underscore. Purely alphanumeric entities will not be quoted (no entities were quoted by default prior to 2.3.928). You can prevent that auto-quoting by explicitly passing `:quoted false` into the `format` call but, from a security point of view, you should think very carefully before you do that: quoting entity names helps protect you from injection attacks! As of 2.4.947, you can change the default setting of `:quoted` from `nil` to `true` (or `false`) via the `set-options!` function.

2
src/honey/sql/helpers.cljc
View file

@ -1,4 +1,4 @@
;; copyright (c) 2020-2023 sean corfield, all rights reserved ;; copyright (c) 2020-2024 sean corfield, all rights reserved
(ns honey.sql.helpers (ns honey.sql.helpers
"Helper functions for the built-in clauses in honey.sql. "Helper functions for the built-in clauses in honey.sql.

2
src/honey/sql/pg_ops.cljc
View file

@ -1,4 +1,4 @@
;; copyright (c) 2022 sean corfield, all rights reserved ;; copyright (c) 2022-2024 sean corfield, all rights reserved
(ns honey.sql.pg-ops (ns honey.sql.pg-ops
"Register all the PostgreSQL JSON/JSONB operators "Register all the PostgreSQL JSON/JSONB operators

2
src/honey/sql/protocols.cljc
View file

@ -1,4 +1,4 @@
;; copyright (c) 2022 sean corfield, all rights reserved ;; copyright (c) 2022-2024 sean corfield, all rights reserved
(ns honey.sql.protocols (ns honey.sql.protocols
"InlineValue -- a protocol that defines how to inline "InlineValue -- a protocol that defines how to inline

2
test/honey/bigquery_test.cljc
View file

@ -1,4 +1,4 @@
;; copyright (c) 2022 sean corfield, all rights reserved ;; copyright (c) 2022-2024 sean corfield, all rights reserved
(ns honey.bigquery-test (ns honey.bigquery-test
(:refer-clojure :exclude [format]) (:refer-clojure :exclude [format])

2
test/honey/cache_test.clj
View file

@ -1,4 +1,4 @@
;; copyright (c) 2022 sean corfield, all rights reserved ;; copyright (c) 2022-2024 sean corfield, all rights reserved
(ns honey.cache-test (ns honey.cache-test
(:refer-clojure :exclude [format group-by]) (:refer-clojure :exclude [format group-by])

2
test/honey/ops_test.cljc
View file

@ -1,4 +1,4 @@
;; copyright (c) 2023 sean corfield, all rights reserved ;; copyright (c) 2023-2024 sean corfield, all rights reserved
(ns honey.ops-test (ns honey.ops-test
(:refer-clojure :exclude [format]) (:refer-clojure :exclude [format])

2
test/honey/sql/pg_ops_test.cljc
View file

@ -1,4 +1,4 @@
;; copyright (c) 2022 sean corfield, all rights reserved ;; copyright (c) 2022-2024 sean corfield, all rights reserved
(ns honey.sql.pg-ops-test (ns honey.sql.pg-ops-test
(:require [clojure.test :refer [deftest is testing]] (:require [clojure.test :refer [deftest is testing]]

2
test/honey/union_test.cljc
View file

@ -1,4 +1,4 @@
;; copyright (c) 2023 sean corfield, all rights reserved ;; copyright (c) 2023-2024 sean corfield, all rights reserved
(ns honey.union-test (ns honey.union-test
(:refer-clojure :exclude [format]) (:refer-clojure :exclude [format])