Raven DB

RavenDB Tutorial, Part 1 - Introduction and Basic Operations

When starting new project we (at least lots of my collegues do) tend to automatically think about SQL whilst picking data backend for our application. Or to be honest - we sometimes skip the thinking part, picking SQL is a reflex. If you only know how to use a hammer, then everything looks like a nail. And then solving any problem automatically means hitting things hard with it (the hammer, not the nail). Credit should go where the credit’s due and I think one of the benefits of the Ruby/Rails bloom is wider popularity of so-called “No-SQL” databases. In R/R world the two most commonly heard names are: MongoDB and CouchDB. If you’re in doubt what these are - before we get to the subject - enjoy the movie How No-SQL databases are web-scale.

Now, that you know everything about things that make No-SQL databases a cool kid on the block, let me take you on the tour of RavenDB - .NET response to No-SQL movement, brought by one and only @ayende. Without further delay - here we go:

There are four distinct ways in which you may configure RavenDB to run, all of them begin with downloading Raven binaries (or sources and compiling them yourself). From here you can run RavenDB as a:

1. Service. You can install Raven service under Windows using command ‘Raven.Server.exe /install’ and configure it like any other Service on Windows. Of course later on it can also be uninstalled (Raven.Server.exe /uninstall). For me this is a preferred way of running Raven when I’m developing on my machine (and hosting production version of the application too). It’s easy, you don’t need to do anything else when working on a new project, it doesn't use much memory - most of the time circa 30MB 
2. IIS hosted Web Site with detailed instructions here
3. Embedded (it will run similarity to .exe mode - but it will automatically start when you start running your application and do something programmatically to RavenDB instance.) 
4. Embedded In Memory - In this mode RavenDB never stores files on your disk, all documents, indexes, etc are created in memory. I personally use it for integration testing, 

Side note for the code: There are many, many things you need to take into account when writing your code, even if it seems like it should be a very simple one. For example - initialization of RavenDB in the code can be as simple as two short lines of code (of course, in c# you can make your whole program to fit in one line, I’m saying about a case where programmer is more or less reasonable), however - question remains where this code should be contained. For simple command-line application - this could be in default Program.cs file, in Main() method, but when considering the topic in the context of e.g. ASP MVC 3 - things quickly tend to get a little more complicated (not because of MVC itself).

For example:

DocumentStore should be used as singleton, however - how you will make sure that it indeed is, is a different story. You could use DI framework, implement your own Singleton and make DocumentStore implementation accessible via property on the instance of the singleton. You could make it public static property on e.g. MvcApplication class (default name for the new ASP MVC application), you could do hundreds of other things to make it happen, some of them not bad, some good, some just horrible.

I’ve mentioned Singleton pattern - but this however is an issue on its own because a proper singleton implementation is a pretty tricky challenge, Jon Skeet has written up a pretty extensive explanation why - I strongly encourage you to read it Implementing Singleton in c#.

When accessing data you need to decide whether in the context of your ASP .NET MVC 3 application it makes any sense to implement some kind of repository, or whether you’re going to use RavenDB’s session directly in your controllers. People tend to have pretty strongly formed opinions, with most of them gravitating towards having some kind of repository, however, Ayende (RavenDB’s project leader and owner of the company which released RavenDB) tends to consider everything in context, and for small application he uses IDocumentSession directly, skipping the repository.

You also need to make IDocumentSession (representing unit of work in RavenDB) available in your classess and it would probably make sense to avoid code duplication when making it happen. No matter if you pick using IDocumentSession directly in your controllers, or hidden from the controller, inside of your implementation of repository, you need to make that decision, implement it, and live with it and maintain it.

Now that we’ve cleared some basic aspects up, let’s take a look at some code. Before we are able to do any CRUD on the db, it needs to be initialized. Initialization, when you’re using RavenDB hosted as a Service or IIS Web Site can be done with the following code:

DocumentStore initialization for RavenDB standalone

IDocumentStore store = new DocumentStore { ConnectionStringName = "http://localhost:8080" }; store.Initialize(); 
and this is how you it’s done when you want to initialize embedded, in-memory version:
IDocumentStore store = new EmbeddableDocumentStore { RunInMemory = true }; store.Initialize();

Storing simple entities inside RavenDB is done using Raven’s Client API and is really straightforward. Let’s assume you have a following type,

public class Location { public string Id { get; set; } public string Name { get; set; } public string Description { get; set; } public decimal Latitude { get; set; } public decimal Longitude { get; set; } }

and then somewhere in the code you create and initialize your entity with following code:

var location = new Location { Name = "Wawel castle", Description = "The most amazing castle in the whole world", Latitude = 50.05386m, Longitude = 19.9353m };

persisting it in RavenDB is dead-simple:
using (IDocumentSession session = store.OpenSession()) { session.Store(location); session.SaveChanges(); }

What has been persisted once, now needs to be fetched. This is how we can get our precious Wawel back from Raven:

using (IDocumentSession session = store.OpenSession()) { var wawel = session.Load<Location>("locations/1"); }

Need to update? It’s quite simple and similar to what we’ve just done in previous step

using (IDocumentSession session = store.OpenSession()) { var wawel = session.Load<Location>("locations/1"); wawel.Description = "changed description"; session.SaveChanges(); }


Something went wrong? Seek and destroy. In one step
using (IDocumentSession session = store.OpenSession()) { var wawel = session.Load<Location>("locations/1"); session.Delete(wawel); session.SaveChanges(); }

We’ve barely scratched the surface here, but this should be enough to get you started. RavenDB can be downloaded from RavenDB or installed (and previously automaticaly downloaded) via NuGet (.NET assemblies package manager). In the next post I’ll take you through some more advanced usages (mostly indexing and querying) and in the post after that one we’ll take a peek into the source code of one of the serious projects based on RavenDB to find the most interesting usage patterns.

Reference:http://www.geekbeing.com