Liking cljdoc? Tell your friends :D
Taoensso open-source

CHANGELOG | API | current Break Version:

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

Build Status

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: coverage of the most useful DynamoDB features
  • Great performance (zero overhead to the official Java SDK)
  • Uses Nippy for full support of Clojure's rich data types

3rd-party stuff

LinkDescription
@mixradio/faraday-atomAtom implementation for Faraday
@ricardojmendez/ddb-tutorialTutorial: 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

   ;;; You may optionally provide your own (pre-configured) instance of the Amazon
   ;;; DynamoDB client for Faraday functions to use.
   ;; :client (AmazonDynamoDBClientBuilder/defaultClient)
  })

(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:

lein test

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.

Can you improve this documentation? These fine people already did:
Peter Taoussanis, Joe Littlejohn, Paul Lam, James Carnegie, Marcus Richardson, Sheel Choksi, Matt Innes, Philipp Küng, Paul Butcher, Ricardo J. Mendez & Richard Barker
Edit on GitHub

cljdoc is a website building & hosting documentation for Clojure/Script libraries

× close