Liking cljdoc? Tell your friends :D

honey.sql

Primary API for HoneySQL 2.x.

This includes the format function -- the primary entry point -- as well as several public formatters that are intended to help users extend the supported syntax.

In addition, functions to extend HoneySQL are also provided here:

  • clause-order -- returns the current clause priority ordering; intended as aid when registering new clauses.
  • format-dsl -- intended to format SQL statements; returns a vector containing a SQL string followed by parameter values.
  • format-entity -- intended to format SQL entities; returns a string representing the SQL entity.
  • format-expr -- intended to format SQL expressions; returns a vector containing a SQL string followed by parameter values.
  • format-expr-list -- intended to format a list of SQL expressions; returns a pair comprising: a sequence of SQL expressions (to be join with a delimiter) and a sequence of parameter values.
  • register-clause! -- register a new statement/clause formatter.
  • register-fn! -- register a new function call (or special syntax) formatter.
  • register-op! -- register a new operator formatter.
  • set-dialect! -- set the default dialect to be used for formatting, and optionally set a global :quoted option.
  • sql-kw -- turns a Clojure keyword (or symbol) into SQL code (makes it uppercase and replaces - with space).
Primary API for HoneySQL 2.x.

This includes the `format` function -- the primary entry point -- as well
as several public formatters that are intended to help users extend the
supported syntax.

In addition, functions to extend HoneySQL are also provided here:
* `clause-order` -- returns the current clause priority ordering;
      intended as aid when registering new clauses.
* `format-dsl` -- intended to format SQL statements; returns a vector
      containing a SQL string followed by parameter values.
* `format-entity` -- intended to format SQL entities; returns a string
      representing the SQL entity.
* `format-expr` -- intended to format SQL expressions; returns a vector
      containing a SQL string followed by parameter values.
* `format-expr-list` -- intended to format a list of SQL expressions;
      returns a pair comprising: a sequence of SQL expressions (to be
      join with a delimiter) and a sequence of parameter values.
* `register-clause!` -- register a new statement/clause formatter.
* `register-fn!` -- register a new function call (or special syntax)
      formatter.
* `register-op!` -- register a new operator formatter.
* `set-dialect!` -- set the default dialect to be used for formatting,
      and optionally set a global `:quoted` option.
* `sql-kw` -- turns a Clojure keyword (or symbol) into SQL code (makes
      it uppercase and replaces - with space). 
raw docstring

->numberedclj/s

(->numbered v)
source

->numbered-paramclj/s

(->numbered-param k)
source

add-clause-beforeclj/s

(add-clause-before order clause before)

Low-level helper just to insert a new clause.

If the clause is already in the list, this moves it to the end.

Low-level helper just to insert a new clause.

If the clause is already in the list, this moves it to the end.
sourceraw docstring

clause-bodyclj/s

(clause-body clause)

If the current DSL expression being formatted contains the specified clause (as a keyword or symbol), returns that clause's value.

If the current DSL expression being formatted contains the specified clause
(as a keyword or symbol), returns that clause's value.
sourceraw docstring

clause-orderclj/s

(clause-order)

Return the current order that known clauses will be applied when formatting a data structure into SQL. This may be useful when you are figuring out the before argument of register-clause! as well as for debugging new clauses you have registered.

Return the current order that known clauses will be applied when
formatting a data structure into SQL. This may be useful when you are
figuring out the `before` argument of `register-clause!` as well as
for debugging new clauses you have registered.
sourceraw docstring

contains-clause?clj/s

(contains-clause? clause)

Returns true if the current DSL expression being formatted contains the specified clause (as a keyword or symbol).

Returns true if the current DSL expression being formatted
contains the specified clause (as a keyword or symbol).
sourceraw docstring

formatclj/s

(format data)
(format data opts)
(format data k v & {:as opts})

Turn the data DSL into a vector containing a SQL string followed by any parameter values that were encountered in the DSL structure.

This is the primary API for HoneySQL and handles dialects, quoting, and named parameters.

If the data DSL is a hash map, it will be treated as a SQL statement and formatted via format-dsl, otherwise it will be treated as a SQL expression and formatted via format-expr.

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.

Turn the data DSL into a vector containing a SQL string followed by
any parameter values that were encountered in the DSL structure.

This is the primary API for HoneySQL and handles dialects, quoting,
and named parameters.

If the data DSL is a hash map, it will be treated as a SQL statement
and formatted via `format-dsl`, otherwise it will be treated as a SQL
expression and formatted via `format-expr`.

`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.
sourceraw docstring

format-dslclj/s

(format-dsl statement-map & [{:keys [aliased nested pretty]}])

Given a hash map representing a SQL statement and a hash map of options, return a vector containing a string -- the formatted SQL statement -- followed by any parameter values that SQL needs.

This is intended to be used when writing your own formatters to extend the DSL supported by HoneySQL.

Given a hash map representing a SQL statement and a hash map
of options, return a vector containing a string -- the formatted
SQL statement -- followed by any parameter values that SQL needs.

This is intended to be used when writing your own formatters to
extend the DSL supported by HoneySQL.
sourceraw docstring

format-entityclj/s

(format-entity e & [{:keys [aliased drop-ns]}])

Given a simple SQL entity (a keyword or symbol -- or string), return the equivalent SQL fragment (as a string -- no parameters).

Handles quoting, splitting at / or ., replacing - with _ etc.

Given a simple SQL entity (a keyword or symbol -- or string),
return the equivalent SQL fragment (as a string -- no parameters).

Handles quoting, splitting at / or ., replacing - with _ etc.
sourceraw docstring

format-exprclj/s

(format-expr expr & [{:keys [nested] :as opts}])

Given a data structure that represents a SQL expression and a hash map of options, return a vector containing a string -- the formatted SQL statement -- followed by any parameter values that SQL needs.

This is intended to be used when writing your own formatters to extend the DSL supported by HoneySQL.

Given a data structure that represents a SQL expression and a hash
map of options, return a vector containing a string -- the formatted
SQL statement -- followed by any parameter values that SQL needs.

This is intended to be used when writing your own formatters to
extend the DSL supported by HoneySQL.
sourceraw docstring

format-expr-listclj/s

(format-expr-list exprs & [opts])

Given a sequence of expressions represented as data, return a pair where the first element is a sequence of SQL fragments and the second element is a sequence of parameters. The caller should join the SQL fragments with whatever appropriate delimiter is needed and then return a vector whose first element is the complete SQL string and whose subsequent elements are the parameters:

(let [[sqls params] (format-expr-list data opts)] (into [(str/join delim sqls)] params))

This is intended to be used when writing your own formatters to extend the DSL supported by HoneySQL.

Given a sequence of expressions represented as data, return a pair
where the first element is a sequence of SQL fragments and the second
element is a sequence of parameters. The caller should join the SQL
fragments with whatever appropriate delimiter is needed and then
return a vector whose first element is the complete SQL string and
whose subsequent elements are the parameters:

(let [[sqls params] (format-expr-list data opts)]
  (into [(str/join delim sqls)] params))

This is intended to be used when writing your own formatters to
extend the DSL supported by HoneySQL.
sourceraw docstring

format-interspersed-expr-listclj/s

(format-interspersed-expr-list args & [opts])

If there are inline (SQL) keywords, use them to join the formatted expressions together. Otherwise behaves like plain format-expr-list.

This allows for argument lists like:

  • [:overlay :foo :*placing :?subs :*from 3 :*for 4]
  • [:trim :*leading-from :bar]
If there are inline (SQL) keywords, use them to join the formatted
expressions together. Otherwise behaves like plain format-expr-list.

This allows for argument lists like:
* [:overlay :foo :*placing :?subs :*from 3 :*for 4]
* [:trim :*leading-from :bar]
sourceraw docstring

formatfclj/s

(formatf dsl & params)

Experimental implementation of https://github.com/seancorfield/honeysql/issues/495

Currently, does not support options.

Experimental implementation of https://github.com/seancorfield/honeysql/issues/495

Currently, does not support options.
sourceraw docstring

get-dialectclj/s

(get-dialect dialect)

Given a dialect name (keyword), return its definition. Returns nil if the dialect is unknown.

Given a dialect name (keyword), return its definition.
Returns `nil` if the dialect is unknown.
sourceraw docstring

ignore-respect-nullsclj/s

(ignore-respect-nulls k [x])
source

map=clj/s

(map= data)

Given a hash map, return a condition structure that can be used in a WHERE clause to test for equality:

{:select :* :from :table :where (sql/map= {:id 1})}

will produce: SELECT * FROM table WHERE id = ? (and a parameter of 1)

Given a hash map, return a condition structure that can be used in a
WHERE clause to test for equality:

{:select :* :from :table :where (sql/map= {:id 1})}

will produce: SELECT * FROM table WHERE id = ? (and a parameter of 1)
sourceraw docstring

register-clause!clj/s

(register-clause! clause formatter before)

Register a new clause formatter. If before is nil, the clause is added to the end of the list of known clauses, otherwise it is inserted immediately prior to that clause.

New clauses are registered in the base order and the current order so that any dialect selections are able to include them while still working predictably from the base order. Caveat: that means if you register a new clause before a clause that is ordered differently in different dialects, your new clause may also end up in a different place. The only clause so far where that would matter is :set which differs in MySQL.

Use clause-order to see the full ordering of existing clauses.

Register a new clause formatter. If `before` is `nil`, the clause is
added to the end of the list of known clauses, otherwise it is inserted
immediately prior to that clause.

New clauses are registered in the base order and the current order so
that any dialect selections are able to include them while still working
predictably from the base order. Caveat: that means if you register a new
clause `before` a clause that is ordered differently in different
dialects, your new clause may also end up in a different place. The
only clause so far where that would matter is `:set` which differs in
MySQL.

Use `clause-order` to see the full ordering of existing clauses.
sourceraw docstring

register-dialect!clj/s

(register-dialect! dialect dialect-spec)

Register a new dialect. Accepts a dialect name (keyword) and a hash map that must contain at least a :quoted key whose value is a unary function that accepts a string and returns it quoted per the dialect.

It may also contain a :clause-order-fn key whose value is a unary function that accepts a list of SQL clauses (keywords) in order of precedence and returns an updated list of SQL clauses in order. It may use add-clause-before to achieve this. Currently, the only dialect that does this is MySQL, whose SET clause (:set) has a non-standard precedence, compared to other SQL dialects.

Register a new dialect. Accepts a dialect name (keyword) and a hash
map that must contain at least a `:quoted` key whose value is a unary
function that accepts a string and returns it quoted per the dialect.

It may also contain a `:clause-order-fn` key whose value is a unary
function that accepts a list of SQL clauses (keywords) in order of
precedence and returns an updated list of SQL clauses in order. It
may use `add-clause-before` to achieve this. Currently, the only
dialect that does this is MySQL, whose `SET` clause (`:set`) has a
non-standard precedence, compared to other SQL dialects.
sourceraw docstring

register-fn!clj/s

(register-fn! function formatter)

Register a new function (as special syntax). The formatter is either a keyword, meaning that this new function should use the same syntax as an existing function, or a function of two arguments that generates a SQL string and parameters (as a vector). The two arguments are the name of the function (as a keyword) and a sequence of the arguments from the DSL.

Register a new function (as special syntax). The `formatter` is either
a keyword, meaning that this new function should use the same syntax as
an existing function, or a function of two arguments that generates a
SQL string and parameters (as a vector). The two arguments are the name
of the function (as a keyword) and a sequence of the arguments from the
DSL.
sourceraw docstring

register-op!clj/s

(register-op! op & {:keys [ignore-nil]})

Register a new infix operator. All operators are variadic and may choose to ignore nil arguments (this can make it easier to programmatically construct the DSL).

Register a new infix operator. All operators are variadic and may choose
to ignore `nil` arguments (this can make it easier to programmatically
construct the DSL).
sourceraw docstring

registered-clause?clj/s

(registered-clause? clause)

Return true if the clause is known to HoneySQL.

Return true if the clause is known to HoneySQL.
sourceraw docstring

registered-dialect?clj/s

(registered-dialect? dialect)

Return true if the dialect is known to HoneySQL.

Return true if the dialect is known to HoneySQL.
sourceraw docstring

registered-fn?clj/s

(registered-fn? function)

Return true if the function is known to HoneySQL.

Return true if the function is known to HoneySQL.
sourceraw docstring

registered-op?clj/s

(registered-op? op)

Return true if the operator is known to HoneySQL.

Return true if the operator is known to HoneySQL.
sourceraw docstring

set-dialect!clj/s

(set-dialect! dialect & {:keys [quoted]})

Set the default dialect for formatting.

Can be: :ansi (the default), :mysql, :oracle, or :sqlserver.

Can optionally accept :quoted true (or :quoted false) to set the default global quoting strategy. Without :quoted, the default global quoting strategy will be reset (only quoting unusual entity names).

Note that calling set-options! can override this default.

Dialects are always applied to the base order to create the current order.

Set the default dialect for formatting.

Can be: `:ansi` (the default), `:mysql`, `:oracle`, or `:sqlserver`.

Can optionally accept `:quoted true` (or `:quoted false`) to set the
default global quoting strategy. Without `:quoted`, the default global
quoting strategy will be reset (only quoting unusual entity names).

Note that calling `set-options!` can override this default.

Dialects are always applied to the base order to create the current order.
sourceraw docstring

set-options!clj/s

(set-options! opts)

Set default values for any or all of the following options:

  • :checking
  • :inline
  • :numbered
  • :quoted
  • :quoted-snake Note that calling set-dialect! can override the default for :quoted.
Set default values for any or all of the following options:
* :checking
* :inline
* :numbered
* :quoted
* :quoted-snake
Note that calling `set-dialect!` can override the default for `:quoted`.
sourceraw docstring

sql-kwclj/s

(sql-kw k)

Given a keyword, return a SQL representation of it as a string.

A keyword whose name begins with a single quote is left exactly as-is (with the : and ' removed), otherwise a :kebab-case keyword becomes a KEBAB CASE (uppercase) string with hyphens replaced by spaces, e.g., :insert-into => INSERT INTO.

Any namespace qualifier is ignored.

Any ? is escaped to ??.

Given a keyword, return a SQL representation of it as a string.

A keyword whose name begins with a single quote is left exactly as-is
(with the `:` and `'` removed), otherwise a `:kebab-case` keyword
becomes a `KEBAB CASE` (uppercase) string with hyphens replaced
by spaces, e.g., `:insert-into` => `INSERT INTO`.

Any namespace qualifier is ignored.

Any ? is escaped to ??.
sourceraw docstring

stropclj/s

(strop s x e)

Escape any embedded closing strop characters.

Escape any embedded closing strop characters.
sourceraw docstring

through-optsclj/s

If org.clojure/core.cache is available, resolves to a function that calls core.cache.wrapped/lookup-or-miss, otherwise to a function that throws an exception.

In ClojureScript, a resolves to a function that throws an exception because core.cache relies on JVM machinery and is Clojure-only.

If org.clojure/core.cache is available, resolves to a function that
calls core.cache.wrapped/lookup-or-miss, otherwise to a function that
throws an exception.

In ClojureScript, a resolves to a function that throws an exception
because core.cache relies on JVM machinery and is Clojure-only.
sourceraw docstring

upper-caseclj/s≠

(upper-case s)
clj

Upper-case a string in Locale/US to avoid locale-specific capitalization.

Upper-case a string in Locale/US to avoid locale-specific capitalization.
cljs

In ClojureScript, just an alias for cljs.string/upper-case.

In ClojureScript, just an alias for cljs.string/upper-case.
source (clj)source (cljs)raw docstring

cljdoc is a website building & hosting documentation for Clojure/Script libraries

× close