Consistent use of 1.x / 2.x
This commit is contained in:
Sean Corfield
parent
f393a61010
commit
862a2496c6
8 changed files with 29 additions and 37 deletions
|
|
@ -17,13 +17,13 @@
|
|||
* Fix #305 by supporting more complex join clauses.
|
||||
* Fix #303 by supporting MySQL's `ON DUPLICATE KEY UPDATE`.
|
||||
* Fix #301 by adding support for `CREATE`/`DROP`/`REFRESH` on `MATERIALIZED VIEW`.
|
||||
* Add tests to confirm #299 does not affect v2.
|
||||
* Add tests to confirm #299 does not affect 2.x.
|
||||
* Fix #297 by adding both `SELECT .. INTO ..` and `SELECT .. BULK COLLECT INTO ..`.
|
||||
* Fix #295 by adding docstrings to all helper functions (and adding an assert to ensure it stays that way as more are added in future).
|
||||
* Confirm the whole of the [nilenso/honeysql-postgres](https://github.com/nilenso/honeysql-postgres) is implemented out-of-the-box (#293, but see #310 for recent additions not yet incorporated).
|
||||
* Fix #292 by adding support for `SELECT TOP` and `OFFSET`/`FETCH`.
|
||||
* Fix #284 by adding support for `LATERAL` (as special syntax, with a helper).
|
||||
* Reconcile `where` behavior with recent 1.0 changes (porting #283 to v2).
|
||||
* Reconcile `where` behavior with recent 1.x changes (porting #283 to 2.x).
|
||||
* Fix #280 by adding `:escape` as special syntax for regular expression patterns.
|
||||
* Fix #277 by adding `:join-by`/`join-by` so that you can have multiple `JOIN`'s in a specific order.
|
||||
|
||||
|
|
@ -35,7 +35,7 @@
|
|||
* This is a complete rewrite/simplification of HoneySQL that provides just two namespaces:
|
||||
* `honey.sql` -- this is the primary API via the `format` function as well as the various extension points.
|
||||
* `honey.sql.helpers` -- provides a helper function for every piece of the DSL that is supported out-of-the-box.
|
||||
* The coordinates for HoneySQL 2.0 are `com.github.seancorfield/honeysql` so it can be added to a project that already uses HoneySQL 1.0 without any conflicts, making it easier to migrate piecemeal from 1.0 to 2.0.
|
||||
* The coordinates for HoneySQL 2.x are `com.github.seancorfield/honeysql` so it can be added to a project that already uses HoneySQL 1.x without any conflicts, making it easier to migrate piecemeal from 1.x to 2.x.
|
||||
|
||||
# HoneySQL pre-2.x Changes
|
||||
|
||||
|
|
|
|||
14
README.md
14
README.md
|
|
@ -4,21 +4,15 @@ SQL as Clojure data structures. Build queries programmatically -- even at runtim
|
|||
|
||||
## Build
|
||||
|
||||
The latest stable version (1.0.461) on Clojars and on cljdoc (note: `honeysql/honeysql`):
|
||||
|
||||
[](https://clojars.org/honeysql/honeysql) [](https://cljdoc.org/d/honeysql/honeysql/1.0.461)
|
||||
[](https://clojars.org/com.github.seancorfield/honeysql) [](https://cljdoc.org/d/com.github.seancorfield/honeysql/2.0.0-beta1)
|
||||
|
||||
This project follows the version scheme MAJOR.MINOR.COMMITS where MAJOR and MINOR provide some relative indication of the size of the change, but do not follow semantic versioning. In general, all changes endeavor to be non-breaking (by moving to new names rather than by breaking existing names). COMMITS is an ever-increasing counter of commits since the beginning of this repository.
|
||||
|
||||
Prerelease builds of the upcoming 2.x version of HoneySQL are available for testing:
|
||||
|
||||
[](https://clojars.org/com.github.seancorfield/honeysql) [](https://cljdoc.org/d/com.github.seancorfield/honeysql/2.0.0-beta1)
|
||||
|
||||
HoneySQL 2.x requires Clojure 1.9 or later.
|
||||
|
||||
This is the README for the upcoming 2.x version of HoneySQL which 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 the 1.x version).
|
||||
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).
|
||||
|
||||
See this [summary of differences between v1 and v2](doc/differences-from-1-x.md) if you want to help test v2!
|
||||
> 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 on code samples
|
||||
|
||||
|
|
@ -83,8 +77,6 @@ If you want to format the query as a string with no parameters (e.g. to use the
|
|||
|
||||
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.
|
||||
|
||||
_[In HoneySQL 1.x, this was the behavior when `:namespace-as-table? true` was specified]_
|
||||
|
||||
```clojure
|
||||
(def q-sqlmap {:select [:foo/a :foo/b :foo/c]
|
||||
:from [:foo]
|
||||
|
|
|
|||
|
|
@ -480,7 +480,7 @@ example above with `:insert-into`.
|
|||
that they should be assigned. This precedence -- between
|
||||
`:columns` and `:from` -- corresponds to ANSI SQL which
|
||||
is correct for most databases. The MySQL dialect that
|
||||
HoneySQL 2.0 supports has a different precedence (below).
|
||||
HoneySQL 2.x supports has a different precedence (below).
|
||||
|
||||
```clojure
|
||||
user=> (sql/format {:update :order
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ The goal of HoneySQL 1.x and earlier was to provide a DSL for vendor-neutral SQL
|
|||
The goal of HoneySQL 2.x is to provide an easily-extensible DSL for SQL, supporting vendor-specific differences and extensions, that is as consistent as possible. A secondary goal is to make maintenance much easier by streamlining the machinery and reducing the number of different ways to write and/or extend the DSL.
|
||||
|
||||
The DSL itself -- the data structures that both versions convert to SQL and parameters via the `format` function -- is almost exactly the same between the two versions so that migration is relatively painless. The primary API -- the `format` function -- is preserved in 2.x, although the options have changed between 1.x and 2.x. See the **Option Changes** section below for the differences in the options supported.
|
||||
`format` can accept its options as a single hash map or as named arguments (v1 only supported the latter).
|
||||
`format` can accept its options as a single hash map or as named arguments (1.x only supported the latter).
|
||||
If you are using Clojure 1.11, you can invoke `format` with a mixture of named arguments and a trailing hash
|
||||
map of additional options, if you wish.
|
||||
|
||||
|
|
@ -49,7 +49,7 @@ Supported Clojure versions: 1.7 and later.
|
|||
|
||||
```clojure
|
||||
;; in deps.edn:
|
||||
com.github.seancorfield/honeysql {:mvn/version "2.x"}
|
||||
com.github.seancorfield/honeysql {:mvn/version "2.0.0-beta1"}
|
||||
|
||||
;; in use:
|
||||
(ns my.project
|
||||
|
|
@ -85,11 +85,11 @@ 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).
|
||||
* `:allow-dashed-names?` -- if you provide dashed-names in 2.x, 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`.
|
||||
* `:namespace-as-table?` -- this is the default in 2.x: `: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).
|
||||
* `:return-param-names` -- this was added to v1 back in 2013 without an associated issue or PR so I've no idea what use case this was intended to support.
|
||||
* `:return-param-names` -- this was added to 1.x back in 2013 without an associated issue or PR so I've no idea what use case this was intended to support.
|
||||
|
||||
> Note: I expect some push back on those first three options and the associated behavior changes.
|
||||
|
||||
|
|
@ -114,12 +114,12 @@ The following new syntax has been added:
|
|||
* `: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.
|
||||
* `: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 1.x behavior but should be more flexible, since you can now embed `:inline`, `:param`, and `:lift` inside a `:raw` expression.
|
||||
|
||||
> 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
|
||||
definitions in `CREATE TABLE` clauses, now that 2.x supports DDL statement
|
||||
construction:
|
||||
|
||||
* `:constraint`, `:default`, `:foreign-key`, `:index`, `:primary-key`, `:references`, `:unique`,
|
||||
|
|
@ -135,7 +135,7 @@ user=> (sql/format {:select [:a [:b :c] [[:d :e]] [[:f :g] :h]]})
|
|||
["SELECT a, b AS c, D(e), F(g) AS h"]
|
||||
```
|
||||
|
||||
On a related note, `sql/call` has been removed because it should never be needed now: `[:foo ...]` should always be treated as a function call, consistently, avoiding the special cases in v1 that necessitated the explicit `sql/call` syntax.
|
||||
On a related note, `sql/call` has been removed because it should never be needed now: `[:foo ...]` should always be treated as a function call, consistently, avoiding the special cases in 1.x that necessitated the explicit `sql/call` syntax.
|
||||
|
||||
### select modifiers
|
||||
|
||||
|
|
@ -173,11 +173,11 @@ You can also register new "functions" that can implement special syntax (such as
|
|||
|
||||
And, finally, you can register new operators that will be recognized in expressions via `honey.sql/register-op!`. This accepts an operator name as a keyword and optional named parameters to indicate whether the operator is `:variadic` (the default is strictly binary) and whether it should ignore operands that evaluate to `nil` (via `:ignore-nil`). The latter can make it easier to construct complex expressions programmatically without having to worry about conditionally removing "optional" (`nil`) values.
|
||||
|
||||
> Note: because of the changes in the extension machinery between v1 and v2, it is not possible to use the https://github.com/nilenso/honeysql-postgres library with HoneySQL v2 but the goal is to incorporate all of the syntax from that library into the core of HoneySQL.
|
||||
> Note: because of the changes in the extension machinery between 1.x and 2.x, it is not possible to use the https://github.com/nilenso/honeysql-postgres library with HoneySQL 2.x but the goal is to incorporate all of the syntax from that library into the core of HoneySQL.
|
||||
|
||||
## Helpers
|
||||
|
||||
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 `honey.sql.helpers` namespace includes a helper function that corresponds to every supported piece of the data DSL understood by HoneySQL (1.x only had a limited set of helper functions). Unlike 1.x helpers which sometimes had both a regular helper and a `merge-` helper, 2.x 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:
|
||||
* The SQL set operations `intersect`, `union`, `union-all`, `except`, and `except-all` which always wrap around their arguments,
|
||||
|
|
|
|||
|
|
@ -77,9 +77,9 @@ qualifier from the name, regardless of the `:dialect` or `:quoted` settings:
|
|||
|
||||
Some databases support "composite values" which are usually
|
||||
represented as tuples in SQL, eg., `(col1,col2)` or `(13,42,'foo')`.
|
||||
In HoneySQL v1, you could sometimes get away with just using a
|
||||
In HoneySQL 1.x, you could sometimes get away with just using a
|
||||
vector of entities and/or values, but it was very much dependent
|
||||
on the context. HoneySQL v2 always treats vectors (and sequences)
|
||||
on the context. HoneySQL 2.x always treats vectors (and sequences)
|
||||
as function calls (which may be "special syntax" or an actual
|
||||
function call).
|
||||
|
||||
|
|
@ -111,5 +111,5 @@ 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-beta1/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.
|
||||
If you're migrating to HoneySQL 2.x, this [overview of differences
|
||||
between 1.x and 2.x](differences-from-1-x.md) should help.
|
||||
|
|
|
|||
|
|
@ -246,7 +246,7 @@ a lot of PostgreSQL extensions in that mode. PostgreSQL is mostly
|
|||
a superset of ANSI SQL so it makes sense to support as much as
|
||||
possible of the union of ANSI SQL and PostgreSQL out of the box.
|
||||
|
||||
The dialects supported by HoneySQL v2 are:
|
||||
The dialects supported by HoneySQL 2.x are:
|
||||
* `:ansi` -- the default, including most PostgreSQL extensions
|
||||
* `:sqlserver` -- Microsoft SQL Server
|
||||
* `:mysql` -- MySQL (and Percona and MariaDB)
|
||||
|
|
@ -321,5 +321,5 @@ documentation for the helper functions is in the
|
|||
[honey.sql.helpers](https://cljdoc.org/d/com.github.seancorfield/honeysql/2.0.0-beta1/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.
|
||||
If you're migrating to HoneySQL 2.x, this [overview of differences
|
||||
between 1.x and 2.x](differences-from-1-x.md) should help.
|
||||
|
|
|
|||
|
|
@ -1,11 +1,11 @@
|
|||
;; copied from https://github.com/nilenso/honeysql-postgres
|
||||
;; on 2021-02-13 to verify the completeness of support for
|
||||
;; those features within HoneySQL v2
|
||||
;; those features within HoneySQL 2.x
|
||||
|
||||
;; where there are differences, the original code is kept
|
||||
;; with #_ and the modified code follows it (aside from
|
||||
;; the ns form which has numerous changes to both match
|
||||
;; the structure of HoneySQL v2 and to work with cljs)
|
||||
;; the structure of HoneySQL 2.x and to work with cljs)
|
||||
|
||||
(ns honey.sql.postgres-test
|
||||
(:refer-clojure :exclude [update partition-by set])
|
||||
|
|
|
|||
|
|
@ -83,7 +83,7 @@
|
|||
:from [:Candidate]} :sub-q-alias]]}
|
||||
{:dialect :oracle :quoted false}))))
|
||||
|
||||
;; tests lifted from HoneySQL v1 to check for compatibility
|
||||
;; tests lifted from HoneySQL 1.x to check for compatibility
|
||||
|
||||
(deftest alias-splitting
|
||||
(is (= ["SELECT `aa`.`c` AS `a.c`, `bb`.`c` AS `b.c`, `cc`.`c` AS `c.c`"]
|
||||
|
|
@ -311,7 +311,7 @@
|
|||
[:= :quux "quux"]]}
|
||||
{:parameterizer :postgresql})
|
||||
["WHERE (foo = ?) AND (bar = $2) AND (quux = $3)" "foo" "bar" "quux"])))
|
||||
;; new :inline option is similar to :parameterizer :none in 1.0
|
||||
;; new :inline option is similar to :parameterizer :none in 1.x
|
||||
(testing "should fill param with single quote"
|
||||
(is (= (format {:where [:and
|
||||
[:= :foo "foo"]
|
||||
|
|
@ -642,7 +642,7 @@ ORDER BY id = ? DESC
|
|||
|
||||
(deftest issue-299-test
|
||||
(let [name "test field"
|
||||
;; this was a bug in v1 -- adding here to prevent regression:
|
||||
;; this was a bug in 1.x -- adding here to prevent regression:
|
||||
enabled [true, "); SELECT case when (SELECT current_setting('is_superuser'))='off' then pg_sleep(0.2) end; -- "]]
|
||||
(is (= ["INSERT INTO table (name, enabled) VALUES (?, (TRUE, ?))" name (second enabled)]
|
||||
(format {:insert-into :table
|
||||
|
|
|
|||
Loading…
Reference in a new issue