Liking cljdoc? Tell your friends :D

Aerospike-clj

An opinionated Clojure library wrapping Aerospike Java Client.

Requirements:

  • Java 8
  • Clojure 1.8

Features:

  • Converts Java client's callback model into a future (manifold/deferred) based API.
  • Expose passing functional transcoders over payloads (both put/get).
  • Health-check utility.
  • Functions return Clojure maps.

Opinionated:

  • Non blocking only: Expose only the non-blocking API. Block with deref if you like.
  • Futures instead of callbacks. Futures (and functional chaining) are more composable and less cluttered. If a synchronous behaviour is still desired, the calling code can still deref (@) the returned future object. For a more sophisticated coordination, a variety of control mechanism is supplied by manifold/deferred.
  • Tries to follow the method names of the underlying Java API (with Clojure standard library limitations)
  • TTLs should be explicit, and developers should think about them. Forces passing a ttl and not use the cluster default.
  • Minimal dependencies.
  • Single client per Aerospike namespace.

Limitations/ caveats

  • Currently supports only single bin records.
  • Does not expose batch operations.
  • Does not support passing all Policy flags as Clojure keywords yet (WIP).

TBD

  • use batch asynchronous APIs

Usage:

Most of the time just create a simple client (single cluster)

(require '[aerospike-clj.client :as client)

(def db (client/init-simple-aerospike-client
          ["aerospike-001.com", "aerospik-002.com"] "my-ns" {:enable-logging true}))

It is possible to inject additional asynchronous user-defined behaviour. To do that add an instance of ClientEvents. Some useful info is passed in in-order to support metering and to read client configuration. op-start-time is (System/nanoTime).

(let [c (client/init-simple-aerospike-client
          ["localhost"]
          "test"
          {:client-events (reify ClientEvents
                            (on-success [_ op-name op-result index op-start-time db]
                              (when (:enable-logging? db)
                                (println op-name "success!")))
                            (on-failure [_  op-name op-ex index op-start-time db]
                              (println "oh-no" op-name "failed on index" index)))})]

  (get-single-with-meta c "index" "set-name"))

Query

(let [data (rand-int 1000)]
    (is (true? @(client/create db "a-key" "a-set" data 100)))
    (let [{:keys [payload gen]} @(client/get-single-with-meta db "a-key" "a-set")]
      (is (= data payload))
      (is (= 1 gen))))

Unix EPOCH TTL

Aerospike returns a TTL on the queried records that is Epoch style, but with a different "beginning of time" which is "2010-01-01T00:00:00Z". Call expiry-unix with the returned TTL to get a UNIX TTL if you want to convert it later to a more standard timestamp.

Put

(let [data (rand-int 1000)]
    (is (true? @(client/put db "another-key" "a-set" data 100{:record-exist-action :replace :transcoder identity})))
    (let [{:keys [payload gen]} @(client/get-single-with-meta db "another-key" "a-set")]
      (is (= data payload))
      (is (= 1 gen))))

Creating additional clients

Implement IAerospikeClient. For example, creating a client that is sharding reads and writes between several clients:

(defrecord ShardedAerospikeClient [^"[Lcom.aerospike.client.AerospikeClient;" acs
                                   ^int shards
                                   ^EventLoop el
                                   ^ClientPolicy cp
                                   ^String dbns
                                   ^String cluster-name
                                   ^boolean logging?
                                   client-events]
  IAerospikeClient
  (get-client ^AerospikeClient [_ index] (get acs (mod (hash index) shards)))
  (get-client-policy ^ClientPolicy [_] cp)
  (get-all-clients [_] acs))

Testing

Testing is performed against a local Aerospike running in the latest docker

$ sudo docker run -d --name aerospike -p 3000:3000 -p 3001:3001 -p 3002:3002 -p 3003:3003 aerospike
$ lein test

Contributing

PRs are welcome!

License

Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.

Edit on GitHub

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

× close