Starting out with RavenDB

I’m just starting to try out RavenDB, so thought I’d write a quick post highlighting basic CRUD operations using it.

RavenDB can be run as both a server or locally as an embedded datastore. For these examples we’ll use the server run via the command prompt. At the end of the post I will demonstrate what’s needed to get the Embeddable version up and running.

Let’s get the server and get an instance of RavenDB up and running

  • Download the current release of RavenDB from here
  • I downloaded the zip – so either unzip then go to the RavenDB\Server folder or find this folder where the installation place the RavenDB app.
  • Run Raven.Server.exe from the Server folder. If all went well you should have an instance of the RavenDB server running, to check this, from your preferred browser navigate to http://http://localhost:8080/ and you should see the RavenDB studio
  • From the studio create a new database, for simplicity I named mine Test1

Creating a client

Before we get into the actual CRUD operations, let’s get a project up with the pre-requisites for the code to follow

  • Run Visual Studio and create a new console application
  • Using NuGet install the RavenDB Client package
  • Let’s create a simple Person object to store, here’s mine
    public enum Gender
    {
       Male,
       Female
    }
    
    public class Person
    {
       public string FirstName { get; set; }
       public string LastName { get; set; }
       public DateTime DateOfBirth { get; set; }
       public Gender Gender { get; set; } 
    }
    

Let’s create some data in our new database

Now let’s access the store and save a new Person object, something like this

var documentStore = new DocumentStore 
{ 
   Url = "http://localhost:8080/", 
   DefaultDatabase = "Test1"
};
documentStore.Initialize();

using (var session = documentStore.OpenSession())
{
   Person person = new Person
   {
      FirstName = "Scooby",
      LastName = "Doo",
      DateOfBirth = new DateTime(1969, 9, 13),
      Gender = Gender.Male
   };

   session.Store(person);
   session.SaveChanges();
}

Now if we look at the RavenDB studio and the Test1 database we should see two documents, one system document and a “People” document.

Time to retrieve an object from the database

Now let’s see how we get the object. Raven stored an Id “people/1” with my data, so we’ll use that key to get that document.

var documentStore = new DocumentStore 
{ 
   Url = "http://localhost:8080/", 
   DefaultDatabase = "Test1"
};
documentStore.Initialize();

using (var session = documentStore.OpenSession())
{
   Person person = session.Load<Person>("people/1");
   // do something with the person instance
}

Updating a document

To update a document we simply load the document, make the changes then save if, for example

var documentStore = new DocumentStore 
{ 
   Url = "http://localhost:8080/", 
   DefaultDatabase = "Test1"
};
documentStore.Initialize();

using (var session = documentStore.OpenSession())
{
   Person person = session.Load<Person>("people/1");
   person.DateOfBirth = new DateTime(1996, 9, 13);
   session.SaveChanges();
}

You’ll have noticed that key’s are automatically generated, if our Person object included an Id property, such as

public class Person
{
   public string Id { get; set; }
   /// other properties
}

then Raven will automatically fill in this field when you first save an object, with the id it assigned. Alternatively you can give you own Id for an object and this will become the Id within RavenDB also, i.e. you’re assigning your own id’s at this point.

Deleting a document

So we’ve created a document, retrieved it and updated it, so now it’s time to delete a document.

using (var session = documentStore.OpenSession())
{
   Person person = session.Load<Person>("123");
   session.Delete(person);
   session.SaveChanges();
}

In the above we’re deleting using an instance of an object but it might be we’ve not loaded the object and want to simply delete using the id, in which case can can do the following

using (var session = documentStore.OpenSession())
{
   session.Advanced.DocumentStore.DatabaseCommands.Delete("123", null);
   session.SaveChanges();
}

RavenDB as an embeddable datastore

The only changes we need from the server based code (shown above) is that we no longer use the DocumentStore object but instead use the EmbeddableDocumentStore, so let’s look at this and how we get it up and running in a client.

  • RavenDB Embedded 2.5.2916 shows the package we need to install from NuGet to use the EmbeddableDocumentStore however I was getting the error “Install-Package : Updating ‘System.Spatial 5.2.0’ to ‘System.Spatial 5.0.2’ failed. Unable to find a version of ‘RavenDB.Database’ that is compatible with ‘System.Spatial 5.0.
    2’.”. Instead use Install-Package RavenDB.Embedded -DependencyVersion Highest from the Package Manager Console.

So as mentioned, to use the embeddable version of RavenDB we use the EmbeddableDocumentStore object, thus

var documentStore = new EmbeddableDocumentStore
{
   DataDirectory = "Data"
};
documentStore.Initialize();

// everything else as per the DocumentStore code from earlier

The DataDirectory is the location of your local datastore, this case the folder Data will be created off of the directory you application is run from.