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

Fix #213 by add raw/inline explanations to README

Browse source
This commit is contained in:
Sean Corfield 2018-06-25 12:30:48 -07:00
parent 83f16780b0
commit cc9b786602
1 changed files with 10 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

18
README.md
View file

@ -114,7 +114,7 @@ To add to clauses instead of replacing them, use `merge-select`, `merge-where`,
=> ["SELECT * FROM foo WHERE (a = ? AND b < ?)" 1 100] => ["SELECT * FROM foo WHERE (a = ? AND b < ?)" 1 100]
``` ```
Inserts are supported in two patterns. Inserts are supported in two patterns.
In the first pattern, you must explicitly specify the columns to insert, In the first pattern, you must explicitly specify the columns to insert,
then provide a collection of rows, each a collection of column values: then provide a collection of rows, each a collection of column values:
@ -227,23 +227,25 @@ Keywords that begin with `?` are interpreted as bindable parameters:
=> ["SELECT id FROM foo WHERE a = ?" "BAZ"] => ["SELECT id FROM foo WHERE a = ?" "BAZ"]
``` ```
There are helper functions and data literals for SQL function calls, field qualifiers, raw SQL fragments, and named input parameters: There are helper functions and data literals for SQL function calls, field qualifiers, raw SQL fragments, inline values, and named input parameters:
```clojure ```clojure
(def call-qualify-map (def call-qualify-map
(-> (select (sql/call :foo :bar) (sql/qualify :foo :a) (sql/raw "@var := foo.bar")) (-> (select (sql/call :foo :bar) (sql/qualify :foo :a) (sql/raw "@var := foo.bar"))
(from :foo) (from :foo)
(where [:= :a (sql/param :baz)]))) (where [:= :a (sql/param :baz)] [:= :b (sql/inline 42)])))
call-qualify-map call-qualify-map
=> '{:where [:= :a #sql/param :baz] => '{:where [:and [:= :a #sql/param :baz] [:= :b #sql/inline 42]]
:from (:foo) :from (:foo)
:select (#sql/call [:foo :bar] :foo.a #sql/raw "@var := foo.bar")} :select (#sql/call [:foo :bar] :foo.a #sql/raw "@var := foo.bar")}
(sql/format call-qualify-map :params {:baz "BAZ"}) (sql/format call-qualify-map :params {:baz "BAZ"})
=> ["SELECT foo(bar), foo.a, @var := foo.bar FROM foo WHERE a = ?" "BAZ"] => ["SELECT foo(bar), foo.a, @var := foo.bar FROM foo WHERE (a = ? AND b = 42)" "BAZ"]
``` ```
Raw SQL fragments are treated exactly as-is when rendered into the formatted SQL string (with no parsing or parameterization). Inline values will not be lifted out as parameters, so they end up in the SQL string as-is.
To quote identifiers, pass the `:quoting` keyword option to `format`. Valid options are `:ansi` (PostgreSQL), `:mysql`, or `:sqlserver`: To quote identifiers, pass the `:quoting` keyword option to `format`. Valid options are `:ansi` (PostgreSQL), `:mysql`, or `:sqlserver`:
```clojure ```clojure
@ -382,7 +384,7 @@ You can also define your own clauses:
``` ```
If you do implement a clause or function handler, consider submitting a pull request so others can use it, too. If you do implement a clause or function handler, consider submitting a pull request so others can use it, too.
## why does my parameter get emitted as `()`? ## why does my parameter get emitted as `()`?
If you want to use your own datatype as a parameter then the idiomatic approach of implementing `clojure.java.jdbc`'s [`ISQLValue`](https://clojure.github.io/java.jdbc/#clojure.java.jdbc/ISQLValue) protocol isn't enough as `honeysql` won't correct pass through your datatype, rather it will interpret it incorrectly. If you want to use your own datatype as a parameter then the idiomatic approach of implementing `clojure.java.jdbc`'s [`ISQLValue`](https://clojure.github.io/java.jdbc/#clojure.java.jdbc/ISQLValue) protocol isn't enough as `honeysql` won't correct pass through your datatype, rather it will interpret it incorrectly.
@ -399,10 +401,10 @@ To teach `honeysql` how to handle your datatype you need to implement [`honeysql
;; results in => "where :some_column > ()" ;; results in => "where :some_column > ()"
;; we can teach honeysql about it: ;; we can teach honeysql about it:
(extend-protocol honeysql.format.ToSql (extend-protocol honeysql.format.ToSql
MyDateWrapper MyDateWrapper
(to-sql [v] (to-sql (date/to-sql-timestamp v)))) (to-sql [v] (to-sql (date/to-sql-timestamp v))))
;; allowing us to now: ;; allowing us to now:
(hsql/format {:where [:> :some_column (MyDateWrapper. ...)]}) (hsql/format {:where [:> :some_column (MyDateWrapper. ...)]})
;; which correctly results in => "where :some_column>?" and the parameter correctly set ;; which correctly results in => "where :some_column>?" and the parameter correctly set