{"id":15286897,"url":"https://github.com/taoensso/faraday","last_synced_at":"2025-12-12T01:06:26.398Z","repository":{"id":36064082,"uuid":"10190783","full_name":"taoensso/faraday","owner":"taoensso","description":"Amazon DynamoDB client for Clojure","archived":false,"fork":false,"pushed_at":"2024-06-01T19:39:27.000Z","size":952,"stargazers_count":242,"open_issues_count":3,"forks_count":83,"subscribers_count":21,"default_branch":"master","last_synced_at":"2025-03-31T22:21:45.417Z","etag":null,"topics":["aws","clojure","dynamodb","epl","taoensso"],"latest_commit_sha":null,"homepage":"https://www.taoensso.com/faraday","language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"epl-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/taoensso.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-05-21T08:04:54.000Z","updated_at":"2025-03-04T17:43:58.000Z","dependencies_parsed_at":"2022-08-08T13:01:15.287Z","dependency_job_id":"ba25ffda-6e62-4282-ad2a-9b83f7622297","html_url":"https://github.com/taoensso/faraday","commit_stats":{"total_commits":465,"total_committers":46,"mean_commits":"10.108695652173912","dds":"0.36989247311827955","last_synced_commit":"1ad26007ef31fa67e32371f9841f6c606891b6fc"},"previous_names":["ptaoussanis/faraday"],"tags_count":58,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taoensso%2Ffaraday","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taoensso%2Ffaraday/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taoensso%2Ffaraday/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taoensso%2Ffaraday/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/taoensso","download_url":"https://codeload.github.com/taoensso/faraday/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247744335,"owners_count":20988783,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","clojure","dynamodb","epl","taoensso"],"created_at":"2024-09-30T15:18:53.890Z","updated_at":"2025-12-12T01:06:26.325Z","avatar_url":"https://github.com/taoensso.png","language":"Clojure","funding_links":[],"categories":["\u003ca name=\"Clojure\"\u003e\u003c/a\u003eClojure"],"sub_categories":[],"readme":"# Faraday\n\n#### Amazon DynamoDB client for Clojure\n\n* API reference: [Codox][Codox docs], [clj-doc][clj-doc docs]\n* Leiningen: `[com.taoensso/faraday \"1.12.3\"]`\n* deps.edn: `com.taoensso/faraday {:mvn/version \"1.12.3\"}`\n\n[![Main tests][Main tests SVG]][Main tests URL]\n[![Graal tests][Graal tests SVG]][Graal tests URL]\n\nDynamoDB makes a great companion for Clojure apps that need a **simple, reliable way to persist data, that scales with predictable performance**. Faraday is a small, fast and intuitive DynamoDB client library for Clojure, built around the AWS Java SDK and originally adapted from [Rotary](https://github.com/weavejester/rotary) by James Reeves.\n\n## Why Faraday?\n* Small and simple API, with coverage of the most useful DynamoDB features\n* Great performance (zero overhead to the official Java SDK)\n* Uses [Nippy](https://github.com/ptaoussanis/nippy) for full support of Clojure's rich data types (with compression too)\n* The AWS Java SDK for DynamoDB is awkward and verbose\n* General purpose AWS SDKs for Clojure such as [Amazonica](https://github.com/mcohen01/amazonica) or [aws-api](https://github.com/cognitect-labs/aws-api) inherit the awkwardness of the AWS SDK when used to interact with DynamoDB\n\n## Getting started\n\nAdd Faraday as a dependency to your project and import faraday into your namespace:\n\n```clojure\n(ns my-ns\n (:require [taoensso.faraday :as far]))\n```\n\n### Preparing a database\n\n#### Option 1 - Run a local DynamoDB instance\n\nFirst thing is to start a DynamoDB Local instance. Once DynamoDB Local is up and running in your terminal, you should see something like:\n\n```sh\n$ docker run -p 8000:8000 amazon/dynamodb-local\nInitializing DynamoDB Local with the following configuration:\nPort:\t\t8000\nInMemory:\ttrue\nDbPath:\t\tnull\nSharedDb:\tfalse\nshouldDelayTransientStatuses:\tfalse\nCorsParams:\t*\n```\n\nThen proceed to connecting with your local instance in the next section.\n\n#### Option 2 - Use DynamoDB in the cloud\n\nMake sure you've got an AWS account - note that there's a **free tier** with limited DynamoDB storage and read/write throughput. Next you'll need credentials for an IAM user with read/write access to your DynamoDB tables.\n\nReady?\n\n### Connecting\n\n```clojure\n(def client-opts\n  {;;; For DynamoDB Local just use some random strings here, otherwise include your\n   ;;; production IAM keys:\n   :access-key \"\u003cAWS_DYNAMODB_ACCESS_KEY\u003e\"\n   :secret-key \"\u003cAWS_DYNAMODB_SECRET_KEY\u003e\"\n\n   ;;; You may optionally override the default endpoint if you'd like to use DynamoDB\n   ;;; Local or a different AWS Region (Ref. http://goo.gl/YmV80o), etc.:\n   ;; :endpoint \"http://localhost:8000\"                   ; For DynamoDB Local\n   ;; :endpoint \"http://dynamodb.eu-west-1.amazonaws.com\" ; For EU West 1 AWS region\n\n   ;;; You may optionally provide your own (pre-configured) instance of the Amazon\n   ;;; DynamoDB client for Faraday functions to use.\n   ;; :client (AmazonDynamoDBClientBuilder/defaultClient)\n  })\n\n(far/list-tables client-opts)\n=\u003e [] ; That's good, we don't have any tables yet :)\n```\n\nNow 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](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DataModel.html#DataModelPrimaryKey) work. We can safely ignore the specifics for now.\n\n```clojure\n(far/create-table client-opts :my-table\n  [:id :n]  ; Primary key named \"id\", (:n =\u003e number type)\n  {:throughput {:read 1 :write 1} ; Read \u0026 write capacity (units/sec)\n   :block? true ; Block thread during table creation\n   })\n\n;; Wait a minute for the table to be created... got a sandwich handy?\n\n(far/list-tables client-opts)\n=\u003e [:my-table] ; There's our new table!\n```\n\nLet's write something to `:my-table` and then fetch it:\n\n```clojure\n(far/put-item client-opts\n    :my-table\n    {:id 0 ; Remember that this is our primary (indexed) key\n     :name \"Steve\" :age 22 :data (far/freeze {:vector    [1 2 3]\n                                              :set      #{1 2 3}\n                                              :rational (/ 22 7)\n                                              ;; ... Any Clojure data goodness\n                                              })})\n\n(far/get-item client-opts :my-table {:id 0})\n=\u003e {:id 0 :name \"Steve\" :age 22 :data {:vector [1 2 3] ...}}\n```\n\n### Remaining API\n\nDynamoDB gives you tons of power including **secondary indexes**, **conditional writes**, **batch operations**, **atomic counters**, **tuneable read consistency** and more.\n\nMost of this stuff is controlled through optional arguments and is pretty easy to pick up by seeing the relevant [API] docs:\n\n**Tables**: `list-tables`, `describe-table`, `create-table`, `ensure-table`, `update-table`, `delete-table`.\n\n**Items**: `get-item`, `put-item`, `update-item`, `delete-item`.\n\n**Batch items**: `batch-get-item`, `batch-write-item`.\n\n**Querying**: `query`, `scan`, `scan-parallel`.\n\n**Transactions**: `transact-write-items`, `transact-get-items`\n\nYou can also check out the [official AWS DynamoDB documentation](http://aws.amazon.com/documentation/dynamodb/), though there's a lot of Java-land complexity that you won't need to deal with when using Faraday. The most useful single doc is probably on the [DynamoDB data model](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DataModel.html) and the [DynamoDB Best Practices](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/best-practices.html).\n\n## Development\n\nThis project uses [Testcontainers](https://www.testcontainers.org/) to manage starting and stopping a local DynamoDB instance in docker.\n\nRun the tests locally with:\n\n```bash\nlein test\n```\n\nOr run tests from a REPL like:\n\n```clj\ntaoensso.faraday.tests.main\u003e (clojure.test/run-tests)\n```\n\nTo run the entire test suite against all supported versions of Clojure, use:\n\n```bash\nlein test-all\n```\n\n## Contributions\n\nPlease see GitHub issues for bugs, ideas, etc. **Pull requests welcome**. For a general question on usage, try StackOverflow or ask the Faraday users and developers in `#faraday` at clojurians.slack.com.\n\n## License\n\nCopyright \u0026copy; 2013-2023 [Peter Taoussanis][] and contributors, licensed under [EPL 1.0][] (same as Clojure).\n\n\u003c!--- Common links --\u003e\n[EPL 1.0]: LICENSE\n[Peter Taoussanis]: https://www.taoensso.com\n\n\u003c!--- Project links --\u003e\n[Taoensso docs]: https://www.taoensso.com/faraday\n[Codox docs]: http://taoensso.github.io/faraday/\n[clj-doc docs]: https://cljdoc.org/d/com.taoensso/faraday/\n\n[Clojars SVG]: https://img.shields.io/clojars/v/com.taoensso/faraday.svg\n[Clojars URL]: https://clojars.org/com.taoensso/faraday\n\n[Main tests SVG]: https://github.com/taoensso/faraday/actions/workflows/main-tests.yml/badge.svg\n[Main tests URL]: https://github.com/taoensso/faraday/actions/workflows/main-tests.yml\n[Graal tests SVG]: https://github.com/taoensso/faraday/actions/workflows/graal-tests.yml/badge.svg\n[Graal tests URL]: https://github.com/taoensso/faraday/actions/workflows/graal-tests.yml\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaoensso%2Ffaraday","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftaoensso%2Ffaraday","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaoensso%2Ffaraday/lists"}