RavenDB 2.x Beginner's Guide: For .NET developers who want to acquire document-oriented database skills, there is no better introduction to RavenDB than this book. It covers all the bases in a user-friendly style that makes learning fast and easy.

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.

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.

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.

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.

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 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 (BLOBs – Binary 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.

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:

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).

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:

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.

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:

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

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

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.

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.

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.

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.

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:

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".

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.

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

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.

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

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.

Note

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.

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:

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 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.

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.