Overview

Query for data in the Clojure world

Being an ecosystem that emphasizes simplicity, the Clojure world has most of its SQL libraries follow a pattern of querying for data:

(execute-query database-instance the-query)

for instance, this is how to do it with plain clojure.java.jdbc:

(clojure.java.jdbc/query {:connection-uri "postgresql://..."}
  ["select * from fruit where appearance = ?" "rosy"])

A strange SQL library

Walkable is no ordinary SQL library but one for building APIs. Each element of the said pattern has evolved into rather a comprehensive counterpart:

  • execute-query is still a function, but no longer a generic one, but one that is specific to your project. You generate such functions by providing the neccessary information. The most important piece of this information is called the registry.

  • query now uses EQL format so it can describe complex, nested structures. It is expected to be sent from untrusted environments (ie remote client over the internet)

  • database-instance alone is not sufficient to derive the result, for instance you may need to provide current user’s id (for authentication/authorization purpose). Therefore, database-instance is replaced with a hash-map of relevant data called the env.

To sum up:

(let [execute-query (make-execute-function ...) (1)
      env {:db database-instance (2)
           :user-id some-id
           :other-stuff ...}]
  (execute-query env eql-query))
;; => result
1 how to build the execute-query function will be covered in installation page.
2 the key in env can be anything, you can even have different keys for different databases, eg {:redis some-instance :sqlite other-instance :postgres another :datomic ...}.