RavenDB 2.x Beginner's Guide

4 (1 reviews total)
By Khaled Tannir
    What do you get with a Packt Subscription?

  • Instant access to this title and 7,500+ eBooks & Videos
  • Constantly updated with 100+ new titles each month
  • Breadth and depth in over 1,000+ technologies
  1. Getting Started with RavenDB

About this book

RavenDB is a second generation document database written in .NET, offering a flexible data model designed to address requirements coming from real-world systems. It is different from the other document databases around, as with RavenDB you can get up and running in a few minutes, and that includes grasping all the basics. It allows you to build high-performance, low-latency applications with ease and efficiency.

RavenDB 2.x Beginner’s Guide introduces RavenDB concepts and teaches you everything, right from installing RavenDB, to creating documents, and querying indexes. This book will help you take advantage of powerful, document-oriented NoSQL databases and build a solid foundation on which you can create your .NET applications.

This book presents RavenDB, the .NET document-oriented NoSQL database, through a series of clear and practical exercises that will help you to take advantage of this database server.

The book starts off with an introduction to RavenDB and its Management Studio. You will then move ahead and learn how to quickly and efficiently build high performance, NoSQL document-oriented .NET applications using the .NET client API or the HTTP REST API. Next, Dynamic and static indexes that use map/reduce to process datasets are covered. You will then see how to create and query these indexes, with the help of detailed examples. You will also learn how to deploy your RavenDB server in a production environment and how to optimize and secure it.

With numerous practical examples, RavenDB 2.x Beginner's Guide teaches you everything you need to know for building high performance .NET document-oriented NoSQL databases.

Publication date:
September 2013


Chapter 1. Getting Started with RavenDB

In this chapter, you will learn about RavenDB database server which is a document-oriented database and belongs to the NoSQL database family. RavenDB is an open source software and it does not use SQL language to manipulate data, but it stores what we call "Documents".

You will start by learning briefly the basics of NoSQL databases, to be familiar with its concepts, and then you will learn about document-oriented databases and the JSON format (JavaScript Object Notation). Before you can start working with RavenDB, we have to set up an environment with system requirements, where you can test and play around with, to get familiar with RavenDB. Then you will go forward by learning how to launch RavenDB and its embedded management tool the RavenDB Management Studio and understanding the basic configuration file application key settings.

Once RavenDB is installed and running, you will learn to open the Management Studio to access the database and create some sample data. Then we will move forward and learn how to shut down the RavenDB server in the Console mode.

In this chapter we will cover:

  • Basics of NoSQL databases

  • What is RavenDB and how it works

  • RavenDB documents and JSON format

  • Downloading and installing RavenDB

  • Configuring RavenDB

  • Running RavenDB in the Console mode


Understanding the basics of NoSQL Databases

What is NoSQL? What makes NoSQL different from a relational database and why do we need it? These are some questions that we attempt to answer in a few lines.

NoSQL is a term used when talking about non-traditional databases. It is a very wild term. It basically defines a database that uses other Data Manipulation Language (DML) than SQL. This is why NoSQL is literally a combination of two words: No and SQL and it means "Not only SQL".

We use SQL when we want to manipulate data and access relational database servers such as Oracle, MySQL, Microsoft SQL Server, and all other relational databases. NoSQL Databases are not relational and they don't use the Codd's model.


E.F. Codd was a famous mathematician who introduced 12 rules for the relational model for databases commonly known as Codd's rules. The rules mainly define what is required for a DBMS for it to be considered relational. For more information about Codd's model follow this link: http://fr.wikipedia.org/wiki/Edgar_Frank_Codd.

In a relational database, we can have a table and in this table an ID column which is used as a foreign key in another table. NoSQL Database does not have relational enforcement and it does not use SQL language to interact with stored data.

A NoSQL System aims to be easy to scale out. Scalability is the ability of a system to change its size while maintaining proportions and this usually means to increase throughput with addition of resources to address load increases. The problem with Relational Database Management System (RDBMS) isn't that they don't scale, it's that it becomes cost prohibitive to scale vertically, versus scaling horizontally. Vertical scaling means that you scale by adding more power (CPU, RAM, Hard disk space) to your existing machine, while horizontal scaling means that you scale by adding more machines into your pool of resources.


A good example for horizontal scaling is Cassandra, MongoDB, and RavenDB. A good example for vertical scaling is MySQL – Amazon RDS (the cloud version of MySQL) which provides an easy way to scale vertically by switching from smaller to bigger machines, but this process often involves downtime.

Typical RDBMS makes strong guaranties about consistency. This requires to some extended communication between nodes for every transaction. This limits the ability to scale out because more nodes mean more communication.


In general, NoSQL Systems are open source, freely available on the Internet, and their use is increasingly gaining momentum in consumer and enterprise applications.

Types of NoSQL Databases

NoSQL itself is a very large concept and it involves a large number of technologies. In this section, we will introduce the different types of NoSQL but we will focus only on the RavenDB NoSQL Database type, the document-oriented database. The concepts we are introducing here apply on RavenDB and some other NoSQL Databases but not all NoSQL Database types.

Currently, the NoSQL databases types can be categorized in more than ten types. But we will only focus on the four major different types:

  • key-value databases: A key-value database has a key and a corresponding value together as dataset. In key-value models, the key has to be unique and the value is associated with that key. Values can be of different types such as strings, integers, floats, or byte arrays. Some databases do not even care about the data type of the value, they just store what you feed. These inputs are called blobs, meaning an arbitrary binary object, which the database does not need to interpret. It is a very simple kind of database; it is operating as a dictionary. Examples of key-value NoSQL Databases are Amazon Dynamo, Redis.

  • column-oriented databases: The basic idea behind column-oriented databases is that the data is not a dataset with its attributes stored in one unit as in SQL databases (row oriented) but one attribute of a set of datasets is stored in one unit (column oriented). From the simplicity of the columnar approach may accrue many benefits, especially for those seeking a high-performance environment to meet the growing needs of extremely large analytic databases. Google's BigTable, Cassandra, HBase, Hypertable are examples of column-oriented NoSQL Databases.

  • graph-oriented databases: The graph-oriented databases originated from the graph theory, where you have vertices (singular: vertex) and edges connecting the vertices. In databases, vertices are entities like persons and edges are relations between entities. These relations are similar to the relations in Relational Database Management Systems. Twitter uses FlockDB the graph-oriented database, Facebook and LinkedIn use also a graph-oriented NoSQL database.

  • document-oriented databases: The document-oriented databases use entire documents of different types as datasets. The document types are structured human readable data format such as XML or JSON. Document-oriented databases can be interpreted as particular cases of a key-value database. The database knows the format of document and it interprets it. This is the biggest difference to key-value storage. Therefore, in a document database, it is also the server itself that can operate with the document and not just the client. Ergo, it is also possible to directly work with the data in the document on the server side. Document store databases are schema free. In a schema free database you do not have to predefine what your documents looks like. For the storage this does not seem to be a problem, because the documents do not depend on each other. When the documents have some kind of structure or schema it is called semi-structured. Other examples of document-oriented databases are CouchDB, MongoDB, and obviously RavenDB.

RavenDB is a NoSQL document store database. In the context of RavenDB or a document-oriented database, you can think of a document as a web page with a hierarchical nested structure and all this data can be retrieved and fetched in one time. A document store can have a key and then it will have a document associated with that key.


The NoSQL Databases website (http://www.nosql-database.org/) currently lists more than 150 databases.


What is RavenDB?

RavenDB is an open source document-oriented NoSQL designed especially for the .NET/Windows platform. It requires commercial licensing (with a special pricing available for BizSpark startup organizations). A free edition is available for open source projects, but it must be applied for.

RavenDB supports multiple databases and, as other database servers, a database acts as a container of data. RavenDB can easily handle hundreds or thousands of databases on the same instance and was explicitly designed with multi-tenancy (or multi-instances) in mind. This allows RavenDB to manage large numbers of databases, but at any given time, only one database is active and taking resources.

Each RavenDB database contains a set of documents which can be divided into collections. A Collection is a logical way of thinking of document groups. Within a Collection, documents share the same entity name.


RavenDB's collections are very similar to MongoDB's collections which is another document-oriented NoSQL database.

A Document is a unit of data and it contains a set of fields or key-value pairs. It is important to note that values can be arrays, complex types, or even arrays of complex types. The keys are strings; the values can be of various types such as strings, integers, and so on. You can even store a document as the value of a field.

RavenDB database contains Indexes which works differently than RDBMS indexes. RavenDB uses indexes to satisfy queries. You may index the whole query's field or specify the fields you want to index in a document. RavenDB takes the query, analyses it and extracts an index which can answer the query. Also, it has the ability to auto generate indexes from your queries.

RavenDB uses JSON (JavaScript Object Notation) to store documents. JSON is a way to serialize data and is a lightweight data-interchange format. On the client side, this is used primarily by RavenDB and then data is serialized to .NET objects. But on the server side that data is all JSON, all the time.

RavenDB does not have a schema (schema-less) and documents do not have to have a specific field or column. Also, there are no explicit relations among the documents that exist in RavenDB. We might have some Document when we build a store Document and maybe we want to use a Document to lookup in other Document, this relation is only in data and not enforced by the database.


RavenDB is a document-oriented database and is not relational. That means it doesn't maintain foreign key constraints.

RavenDB is fully transactional. That means, it fully supports both implicit and explicit transactions and we can take full advantage of this feature. Unlike most NoSQL databases that adhere to the BASE properties, RavenDB supports the ACID properties for write operations. ACID, as we all know, stands for Atomicity, Consistency, Isolation, and Durability, and support for ACID is what makes us so comfortable using RDBMS systems with respect to data integrity. BASE, on the other hand, stands for Basically Available, Soft state, Eventual consistency.

RavenDB stores Indexes data and allows storing large data files through using attachments. Attachments are a large chunk of data (BLOBsBinary Large OBjects) that are used to store images, music files, videos, and other kind of binary data. Attachments in RavenDB can have metadata and can be replicated between nodes. Also, it can be cascade deleted on document deletions (which requires the CascadeDelete bundle called Raven.Bundles.CascadeDelete to be activated) and are HTTP cacheable.


RavenDB Indexes look like a LINQ query, but they aren't. They are used to build an Index that you can then use just such as in RDBMS.


From relational databases to RavenDB

Developers and database administrators with a background on working with relational database systems will quickly recognize the similarities between the logical abstractions of the relational data model and the RavenDB data model. The next figure gives a quick view of a relational data model and their equivalent with those of the RavenDB data model:


A Document in RavenDB will typically contain data from multiple tables in a Relational Database Management System (RDBMS).

When you work with RavenDB, you need to consider that RavenDB is non-relational. The reason is that RavenDB treats each document as an independent entity. There are no foreign keys in a collection and as a result, there are no JOIN queries. Constraint management is typically handled in the application layer. Also, because of its flexible schema property, there is no need for the expensive ALTER TABLE statement in RavenDB and you can have user defined content much more easily.

RavenDB is able to store large amounts of data and also is able to optimize the way documents are stored and managed. It supports Horizontal scaling and each document can be stored on any node of the horizontal resource pool (this is called sharding).


Why RavenDB?

Let's move forward and take a look at the basics of RavenDB, why it is different, and why the new approach has made everybody excited about using RavenDB. Looking back at the NoSQL databases history, most of them have started as ways to address problems that people have with the relational databases. RavenDB was produced out of the needs and necessities of a better environment. Developers are becoming more savvy every year, with better environments, better tools, and simpler and more straightforward methods for achieving a range of goals.

The benefits of NoSQL solutions depend on use cases. When considering a NoSQL solution, users must choose the appropriate database management system that best suits their applications. An appropriate choice brings best performance or decrease a costs.

Why does RavenDB make managing document-oriented data easier? Here are the main advantages of adopting RavenDB:

  • RavenDB is written in C#, .NET, and it is easy to learn how to use it. This is a real advantage. Data can be queried efficiently using LINQ queries from .NET code or using RESTful (REpresentational State Transfer) APIs.

  • In RavenDB, the database schema is no longer fixed, data is stored schema-less as the JSON documents, so the documents can have arbitrary structures and attributes associated with them. Internally, RavenDB makes use of Indexes which are automatically created based on your usage, or were created explicitly by the consumer.

  • RavenDB is highly scalable and is built for web-scale. It offers replication and sharding support out-of-the-box.

  • RavenDB is fully transactional with the ACID support.

You can use RavenDB in many cases and it is the perfect choice. For example, RavenDB can be used to archive a huge number of documents, it can be used as a content management database, to store orders, inventory, and suppliers in an e-commerce solution. For some reason, there are a lot of real estate/rental people using RavenDB.

But the case that we don't recommend using RavenDB for is reporting. This is because in many cases, reporting requires dynamic data aggregation over large dataset, and that isn't an OLTP (Online Transaction Processing) task, which is what RavenDB was designed for. For reporting, we recommend just throwing that data into a reporting warehouse database (either star schema or a cube) and doing the reporting directly from there.


With the RavenDB SQL Replication bundle, you can replicate to an Microsoft SQL Server and do the reporting from there very easily.


How RavenDB works?

When you are using RavenDB, basically you have a client application that communicates with a database server. The client application will communicate with RavenDB database server over HTTP. It will look like any web service and REST (REpresentational State Transfer) based web service. REST is an architecture that uses the strengths of the web to build services. It proposes a set of constraints that simplifies development and encourages more scalable designs. In REST, resources are identified by a unique URI (Unique Resource Identifier).Client applications interact with resources using four main HTTP verbs.

The following figure illustrates basics of RavenDB client/server application architecture:


In the RavenDB architecture model, the data is communicated across the network in JSON format from the server to the client.

RavenDB can be launched in different modes. It can be launched in:

  • Console mode: This mode is good for learning and testing.

  • Hosted by IIS (Internet Information Server): This is probably the most common scenario to run RavenDB in a production environment.

  • As a Windows Service: RavenDB will create its own HTTP server and process all requests internally.

  • Embedded mode: In this mode, RavenDB will be embedded in your application and may run completely in memory.

Also, RavenDB comes with built-in authentication functionality and it supports two types of authentication:

  • Windows authentication: This authentication method is chosen when a request needs to be authenticated and no other authentication method is detected.

  • OAuth authentication: OAuth is an open authorization framework that enables application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the application to obtain access on its own behalf.

As stated, the RavenDB databases were designed with multi-databases support. In order to do that, RavenDB will only keep one database open, the active database. When accessing a database for the first time, that database will be opened and started, so the next request to that database wouldn't have to be opened again, which is good for performances. But if a database hasn't been accessed for a while, RavenDB will clean up all resources associated with the database and close it.


Anatomy of a Document

In RavenDB, data is stored as Documents and must be serialized from the native .NET objects to the JSON format before being sent to RavenDB database engine, they are later deserialized from JSON, and then to native .NET objects.

The flexible document-based structure reduces the need to worry about the structure of the data, either before or during the application development. You do still have to think about the structure of data in terms of identifying natural transactional boundaries (which in this case is the Document).

This helps in mapping the data and allow querying, combining, and filtering the information. Replication is also easy-to-use so you can copy, share, and synchronize your data between databases, machines, and even continents.

In a typical database, we store different related pieces of data. We might have an object and we might model this object using multiple objects. Take the example of a desktop computer in a company with different softwares installed by a user. We want to keep track of all these installed softwares. By modeling the Computer entity and its related Inventory, we will have a tree of related objects. Usually, in traditional RDBMS, we will store each one object as a part of the data tree in a table in the database and relate them together.

In a Document type database we skip the task of splitting the model in smaller entities and the entire structure will remain as a one single object. This object is stored in the database using a single REST verb (POST or PUT) and there is no need to split the object, or separate its data into primary entities. When we want to retrieve the object, we retrieve it entirely and we do not care where the data went or how to join it from different entities or documents.

Document-oriented databases are not limited to just storing keys and values. Instead, you can store complex object graphs as a single document. In a relational database, a row can only contain simple values and more complex data structures need to be stored as relations. In RavenDB, a Document can handle complex structure and we can store all the data that we need to work with as a single document.


To enhance the overall performance of your system, it is a good practice to include all of the information you need in a single document when using RavenDB and you are encouraged to do so.

At a collection level, this allows for putting together a diverse set of documents into a single collection. Document databases allow indexing of documents on the basis of not only its primary identifier but also its properties.


Do not confuse "Document-oriented databases" and "Document Management Systems". The Document-oriented databases connotes loosely structured sets of key-value pairs in documents and a Document Management System is a computer system used to track and store documents.

Each RavenDB document contains data (other than yours) that describes other data (metadata), which aren't a direct part of the document. Metadata provides information about the CLR-type, the entity-name, the last-modified date, and so on. These metadata are attached to the document and are being used internally; but they can be exposed to your code.


The JSON format

JSON, short for JavaScript Object Notation, is a generic text format easy for humans to read and write and it's easy for machines to parse it and generate it. This format is used by RavenDB to store data and databases' metadata. RavenDB can write the JSON document directly, simplifying the writing/updating process. It is important to know that the JSON format may "denormalize" data. We might be storing the same class object multiple times in the database but that is not a problem because we are storing the entire document and we retrieve it as a document and not as a piece of data.

The JSON format is built on two structures:

  • A collection of name/value pairs. Programming languages support this data structure in different names such as object, record, struct, dictionary, hash table, keyed list, or associative array.

  • An ordered list of values. In various programming languages, this is realized as an array, vector, list, or sequence.

The following screenshot illustrates a Document entity as it will be stored in RavenDB using JSON format:

In this JSON example which describes the Computer entity, the object begins with { (left brace) and ends with } (right brace). Each name is followed by : (colon) and the name/value pairs are separated by , (comma). So, the "CompuerID" entity represents the key name and "12345" represents the value assigned to that key name.

The "Inventory" key name is an array and is an ordered collection of values. In JSON, an array begins with [ (left bracket) and ends with ] (right bracket). Values are separated by , (comma). In this example, the "Inventory" array contains two object instances where each one is composed of three name/value pairs "SoftawareName", "SoftwareVersion", and "InstallDate".


You can learn more about JSON structures at: http://www.json.org/.


Downloading and installing RavenDB

We are done with the theoretical part, at least for now. It is important to get familiar with all these concepts to take advantage of using RavenDB. It is time for us to download, install, and start using RavenDB on the computer.

What do you need to run RavenDB?

Basically, the primary installation target of RavenDB is Microsoft Windows. The Microsoft's .NET Framework should also be installed on the computer where RavenDB will run and where the application client will run. The RavenDB package comes with different client versions. To run the lightweight RavenDB client on your computer, Microsoft's .NET 4.0 Framework Client Profile is required.


We recommend that the latest Microsoft's .NET Framework should be installed on the computer where RavenDB will run.

The RavenDB Management Studio is a Silverlight application and it needs Microsoft's Silverlight plugin to be installed on the web browser. The minimum Microsoft Silverlight version required to run Management Studio is Silverlight version 5.0 (the current version).


If your computer does not run Microsoft Windows operating system, you can still use some RavenDB features (at the time of writing) on a Linux or a Mac OS environment by installing the Mono framework which is a free open source implementation of Microsoft's .NET Framework. For more information about the Mono framework go to http://www.mono-project.com/Main_Page.

To run RavenDB server or RavenDB embedded, you need at least Microsoft's .NET Framework v 4.0 to be installed on a computer running on Microsoft Windows operating system. To run RavenDB server as a Microsoft Windows service or to host RavenDB by IIS (Internet Information Server), a Microsoft Windows operating system is required.


Time for action – downloading and installing RavenDB

We are going to learn how to download and install RavenDB on a computer running on Microsoft Windows, using the following steps:

  1. To download RavenDB, head to the download page on the RavenDB official website, http://ravendb.net/download.


    On the official website download page, we will find a couple of selections and different versions that can be downloaded. We can download the latest official release, the latest unstable release which is not recommended for use in a production environment.

  2. Click on the download link for the latest stable release under RavenDB's latest official release. This will start downloading a ZIP archive.


    At the time of writing, RavenDB v2.0.0 Build 2375 was the latest version. If a newer stable release is available, you should download that version instead.

  3. Once the download is finished, open this file up, and extract everything to C:\RavenDB-Build-2375 (which is the name of ZIP archive file at the time of writing).

  4. Open C:\RavenDB-Build-2375 and explore it. It should look like this:

What just happened?

In steps 1 and 2, we downloaded the ZIP archive containing the .NET assembly files for the RavenDB server.


As an alternative to the official RavenDB website, RavenDB is also available for download via the NuGet package manager: http://nuget.org/packages/RavenDB.Client.

The NuGet package manager is a Visual Studio extension that makes it easy to add, remove, and update libraries and tools in Visual Studio projects that use the .NET Framework.

You can also download the source code of RavenDB and some other bundles, which are additions to RavenDB to extend its features and functionalities.

In step 3, we extracted files from the ZIP archive file to C:\RavenDB-Build-2375.

In step 4, we explored the different files and folders of RavenDB.

We do not have to be concerned about all the folders extracted, there are different versions of a RavenDB client. You have the lightweight client compatible with the Microsoft's .NET 4.0 Framework Client Profile and the Embedded RavenDB Client that you can use if you want to embed RavenDB in your application. The extracted files folder contains some samples that can be useful to learn how to do different things in RavenDB especially more complex things such as Sharding.

The important directory that we will really worry about here is the Server directory. The Server directory contains the Raven.Server.exe file which is our main executable file that we will run to launch our database server.

Raven.Server.exe can be run directly from the Server directory or by using the Start.cmd file located at the root of our folder C:\RavenDB-Build-2375.


The latest RavenDB installation package includes these directories:

  • Client: A lightweight client for use with .NET 4.0

  • Silverlight: Silverlight 5.0 client

  • Silverlight-4: Silverlight 4.0 client

  • EmbeddedClient: The files necessary for using RavenDB in embedded mode

  • Server: The files required to use RavenDB in server mode

  • Web: The files required to use RavenDB under IIS

  • Bundles: The files for extending RavenDB in various ways

  • Samples: The sample RavenDB applications to get you started


Running RavenDB server in the Console mode

Running RavenDB in the Console mode is pretty good for learning and testing purposes and it is not suitable in a production environment. In production environment, RavenDB must be run as a Windows service or be hosted by IIS as a web application. This assumes that RavenDB will be more secure and will run faster.

Exploring the Start.cmd file

The RavenDB distribution package provides a command file, named Start.cmd, which you can use to launch RavenDB server in the Console mode. This file is located on the root of the package.


Time for action – exploring the Start.cmd file

We will open Start.cmd in the Notepad application to learn how RavenDB would be launched.

  1. In Windows Explorer, go to C:\RavenDB-Build-2375.

  2. Select the Start.cmd file and open it in the Notepad application. It should look like this:

What just happened?

In steps 1 and 2, we opened the Start.cmd file and took a look at its command line parameters.

The Raven.Server.exe file is launched with two parameters --debug and --browser. The debug parameter is used by developers for applications debugging purposes and the browser parameter is used to open the Management Studio in the web browser automatically.

Configuring the RavenDB server

Before launching the RavenDB server, you might need to configure it. We can do configuration by editing the Raven.server.exe.config file located in the Server directory. This is a text file and can be edited and modified with the Notepad application.

There are three key-values in the appSettings section. These keys settings that you can modify to meet your needs are:

  • Raven/Port: This setting represents the TCP/IP listening port

  • Raven/DataDir: This setting lets you define the directory where the data will be stored

  • Raven/AnonymousAccess: This setting defines the security level access which you can use to define which user can do which action on the server

Raven.Server.exe runs by default on port 8080. The Start.cmd file will run the Raven.Server.exe file with the command-line parameter –browser. This will automatically open the Management Studio in the web browser and point to this location: http://hostname:port/raven/studio.html.


A few points to be noted about default values:

  • The * value assigned to the Raven/Port indicates that RavenDB will find the first available port from 8080 and upward. By default, RavenDB server selects the 8080 TCP/IP port if it is not already in use. And once this is done that port is fixed.

  • The path for the database directory is defined by the Raven/DataDir key. The use of ~\ indicates to start from the RavenDB root directory, in which case the path will start from the server-based directory. The default value is: ~\Database\System.

  • The Raven/AnonymousAccess key by default is set to Get and it determines what actions an anonymous user can do. You can control the access level by setting this key to one of these values; Get for read only, All for read/write, and None allows access to authenticated users only.

Launching the RavenDB server in the Console mode

When RavenDB is launched in the console mode it will open a CMD prompt window which will stay open until the user has entered one of the four available commands:

  • cls: This command is used to clear the screen

  • reset: This command is used to reset the RavenDB server

  • gc: This command is used to initiate the garbage collection

  • q: This command is used to shut down the RavenDB server and terminate the CMD prompt window


Time for action – launching RavenDB in the Console mode

You have already downloaded the RavenDB package and extracted it to a local folder on your computer. Now you are ready to launch RavenDB in the Console mode. You will run the database server using the Start.cmd command file:

  1. In the Windows Explorer, select file C:\RavenDB-Build-2375\Start.cmd and press Enter or double-click on it to launch the RavenDB database server in the Console mode.


    While the Raven.Server.exe application is running, it logs any activity on the RavenDB server. In the Console mode, the log activity is displayed within the command prompt window.

  2. Click on the command prompt window to activate it and take a look at the RavenDB activity log.

What just happened?

We learned how to launch the RavenDB server.

In step 1, we launched the RavenDB server using the command file C:\RavenDB-Build-2261\Start.cmd.

In step 2, we activated the command prompt window and analyzed the RavenDB activity log.

Let's have a closer look at the activity log displayed within the launching process of RavenDB and analyze it.

The first log line indicates that the RavenDB server has been launched and it is ready to process requests. We can also see the RavenDB server's Build version, in our case it is Version 2.0.3 with 2375 as the Build number. If you have downloaded a newer version of RavenDB, you might have another version number and/or another Build version number.

The second line of the server activity log displays the time indicated in milliseconds that was needed by RavenDB to be launched and ready to process requests. This launching time will be different from one computer to another, based on the computer hardware configuration, the CPU activity, and the available memory resources.

Other configuration parameters are also logged and displayed such as the Data Directory, which indicates the directory where your data will be saved, the machine hostname, and the TCP/IP listening port number which is a part of the Server URL.

Creating your first RavenDB database

We are going to explore another great feature of the Management Studio by creating a new database and add some sample data that we can use to learn more about the Management Studio and RavenDB.

Many times, when you start building an application, you want to see what the data will look like in the user interface well before the database (or the web service) is actually ready. RavenDB makes it easier to see that data, compared to other systems. To do this, we can use the Management Studio.


Time for action – creating a new database and adding sample data

Currently, the server is empty and we have an empty default database named system. In order to see what the data will look like in the Document database, we are going to use the Management Studio features to create a new database and create some sample data to populate the database with these data.


We assume that the RavenDB server is running and the Management Studio is open in the web browser. If not, you can refer to the previous section to launch the RavenDB server in the Console mode.

  1. Click on your web browser to activate it. The RavenDB Management Studio is open.


    On the right side of the wizard form, you can choose to activate features provided by some available bundles (the RavenDB extensions). You can choose to activate data compression or data encryption and so on. These choices are inclusive and you can activate more than one bundle.

  2. Create a new database using the wizard form and name it Sales.

  3. Click on the Tasks tab to display the tasks screen.

  4. Click on the Create Sample Data button to create the sample data.

  5. Click on the Documents tab to display the Documents screen and verify that the sample data has been added to the current database.

What just happened?

We just created a new database and populated it with sample data.

In steps 1 and 2, we created a new database named Sales using the Management Studio's Create new database wizard.

By default, RavenDB allows anonymous access only for read requests (HTTP GET), and since we are creating data, we need to specify a username and a password to generate the data. You can control this by changing the AnonymousAccess setting in the server configuration file, which requires the server restart to apply changes.

In steps 3 and 4, we generated sample data using the Management Studio features.

When we create sample data using the Create Sample Data feature of the Management Studio, the current database must be empty and there shouldn't be any documents in the database, otherwise, the data generation action will fail.

While inserting the sample data into the Sales database, the Management Studio displays the progress log. When the process is done, there are about 250 documents and four new indexes in the database.

In step 5, we opened the Documents screen and verified that the sample data has been added to the Sales database.

Shutting down the RavenDB server in the Console mode

As easy it is to launch the RavenDB server in the Console mode, it is also easy to shutdown the RavenDB server in the Console mode.

Once the Start.cmd file is executed, a new command prompt window is opened and it shows the server activity log. This RavenDB server instance would still be running until you press the q key command which will shutdown the RavenDB server and close the command prompt window.


Time for action – shutting down RavenDB

We assume that RavenDB is running in the Console mode, otherwise, please refer to the previous sections to launch the RavenDB server in the Console mode.

In the command prompt window, enter the q command and press Enter to shutdown the RavenDB server. This will also close the command prompt window.

What just happened?

In this one step, we learned how to shutdown the RavenDB server using the q command in the command prompt window.

When Raven.Server.exe is launched with the –browser parameter, it will automatically open the Management Studio in the web browser. But when the RavenDB instance is shutdown, it will not close the Management Studio and it should be closed manually.

Have a go hero – connecting to a RavenDB server on a networked computer

Suppose your computer is connected to a local area network. There is another computer in the network where RavenDB was installed and is currently running on the IP address and listening on port 8080. You can access the Management Studio from your computer simply by typing the complete URL in your web browser that points to the Management Studio, providing the IP address, and the listening port where RavenDB is running. The URL should look like:


Downloading the example code:

You can download the example code files for all Packt books you have purchased from your

account at http://www.packtpub.com . If you purchased this book elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed directly to you.



We learned a lot in this chapter about the RavenDB server and NoSQL and their concepts.

Specifically, we covered the document anatomy in a NoSQL document-oriented database and how it is represented in the JSON format. We learned the RavenDB concepts and how they work. Also, we looked at how to download and install RavenDB on the local machine. We covered how to launch and shutdown RavenDB in the Console mode and took a look at its activity log and its basic configuration file parameters. Finally, we created a new database in RavenDB and populated it with sample data using the RavenDB Management Studio wizards.

Now that we've learned about the RavenDB server, we're ready to start using the Management Studio, which is the topic of the next chapter.

About the Author

  • Khaled Tannir

    Khaled Tannir has been working with computers since 1980. He began programming with the legendary Sinclair Zx81 and later with Commodore home computer products (Vic 20, Commodore 64, Commodore 128D, and Amiga 500). He has a Bachelor's degree in Electronics, a Master's degree in System Information Architectures, in which he graduated with a professional thesis, and completed his education with a Master of Research degree. He is a Microsoft Certified Solution Developer (MCSD) and has more than 20 years of technical experience leading the development and implementation of software solutions and giving technical presentations. He now works as an independent IT consultant and has worked as an infrastructure engineer, senior developer, and enterprise/solution architect for many companies in France and Canada. With significant experience in Microsoft .Net, Microsoft Server Systems, and Oracle Java technologies, he has extensive skills in online/offline applications design, system conversions, and multilingual applications in both domains: Internet and Desktops. He is always researching new technologies, learning about them, and looking for new adventures in France, North America, and the Middle-east. He owns an IT and electronics laboratory with many servers, monitors, open electronic boards such as Arduino, Netduino, RaspBerry Pi, and .Net Gadgeteer, and some smartphone devices based on Windows Phone, Android, and iOS operating systems. In 2012, he contributed to the EGC 2012 (International Complex Data Mining forum at Bordeaux University, France) and presented, in a workshop session, his work on "how to optimize data distribution in a cloud computing environment". This work aims to define an approach to optimize the use of data mining algorithms such as k-means and Apriori in a cloud computing environment. He is the author of RavenDB 2.x Beginner's Guide, Packt Publishing. He aims to get a PhD in Cloud Computing and Big Data and wants to learn more and more about these technologies. He enjoys taking landscape and night time photos, travelling, playing video games, creating funny electronic gadgets with Arduino/.Net Gadgeteer, and of course, spending time with his wife and family. You can reach him at [email protected]

    Browse publications by this author

Latest Reviews

(1 reviews total)
RavenDB 2.x Beginner's Guide
Unlock this book and the full library FREE for 7 days
Start now