Getting Started with RavenDB Cloud Database

RavenDB Cloud is a new database-as-a-service from the creators of RavenDB NoSQL Database. No need to download any software, futz with port forwarding or virtual machine management: just visit cloud.ravendb.net and spin up a RavenDB instance.

RavenDB itself is a distributed database: while it can run as a single server, Raven is designed to work well in a cluster, multiple instances of your database that sync to each other and keep your app running even if a database server goes down. RavenDB Cloud builds on this and makes it super simple to spin up a database cluster to make your app more scalable and resilient.

In this article, I’ll walk you through both. We’ll start by spinning up a basic, single node instance in RavenDB Cloud. Then I’ll show you how to spin up a full cluster. All the while, we’ll be talking to our database from an ASP.NET Core web app. Let’s get started!

Spinning up a (free!) RavenDB Cloud instance

RavenDB Cloud offers a free instance. This is great for testing the waters and doing some dev hacking on Raven. I also use the free instance as my "local" database during development; it’s super easy to spin up an instance in RavenDB Cloud and point my locally running apps at. Let’s do that now.

Head over to cloud.ravendb.net and click "Get started free":

You’ll register with your email address and then you’ll be asked what domain you’d like. This will be the URL through which you’ll access your databases. For this CodeProject article, I decided on a fitting name :

The next step is optional: billing information. If you’re just playing around with the free instance, you can click "skip billing information." Now we’re presented with the final summary of our information. Click "Sign up" and we’re ready to roll:

Now we’re registered and we’ll receive our sign in link via email:

I’ve now got an email with a magic link that signs me in. Clicking that link takes me to my RavenDB Cloud dashboard:

Here we’ll create a new product: our free RavenDB Cloud instance.

You might wonder: what do we mean by "product" here – is it just a single database? A product here really means a cloud server(s) in which one or more databases reside. So, for example, our free instance can have multiple databases inside of it, as we’ll see shortly.

We’ll click "Add Product" and we’re asked what we want to create, with the default being the free instance:

If we change nothing on this screen, we’ll create a free instance, which is perfect for our initial setup.

Before we move on, notice we can create an instance either in Amazon’s or Microsoft’s cloud. We can also choose the region, for example, AWS Canada, or Azure West US:

We can also choose the tier: Free, Development, or Production. For our first example here, we’re going to go with the free instance.

It’s limited to a single node – no highly available cluster –10 GB of disk space, running on low-end hardware (2 vCPUs and 0.5 GB RAM). That’s fine for testing and for small projects; perfect for testing the waters. We’ll go ahead and choose the free instance and click Next.

Now we can specify the Display Name of the product; this is what we’ll see on our dashboard. Optionally, you can limit access to your database by IP range. Raven databases are secure by default using client certificates – we’ll talk about these more in a moment – so limiting access to an IP range isn’t strictly necessary, but adds an additional layer of security. For now, I’ll leave the IP range opened to the world.

We’ll click Next to see the summary of our RavenDB Cloud product, then click Create.

Once we click Create, I can see the free instance on my dashboard:

Here you can see our free instance spinning up in AWS, with a yellow "Creating" status. After a moment, it will finish spinning up and you’ll see the product go green in the Active state:

Congrats! You just spun up a free RavenDB Cloud instance.

We want to connect to this instance and create some databases. We can do that through code, but with RavenDB, we can also do it through the web using Raven’s built-in tooling, Raven Studio. You’ll notice the URLs section of the instance: that’s the URL that we can access our database server and create databases in.

But wait – isn’t that a security risk? If you try it right now in your browser, going to https://a.free.clistctrl.ravendb.cloud, you’ll be prompted for a security certificate. Where do you get the certificate? RavenDB Cloud generates one for you, and it’s available through the "Download Certificate" button:

Clicking "Download Certificate" will download a zip file containing a .pfx file – the certificate we need to access our database server:

(Yes, I really did pay for a registered copy of WinRAR)

You’ll see 2 .pfx files in there: one with a password, one without. You’re free to use either, but for our purposes, we’re going to use the one without a password. I’ll double-click free.clistctrl.client.certificate.pfx and click Next all the way through until I’m done; no special settings needed.

Once I’ve installed that certificate, I can now securely access my database using the URL listed in the dashboard:

Note: If you tried to access the URL before installing the certificate, you may run into an issue where your browser won’t prompt you for a certificate even after installing it. If that happens, simply restart your browser, or alternately, open the link in a private/incognito browser window.

Going to that URL in Chrome will prompt me to choose a certificate. I’ll choose the one we just installed, free.clistctrl. Hooray! We’re connected to our free RavenDB Cloud instance:

What we’re looking at here is RavenDB’s built-in tooling, Raven Studio. You can think of Raven Studio akin to e.g. SQL Management Studio: it’s where we can create databases, view data in our databases, execute queries, etc.

Our first step is going to be creating a database. I’m going to click Databases -> New database. I’m going to name it Outlaws, which we’ll use to store wonderful mythic outlaws of the wild west.

After clicking, we have a new database up and running in RavenDB Cloud – woohoo!

How does it look to connect to this database from, say, an ASP.NET Core web app? It’s pretty simple, actually. I’m going to do that now, just to show how simple it is.

While RavenDB has official clients for .NET, JVM, Go, Python, Node.js, and C++, I’m most familiar with C# and .NET, and I think Raven shines brightest on .NET Core. So, I’ve created a new ASP.NET Core web app in Visual Studio, then I add the RavenDB.Client NuGet package.

Inside our StartUp.cs, I initialize our connection to Raven:

var raven = new DocumentStore
{
    Urls = new[] { "https://a.free.clistctrl.ravendb.cloud" },
    Database = "Outlaws",
    Certificate = new X509Certificate2("\path\to\free.clistctrl.client.certificate.pfx", "")
};
raven.Initialize();

That’s it! We can now store stuff in our database:

using (var session = raven.OpenSession())
{
    var outlaw = new Outlaw
    {
        Name = "Simmons, J.",
        IsGunslinger = true
    };
    session.Store(outlaw);
    session.SaveChanges();
}

Likewise, we can query for our objects easily:

using (var session = raven.OpenSession())
{
    var gunslingers = session.Query<Outlaw>().Where(o => o.IsGunslinger);
}

Saving and querying is a breeze – if you’re new to Raven, I encourage you to check out the awesome learning materials to help you get started.

One final note here: you can spin up multiple databases inside your RavenDB Cloud product. In this case, we’ve spun up a free instance and created a single Outlaws database inside it, but we can also can spin up other databases on this same free server as needed. Since the free tier supports 10GB disk space, we can spin up as many databases as can fit inside 10GB.

Spinning up a cluster in RavenDB Cloud

We just finished setting up a free instance in RavenDB Cloud, created a database, and connected to it, saved and queried some data.

All well and good.

But what happens when your database server goes down – does your app stop working? In our case, suppose AWS or Azure had a major outage, and our free instance goes offline. The result is that our app would stop working; it can’t reach the database.

RavenDB is, at its core, a distributed database: it’s designed to run multiple copies of your database in a cluster. A cluster is 3 or more nodes – database server instances – in which all the databases sync with each other. If one node goes down, the others still work, and your app will automatically switch to one of the online nodes. We call this transparent failover. When the node comes back online, all the changes that happened while it was offline get automatically synced to it.

A wonderful part of all this is you don’t have to do extra work to make this happen – you just setup your database as a cluster, and Raven takes care of the rest. The upside is your app is more resilient to failure: if one of your database nodes goes down, your app keeps working.

Let’s try that now using RavenDB Cloud.

We’ll go back to the RavenDB Cloud portal. We already have our CodeProjectFree product:

Let’s add a new product, we’ll call it CodeProjectCluster. I’ll click Add Product like before, but this time, we’re going to specify Production tier, which will setup our database in a 3 node cluster:

You’ll notice above we set Tier level to Production – this will setup our database in a cluster. We can tweak the CPU priority, cluster size, and storage size as needed; for this example we’ll leave these at the smallest sizes.

We’ll click next and set the instance names as before. Click finish, and we’re ready to roll: on our dashboard, we now see the cluster being created:

Notice that while our CodeProjectFree instance contains a single URL – there’s only 1 node – our new CodeProjectCluster contains 3 URLs, each one being a node in the cluster. The first node is node A, so its URL is a.cluster.clistctrl.ravendb.cloud, the second node is node B with a corresponding URL, and so on.

Once the cluster is finished creating, I’ll download and install the certificate as before:

Even though we have 3 nodes, we have a single certificate that will work for all 3 nodes. Once I’ve downloaded and installed it, I can click on any of the node URLs. Let’s try the 2nd node, Node B, which is at https://b.cluster.clistctrl.ravendb.cloud. That URL takes me to Raven Studio for Node B:

Let’s go ahead and create a new database on this node. As before, I’ll click Databases -> New Database, and we’ll call it OldWestHeroes:

Notice we now have a Replication factor of 3. This means our OldWestHeroes database will be replicated – copied and automatically synchronized – across all 3 nodes. Once we click Create, the database will be created and we’ll see it on the node:

But since we’re running in a cluster, this database will also automatically be created on the other nodes. Notice under the database name, we see Node B, Node C, and Node A; Raven Studio is telling us this database is up and ready on all our 3 nodes.

Click the Manage group button, and we can see a visual description of our cluster topology:

On the right, we can see all 3 nodes are all replicating to each other. (If any nodes were offline, we would see the node here as red with a broken connection.)

This visual tells us our database is working on all 3 nodes in our cluster. It also shows ongoing tasks, such as automatic backups, hanging off the nodes responsible for the task. You’ll notice that "Server Wide Backup" task is hanging off Node A – RavenDB Cloud creates this task for us automatically. Database backups are free for up to 1GB, and for $1/GB/month beyond that.

We’re looking at Node B right now, but since all 3 nodes in our cluster are up and running, we should see the database on any of the other nodes.

Let’s try it! I’ll go to Node A, over at https://a.cluster.clistctrl.ravendb.cloud. What do we see?

Yep! Our OldWestHeroes database has been automatically created on this node. And because these nodes are automatically synchronized, any changes we make to one node will show up automatically on the other nodes.

Let’s try that out too. Here on Node A, I’m going to click the OldWestHeroes database, then click New Document. I’ll create a new Cowboy document:

I’ll click save and our database now has a single Cowboy in it:

And because we’re in cluster, all the other nodes will now have this same document in it. Let’s head over to Node C, located at: https://c.cluster.clistctrl.ravendb.cloud:

Sure enough, our Cowboy document is there. I can edit this Cowboy and change his name, and of course those changes will be synced to all the other nodes.

How does that change our app code? Going back to our C# web app, does our code have to change?

Not much! The code is essentially the same as before, but instead of specifying a single URL, we specify the URLs of all the nodes in our cluster:

// Connect to our RavenDB Cloud cluster. 
// Notice the only thing that has changed is that we're passing 3 URLs in, one for each node in our cluster.
var raven = new DocumentStore
{
    Database = "OldWestHeroes",
    Urls = new[] 
    {
        "https://a.cluster.clistctrl.ravendb.cloud",
        "https://b.cluster.clistctrl.ravendb.cloud",
        "https://c.cluster.clistctrl.ravendb.cloud",
    },                
    Certificate = new X509Certificate2("\path\to\cluster.clistctrl.client.certificate.pfx", "")
};
raven.Initialize();

This one-time initialization code in our Startup.cs file is the only code that has to change. The rest of the app code doesn’t change; we can still write objects and query them as usual:

using (var session = raven.OpenSession())
{
    var cowboy = new Cowboy
    {
        Name = "Maunder, C.",
        FavoriteColor = "Orange"
    };
    session.Store(outlaw);
    session.SaveChanges();
}

Ditto for querying:

using (var session = raven.OpenSession())
{
    var cowboys = session.Query<Cowboy>().Where(c => c.FavoriteColor == "Orange");
}

The upside for our app is even if some of the nodes in our cluster goes down – say, for instance, if there’s an Azure outage – our app keeps working, transparently failing over to other nodes in the cluster. No extra code needed!

Summary

In this article, I’ve shown how to quickly spin up a free database in RavenDB Cloud. We showed how it’s secured with a certificate and how we can connect to it from a C# web app. It’s quick and easy and great for testing the waters.

We also looked at something more production-ready: spinning up a 3 node cluster in RavenDB Cloud. We looked at how databases in the cluster are automatically synced with all the nodes. Any changes in one node are automatically and quickly replicated to the other nodes. We also looked at the minimal (2 additional lines) code required to change our web app from our free single-node instance to our 3 node cluster.

Apps running against a cluster are more resilient in the face of failure: your app keeps running even if some of the nodes go down. Raven allows reading and writing to any of the nodes of the cluster, keeping your app running in the face of hardware failure or network issues.

RavenDB Cloud lets you spin up a single RavenDB instance or full production cluster quickly and easily in the cloud. I hope this article has helped you understand what it is and why you’d use it, and I hope you’ll give it try today: cloud.ravendb.net