Connecting
There are three steps to get started and you may not need to do all of them:
- Verify Riak installation and operation.
- Riak .NET Client configuration.
- Build your client and connect.
You need to know Riak's protocol buffers and HTTP port numbers.
- If you installed Riak via a package (such as a Debian
.debpackage or Homebrew) or from source and built usingmake rel, then by default the port number on which Riak listens for protocol buffers connections is8087. For HTTP connections it will be8098. - If you installed Riak from source and built it using
make devrelyou can assume that there is a 3-node cluster ready and listening on ports10017,10027and10037(10018,10028and10038for HTTP connections).
Fire up a browser and point it to your Riak machine with a URL like http://127.0.0.1:8098/riak/status. You can connect to any node in your Riak cluster (you could even have it behind some kind of load balancing proxy). Verify the port number with your admin if you can't get connected. If the port number is right and you can't connect then we need to move on to verifying if Riak is listening. If you get connected at this point, then move on to the next step.
If you can't get connected, the best bet is to make sure Riak is listening on the right IP and port. Open up the app.config file and look in the riak_core and riak_kv sections. Make sure the http, https, and/or pb_ip/pb_port configuration values list the IP and port combinations that you're expecting. If you're a developer with a development cluster running on a different machine to the one you intend to connect from using the Riak .NET Client then it is important that IP addresses for pb_ip, http and https (if used) are not set to 127.0.0.1 as this is the loopback address. Binding to this address will prevent any connections from applications not on the local machine from connecting to Riak. If in doubt, the easiest way to solve the IP binding problem is to change all instances of 127.0.0.1 to 0.0.0.0, which will tell Riak to bind to all interfaces on the machine.
The Riak .NET Client makes use of both the HTTP and PBC interfaces, so it is important that both of these are configured correctly. Where possible, the Riak .NET Client uses the Protocol Buffers API instead of the HTTP API to improve application throughput and performance, but it will fall back to the HTTP API in cases where the required feature set is not available via the Protocol Buffers interface.
When all else fails, check the official Riak documentation.
Now that you can talk to Riak, the next step is to set the Riak .NET Client configuration. This can be done manually or automatically depending on your environment.
In your configuration file, create a configuration section for Riak:
<configSections>
<section name="riakConfig"
type="RiakClient.Config.RiakClusterConfiguration, RiakClient"/>
</configSections>You've told your application to expect a configuration section, now actually add the configuration section:
<riakConfig nodePollTime="5000" defaultRetryWaitTime="200" defaultRetryCount="3">
<nodes>
<node name="dev1" hostAddress="riak-test"
pbcPort="10017" restPort="10018" poolSize="20" />
<node name="dev2" hostAddress="riak-test"
pbcPort="10027" restPort="10028" poolSize="20" />
<node name="dev3" hostAddress="riak-test"
pbcPort="10037" restPort="10038" poolSize="20" />
</nodes>
</riakConfig>Here you're creating a 3 node cluster listening on the riak-test machine, which is the cluster you would have created if you walked through the Riak Five-Minute Install. Note that the riak-test hostname must be resolvable by DNS or via your hosts file. You could configure a single node, five node, or 60 node cluster. The Riak .NET Client ships with a basic round robin load balancer.
It's important to note that the configuration shown above does not include all possible configuration options - the remaining options have sane defaults.
| Attribute | Default |
|---|---|
nodePollTime |
5000ms |
defaultRetryWaitTime |
200ms |
defaultRetryCount |
3 |
pbcPort |
8087 |
restScheme |
http |
restPort |
8098 |
poolSize |
30 |
networkReadTimeout |
4000ms |
networkWriteTimeout |
4000ms |
networkConnectTimeout |
4000ms |
This configuration information can be added to a web.config or app.config file. However, applications don't always have these configuration files so the Riak .NET Client supports the loading of configuration from any configuration file, so long as it takes the same form as the XML listed above.
As of v1.3.0, the Riak .NET Client supports on-the-fly connections as well as pooling. To enable this feature, set the poolSize attribute of a given node to 0.
At this point, you should have Riak configured to accept connections and the configuration should be set up and ready to go. The next step is to wire up the Riak .NET Client. This example shows how you would connect to Riak using plain old .NET.
var cluster = RiakCluster.FromConfig("riakConfig");
var client = cluster.CreateClient();This code assumes that you're using app.config or web.config. If you're one of those people who isn't using either, but instead have your configuration stored somewhere else, you can use the overload provided that looks like this:
var cluster = RiakCluster.FromConfig("riakConfig", @"path\to\riak.config");
var client = cluster.CreateClient();The second parameter specifies the path to the file which takes the configuration.
After you've connected, you can issue a Client.Ping() to make sure you're able to communicate with Riak. Client.Ping() returns a RiakResult object. If the Ping() is successful RiakResult.IsSuccess will be true. At this point, you should get a valid response from Riak. If not, take a look through your configuration, run through the Riak Five-Minute Install, and hit up either the Riak developer mailing list or else the #riak IRC channel on freenode.
If you don't want to do things the old fashioned way, you can always use an IoC library to get connected to Riak through RiakClient. The Riak .NET Client sample projects demonstrate how to use a variety of IoC containers to wire up RiakClient. Here's what this might look like using Unity:
using RiakClient;
using RiakClient.Comms;
using RiakClient.Config;
using Microsoft.Practices.Unity;
namespace Sample.Unity
{
public static class UnityBootstrapper
{
public static IUnityContainer Bootstrap()
{
var clusterConfig = RiakClusterConfiguration.LoadFromConfig("riakConfig");
var container = new UnityContainer();
container.RegisterInstance<IRiakClusterConfiguration>(clusterConfig);
container.RegisterType<IRiakConnectionFactory, RiakConnectionFactory>(new ContainerControlledLifetimeManager());
container.RegisterType<IRiakCluster, RiakCluster>(new ContainerControlledLifetimeManager());
// tell unity to use the IRiakCluster.CreateClient() function to generate new client instances
container.RegisterType<IRiakClient>(new InjectionFactory(c => c.Resolve<IRiakCluster>().CreateClient()));
return container;
}
}
}Note: the above sample shows every piece of the puzzle that makes up the wiring of a RiakClient for the purposes of showing you what can be configured. In most cases, all that would be needed is the following:
using RiakClient;
using RiakClient.Comms;
using RiakClient.Config;
using Microsoft.Practices.Unity;
namespace Sample.Unity
{
public static class UnityBootstrapper
{
public static IUnityContainer Bootstrap()
{
var cluster = RiakCluster.FromConfig("riakConfig");
var container = new UnityContainer();
container.RegisterInstance<IRiakCluster>(cluster, new ContainerControlledLifetimeManager());
container.RegisterType<IRiakClient>(new InjectionFactory(_ => cluster.CreateClient()));
return container;
}
}
}Bootstrapping only needs to happen once in each application and can be called like so:
var container = UnityBootstrapper.Bootstrap();Then, create a client:
var client = container.Resolve<IRiakClient>();You can find more examples of configuring the Riak .NET Client in the samples project hosted on GitHub.
