About this guide

This guide covers:

  • Using Riak's HTTP transport with Welle
  • Using Protocol Buffers (PBC) transport
  • Checking connection health

This work is licensed under a Creative Commons Attribution 3.0 Unported License (including images & stylesheets). The source is available on Github.

What version of Welle does this guide cover?

This guide covers Welle 3.0, including development releases.


Riak and Welle support two transports: HTTP and Protocol Buffers. They vary in performance characteristics and supported features (PBC API supports searcn and secondary indexes starting with Riak 1.2). Most applications use HTTP API: it delivers pretty good performance, easier to develop clients against and debug.

Using Riak's HTTP transport

clojurewerkz.welle.core/connect function sets up a connection to Riak using HTTP transport and returns it. You can invoke it in three ways:

(ns welle.docs.examples
  (:require [clojurewerkz.welle.core :as wc]))

;; connects to a Riak node at

;; connects to a Riak node at the given endpoint, client id will be generated
(wc/connect "http://riak.data.megacorp.internal:8098/riak")

;; the same as the previous example but also uses provided client id
(wc/connect "http://riak.data.megacorp.internal:8098/riak" "myapp-client.0001")

It is very common to use the 1-arity (first example) in development and the 2-arity (second example) for QA and production environments. Most of the time, relying on client id to be generated by Welle is sufficient. You can learn more about client ids and how they are used by Riak for conflict detection and resolution in the Riak documentation.

Using Protocol Buffers Transport

To connect using the Protocol Buffers transport, use clojurewerkz.welle.core/connect-via-pb:

(ns welle.docs.examples
  (:require [clojurewerkz.welle.core :as wc]))

;; connects to a Riak node at via Protocol Buffers transport

;; connects to a Riak node at the given endpoint
(wc/connect-via-pb "riak.data.megacorp.internal", 8098)

Protocol Buffers client (often abbreviated as PBC) is more efficient on the wire and will likely result in higher throughput, but historically hasn't had feature parity with the HTTP client.

Recent Riak releases bring PBC very close to the HTTP client in terms of supported features.

Cluster Clients

Welle supports cluster clients: clients that round robin between multiple nodes. Cluster clients help make your application more resilient to failure but also stress the importance of conflict resolution that may arise.

HTTP Cluster Client

To use an HTTP cluster client, use clojurewerkz.welle.core/connect-to-cluster, which takes a list of HTTP URIs and works exactly like clojurewerkz.welle.kv/connect.

(ns welle.docs.examples
  (:require [clojurewerkz.welle.core :as wc]))

(wc/connect-to-cluster ["" ""])

Protocol Buffers Cluster Client

To use a Protocol Buffers cluster client, use clojurewerkz.welle.core/connect-to-cluster-via-pb, which takes a list of node IP addresses and works exactly like clojurewerkz.welle.kv/connect-via-pb.

(ns welle.docs.examples
  (:require [clojurewerkz.welle.core :as wc]))

(wc/connect-to-cluster-via-pb ["", "", "", "", ""])

Checking Connection Health

To check connection health, use clojurewerkz.welle.core/ping function. It takes a connection and always returns nil.

If Riak is not reachable, a java.io.IOException will be thrown.

Differences Between Two Transports

As far as Welle API goes, you don't have to change anything besides using clojurewerkz.welle.core/connect-via-pb! instead of clojurewerkz.welle.core/connect! to go from one transport to the other. However, the PBC transport has certain limitations, for example, it only supports secondary indexes (2i) and search starting with Riak 1.2.

If you try to use a feature that the PBC API does not support, an exception will be raised. Going between two transports is straightforward with Welle, so don't hesitate to give Protocol Buffers a try.

The documentation is organized as a number of guides, covering all kinds of topics.

We recommend that you read the following guides first, if possible, in this order:

Tell Us What You Think!

Please take a moment to tell us what you think about this guide on Twitter or the Welle mailing list

Let us know what was unclear or what has not been covered. Maybe you do not like the guide style or grammar or discover spelling mistakes. Reader feedback is key to making the documentation better.

comments powered by Disqus