Clarango: a Clojure driver for ArangoDB

Clarango is a library to connect Clojure with the database ArangoDB. Although it is work in progress, the parts which are already there are stable.

The latest version of Clarango on Clojars is 0.7.1.

The compatibility is as follows:

• 0.7.1 is compatible with ArangoDB versions 2.6 to 2.8 (and possibly higher; latest test was with version 2.8.11).
• 0.6.0 is compatible with ArangoDB 2.3 and 2.4 (ArangoDB 2.5 is untested; to see what changed with version 0.6, check out this blog post).
• 0.5.0 is compatible with ArangoDB versions 1.4 to 2.2.

Features

• various options for connecting
• document CRUD including various options
• querying by example
• AQL queries & custom functions
• collection management
• database management
• graph functions
• managing indices
• transactions
• experimental clojure idiomatic collection methods like cla-assoc! and cla-conj!
• simple exception handling

Documentation

For an overview of the features and how to use see below. For more detailed documentation have a look at:

• The Clarango API overview
• or the API overview on crossclj (possibly older version)
• our book as pdf for printing / download or as html readable online (possibly older version)

Installation

The driver is hosted on Clojars. Add this Leiningen dependency to your project.clj:

[clarango "0.7.1"]

Then require the lib in your clojure file. For example:

(:require [clarango.core :as clacore]
          [clarango.document :as document]
          [clarango.collection :as collection]
          [clarango.graph :as graph])

Setting the Connection

;; connect to localhost and default port 8529
(clacore/set-connection!)

;; pass a connection map
(clacore/set-connection!
  {
    :connection-url "http://localhost:8529/"
    :db-name "my-db"
    :collection-name "my-collection"
    ; if you are working with graphs you can optionally add :graph-name "my-graph"
  })

;; change default db
(clacore/set-default-db! "my-db")

;; ... or just
(clacore/with-connection {:connection-url "http://localhost:8529/" ...}
  ;; ... do your business here
  )

The server url is mandatory. Default database and collection are optional.

Document CRUD

(collection/create "test-collection")
(with-collection "test-collection"
  ;; create
  (document/create-with-key {:description "some test document"} :test-doc)
  ;; read
  (document/get-by-key :test-doc)
  (document/get-by-example {:description "some test document"})
  ;; update
  (document/update-by-key {:additional "some additional info"} :test-doc)
  ;; delete
  (document/delete-by-key :test-doc))

Graph

(collection/create "people" {"type" 2})
(collection/create "content" {"type" 2})
(graph/create :test-graph [{:edge-collection "my-test-edges" :from [:people] :to [:content]}])
(with-graph :test-graph
  (graph/create-vertex {:name "Rich Hickey"} :people))

All methods will use the default database and collection unless the names of different ones are passed as optional arguments. For a complete list of methods see the API overview

Bugs / Contributors

If you find bugs or are missing a feature open an issue or feel free to pull request. Furthermore we have easy and hard open issues. So if you like to help us, contact us or / and pick an issue. Also check out contributions.md.

We are looking for contributors to keep the project running, so please get in touch or just pull!

License

Licensed under the Apache Public License 2.0.