README.md

Hildebrand

Hildebrand is a high-level client for Amazon's Dynamo DB, built on top of Eulalie.

• core.async-based API
• Targets both Clojure and Clojurescript/Node
• Survives the Google Closure compiler's :advanced optimizations, for e.g. Clojurescript AWS Lambda functions
• Exposes advanced Dynamo features, including the Dynamo Streams service
• Plain EDN representations of Dynamo tables, items, queries, and their components: conditional writes, atomic updates, filters, and so on.

Documentation

• The API introduction on the wiki is a good place to start.
• Introducing Hildebrand, a blog post, has a bunch of usage examples in it. The namespace layout has changed since (hildebrand -> hildebrand.core)

Examples

Querying

(require '[hildebrand.channeled :refer [query!]])

(async/into []
  (query! creds :games
          {:user-id [:= "moea"]}
          {:filter [:< [:score] 50]
           :sort :desc
           :limit 10}
          {:chan (async/chan 10 (map :score))}))
;; => [15 10]

Querying + Batched Deletes

(require '[hildebrand.channeled :refer [query! batching-deletes]])

(let [[results errors]
      (->> (query! creds :games
                   {:user-id [:= "moea"]
                    :game-title [:begins-with "Super"]}
                   {:filter [:< [:score] 100]
                    :limit  100})
           (async/split map?))
      {delete-chan :in-chan} (batching-deletes creds {:table :games})]
  (async/pipe results delete-chan))

Clojurescript

All of the functionality (barring the synchronous convenience functions) is exposed via Clojurescript. The implementation specifically targets Node, and uses lein-npm for declaring its dependency on bignumber.js. The wiki contains more information about number handling, which is the only substantial difference from the Clojure implementation.

The specific use-case I had in mind for Node support is writing AWS Lambda functions in Clojurescript.

See the Eulalie README for other Node-relevant details.

Development

Most of the integration tests expect an instance of DynamoDB Local. If the LOCAL_DYNAMO_URL environment variable isn't set, those tests will be skipped.

A couple of the tests expect to get capacity information back from Dynamo, and so can't run against a local instance. If AWS_ACCESS_KEY and AWS_SECRET_KEY are set, these tests'll try to connect and interact with a table (in Dynamo's default region, us-east-1).

Assuming a local Node install, lein cljsbuild once test-none will run the Clojurescript tests. test-advanced will run the tests under :optimizations :advanced.

Contributions welcomed.

See Also

• Faraday - An excellent, synchronous Dynamo client built on the official AWS client library. Hildebrand's approach to type handling was largely copied from Faraday.

License

hildebrand is free and unencumbered public domain software. For more information, see http://unlicense.org/ or the accompanying UNLICENSE file.