API docs | CHANGELOG | other Clojure libs | Twitter | contact/contributing | current (semantic) version:

[com.taoensso/faraday "1.3.0"] ; Stable

v1.3.x is a significant, backwards-compatible release. Please see the CHANGELOG for details.

Faraday, a Clojure DynamoDB client

DynamoDB is terrific and makes a great companion for Clojure web apps that need a simple, highly-reliable way to scale with predictable performance and without the usual headaches. Seriously, it rocks.

Concerned about the costs? They've been getting better recently and are actually pretty decent as of May 2013.

Faraday was adapted from James Reaves' Rotary client. Why adapt? Freedom to experiment rapidly+aggresively without being particularly concerned about backwards compatibility.

What's in the box™?

• Small, simple, API: complete coverage of DynamoDBv2 features.
• Great performance (zero overhead to the official Java SDK).
• Uses Nippy to support Clojure's rich data types and high-strength encryption.

Getting started

DynamoDB's done a fantastic job of hiding (in a good way) a lot of the complexity (in the Rich Hickey sense) that comes with managing large amounts of data. Despite the power at your disposal, the actual API you'll be using is pretty darn simple (especially via Clojure, as usual).

Dependencies

Add the necessary dependency to your Leiningen project.clj and require the library in your ns:

[com.taoensso/faraday "1.3.0"] ; project.clj
(ns my-app (:require [taoensso.faraday :as far])) ; ns

Preparing a database

First thing is to make sure you've got an AWS DynamoDB account (there's a free tier with 100MB of storage and limited read+write throughput). Next you'll need credentials for an IAM user with read+write access to your DynamoDB tables (see the IAM section of your AWS Management Console). Ready?

Connecting

(def client-opts
  {:access-key "<AWS_DYNAMODB_ACCESS_KEY>"
   :secret-key "<AWS_DYNAMODB_SECRET_KEY>"} ; Your IAM keys here
  )

;; or

(def client-opts
     {:provider <AWS_CREDENTIALS_PROVIDER>} ; Your Favorite AWSCredentialsProvider here
)

(far/list-tables client-opts)
=> [] ; No tables yet :-(

Well that was easy. How about we create a table? (This is actually one of the most complicated parts of working with DynamoDB since it requires understanding how DynamoDB provisions capacity and how its primary keys work. Anyway, we can safely ignore the specifics for now).

(far/create-table client-opts :my-table
  [:id :n]  ; Primary key named "id", (:n => number type)
  {:throughput {:read 1 :write 1} ; Read & write capacity (units/sec)
   :block? true ; Block thread during table creation
   })

;; Wait a minute for the table to be created... got a sandwich handy?

(far/list-tables client-opts)
=> [:my-table] ; There's our new table!

Let's write something to :my-table and fetch it back:

(far/put-item client-opts
    :my-table
    {:id 0 ; Remember that this is our primary (indexed) key
     :name "Steve" :age 22 :data (far/freeze {:vector    [1 2 3]
                                              :set      #{1 2 3}
                                              :rational (/ 22 7)
                                              ;; ... Any Clojure data goodness
                                              })})

(far/get-item client-opts :my-table {:id 0})
=> {:id 0 :name "Steve" :age 22 :data {:vector [1 2 3] ...}}

It really couldn't be simpler!

API

The above example is just scratching the surface obviously. DynamoDB gives you tons of power including secondary indexes, conditional writes, batch operations, atomic counters, tuneable read consistency and more.

Most of this stuff is controlled through optional arguments and is pretty easy to pick up by seeing the appropriate docstrings:

Tables: list-tables, describe-table, create-table, ensure-table, update-table, delete-table.

Items: get-item, put-item, update-item, delete-item.

Batch items: batch-get-item, batch-write-item.

Querying: query, scan, scan-parallel.

You can also check out the official AWS DynamoDB documentation though there's a lot of irrelevant Java-land complexity you won't need to deal with with Farady. The most useful doc is probably on the DynamoDB data model.

Performance

Faraday adds negligable overhead to the official Java AWS SDK:

Contact & contributing

lein start-dev to get a (headless) development repl that you can connect to with Cider (emacs) or your IDE.

Please use the project's GitHub issues page for project questions/comments/suggestions/whatever (pull requests welcome!). Am very open to ideas if you have any!

Otherwise reach me (Peter Taoussanis) at taoensso.com or on Twitter. Cheers!

License

Copyright © 2012-2014 Peter Taoussanis. Distributed under the Eclipse Public License, the same as Clojure.