CHANGELOG | API | current Break Version:

[com.taoensso/faraday "1.9.0"] ; BREAKING, see CHANGELOG for details

Please consider helping to support my continued open-source Clojure/Script work?

Even small contributions can add up + make a big difference to help sustain my time writing, maintaining, and supporting Faraday and other Clojure/Script libraries. Thank you!

- Peter Taoussanis

Faraday

Clojure DynamoDB client

DynamoDB is awesome and makes a great companion for Clojure web apps that need a simple, reliable way to scale with predictable performance and without the usual headaches.

Faraday was originally adapted from the Rotary client by James Reeves.

Library status

I'm not currently using DDB or Faraday myself but will make a best effort to continue maintaining the library as I can.

The bulk of recent development work has been thanks to the generosity of Faraday's contributors!

PRs for fixes and/or new features very welcome!

- Peter Taoussanis

Features

• Small, simple, API: complete coverage of DynamoDBv2 features
• Great performance (zero overhead to the official Java SDK)
• Uses Nippy for full support of Clojure's rich data types

3rd-party stuff

Link	Description
@mixradio/faraday-atom	Atom implementation for Faraday
@ricardojmendez/ddb-tutorial	Tutorial: Clojure and DDB with Faraday
Your link here?	PR's welcome!

Getting started

Add the necessary dependency to your project:

[com.taoensso/faraday "1.9.0"]

And setup your namespace imports:

(ns my-ns (:require [taoensso.faraday :as far]))

Preparing a database

Option 1 - Run a local DDB instance

First thing is to start a DynamoDB Local instance. Once DynamoDB Local is up and running in your terminal, you should see something like:

$ lein dynamodb-local
dynamodb-local: Options {:port 6798, :in-memory? true, :db-path /home/.../.clj-dynamodb-local}
dynamodb-local: Started DynamoDB Local

Then proceed to connecting with your local instance in the next section.

Option 2 - Spin up a cloud DDB instance on AWS

Make sure you've got an AWS DynamoDB account - note that there's a free tier with limited storage and 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
  {;;; For DDB Local just use some random strings here, otherwise include your
   ;;; production IAM keys:
   :access-key "<AWS_DYNAMODB_ACCESS_KEY>"
   :secret-key "<AWS_DYNAMODB_SECRET_KEY>"

   ;;; You may optionally override the default endpoint if you'd like to use DDB
   ;;; Local or a different AWS Region (Ref. http://goo.gl/YmV80o), etc.:
   ;; :endpoint "http://localhost:6798"                   ; For DDB Local
   ;; :endpoint "http://dynamodb.eu-west-1.amazonaws.com" ; For EU West 1 AWS region
  })

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

Now let's create a table? This is actually one of the more complicated parts of working with DynamoDB since it requires understanding how DynamoDB provisions capacity and how its idiosyncratic primary keys work. 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] ...}}

Remaining API

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 relevant API docs:

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 Faraday. The most useful single doc is probably on the DynamoDB data model.

Development

This project uses the dynamodb-local Lein plugin to manage downloading, starting and stopping an in-memory DynamoDB instance.

To run all the tests locally, run:

./run-tests local

If you intend to run tests from a repl, you can start a local DynamoDB instance:

lein dynamodb-local

Contacting me / contributions

Please use the project's GitHub issues page for all questions, ideas, etc. Pull requests welcome. See the project's GitHub contributors page for a list of contributors.

Otherwise, you can reach me at Taoensso.com. Happy hacking!

- Peter Taoussanis

License

Distributed under the EPL v1.0 (same as Clojure).
Copyright © 2013-2016 Peter Taoussanis.