Get started with Redis on Compose

Redis Logo

In this article, we're going to run through the steps you'll go through to get going with Redis on Compose. Once you've realised you've got some write intensive operations in your application or need a transient message queue, you'll probably want to use Redis in your architecture to relieve yourself of performance constraints. With it's memory-first design and blistering performance, Redis can take on the challenge and leave your other database deployments to free to focus on storage, queries and analysis.

The simple part is provisioning your Redis database on Compose. Assuming you've signed up and signed in, just click "Add Deployment", select Redis, give the deployment a name and a starting capacity, click add and you're done. Compose takes care of all that for you giving you a two database node cluster with a monitoring Sentinel node and a HTTP access portal. Your next step is that you are going to want to learn how to talk Redis so...

Getting Redis-CLI

The redis-cli command will let you talk directly to your Redis deployment, but there's a small catch; redis-cli is part of the whole Redis package, server and all. So you'd have to install that and that typically comes as source code from the Redis downloads page. There are exceptions to this rule, some Linux distributions have a separate Redis-tools package - on Ubuntu you can do sudo apt-get install redis-tools to get just the tools. But for most people, they'll need to build from source. The downloads page shows you a quick way to download and build Redis, like so:

$ wget http://download.redis.io/releases/redis-2.8.17.tar.gz
$ tar xzf redis-2.8.17.tar.gz
$ cd redis-2.8.17
$ make

If you follow those instructions on the downloads page, you'll build all of Redis and we only want the redis-cli tool, so change the make to

make redis-cli  

And it will just build that. Copy the resulting binary from the src directory to somewhere where you can run it, for example:

$ cp src/redis-cli /usr/local/bin/

And as long as you have permission to do that copy, you'll be ready to connect.

Connecting with Redis-CLI

We have our command line tool, now we need to connect to Redis on Compose. Pull up your Compose Dashboard and select your Redis deployment. You'll see an overview of your database:

Redis connection Strings

And in the Connect Strings section a URI connection string which can be given to applications with Redis drivers and a command line string. Here it's

redis-cli -h portal.0.dblayer.com -p 10114 -a [password]  

This should be fairly self-explanatory; the -h parameter is the name of host to connect to, the -p parameter is the port to connect to there and the -a parameter is the password which you won't know.

Redis uses a simple password only authentication. One password gives access to the database, no username needed. At Compose we use that same password to give access through the proxy to the Redis database. We'll come back to some ways to tighten up your control on that in a moment. For now, just know that's all you need. To get the password, scroll down on the overview page to the Additional Information section.

Redis password

By default the password is hidden behind a button. Click the button and the password is revealed as we're showing here. You can also change the password here but pay attention to that note - it will require a restart on your database to put into effect. Anyway, here our password is REDISPASS. I could now connect to my Redis with the command:

$ redis-cli -h portal.0.dblayer.com -p 10114 -a REDISPASS
portal.0.dblayer.com:10114>  

and you can connect to your Redis by assembling those two strings into a similar command. Now we are able to use the CLI. It has tab auto-completion, history and other handy features for interacting including an extensive help system. Actually interacting with the database is as simple as SET and GET:

portal.0.dblayer.com:10114> set fred 1  
OK  
portal.0.dblayer.com:10114> get fred  
"1"
portal.0.dblayer.com:10114>  

If you are completely new to Redis, check out the Try Redis interactive tutorial. If you just want to see what commands are at your command, check out the command documentation which lists them all and links through to more documentation on each.

Securing your Redis

As you'll have noticed, there's only one password for the Redis installation and you will most likely want more control of who can access it. First is IP Whitelisting which can be applied to the TCP/HTTP access portal. When activated, it will block all connections to the proxy unless they come from IP addresses you have added to the white list. You'll find the white list controls on the Security tab of the database's deployment. This is probably the simplest route for most users because of what the proxy does behind the scenes.

When a Redis client connects to the TCP/HTTP access portal, the proxy converses with a Redis Sentinel process within the cluster to locate the current Redis master instance. It then connects to the user's session to that instance. This means you are always connected to the master with no need to be aware of how the Redis Sentinel system works and no need for your drivers to support the Sentinel's discovery system.

Connecting a driver

We are now ready to connect an application to the Redis server. As an example, we'll use Node.js to write a simple application that sets a key to a value. Here's the code:

var redis = require("redis");  
var client = require("redis-url").connect();

client.on("error", function (err) {  
  console.log("Error " + err);
});

client.set("just a test set", "a test set", redis.print);

client.quit();  

This uses the redis npm package which provides an extensive API for accesssing the Redis database. The one thing it doesn't do is allow you pass it a Redis URL. If you look on the Overview page, a Redis URL what you'll be given. It looks something like this:

redis://x:REDISPASS@portal.0.dblayer.com:10114  

Now, it's a simple process to manually break this up into its parts: the host is "portal.0.dblayer.com", the port is "10117" and the authentication password is "REDISPASS". (You can also get those values from the redis_cli command given on the same page). Those three values could be passed to the createClient method of the Redis npm package.

If you'd rather not hardwire them in, then you'd have to work with multiple environment variables. Or... you can use redis-url which can take as a parameter or from a REDIS_URL environment variable the Redis URL, parse it and helpfully sets up the connection got you. This is what the second line of the code does. The rest of the code simply sets up an error handler, sets a key to a value and quits the connection.

Redis URL support isn't uniformly available through drivers, so do check when you are selecting which of the many Redis clients you want to use with your application.

Wrapping up

You should have everything you need to know and use for connecting to Redis on Compose. Redis-CLI will give you an easy way to connect and manipulate the data, you can restrict access to your Redis database using whitelists and we've noted how you'll have to decide whether you want to use convenient Redis URLs or work with the host, port and password separately when writing applications. Next stop is a Redis optimised application as part of your polybased full database stack.