This guide covers:
This work is licensed under a Creative Commons Attribution 3.0 Unported License (including images & stylesheets). The source is available on Github.
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.
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 http://127.0.0.1:8098/riak
(wc/connect)
;; 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.
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 127.0.0.1:8087 via Protocol Buffers transport
(wc/connect-via-pb)
;; 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.
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.
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 ["http://10.0.1.2:8098/riak" "http://10.0.1.3:8098/riak"])
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 ["10.0.1.2", "10.0.1.3", "10.0.1.4", "10.0.1.5", "10.0.1.6"])
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.
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:
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.