{"id":13591597,"url":"https://github.com/seancorfield/honeysql","last_synced_at":"2026-01-23T21:31:47.222Z","repository":{"id":3929711,"uuid":"5020045","full_name":"seancorfield/honeysql","owner":"seancorfield","description":"Turn Clojure data structures into SQL","archived":false,"fork":false,"pushed_at":"2025-12-11T14:47:47.000Z","size":1968,"stargazers_count":1870,"open_issues_count":2,"forks_count":173,"subscribers_count":31,"default_branch":"develop","last_synced_at":"2026-01-14T07:38:44.603Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://cljdoc.org/d/com.github.seancorfield/honeysql/CURRENT","language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"scottksmith95/beerlocker","license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/seancorfield.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":null,"code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"seancorfield"}},"created_at":"2012-07-13T13:58:26.000Z","updated_at":"2026-01-11T04:35:51.000Z","dependencies_parsed_at":"2024-01-14T23:52:56.509Z","dependency_job_id":"5fc6a260-5b06-43bd-9340-a4c8fda411a4","html_url":"https://github.com/seancorfield/honeysql","commit_stats":{"total_commits":907,"total_committers":70,"mean_commits":"12.957142857142857","dds":"0.43329658213891953","last_synced_commit":"7fcb9d97d39429b1dc0021c1c4605358de0dc33b"},"previous_names":["jkk/honeysql"],"tags_count":86,"template":false,"template_full_name":null,"purl":"pkg:github/seancorfield/honeysql","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seancorfield%2Fhoneysql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seancorfield%2Fhoneysql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seancorfield%2Fhoneysql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seancorfield%2Fhoneysql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/seancorfield","download_url":"https://codeload.github.com/seancorfield/honeysql/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seancorfield%2Fhoneysql/sbom","scorecard":{"id":522511,"data":{"date":"2025-08-11","repo":{"name":"github.com/seancorfield/honeysql","commit":"79c04f2e4116289c150a2bd07050ff3e072183c8"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":4.1,"checks":[{"name":"Maintained","score":10,"reason":"30 commit(s) and 9 issue activity found in the last 90 days -- score normalized to 10","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Code-Review","score":0,"reason":"Found 1/23 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/test-and-release.yml:1","Warn: no topLevel permission defined: .github/workflows/test-and-snapshot.yml:1","Warn: no topLevel permission defined: .github/workflows/test.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test-and-release.yml:12: update your workflow using https://app.stepsecurity.io/secureworkflow/seancorfield/honeysql/test-and-release.yml/develop?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test-and-release.yml:15: update your workflow using https://app.stepsecurity.io/secureworkflow/seancorfield/honeysql/test-and-release.yml/develop?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/test-and-release.yml:20: update your workflow using https://app.stepsecurity.io/secureworkflow/seancorfield/honeysql/test-and-release.yml/develop?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test-and-release.yml:25: update your workflow using https://app.stepsecurity.io/secureworkflow/seancorfield/honeysql/test-and-release.yml/develop?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test-and-snapshot.yml:12: update your workflow using https://app.stepsecurity.io/secureworkflow/seancorfield/honeysql/test-and-snapshot.yml/develop?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test-and-snapshot.yml:13: update your workflow using https://app.stepsecurity.io/secureworkflow/seancorfield/honeysql/test-and-snapshot.yml/develop?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/test-and-snapshot.yml:18: update your workflow using https://app.stepsecurity.io/secureworkflow/seancorfield/honeysql/test-and-snapshot.yml/develop?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test-and-snapshot.yml:23: update your workflow using https://app.stepsecurity.io/secureworkflow/seancorfield/honeysql/test-and-snapshot.yml/develop?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test-and-snapshot.yml:44: update your workflow using https://app.stepsecurity.io/secureworkflow/seancorfield/honeysql/test-and-snapshot.yml/develop?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test-and-snapshot.yml:45: update your workflow using https://app.stepsecurity.io/secureworkflow/seancorfield/honeysql/test-and-snapshot.yml/develop?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/test-and-snapshot.yml:50: update your workflow using https://app.stepsecurity.io/secureworkflow/seancorfield/honeysql/test-and-snapshot.yml/develop?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test-and-snapshot.yml:55: update your workflow using https://app.stepsecurity.io/secureworkflow/seancorfield/honeysql/test-and-snapshot.yml/develop?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yml:12: update your workflow using https://app.stepsecurity.io/secureworkflow/seancorfield/honeysql/test.yml/develop?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yml:13: update your workflow using https://app.stepsecurity.io/secureworkflow/seancorfield/honeysql/test.yml/develop?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/test.yml:18: update your workflow using https://app.stepsecurity.io/secureworkflow/seancorfield/honeysql/test.yml/develop?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yml:23: update your workflow using https://app.stepsecurity.io/secureworkflow/seancorfield/honeysql/test.yml/develop?enable=pin","Warn: downloadThenRun not pinned by hash: .github/workflows/test-and-snapshot.yml:68","Warn: downloadThenRun not pinned by hash: .github/workflows/test.yml:36","Info:   0 out of  12 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   4 third-party GitHubAction dependencies pinned","Info:   0 out of   2 downloadThenRun dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":0,"reason":"license file not detected","details":["Warn: project does not have a license file"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'develop'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 9 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-20T03:25:13.330Z","repository_id":3929711,"created_at":"2025-08-20T03:25:13.330Z","updated_at":"2025-08-20T03:25:13.330Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28700526,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-23T17:25:48.045Z","status":"ssl_error","status_checked_at":"2026-01-23T17:25:47.153Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T16:00:59.630Z","updated_at":"2026-01-23T21:31:47.216Z","avatar_url":"https://github.com/seancorfield.png","language":"Clojure","funding_links":["https://github.com/sponsors/seancorfield"],"categories":["Clojure","\u003ca name=\"Clojure\"\u003e\u003c/a\u003eClojure"],"sub_categories":[],"readme":"# Honey SQL [![Clojure CI Release](https://github.com/seancorfield/honeysql/actions/workflows/test-and-release.yml/badge.svg)](https://github.com/seancorfield/honeysql/actions/workflows/test-and-release.yml) [![Clojure CI Develop](https://github.com/seancorfield/honeysql/actions/workflows/test-and-snapshot.yml/badge.svg)](https://github.com/seancorfield/honeysql/actions/workflows/test-and-snapshot.yml) [![Clojure CI Pull Request](https://github.com/seancorfield/honeysql/actions/workflows/test.yml/badge.svg)](https://github.com/seancorfield/honeysql/actions/workflows/test.yml)\n\nSQL as Clojure data structures. Build queries programmatically -- even at runtime -- without having to bash strings together.\n\n## Build\n\n[![Clojars](https://img.shields.io/badge/clojars-com.github.seancorfield/honeysql_2.7.1368-blue.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/com.github.seancorfield/honeysql)\n[![cljdoc](https://cljdoc.org/badge/com.github.seancorfield/honeysql?2.7.1368)](https://cljdoc.org/d/com.github.seancorfield/honeysql/CURRENT)\n[![Slack](https://img.shields.io/badge/slack-HoneySQL-orange.svg?logo=slack)](https://clojurians.slack.com/app_redirect?channel=honeysql)\n[![Join Slack](https://img.shields.io/badge/slack-join_clojurians-orange.svg?logo=slack)](http://clojurians.net)\n[![Zulip](https://img.shields.io/badge/zulip-honeysql-orange.svg?logo=zulip)](https://clojurians.zulipchat.com/#narrow/channel/152091-honeysql)\n\nThis 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.\n\n\u003e Note: every commit to the **develop** branch runs CI (GitHub Actions) and successful runs push a MAJOR.MINOR.9999-SNAPSHOT build to Clojars so the very latest version of HoneySQL is always available either via that [snapshot on Clojars](https://clojars.org/com.github.seancorfield/honeysql) or via a git dependency on the latest SHA.\n\nHoneySQL 2.7.y requires Clojure 1.10.3 or later.\nEarlier versions of HoneySQL support Clojure 1.9.0.\nIt also supports recent versions of ClojureScript and Babashka.\n\nCompared 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).\n\n\u003e 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!\n\n## Try HoneySQL Online!\n\n[John Shaffer](https://github.com/john-shaffer) has created this awesome\n[HoneySQL web app](https://john.shaffe.rs/honeysql/), written in ClojureScript,\nso you can experiment with HoneySQL in a browser, including setting different\noptions so you can generate pretty SQL with inline values (via `:inline true`)\nfor copying and pasting directly into your SQL tool of choice!\n\n## Note on code samples\n\nSample code in this documentation is verified via\n[lread/test-doc-blocks](https://github.com/lread/test-doc-blocks).\n\nSome of these samples show pretty-printed SQL: HoneySQL 2.x supports `:pretty true` which inserts newlines between clauses in the generated SQL strings.\n\n## Usage\n\nThis section includes a number of usage examples but does not dive deep into the\nway the data structure acts as a DSL that can specify SQL statements (as hash maps)\nand SQL expressions and function calls (as vectors). It is recommended that you read the\n[**Getting Started**](https://cljdoc.org/d/com.github.seancorfield/honeysql/CURRENT/doc/getting-started)\nsection of the documentation before trying to use HoneySQL to build your own queries!\n\nFrom Clojure:\n\u003c!-- {:test-doc-blocks/reader-cond :clj} --\u003e\n```clojure\n(refer-clojure :exclude '[assert distinct filter for group-by into partition-by set update])\n(require '[honey.sql :as sql]\n         ;; CAUTION: this overwrites several clojure.core fns:\n         ;;\n         ;; distinct, filter, for, group-by, into, partition-by, set, and update\n         ;;\n         ;; you should generally only refer in the specific\n         ;; helpers that you want to use!\n         '[honey.sql.helpers :refer :all :as h]\n         ;; so we can still get at clojure.core functions:\n         '[clojure.core :as c])\n```\n\nFrom ClojureScript, we don't have `:refer :all`. If we want to use `:refer`, we have no choice but to be specific:\n\u003c!-- {:test-doc-blocks/reader-cond :cljs} --\u003e\n```Clojure\n(refer-clojure :exclude '[filter for group-by into partition-by set update])\n(require '[honey.sql :as sql]\n         '[honey.sql.helpers :refer [select select-distinct from\n                                     join left-join right-join\n                                     where for group-by having union\n                                     order-by limit offset values columns\n                                     update insert-into set composite\n                                     delete delete-from truncate] :as h]\n         '[clojure.core :as c])\n```\n\nEverything is built on top of maps representing SQL queries:\n\n```clojure\n(def sqlmap {:select [:a :b :c]\n             :from   [:foo]\n             :where  [:= :foo.a \"baz\"]})\n```\n\nColumn names can be provided as keywords or symbols (but not strings -- HoneySQL treats strings as values that should be lifted out of the SQL as parameters).\n\n### `format`\n\n`format` turns maps into `next.jdbc`-compatible (and `clojure.java.jdbc`-compatible), parameterized SQL:\n\n```clojure\n(sql/format sqlmap)\n=\u003e [\"SELECT a, b, c FROM foo WHERE foo.a = ?\" \"baz\"]\n;; sqlmap as symbols instead of keywords:\n(-\u003e '{select (a, b, c) from (foo) where (= foo.a \"baz\")}\n    (sql/format))\n=\u003e [\"SELECT a, b, c FROM foo WHERE foo.a = ?\" \"baz\"]\n```\n\nHoneySQL is a relatively \"pure\" library, it does not manage your JDBC connection\nor run queries for you, it simply generates SQL strings. You can then pass them\nto a JDBC library, such as [`next.jdbc`](https://github.com/seancorfield/next-jdbc):\n\n\u003c!-- :test-doc-blocks/skip --\u003e\n```clojure\n(jdbc/execute! conn (sql/format sqlmap))\n```\n\n\u003e 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.\n\nIf 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`:\n\n```clojure\n(sql/format sqlmap {:inline true})\n=\u003e [\"SELECT a, b, c FROM foo WHERE foo.a = 'baz'\"]\n```\n\nAs seen above, the default parameterization uses positional parameters (`?`) with the order of values in the generated vector matching the order of those placeholders in the SQL. As of 2.4.962, you can specified `:numbered true` as an option to produce numbered parameters (`$1`, `$2`, etc):\n\n```clojure\n(sql/format sqlmap {:numbered true})\n=\u003e [\"SELECT a, b, c FROM foo WHERE foo.a = $1\" \"baz\"]\n```\n\nNamespace-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.\n\n```clojure\n(def q-sqlmap {:select [:foo/a :foo/b :foo/c]\n               :from   [:foo]\n               :where  [:= :foo/a \"baz\"]})\n(sql/format q-sqlmap)\n=\u003e [\"SELECT foo.a, foo.b, foo.c FROM foo WHERE foo.a = ?\" \"baz\"]\n;; this also works with symbols instead of keywords:\n(-\u003e '{select (foo/a, foo/b, foo/c)\n      from   (foo)\n      where  (= foo/a \"baz\")}\n    (sql/format))\n=\u003e [\"SELECT foo.a, foo.b, foo.c FROM foo WHERE foo.a = ?\" \"baz\"]\n```\n\nAs of 2.6.1126, there is a helper macro you can use with quoted symbolic\nqueries (that are purely literal, not programmatically constructed) to\nprovide \"escape hatches\" for certain symbols that you want to be treated\nas locally bound symbols (and, hence, their values):\n\n\u003c!-- :test-doc-blocks/skip --\u003e\n```clojure\n;; quoted symbolic query with local substitution:\n(let [search-value \"baz\"]\n  (sql/formatv [search-value]\n   '{select (foo/a, foo/b, foo/c)\n     from   (foo)\n     where  (= foo/a search-value)}))\n=\u003e [\"SELECT foo.a, foo.b, foo.c FROM foo WHERE foo.a = ?\" \"baz\"]\n```\n\n\u003e Note: this is a Clojure-only feature and is not available in ClojureScript, and it is intended for literal, inline symbolic queries only, not for programmatically constructed queries (where you would be able to substitute the values directly, as you build the query).\n\nDocumentation for the entire data DSL can be found in the\n[Clause Reference](doc/clause-reference.md), the\n[Operator Reference](doc/operator-reference.md), and the\n[Special Syntax reference](doc/special-syntax.md).\n\n### Vanilla SQL clause helpers\n\nFor every single SQL clause supported by HoneySQL (as keywords or symbols\nin the data structure that is the DSL), there is also a corresponding\nfunction in the `honey.sql.helpers` namespace:\n\n```clojure\n(-\u003e (select :a :b :c)\n    (from :foo)\n    (where [:= :foo.a \"baz\"]))\n=\u003e {:select [:a :b :c] :from [:foo] :where [:= :foo.a \"baz\"]}\n```\n\nIn general, `(helper :foo expr)` will produce `{:helper [:foo expr]}`\n(with a few exceptions -- see the docstring of the helper function\nfor details).\n\nOrder doesn't matter (for independent clauses):\n\n```clojure\n(= (-\u003e (select :*) (from :foo))\n   (-\u003e (from :foo) (select :*)))\n=\u003e true\n```\n\nWhen using the vanilla helper functions, repeated clauses will be merged into existing clauses, in the natural evaluation order (where that makes sense):\n\n```clojure\n(-\u003e sqlmap (select :d))\n=\u003e {:from [:foo], :where [:= :foo.a \"baz\"], :select [:a :b :c :d]}\n```\n\nIf you want to replace a clause, you can `dissoc` the existing clause first, since this is all data:\n\n```clojure\n(-\u003e sqlmap\n    (dissoc :select)\n    (select :*)\n    (where [:\u003e :b 10])\n    sql/format)\n=\u003e [\"SELECT * FROM foo WHERE (foo.a = ?) AND (b \u003e ?)\" \"baz\" 10]\n```\n\n\u003e 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.\n\n`where` will combine multiple clauses together using SQL's `AND`:\n\n```clojure\n(-\u003e (select :*)\n    (from :foo)\n    (where [:= :a 1] [:\u003c :b 100])\n    sql/format)\n=\u003e [\"SELECT * FROM foo WHERE (a = ?) AND (b \u003c ?)\" 1 100]\n```\n\nThe power of this approach comes from the abiliity to programmatically and\nconditionally build up queries:\n\n\u003c!-- :test-doc-blocks/skip --\u003e\n```clojure\n(defn fetch-user [\u0026 {:keys [id name]}]\n  (-\u003e (select :*)\n      (from :users)\n      (cond-\u003e\n        id    (where [:= :id id])\n        name  (where [:= :name name]))\n      sql/format))\n```\n\nYou can call `fetch-user` with either `:id` or `:name` _or both_ and get back\na query with the appropriate `WHERE` clause, since the helpers will merge the\nconditions into the query DSL.\n\nColumn and table names may be aliased by using a vector pair of the original\nname and the desired alias:\n\n```clojure\n(-\u003e (select :a [:b :bar] :c [:d :x])\n    (from [:foo :quux])\n    (where [:= :quux.a 1] [:\u003c :bar 100])\n    sql/format)\n=\u003e [\"SELECT a, b AS bar, c, d AS x FROM foo AS quux WHERE (quux.a = ?) AND (bar \u003c ?)\" 1 100]\n```\n\nor conditionally:\n\n\u003c!-- :test-doc-blocks/skip --\u003e\n```clojure\n(-\u003e (select :a [:b :bar])\n    (cond-\u003e\n      need-c (select :c)\n      x-val  (select [:d :x]))\n    (from [:foo :quux])\n    (where [:= :quux.a 1] [:\u003c :bar 100])\n    (cond-\u003e\n      x-val  (where [:\u003e :x x-val]))\n    sql/format)\n```\n\nIn particular, note that `(select [:a :b])` means `SELECT a AS b` rather than\n`SELECT a, b` -- helpers like `select` are generally variadic and do not take\na collection of column names.\n\nThe examples in this README use a mixture of data structures and the helper\nfunctions interchangably. For any example using the helpers, you could evaluate\nit (without the call to `sql/format`) to see what the equivalent data structure\nwould be.\n\nDocumentation for all the helpers can be found in the\n[`honey.sql.helpers` API reference](https://cljdoc.org/d/com.github.seancorfield/honeysql/CURRENT/api/honey.sql.helpers).\n\n### Inserts\n\nInserts are supported in two patterns.\nIn the first pattern, you must explicitly specify the columns to insert,\nthen provide a collection of rows, each a collection of column values:\n\n```clojure\n(-\u003e (insert-into :properties)\n    (columns :name :surname :age)\n    (values\n     [[\"Jon\" \"Smith\" 34]\n      [\"Andrew\" \"Cooper\" 12]\n      [\"Jane\" \"Daniels\" 56]])\n    (sql/format {:pretty true}))\n=\u003e [\"\nINSERT INTO properties (name, surname, age)\nVALUES (?, ?, ?), (?, ?, ?), (?, ?, ?)\n\"\n\"Jon\" \"Smith\" 34 \"Andrew\" \"Cooper\" 12 \"Jane\" \"Daniels\" 56]\n;; or as pure data DSL:\n(-\u003e {:insert-into [:properties]\n     :columns [:name :surname :age]\n     :values [[\"Jon\" \"Smith\" 34]\n              [\"Andrew\" \"Cooper\" 12]\n              [\"Jane\" \"Daniels\" 56]]}\n    (sql/format {:pretty true}))\n=\u003e [\"\nINSERT INTO properties (name, surname, age)\nVALUES (?, ?, ?), (?, ?, ?), (?, ?, ?)\n\"\n\"Jon\" \"Smith\" 34 \"Andrew\" \"Cooper\" 12 \"Jane\" \"Daniels\" 56]\n```\n\nIf the rows are of unequal lengths, they will be padded with `NULL` values to make them consistent.\n\nAlternately, you can simply specify the values as maps:\n\n```clojure\n(-\u003e (insert-into :properties)\n    (values [{:name \"John\" :surname \"Smith\" :age 34}\n             {:name \"Andrew\" :surname \"Cooper\" :age 12}\n             {:name \"Jane\" :surname \"Daniels\" :age 56}])\n    (sql/format {:pretty true}))\n=\u003e [\"\nINSERT INTO properties (name, surname, age)\nVALUES (?, ?, ?), (?, ?, ?), (?, ?, ?)\n\"\n\"John\" \"Smith\" 34\n\"Andrew\" \"Cooper\"  12\n\"Jane\" \"Daniels\" 56]\n;; or as pure data DSL:\n(-\u003e {:insert-into [:properties]\n     :values [{:name \"John\", :surname \"Smith\", :age 34}\n              {:name \"Andrew\", :surname \"Cooper\", :age 12}\n              {:name \"Jane\", :surname \"Daniels\", :age 56}]}\n    (sql/format {:pretty true}))\n=\u003e [\"\nINSERT INTO properties (name, surname, age)\nVALUES (?, ?, ?), (?, ?, ?), (?, ?, ?)\n\"\n\"John\" \"Smith\" 34\n\"Andrew\" \"Cooper\"  12\n\"Jane\" \"Daniels\" 56]\n```\n\nThe set of columns used in the insert will be the union of all column names from all\nthe hash maps: columns that are missing from any rows will have `NULL` as their value\nunless you specify those columns in the `:values-default-columns` option, which takes\na set of column names that should get the value `DEFAULT` instead of `NULL`:\n\n\n```clojure\n(-\u003e (insert-into :properties)\n    (values [{:name \"John\" :surname \"Smith\" :age 34}\n             {:name \"Andrew\" :age 12}\n             {:name \"Jane\" :surname \"Daniels\"}])\n    (sql/format {:pretty true}))\n=\u003e [\"\nINSERT INTO properties (name, surname, age)\nVALUES (?, ?, ?), (?, NULL, ?), (?, ?, NULL)\n\"\n\"John\" \"Smith\" 34\n\"Andrew\" 12\n\"Jane\" \"Daniels\"]\n(-\u003e (insert-into :properties)\n    (values [{:name \"John\" :surname \"Smith\" :age 34}\n             {:name \"Andrew\" :age 12}\n             {:name \"Jane\" :surname \"Daniels\"}])\n    (sql/format {:pretty true :values-default-columns #{:age}}))\n=\u003e [\"\nINSERT INTO properties (name, surname, age)\nVALUES (?, ?, ?), (?, NULL, ?), (?, ?, DEFAULT)\n\"\n\"John\" \"Smith\" 34\n\"Andrew\" 12\n\"Jane\" \"Daniels\"]\n```\n\n### Nested subqueries\n\nThe column values do not have to be literals, they can be nested queries:\n\n```clojure\n(let [user-id 12345\n      role-name \"user\"]\n  (-\u003e (insert-into :user_profile_to_role)\n      (values [{:user_profile_id user-id\n                :role_id         (-\u003e (select :id)\n                                     (from :role)\n                                     (where [:= :name role-name]))}])\n      (sql/format {:pretty true})))\n\n=\u003e [\"\nINSERT INTO user_profile_to_role (user_profile_id, role_id)\nVALUES (?, (SELECT id FROM role WHERE name = ?))\n\"\n12345\n\"user\"]\n;; or as pure data DSL:\n(let [user-id 12345\n      role-name \"user\"]\n  (-\u003e {:insert-into [:user_profile_to_role]\n       :values [{:user_profile_id 12345,\n                 :role_id {:select [:id],\n                           :from [:role],\n                           :where [:= :name \"user\"]}}]}\n      (sql/format {:pretty true})))\n=\u003e [\"\nINSERT INTO user_profile_to_role (user_profile_id, role_id)\nVALUES (?, (SELECT id FROM role WHERE name = ?))\n\"\n12345\n\"user\"]\n```\n\n```clojure\n(-\u003e (select :*)\n    (from :foo)\n    (where [:in :foo.a (-\u003e (select :a) (from :bar))])\n    (sql/format))\n=\u003e [\"SELECT * FROM foo WHERE foo.a IN (SELECT a FROM bar)\"]\n;; or as pure data DSL:\n(-\u003e {:select [:*],\n     :from [:foo],\n     :where [:in :foo.a {:select [:a], :from [:bar]}]}\n    (sql/format))\n=\u003e [\"SELECT * FROM foo WHERE foo.a IN (SELECT a FROM bar)\"]\n```\n\nBecause values can be nested queries -- and also because values can be function calls --\nwhenever you are working with values that are, themselves, structured data, you will\nneed to tell HoneySQL not to interpret that structured data as part of the DSL. This\nespecially affects using JSON values with HoneySQL (e.g., targeting PostgreSQL). There\nare two possible approaches:\n\n1. Use named parameters instead of having the values directly in the DSL structure (see `:param` under **Miscellaneous** below), or\n2. Use `[:lift ..]` wrapped around any structured values which tells HoneySQL not to interpret the vector or hash map value as a DSL.\n\n### Composite types\n\nComposite types are supported:\n\n```clojure\n(-\u003e (insert-into :comp_table)\n    (columns :name :comp_column)\n    (values\n     [[\"small\" (composite 1 \"inch\")]\n      [\"large\" (composite 10 \"feet\")]])\n    (sql/format {:pretty true}))\n=\u003e [\"\nINSERT INTO comp_table (name, comp_column)\nVALUES (?, (?, ?)), (?, (?, ?))\n\"\n\"small\" 1 \"inch\" \"large\" 10 \"feet\"]\n;; with numbered parameters:\n(-\u003e (insert-into :comp_table)\n    (columns :name :comp_column)\n    (values\n     [[\"small\" (composite 1 \"inch\")]\n      [\"large\" (composite 10 \"feet\")]])\n    (sql/format {:pretty true :numbered true}))\n=\u003e [\"\nINSERT INTO comp_table (name, comp_column)\nVALUES ($1, ($2, $3)), ($4, ($5, $6))\n\"\n\"small\" 1 \"inch\" \"large\" 10 \"feet\"]\n;; or as pure data DSL:\n(-\u003e {:insert-into [:comp_table],\n     :columns [:name :comp_column],\n     :values [[\"small\" [:composite 1 \"inch\"]]\n              [\"large\" [:composite 10 \"feet\"]]]}\n    (sql/format {:pretty true}))\n=\u003e [\"\nINSERT INTO comp_table (name, comp_column)\nVALUES (?, (?, ?)), (?, (?, ?))\n\"\n\"small\" 1 \"inch\" \"large\" 10 \"feet\"]\n```\n\n### Updates\n\nUpdates are possible too:\n\n```clojure\n(-\u003e (update :films)\n    (set {:kind \"dramatic\"\n           :watched [:+ :watched 1]})\n    (where [:= :kind \"drama\"])\n    (sql/format {:pretty true}))\n=\u003e [\"\nUPDATE films\nSET kind = ?, watched = watched + ?\nWHERE kind = ?\n\"\n\"dramatic\"\n1\n\"drama\"]\n;; or as pure data DSL:\n(-\u003e {:update :films,\n     :set {:kind \"dramatic\", :watched [:+ :watched 1]},\n     :where [:= :kind \"drama\"]}\n    (sql/format {:pretty true}))\n=\u003e [\"\nUPDATE films\nSET kind = ?, watched = watched + ?\nWHERE kind = ?\n\"\n\"dramatic\"\n1\n\"drama\"]\n```\n\nIf you are trying to build a compound update statement (with `from` or `join`),\nbe aware that different databases have slightly different syntax in terms of\nwhere `SET` should appear. The default above is to put `SET` before `FROM` which\nis how PostgreSQL (and other ANSI-SQL dialects work). If you are using MySQL,\nyou will need to select the `:mysql` dialect in order to put the `SET` after\nany `JOIN` clause.\n\n### Deletes\n\nDeletes look as you would expect:\n\n```clojure\n(-\u003e (delete-from :films)\n    (where [:\u003c\u003e :kind \"musical\"])\n    (sql/format))\n=\u003e [\"DELETE FROM films WHERE kind \u003c\u003e ?\" \"musical\"]\n;; or as pure data DSL:\n(-\u003e {:delete-from [:films],\n     :where [:\u003c\u003e :kind \"musical\"]}\n    (sql/format))\n=\u003e [\"DELETE FROM films WHERE kind \u003c\u003e ?\" \"musical\"]\n```\n\nIf your database supports it, you can also delete from multiple tables:\n\n```clojure\n(-\u003e (delete [:films :directors])\n    (from :films)\n    (join :directors [:= :films.director_id :directors.id])\n    (where [:\u003c\u003e :kind \"musical\"])\n    (sql/format {:pretty true}))\n=\u003e [\"\nDELETE films, directors\nFROM films\nINNER JOIN directors ON films.director_id = directors.id\nWHERE kind \u003c\u003e ?\n\"\n\"musical\"]\n;; or pure data DSL:\n(-\u003e {:delete [:films :directors],\n     :from [:films],\n     :join [:directors [:= :films.director_id :directors.id]],\n     :where [:\u003c\u003e :kind \"musical\"]}\n    (sql/format {:pretty true}))\n=\u003e [\"\nDELETE films, directors\nFROM films\nINNER JOIN directors ON films.director_id = directors.id\nWHERE kind \u003c\u003e ?\n\"\n\"musical\"]\n```\n\nIf you want to delete everything from a table, you can use `truncate`:\n\n```clojure\n(-\u003e (truncate :films)\n    (sql/format))\n=\u003e [\"TRUNCATE TABLE films\"]\n;; or as pure data DSL:\n(-\u003e {:truncate :films}\n    (sql/format))\n=\u003e [\"TRUNCATE TABLE films\"]\n```\n\n### Set operations\n\nQueries may be combined with a `:union`, `:union-all`, `:intersect` or `:except` keyword:\n\n```clojure\n(sql/format {:union [(-\u003e (select :*) (from :foo))\n                     (-\u003e (select :*) (from :bar))]})\n=\u003e [\"SELECT * FROM foo UNION SELECT * FROM bar\"]\n```\n\nThere are also helpers for each of those:\n\n```clojure\n(sql/format (union (-\u003e (select :*) (from :foo))\n                   (-\u003e (select :*) (from :bar))))\n=\u003e [\"SELECT * FROM foo UNION SELECT * FROM bar\"]\n```\n\n\u003e Note: different databases have different precedence rules for these set operations when used in combination -- you may need to use `:nest` to add `(` .. `)` in order to combine these operations in a single SQL statement, if the natural order produced by HoneySQL does not work \"as expected\" for your database.\n\n### Functions\n\nFunction calls (and expressions with operators) can be specified as\nvectors where the first element is either a keyword or a symbol:\n\n```clojure\n(-\u003e (select :*) (from :foo)\n    (where [:\u003e :date_created [:date_add [:now] [:interval 24 :hours]]])\n    (sql/format))\n=\u003e [\"SELECT * FROM foo WHERE date_created \u003e DATE_ADD(NOW(), INTERVAL ? HOURS)\" 24]\n```\n\n\u003e Note: The above example may be specific to MySQL but the general principle of vectors for function calls applies to all dialects.\n\nA shorthand syntax also exists for simple function calls:\nkeywords that begin with `%` are interpreted as SQL function calls:\n\n```clojure\n(-\u003e (select :%count.*) (from :foo) sql/format)\n=\u003e [\"SELECT COUNT(*) FROM foo\"]\n```\n```clojure\n;; with an alias:\n(-\u003e (select [:%count.* :total]) (from :foo) sql/format)\n=\u003e [\"SELECT COUNT(*) AS total FROM foo\"]\n```\n```clojure\n(-\u003e (select :%max.id) (from :foo) sql/format)\n=\u003e [\"SELECT MAX(id) FROM foo\"]\n```\n\nSince regular function calls are indicated with vectors and so are aliased pairs,\nthis shorthand can be more convenient due to the extra wrapping needed for the\nregular function calls in a select:\n\n```clojure\n(-\u003e (select [[:count :*]]) (from :foo) sql/format)\n=\u003e [\"SELECT COUNT(*) FROM foo\"]\n```\n```clojure\n(-\u003e (select [[:count :*] :total]) (from :foo) sql/format)\n=\u003e [\"SELECT COUNT(*) AS total FROM foo\"]\n```\n```clojure\n(-\u003e (select [:%count.*]) (from :foo) sql/format)\n=\u003e [\"SELECT COUNT(*) FROM foo\"]\n;; or even:\n(-\u003e (select :%count.*) (from :foo) sql/format)\n=\u003e [\"SELECT COUNT(*) FROM foo\"]\n```\n```clojure\n(-\u003e (select [[:max :id]]) (from :foo) sql/format)\n=\u003e [\"SELECT MAX(id) FROM foo\"]\n(-\u003e (select [[:max :id] :highest]) (from :foo) sql/format)\n=\u003e [\"SELECT MAX(id) AS highest FROM foo\"]\n;; the pure data DSL requires an extra level of brackets:\n(-\u003e {:select [[[:max :id]]], :from [:foo]} sql/format)\n=\u003e [\"SELECT MAX(id) FROM foo\"]\n(-\u003e {:select [[[:max :id] :highest]], :from [:foo]} sql/format)\n=\u003e [\"SELECT MAX(id) AS highest FROM foo\"]\n;; the shorthand makes this simpler:\n(-\u003e {:select [[:%max.id]], :from [:foo]} sql/format)\n=\u003e [\"SELECT MAX(id) FROM foo\"]\n(-\u003e {:select [[:%max.id :highest]], :from [:foo]} sql/format)\n=\u003e [\"SELECT MAX(id) AS highest FROM foo\"]\n;; or even (no alias):\n(-\u003e {:select [:%max.id], :from [:foo]} sql/format)\n=\u003e [\"SELECT MAX(id) FROM foo\"]\n;; or even (no alias, no other columns):\n(-\u003e {:select :%max.id, :from :foo} sql/format)\n=\u003e [\"SELECT MAX(id) FROM foo\"]\n```\n\nCustom columns using functions are built with the same vector format.\nBe sure to properly nest the vectors so that the first element in the selection\nis the custom function and the second is the column alias.\n```clojure\n(sql/format\n  {:select   [:job_name                                      ;; A bare field selection\n              [[:avg [:/ [:- :end_time :start_time] 1000.0]] ;; A custom function\n               :avg_exec_time_seconds                        ;; The column alias\n               ]]\n   :from     [:job_data]\n   :group-by :job_name})\n=\u003e [\"SELECT job_name, AVG((end_time - start_time) / ?) AS avg_exec_time_seconds FROM job_data GROUP BY job_name\" 1000.0]\n```\n\nIf a keyword begins with `'`, the function name is formatted as a SQL\nentity rather than being converted to uppercase and having hyphens `-`\nconverted to spaces. That means that hyphens `-` will become underscores `_`\nunless you have quoting enabled:\n\n```clojure\n(-\u003e (select :*) (from :foo)\n    (where [:'my-schema.SomeFunction :bar 0])\n    (sql/format))\n=\u003e [\"SELECT * FROM foo WHERE my_schema.SomeFunction(bar, ?)\" 0]\n(-\u003e (select :*) (from :foo)\n    (where [:'my-schema.SomeFunction :bar 0])\n    (sql/format :quoted true))\n=\u003e [\"SELECT * FROM \\\"foo\\\" WHERE \\\"my-schema\\\".\\\"SomeFunction\\\"(\\\"bar\\\", ?)\" 0]\n(-\u003e (select :*) (from :foo)\n    (where [:'my-schema.SomeFunction :bar 0])\n    (sql/format :dialect :mysql))\n=\u003e [\"SELECT * FROM `foo` WHERE `my-schema`.`SomeFunction`(`bar`, ?)\" 0]\n```\n\n\u003e Note: in non-function contexts, if a keyword begins with `'`, it is transcribed into the SQL exactly as-is, with no case or character conversion at all.\n\n### Bindable parameters\n\nKeywords that begin with `?` are interpreted as bindable parameters:\n\n```clojure\n(-\u003e (select :id)\n    (from :foo)\n    (where [:= :a :?baz])\n    (sql/format {:params {:baz \"BAZ\"}}))\n=\u003e [\"SELECT id FROM foo WHERE a = ?\" \"BAZ\"]\n;; or with numbered parameters:\n(-\u003e (select :id)\n    (from :foo)\n    (where [:= :a :?baz])\n    (sql/format {:params {:baz \"BAZ\"} :numbered true}))\n=\u003e [\"SELECT id FROM foo WHERE a = $1\" \"BAZ\"]\n;; or as pure data DSL:\n(-\u003e {:select [:id], :from [:foo], :where [:= :a :?baz]}\n    (sql/format {:params {:baz \"BAZ\"}}))\n=\u003e [\"SELECT id FROM foo WHERE a = ?\" \"BAZ\"]\n```\n\n### Miscellaneous\n\nSometimes you want to provide SQL fragments directly or have certain values\nplaced into the SQL string rather than turned into a parameter.\n\nThe `:raw` syntax lets you embed SQL fragments directly into a HoneySQL expression.\nIt accepts either a single string to embed or a vector of expressions that will be\nconverted to strings and embedded as a single string.\n\nThe `:inline` syntax attempts to turn a Clojure value into a SQL value and then\nembeds that string, e.g., `[:inline \"foo\"]` produces `'foo'` (a SQL string).\n\nThe `:param` syntax identifies a named parameter whose value will be supplied\nvia the `:params` argument to `format`.\n\nThe `:lift` syntax will prevent interpretation of Clojure data structures as\npart of the DSL and instead turn such values into parameters (useful when you\nwant to pass a vector or a hash map directly as a positional parameter value,\nfor example when you have extended `next.jdbc`'s `SettableParameter` protocol\nto a data structure -- as is common when working with PostgreSQL's JSON/JSONB types).\n\nFinally, the `:nest` syntax will cause an extra set of parentheses to be\nwrapped around its argument, after formatting that argument as a SQL expression.\n\nThese can be combined to allow more fine-grained control over SQL generation:\n\n```clojure\n(def call-qualify-map\n  (-\u003e (select [[:foo :bar]] [[:raw \"@var := foo.bar\"]])\n      (from :foo)\n      (where [:= :a [:param :baz]] [:= :b [:inline 42]])))\n```\n```clojure\ncall-qualify-map\n=\u003e {:where [:and [:= :a [:param :baz]] [:= :b [:inline 42]]]\n    :from (:foo)\n    :select [[[:foo :bar]] [[:raw \"@var := foo.bar\"]]]}\n```\n```clojure\n(sql/format call-qualify-map {:params {:baz \"BAZ\"}})\n=\u003e [\"SELECT FOO(bar), @var := foo.bar FROM foo WHERE (a = ?) AND (b = 42)\" \"BAZ\"]\n```\n\n```clojure\n(-\u003e (select :*)\n    (from :foo)\n    (where [:\u003c :expired_at [:raw [\"now() - '\" 5 \" seconds'\"]]])\n    (sql/format))\n=\u003e [\"SELECT * FROM foo WHERE expired_at \u003c now() - '5 seconds'\"]\n```\n\n```clojure\n(-\u003e (select :*)\n    (from :foo)\n    (where [:\u003c :expired_at [:raw [\"now() - '\" [:lift 5] \" seconds'\"]]])\n    (sql/format))\n=\u003e [\"SELECT * FROM foo WHERE expired_at \u003c now() - '? seconds'\" 5]\n```\n\n```clojure\n(-\u003e (select :*)\n    (from :foo)\n    (where [:\u003c :expired_at [:raw [\"now() - '\" [:param :t] \" seconds'\"]]])\n    (sql/format {:params {:t 5}}))\n=\u003e [\"SELECT * FROM foo WHERE expired_at \u003c now() - '? seconds'\" 5]\n```\n\n```clojure\n(-\u003e (select :*)\n    (from :foo)\n    (where [:\u003c :expired_at [:raw [\"now() - \" [:inline (str 5 \" seconds\")]]]])\n    (sql/format))\n=\u003e [\"SELECT * FROM foo WHERE expired_at \u003c now() - '5 seconds'\"]\n```\n\n#### PostGIS\n\nA common example in the wild is the PostGIS extension to PostgreSQL where you\nhave a lot of function calls needed in code:\n\n```clojure\n(-\u003e (insert-into :sample)\n    (values [{:location [:ST_SetSRID\n                         [:ST_MakePoint 0.291 32.621]\n                         [:cast 4325 :integer]]}])\n    (sql/format {:pretty true}))\n=\u003e [\"\nINSERT INTO sample (location)\nVALUES (ST_SETSRID(ST_MAKEPOINT(?, ?), CAST(? AS INTEGER)))\n\"\n0.291 32.621 4325]\n```\n\n#### Entity Names\n\nTo quote SQL entity names, pass the `:quoted true` option to `format` and they will\nbe quoted according to the selected dialect. If you override the dialect in a\n`format` call, by passing the `:dialect` option, SQL entity names will be automatically\nquoted. You can override the dialect and turn off quoting by passing `:quoted false`.\nValid `:dialect` options are `:ansi` (the default, use this for PostgreSQL),\n`:mysql`, `:oracle`, or `:sqlserver`. As of 2.5.1091, `:nrql` is also supported:\n\n```clojure\n(-\u003e (select :foo.a)\n    (from :foo)\n    (where [:= :foo.a \"baz\"])\n    (sql/format {:dialect :mysql}))\n=\u003e [\"SELECT `foo`.`a` FROM `foo` WHERE `foo`.`a` = ?\" \"baz\"]\n```\n```clojure\n(-\u003e (select :foo.a)\n    (from :foo)\n    (where [:= :foo.a \"baz\"])\n    (sql/format {:dialect :nrql}))\n=\u003e [\"SELECT `foo.a` FROM foo WHERE `foo.a` = 'baz'\"]\n```\n\nSee [New Relic NRQL Support](nrsql.md) for more details of the NRQL dialect.\n\n#### Locking\n\nThe ANSI/PostgreSQL/SQLServer dialects support locking selects via a `FOR` clause as follows:\n\n* `:for [\u003clock-strength\u003e \u003ctable(s)\u003e \u003cqualifier\u003e]` where `\u003clock-strength\u003e` is required and may be one of:\n  * `:update`\n  * `:no-key-update`\n  * `:share`\n  * `:key-share`\n* Both `\u003ctable(s)\u003e` and `\u003cqualifier\u003e` are optional but if present, `\u003ctable(s)\u003e` must either be:\n  * a single table name (as a keyword) or\n  * a sequence of table names (as keywords)\n* `\u003cqualifier\u003e` can be `:nowait`, `:wait`, `:skip-locked` etc.\n\nIf `\u003ctable(s)\u003e` and `\u003cqualifier\u003e` are both omitted, you may also omit the `[`..`]` and just say `:for :update` etc.\n\n```clojure\n(-\u003e (select :foo.a)\n    (from :foo)\n    (where [:= :foo.a \"baz\"])\n    (for :update)\n    (sql/format))\n=\u003e [\"SELECT foo.a FROM foo WHERE foo.a = ? FOR UPDATE\" \"baz\"]\n```\n\nIf the `:mysql` dialect is selected, an additional locking clause is available:\n`:lock :in-share-mode`.\n```clojure\n(sql/format {:select [:*] :from :foo\n             :where [:= :name [:inline \"Jones\"]]\n             :lock [:in-share-mode]}\n            {:dialect :mysql :quoted false})\n=\u003e [\"SELECT * FROM foo WHERE name = 'Jones' LOCK IN SHARE MODE\"]\n```\n\nDashes are allowed in quoted names:\n\n```clojure\n(sql/format\n  {:select [:f.foo-id :f.foo-name]\n   :from [[:foo-bar :f]]\n   :where [:= :f.foo-id 12345]}\n  {:quoted true})\n=\u003e [\"SELECT \\\"f\\\".\\\"foo-id\\\", \\\"f\\\".\\\"foo-name\\\" FROM \\\"foo-bar\\\" AS \\\"f\\\" WHERE \\\"f\\\".\\\"foo-id\\\" = ?\" 12345]\n```\n\n### Big, complicated example\n\nHere's a big, complicated query. Note that HoneySQL makes no attempt to verify that your queries make any sense. It merely renders surface syntax.\n\n```clojure\n(def big-complicated-map\n  (-\u003e (select-distinct :f.* :b.baz :c.quux [:b.bla \"bla-bla\"]\n                       [[:now]] [[:raw \"@x := 10\"]])\n      (from [:foo :f] [:baz :b])\n      (join :draq [:= :f.b :draq.x]\n            :eldr [:= :f.e :eldr.t])\n      (left-join [:clod :c] [:= :f.a :c.d])\n      (right-join :bock [:= :bock.z :c.e])\n      (where [:or\n               [:and [:= :f.a \"bort\"] [:not= :b.baz [:param :param1]]]\n               [:and [:\u003c 1 2] [:\u003c 2 3]]\n               [:in :f.e [1 [:param :param2] 3]]\n               [:between :f.e 10 20]])\n      (group-by :f.a :c.e)\n      (having [:\u003c 0 :f.e])\n      (order-by [:b.baz :desc] :c.quux [:f.a :nulls-first])\n      (limit 50)\n      (offset 10)))\n```\n```clojure\nbig-complicated-map\n=\u003e {:select-distinct [:f.* :b.baz :c.quux [:b.bla \"bla-bla\"]\n                     [[:now]] [[:raw \"@x := 10\"]]]\n    :from [[:foo :f] [:baz :b]]\n    :join [:draq [:= :f.b :draq.x]\n           :eldr [:= :f.e :eldr.t]]\n    :left-join [[:clod :c] [:= :f.a :c.d]]\n    :right-join [:bock [:= :bock.z :c.e]]\n    :where [:or\n             [:and [:= :f.a \"bort\"] [:not= :b.baz [:param :param1]]]\n             [:and [:\u003c 1 2] [:\u003c 2 3]]\n             [:in :f.e [1 [:param :param2] 3]]\n             [:between :f.e 10 20]]\n    :group-by [:f.a :c.e]\n    :having [:\u003c 0 :f.e]\n    :order-by [[:b.baz :desc] :c.quux [:f.a :nulls-first]]\n    :limit 50\n    :offset 10}\n```\n```clojure\n(sql/format big-complicated-map\n            {:params {:param1 \"gabba\" :param2 2}\n             :pretty true})\n=\u003e [\"\nSELECT DISTINCT f.*, b.baz, c.quux, b.bla AS \\\"bla-bla\\\", NOW(), @x := 10\nFROM foo AS f, baz AS b\nINNER JOIN draq ON f.b = draq.x INNER JOIN eldr ON f.e = eldr.t\nLEFT JOIN clod AS c ON f.a = c.d\nRIGHT JOIN bock ON bock.z = c.e\nWHERE ((f.a = ?) AND (b.baz \u003c\u003e ?)) OR ((? \u003c ?) AND (? \u003c ?)) OR (f.e IN (?, ?, ?)) OR f.e BETWEEN ? AND ?\nGROUP BY f.a, c.e\nHAVING ? \u003c f.e\nORDER BY b.baz DESC, c.quux ASC, f.a NULLS FIRST\nLIMIT ?\nOFFSET ?\n\"\n\"bort\" \"gabba\" 1 2 2 3 1 2 3 10 20 0 50 10]\n;; with numbered parameters:\n(sql/format big-complicated-map\n            {:params {:param1 \"gabba\" :param2 2}\n             :pretty true :numbered true})\n=\u003e [\"\nSELECT DISTINCT f.*, b.baz, c.quux, b.bla AS \\\"bla-bla\\\", NOW(), @x := 10\nFROM foo AS f, baz AS b\nINNER JOIN draq ON f.b = draq.x INNER JOIN eldr ON f.e = eldr.t\nLEFT JOIN clod AS c ON f.a = c.d\nRIGHT JOIN bock ON bock.z = c.e\nWHERE ((f.a = $1) AND (b.baz \u003c\u003e $2)) OR (($3 \u003c $4) AND ($5 \u003c $6)) OR (f.e IN ($7, $8, $9)) OR f.e BETWEEN $10 AND $11\nGROUP BY f.a, c.e\nHAVING $12 \u003c f.e\nORDER BY b.baz DESC, c.quux ASC, f.a NULLS FIRST\nLIMIT $13\nOFFSET $14\n\"\n\"bort\" \"gabba\" 1 2 2 3 1 2 3 10 20 0 50 10]\n```\n```clojure\n;; Printable and readable\n(require '[clojure.edn :as edn])\n\n(= big-complicated-map (edn/read-string (pr-str big-complicated-map)))\n=\u003e true\n```\n\n## Extensibility\n\nAny keyword (or symbol) that appears as the first element of a vector will be treated as a generic function unless it is declared to be an operator or \"special syntax\". Any keyword (or symbol) that appears as a key in a hash map will be treated as a SQL clause -- and must either be built-in or must be registered as a new clause.\n\nIf your database supports `\u003c=\u003e` as an operator, you can tell HoneySQL about it using the `register-op!` function (which should be called before the first call to `honey.sql/format`):\n\n```clojure\n(sql/register-op! :\u003c=\u003e)\n;; all operators are assumed to be variadic:\n(-\u003e (select :a) (where [:\u003c=\u003e :a \"foo\"]) sql/format)\n=\u003e [\"SELECT a WHERE a \u003c=\u003e ?\" \"foo\"]\n(-\u003e (select :a) (where [:\u003c=\u003e \"food\" :a \"fool\"]) sql/format)\n=\u003e [\"SELECT a WHERE ? \u003c=\u003e a \u003c=\u003e ?\" \"food\" \"fool\"]\n```\n\nSometimes you want an operator to ignore `nil` clauses (`:and` and `:or` are declared that way):\n\n```clojure\n(sql/register-op! :\u003c=\u003e :ignore-nil true)\n```\n\nOr perhaps your database supports syntax like `a BETWIXT b AND c`, in which case you can use `register-fn!` to tell HoneySQL about it (again, called before the first call to `honey.sql/format`):\n\n```clojure\n;; the formatter will be passed your new operator (function) and a\n;; sequence of the arguments provided to it (so you can write any arity ops):\n(sql/register-fn! :betwixt\n                  (fn [op [a b c]]\n                    (let [[sql-a \u0026 params-a] (sql/format-expr a)\n                          [sql-b \u0026 params-b] (sql/format-expr b)\n                          [sql-c \u0026 params-c] (sql/format-expr c)]\n                      (-\u003e [(str sql-a \" \" (sql/sql-kw op) \" \"\n                                sql-b \" AND \" sql-c)]\n                          (c/into params-a)\n                          (c/into params-b)\n                          (c/into params-c)))))\n;; example usage:\n(-\u003e (select :a) (where [:betwixt :a 1 10]) sql/format)\n=\u003e [\"SELECT a WHERE a BETWIXT ? AND ?\" 1 10]\n;; with numbered parameters:\n(-\u003e (select :a) (where [:betwixt :a 1 10]) (sql/format {:numbered true}))\n=\u003e [\"SELECT a WHERE a BETWIXT $1 AND $2\" 1 10]\n```\n\n\u003e Note: the generation of positional placeholders (`?`) or numbered placeholders (`$1`, `$2`, etc) is handled automatically by `format-expr` so you get this behavior \"for free\" in your extensions, as long as you use the public API for `honey.sql`. You should avoid writing extensions that generate placeholders directly if you want them to work with numbered parameters.\n\nYou can also register SQL clauses, specifying the keyword, the formatting function, and an existing clause that this new clause should be processed before:\n\n```clojure\n;; the formatter will be passed your new clause and the value associated\n;; with that clause in the DSL (which is often a sequence but does not\n;; need to be -- it can be whatever syntax you desire in the DSL):\n(sql/register-clause! :foobar\n                      (fn [clause x]\n                        (let [[sql \u0026 params]\n                              (if (ident? x)\n                                (sql/format-expr x)\n                                (sql/format-dsl x))]\n                          (c/into [(str (sql/sql-kw clause) \" \" sql)] params)))\n                      :from) ; SELECT ... FOOBAR ... FROM ...\n;; example usage:\n(sql/format {:select [:a :b] :foobar :baz})\n=\u003e [\"SELECT a, b FOOBAR baz\"]\n(sql/format {:select [:a :b] :foobar {:where [:= :id 1]}})\n=\u003e [\"SELECT a, b FOOBAR WHERE id = ?\" 1]\n```\n\nIf 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.\n\n\u003ca name=\"1.x\"/\u003e\n## HoneySQL 1.x (legacy)\n\n[![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)\n\nHoneySQL 1.x will continue to get critical security fixes but otherwise should be considered \"legacy\" at this point.\n\n## License\n\nCopyright (c) 2020-2024 Sean Corfield. HoneySQL 1.x was copyright (c) 2012-2020 Justin Kramer and Sean Corfield.\n\nDistributed under the Eclipse Public License, the same as Clojure.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseancorfield%2Fhoneysql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fseancorfield%2Fhoneysql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseancorfield%2Fhoneysql/lists"}