ravendb / book

RavenDB Book

RavenDB - An ACID NoSQL Document Database

This repository contains source code for the RavenDB document database. With a RavenDB database you can set up a NoSQL data architecture or add a NoSQL layer to your current relational database.

Supported Platforms

• Windows
• Linux
• Docker
• MacOS
• Raspberry Pi

Grab Your License and Download Latest Version

Request your license.

Download the latest version of RavenDB.

Getting Started

Install and set up your database.

Learn RavenDB Quickly

RavenDB Bootcamp is a free, self-directed learning course. In just three units you will learn how to use RavenDB to create fully-functional, real-world programs with NoSQL Databases. If you are unfamiliar with NoSQL, it’s okay. We will provide you with all the information you need.

Stay Updated on New Developments

We keep adding new features to improve your RavenDB experience. Check out our latest improvements, updated weekly.

Documentation

Access full documentation for RavenDB. Like our database, it is easy to use.

Where to Ask for Help

If you have any questions, or need further assistance, you can contact us directly.

Report an Issue

Please check where to report an issue in our contribution guidelines.

RavenDB Developer Community Group

If you have any questions please visit our discussions page or check Google community group archive. The solutions for the most common challenges are available. You are welcome to join!

Pull Requests

Please check how to submit a Pull Request in our contribution guidelines.

Setup & Run

First please review and set up prerequisites.

Launch RavenDB:

Running locally:

<path/to/ravendb>/Server/Raven.Server

Registering as service in Windows using rvn utility available in the package Server directory:

<path\to\ravendb>\rvn.exe windows-service register --service-name RavenDB4

Hello World (.NET)

Server Side

• Launch a RavenDB server instance as follows:

<path/to/ravendb>/Server/Raven.Server --ServerUrl=http://localhost:8080

• Open a web browser and enter http://localhost:8080

• Click on Databases in the menu on the left-hand side, and then create a new database named SampleDataDB

• Click on Settings and then on Create Sample Data in the left menu. Now Click on Create

Client Side

• Install .NET Core SDK. See : Downloads and PowerShell

• Open a terminal and type:

mkdir HelloWorld
cd HelloWorld
dotnet new console

• Add the RavenDB Client package:

   dotnet add package RavenDB.Client --version 6.0.0-*

• Replace the content of Program.cs with the following:

using System;
using Raven.Client.Documents;

namespace HelloWorld
{
    class Shippers
    {
        public string Name;
        public string Phone;
    }
    
    class Program
    {
        static void Main(string[] args)
        {
            using (var store = new DocumentStore
            {
                Urls = new string[] {"http://localhost:8080"},
                Database = "SampleDataDB"
            })
            {
                store.Initialize();

                using (var session = store.OpenSession())
                {
                    var shipper = session.Load<Shippers>("shippers/1-A");
                    Console.WriteLine("Shipper #1 : " + shipper.Name + ", Phone: " + shipper.Phone);
                }
            }
        }
    }
}

• Type:

dotnet restore
dotnet build
dotnet run

SAST Tools

• PVS-Studio
• Snyk

Enjoy :)

book's Issues

Chapter 1: Add Distributed computing Fallacies

This is currently blank.

Chapter 01: Add Chapter descriptions for Part 4

Part IV simply reads "Operations."

Listing 2.3: Installation of Raven.Client for Commandline Users?

The Listing instructs to use the Package Manager console, but Linux and MacOs don't have Visual Studio.
The dotnet command line should be able to fetch the package, too - but the syntax differs. Especially -IncludePreRelease does not exist.

Unable to build book

Running build.ps1 on Win 10, I get:

xelatex not found. Please select a different --pdf-engine or install xelatex
Start-Process: C:\src\Playground\ravendb\book\build.ps1:22
Line |
  22 |      start $output
     |      ~~~~~~~~~~~~~
     | This command cannot be run due to the error: The system cannot find the file specified.

.\Output\Inside RavenDB 4.0.pdf

I googled installation of xelatex, and it said to install MikTeX, but i have this installed already. Please add a paragraph to the ReadMe to explain the prerequisites.

Also, is there a book forthcoming on RavenDb 5?

Chapter 4 - Listing 4.7 has wrong caption

Which is a copy/pasted caption from Listing 4.6

Docker Example broken

I tried to use your docker example from page 17 and encountered several issues:

1. the generated pdf contains non default characters for several symbols like "=" - so copy paste does not work.
2. Even when fixed, the docker command starts a server which refuses unsecured connections, it seems liike the correct command is: docker run -e UNSECURED_ACCESS_ALLOWED=PublicNetwork -p 8080:8080 ravendb/ravendb
3. Your docker hub readme contains linke to powershell scripts, but the links are broken (Run Ubuntu-based image: run-ubuntu1604.ps1)
4. I found the the scripts on Github, but the documentation was sparse, e.g. there was no mention that you would probably use the AuthenticationDisabled switch

Typo issue at `2.3.2 Graph databases…`

Correct me if I'm wrong but I think there is an extra 'the' in this sentence.

Such
databases are very useful when one of the most important aspects of the data
isn’t the just the data itself, but the association between different pieces of
information.

Attachments: Clarify ACID or base nature?

When I was rereading the newest version of your book on christmas, I was wondering if attachments are BASE or ACID - e.g. when is the document considered "complete" on the server?
When the json is saved on disk or if the json and all attachments are on disk?
If the first, this would be good to know since there might be situations where a document without attachment is not really usable.

Build.ps1 throws error using xelatex

After manually adding the path to xelatex (which I found in %localappdata%\Programs\MiKTeX\miktex\bin\x64 and editied the build.ps1 script accordingly), I am getting more errors:

Error producing PDF.
! Argument of \__sys_tmp:w has an extra }.
<inserted text>
                \par
l.80 ...c__kernel_sys_dvipdfmx_version_int { 0 } }

Start-Process: D:\src\Playground\ravendb\book\build.ps1:22
Line |
  22 |      start $output
     |      ~~~~~~~~~~~~~
     | This command cannot be run due to the error: The system cannot find the file specified.

I must say, this is frustrating as hell. Someone please just provide a pdf, preferably of version 5.

Terminology: ACID vs ACID-compliant?

In Ch01, you mention that RavenDB is an ACID database.

I'm tempted to correct this to "ACID-compliant" because it adheres to the rules/guidelines of ACID, but I'm not sure how you feel about that language.

Thoguhts?

Chapter 01: Add Chapter descriptions for Part 2

Part II simply reads "Indexing."

Bug in Listing 5.5 (Subscription example)

I'm following the subscription example in Listing 5.5 https://github.com/ravendb/book/blob/v4.0/Ch05/Ch05.md#the-subscription-script

await subscription.Run(batch =>
{
    foreach (var item in batch.Items)
    {
        SupportCall call = item.Document;
        
        var age = DateTime.Today - call.Started;
        if (age > DateTime.FromDays(14))
            return; // no need to send survey for old stuff

        using (var session = batch.OpenSession())
        {
            var customer = session.Load<Customer>(
                call.CustomerId);

            call.Survey = true;

            session.Store(call, item.ChangeVector, item.Id);

            try
            {
                session.SaveChanges();
            }
            catch (ConcurrenyException)
            {
                // will be retried by the subscription
                return;
            }

            SendSurveyEmailTo(customer, call);
        }
    }
});

I think the use of return is slightly misleading in here. Since the example uses foreach using return will actually skip processing the rest of the batch. It's probably more correct to either use continue or batch.Items.ForEach(() => { ... return

Also I think the example would be more clear to state // will be retried in the next batch and expand in the following paragraph that a ConcurrencyException implies the document has changed on the server in between assembling the current subscription batch and saving the modification, which will in turn lead to the updated document to be included in a future subscription batch.

Error building pdf

I get this error building (see input.log).

input.log

Listing reference number is wrong

My version: 8. july 2018
p. 89 - see example in listing 3.8 (should be listing 3.7)

Book format usability

The book is very interesting, I'd like to report some issues in the output formats though.
The default pdf format cannot easily be read on mobile devices, there's just too much margin and the font is just to small to be read easily. Sure you can zoom in but usually switching pages requires zooming out again, which makes for a poor read experience.
Exporting in epub format works but there seem to be issues in the validity of the resulting output, for example Google Books cannot import it, and desktop readers (Readium) have issues as well, especially with code fragments.

Missing word in sentence in intro

Intro.md
Introduction
Sentence:
Working with a database be easy and obvious, and to a large extent, RavenDB allows that.
Maybe:
Working with a database should be easy and obvious, and to a large extent, RavenDB allows that.

Chapter 01: Add Chapter descriptions for Part 5

Part IV simply reads "Scale out".

Chapter 3 - A common bad practice is to integrate between different applications using a shared database.

Hello,

I'm not sure if this is the right place to express my opinion

I think that this statement in the chapter 3 is "half wrong".
"A common bad practice is to integrate between different applications using a shared database."

The readers might understand that sharing database between applications is always a bad practices... and it is not true..

IMO, the Application A can make choice

• if it will share the same database X of the application X
• or it will create its own database A and clone (denormalize) informations it wanted from the database X.

it is comparable to make decision at the document-level: if a document will reference to other documents by de-normalization, or by reference id.. Both approaches have its pros and cons depend on the use cases (or context).

I agree with the bad side about sharing database described in the chapter. But for example:
A database which contains references data (common data) is absolutely valid to share among applications.

Chapter 01: Add Chapter descriptions for Part 3

Part III simply reads "Modeling".

build.ps1 throws error with pdflatex

After switching to pdflatex instead of xelatex, in build.ps1 I am getting another error:

Error producing PDF.
! Package inputenc Error: Invalid UTF-8 byte sequence.

See the inputenc package documentation for explanation.
Type  H <return>  for immediate help.
 ...

l.15435 \passthrough{\lstinline!Martín Sommer!}

Try running pandoc with --pdf-engine=xelatex.
Start-Process: D:\src\Playground\ravendb\book\build.ps1:22
Line |
  22 |      start $output
     |      ~~~~~~~~~~~~~
     | This command cannot be run due to the error: The system cannot find the file specified.

.\Output\Inside RavenDB 4.0.pdf

I am sorry, but I don't have time to become an expert in LaTeX just to get a PDF copy of the (as it appears, outdated) book produced.

Typo in introduction

Intro.md
Inrtoduction, line 23, word 16
just drop ACID behavioor
should be
just drop ACID behaviour

Code Listings in PDF broken

When copy-pasting code from the PDF, most examples are broken.
For example Listing 2.4 becomes this:

var s t o r e = new DocumentStore
{
Urls = { ” http :// l o c a l h o s t :8080” } ,
Database = ” Tasks ”
} ;
s t o r e . I n i t i a l i z e ( ) ;

Have the .pdf and .epub available in Releases

Well... not an issue but just an idea to help the lazy developers: have the resulting files available for download directly in the releases tab. :-)

Listing 2.14 - code not working with newest Nuget Client

Urls and Database appears to be have renamed to Url and DefaultDatabase.

Is this type of proofreading even useful for you? I'm working through the examples and would report problems here - but if I just annoy you, it's no problem to stop it.

Filipino Translation/Localization

Hi,
I'm interested in contributing for this project and I'd like to be of help in translating this into the Filipino language. I think it'll be helpful for this to have a wider reach. Hope you'll consider.

Thanks :)

DockerFile on Github / this book: Improve run Documentation

After a lot of try and error (why does the python client not connect? Http works fine!) I digged into the Urls, Python barfed up and discovered that http://nbsauerch03:8080/topology?name=SomeDb
returned results such as:

{
  "Nodes": [
    {
      "Url": "http://<containerid>:8080",
      "ClusterTag": "A",
      "ServerRole": "Member",
      "Database": "SomeDb"
    }
  ],
  "Etag": -1
}

which does not work when seen from an external client - e.g. if I use the standard Docker-MobyLinux on Windows configuration. The Python Client then uses this Urls to try to get more Information, but fails with a TopologyException since the URL cannot be resolved.
Setting PUBLIC_SERVER_URL=http://localhost:8080 fixes that, but I#m unsure if I have to set other values, too.