Hibernating Rhinos

Zero friction databases

RavenDB in practice, Part 1 - An Introduction To RavenDB

Recently I started to learn how to use RavenDB. I never used RavenDB or any other document database before, and when I was thinking on a database it was mainly on the relational form of it. What this means is that for me, a database must have tables, rows and columns in order to be considered as something that I want to use. Well, now that I see what RavenDB can give me, I think that this is all going to change.

As I’m currently learning how to use RavenDB, I’m going to write a series of blog posts that will demonstrate how to use RavenDB without any prior knowledge of it required. This will be an “in practice” demonstration, which means that I’m going to demonstrate how to use RavenDB in practice rather than talk on the ideas that behind it.

Why would I want to use a Document Database?

Using a document database like RavenDB will give you the following benefits:

  • Better performance in your application
  • Faster development time
  • Better maintenance experience

If you want to see more information of those benefits, take a look in the RavenDB documentation.

What is a document database and what is RavenDB?

RavenDB is a document database, which stores each document in JSON format. In a document database any entity can be stored as a document. You don’t have to define in advance the schema of your data in order to store it, all you have to do is to give RavenDB an object and RavenDB will store it. Later in this post, I’ll show you what does a document looks like.

Start using RavenDB

Let’s start to see how to use RavenDB. Go to RavenDB website (http://ravendb.net/download) and download RavenDB. After extracting the .zip file to a folder, you’ll see the following folder structure:


This folder contains both the RavenDB database server and the client’s API binaries. We’ll start with the server first, then I’m going to show you how to manage this server from RavenDB management studio.

You can start RavenDB by simply double clicking on the Start.cmd file.

You have 4 options how to run the server:

  1. A console application that runs on your computer and listen to incoming HTTP requests. In order to use this option, just run the Raven.Server.exe from the Server folder or double click the Start.cmd script from the root directory. This is mostly suitable for debugging and experimentation.
  2. As a Windows Service, which you can install by executing “Raven.Server.exe /install” command.
  3. An IIS website that have the files under the Web directory in the root folder of the website. This option seems to be more suitable for production.
  4. You can run RavenDB in an embedded mode, which will run the database inside your client application process.

In this post we’re going to run the server using the first option. In the RavenDB folder, double click the Start.cmd script. After you have done this, you’ll see this output in the console application:


That is it. The server is running and ready to process any requests. As you can see, in this case the server is listening on port 8080, which is the default port.

You also see here the path of the Data Directory. This is the directory where RavenDB stores your data. If you lose this directory you’ll lose your data. (We’ll talk on backup plans in later blog posts). On the other end, if you close the server, delete this folder and then re-run the server again, you get an empty server. This is great for my case that I want to test things out and then revert back to the beginning.

After that the server is running, we can start to use RavenDB management studio which will let you to manage a various aspects of the database. The Start.cmd script has already done that for us, and you can see the RavenDB Management Studio open inside your browser. The Management Studio is a Silverlight application which you can start using it by browsing the URL that RavenDB is listed to. In our case, the server is listening on port 8080, so we can access it from the following URL:  http://localhost:8080. This is how the Management Studio looks like when you look on a freshly installed database:


As you can see, all we got right now is a default database that was automatically created for us without any data in it. The screen says: There are no documents and no collections yet. You may be wondering what is a document and what is a collection but the first thing that we’re going to touch is what a database is.

In the top-left of the screen there is a back button and a home button. Click on the home button and you’ll see the following screen:


In this screen you can create a new database by clicking on the Create New Database button, or navigate to an existing database by choosing the name of the database from the left list of databases.

For now we’re going to make a use of the default database, so click on “use this database” and the screen will navigate to the database main screen. You can also get to the database screen by clicking on the Back button as this was our previous screen.

Currently we have an empty database. In order to see how the data is look in the document database, you can click on the “Create sample data” button which will generate a sample data for you. When I clicked on the “Create sample data” button I got the following screen:


Be default RavenDB allow anonymous access only for read requests (HTTP GET), and since we creating data, we need to specify a username and password. You can control this by changing the AnonymousAccess setting in the server configuration file.

Enter your username and password of your Windows account and a sample data will be generated for you. This how the database screen looks like now:


As you can see, the sample data contains: 256 documents, 2 collections and 6 indexes. You may be wondering what those things are, so I’m going to start explain them one by one. (I’ll explain what is index in later blog post).

What is a document?

A document is any JSON object. Compared to a relational database, you can think on a document as a row in a table. But unlike a row in relational database, a document contains the entire graph of your object (entity).

Let’s click on the documents item in the left sidebar menu in order to see all the documents that we have right now:


Let’s double-click on one of the documents, and see what a document is:


As you can see a document contains a key, data and metadata. The data is your entire object represented in JOSN. In addition to that each document has a document key which is in this case “albums/410”. You can think of the document key as the primary key in a relational database. Each document contains also some metadata that is automatically generated for us by the client API. The “Raven-Clr-Type” metadata represents the .Net object type that this document is mapped to.

What is a collection?

A collection is list of documents with the same Raven-Entity-Name metadata value. You can think on a collection as a list of documents with the same type. In our example we have two types of documents which are represented by two collections: Albums and Genres.



In this blog post I showed you how to run RavenDB server as a console application. Then, we looked on the server with the RavenDB management studio. We created a sample application, and I explained what a document is and what a collection is.

My roadmap for the next blog posts:

  • Take an existing data and import it to RavenDB.
  • Show how to model the entities in a way that fits more a document database.
  • Build a client application that will make a use of this data.

Any feedback / suggestion will be appreciated.

Posted By: Fitzchak Yitzchaki


04/10/2011 12:20 PM by

I've bee meaning to check out raven DB and I couldn't have asked for a better brief introduction than this.

Really looking forward to the rest of this series. And hopefully I'll start getting more involved with Raven DB.

Martin F
04/14/2011 12:31 AM by
Martin F

If you store meta data about the CLR type, what happens if I decide to refator my application and change the Models namespace or the name of my Model ?

Fitzchak Yitzchaki
04/14/2011 06:52 AM by
Fitzchak Yitzchaki


RavenDB will figure it out and will update itself accordingly. I'll demonstrate the process of refactoring entities in a future blog post.

Henning Kilset
04/17/2011 07:46 PM by
Henning Kilset

Good, short intro to RavenDB. I too am looking to get started with it, but have been clamoring for some tutorial articles. Please keep this up :)

11/18/2011 06:31 AM by

Short nice informative tutorial!!

Michael Dylphe@Window Tinting
03/20/2012 09:42 AM by
Michael Dylphe@Window Tinting

Interesting, this is my first time hearing about RavenDB. I have never use it before. I usually use SQLExpress and MySQL, mostly SQLExpress.

I see is is completely different from relational database, looks more like a file based database, so I can't compare both of them. But how reliable is it? Is the implementation easy enough? I heard a lot negatives using file based database. Correct me if I'm wrong.

Tim James
07/02/2012 03:48 PM by
Tim James

Thanks for this post Fitzchak.

For someone starting to look into using RavenDB, this is a great place to look for info.

Comments have been closed on this topic.