RavenDB version 2.0. Other versions:

Connecting to a RavenDB data store

As we have seen, RavenDB can run in one of two modes: a client/server mode, where communication is made via HTTP; and an embedded mode, in which the client API makes direct calls against the Database API.

The recommended mode for RavenDB to run in is the server mode. We discuss the various deployment options for the server mode later in the documentation.

Since a document store instance is not cheap to create but is thread-safe, the general suggestion is to have one instance of it per-database per-application.

In either mode, when the application shuts down, the document store instance(s) used should be disposed to ensure proper cleanup.

Running in server mode

To run in a server mode, add a reference to Raven.Client.Lightweight.dll to your application, and after launching the server instance separately connect to it using the following code:

    var documentStore = new DocumentStore { Url = "http://myravendb.mydomain.com/" };
    documentStore.Initialize();

Where http://myravendb.mydomain.com/ is your the RavenDB server's address.

This will instantiate a communication channel between your application and the RavenDB server instance in the network address you provided.

Running in embedded mode

When running in embedded mode, the data store is actually a server instance running on top of a local data directory, as opposed to connecting to a separate server instance.

To have this, you will need the entire EmbeddedClient folder from the build package in your solution. Note that you cannot use RavenDB Embedded on the Client Profile, you have to change the project properties to use the full .NET framework profiler.

After referencing Raven.Client.Embedded.dll, you need to initialize a new instance of EmbeddableDocumentStore. This is done by passing the path to the directory that the database resides in to the EmbeddableDocumentStore (the database will be created if it doesn't exists yet):

    var documentStore = new EmbeddableDocumentStore { DataDirectory = "path/to/database/directory" };
    documentStore.Initialize();

Silverlight support

If you are accessing a RavenDB instance from Silverlight, you are going to need the Silverlight folder from the build package, and add a reference to all the DLLs in it to your application.

Using Silverlight, you can only access an external RavenDB server; there's still no embedded RavenDB implementation for Silverlight available to public use. You initialize a document store in Silverlight using:

    var documentStore = new DocumentStore { Url = "http://myravendb.mydomain.com/" };
    documentStore.Initialize();

Where http://myravendb.mydomain.com/ is your the RavenDB server's address.

Using a connection string

To make things even simpler, the RavenDB Client API supports .NET's named connection strings. You can use that by setting the ConnectionStringName, and the RavenDB client will initialize automatically based on the connection string's parameters:

    var documentStore = new DocumentStore
    	                    {
    		                    ConnectionStringName = "MyRavenConStr"
    	                    };

You can then define the connection string in the app.config:

    <connectionStrings>
    <add name="Local" connectionString="DataDir = ~\Data"/>
    <add name="Server" connectionString="Url = http://localhost:8080"/>
    <add name="Secure" connectionString="Url = http://localhost:8080;user=beam;password=up;ResourceManagerId=d5723e19-92ad-4531-adad-8611e6e05c8a"/>
  </connectionStrings>

RavenDB connection string format is:

  • DataDir - run in embedded mode, specify which directory to run from. This requires that you'll initialize an EmbeddableDocumentStore, not just DocumentStore.

  • Url - for server mode only, specify where to locate the server.

  • User / Password - for server mode only, the credentials to use when accessing the server.

  • Enlist - whatever RavenDB should enlist in distributed transactions. Not applicable for Silverlight.

  • ResourceManagerId - Optional, for server mode only, the Resource Manager Id that will be used by the Distributed Transaction Coordinator (DTC) service to identify Raven. A custom resource manager id will need to be configured for each Raven server instance when Raven is hosted more than once per machine. Not applicable for Silverlight.

  • Database - for server mode only, use a specific database, not the default one. Using this will also ensure that the database exists.

The following are samples of a few RavenDB connection strings:

  • Url=http://ravendb.mydomain.com - connect to a remote RavenDB instance at ravendb.mydomain.com, to the default database
  • Url=http://ravendb.mydomain.com;Database=Northwind - connect to a remote RavenDB instance at ravendb.mydomain.com, to the Northwind database there
  • Url=http://ravendb.mydomain.com;User=user;Password=secret- connect to a remote RavenDB instance at ravendb.mydomain.com, with the specified credentials
  • DataDir=~\App_Data\RavenDB;Enlist=False - use embedded mode with the database located in the App_Data\RavenDB folder, without DTC support.

Configuration

Conventions

The RavenDB Client API uses several conventions to control how it works, these can be modified at the DocumentStore level.

  • FindIdentityProperty - Tell the RavenDB Client API how to find the property serving as the id property (the one holding the document key). Defaults to property named Id.

  • FindTypeTagName - Find the tag name for the entity, a tag name is the collection name in which an entity will be enrolled, as well as the default entity key namespace. Defaults to the plural of the entity type. (An entity of type Post would be Posts, an entity of type Person would be People, etc).

  • GenerateDocumentKey - Allows you to control the generation of keys for new entities. The rules for returned values follow the Raven document key generation strategies. By default, RavenDB concatenate the type tag name with an increasing numeric id (posts/1, posts/2, post/3, etc).

  • IdentityPartsSeparator - A string that allows you to customize part of the document key generation. By default, Raven uses "plural_entity_name/id", which some users don't like because it makes putting the document key in the URL harder in some cases. You can set this to another value (such as "-"), which would generate: "plural_entity_name-id". This is an alternative to replacing the whole document key generation process.

Comments add new comment

The comments section is for user feedback or community content. If you seek assistance or have any questions, please post them at our support forums.

Steven
REPLY Posted by Steven on

I was confused for a while that EmbeddableDocumentStore could not be found at compile time, despite intellisense locating it. It seems to be that it doesn't work with the .NET 4 client profile. Maybe you should point this out in the documentation?

Ayende Rahien
REPLY Posted by Ayende Rahien on

Thanks, I'll update the docs

Damian Hickey
REPLY Posted by Damian Hickey on

I may be a bit nit-picky here... but using object initializers on disposable types will result in CA2000 warnings / errors. Personally, I think it's a compiler issue, but that is what it is. (Related: http://youtrack.jetbrains.com/issue/RSRP-209157 )

Ayende Rahien
REPLY Posted by Ayende Rahien on

That is why we have the Initialize() method. Until you call it, nothing is actually done.

Mark McCormick
REPLY Posted by Mark McCormick on

Wondering where a full list of conventions might be found; including things like FailoverBehavior?

Ayende Rahien
REPLY Posted by Ayende Rahien on

Those are actually document in the code itself. You can get the docs using intellisense in VS

Andrei Volkov
REPLY Posted by Andrei Volkov on

Here's how to make RavenDB use "trusted connection":

var documentStore = new DocumentStore{ConnectionStringName = "ravenDb"}; var URL = new Uri(documentStore.Url); documentStore.Credentials = new CredentialCache{{ URL, "NTLM", CredentialCache.DefaultNetworkCredentials }}; documentStore.Initialize();

Ayende Rahien
REPLY Posted by Ayende Rahien on

Or just call:

var store = new DocumentStore { ConnectionStringName = &quot;RavenDB&quot; ,Credentials = CredentialCache.DefaultNetworkCredentials };

Bill
REPLY Posted by Bill on

how do we configure a proxy for the connection? IE: fiddler

Ayende Rahien
REPLY Posted by Ayende Rahien on

Either define this in the app.config or set the url to be http://localhost.fiddler:8080

Martin Slot
REPLY Posted by Martin Slot on

Dont you have to dispose the DocumentStore and the session every time? Like: using (documentStore.Initialize()) { using (session = _documentStore.OpenSession()) { } }

I have problems when not disposing the DocumentStore when running NCrunch (with a NUnit). I have not read anywhere that I needed to dipose the document store, so I was spending alot of time with failing unit tests. I have only read that I needed to remember to only have one instance of DocumentStore disposable when running my application (or in this case, unit test).

I just wan to point this out. I like RavenDB, and the ability to run in memory, and embedded.

Ayende Rahien
REPLY Posted by Ayende Rahien on

Yes, you want to dispose of sessions and the document store. Usually, you only dispose of the doc store in the tests. For your application, there is only one instance of the document store, and it is cleaned up when you app is shutting down.

Martin Slot
REPLY Posted by Martin Slot on

Is there a big performance hit disposing every time?

Ayende Rahien
REPLY Posted by Ayende Rahien on

No, you HAVE to dispose it.

Shawn
REPLY Posted by Shawn on

I'm trying to make sense of "when your app is shutting down" in the context of a Single Web App, with multiple tenant databases. Based on the user logged-in, I want to direct to a different document store. So won't I have to have multiple doc stores, one representing each tenant? When would I then dispose a document store?

Shawn
REPLY Posted by Shawn on

mmm nevermind the above...I see that it is not the documentStore but rather the session that would be specific to a tenant. However, the question about "when the app shuts down" still stands...how/where do I open and dispose my documentStore in such a web app?

Ayende Rahien
REPLY Posted by Ayende Rahien on

In a web app, shutdown happens in the App_Shutdown even of the global.asax

Sajid Ali
REPLY Posted by Sajid Ali on

Surely I am missing a really simple thing because I am newbie in RavenDB. http://localhost:8080 This one connect me to the default database. Who can I connect to a database that I have created in the RavenDB name MyDatabase. ?? thanks in advance..

Ayende Rahien
REPLY Posted by Ayende Rahien on

If you want it to point to a particular database, you need to set the DefaultDatabase property.

Himanshu
REPLY Posted by Himanshu on

How to Configure Username/ Password to Access DB from .Net Client as it is provided in SQL SERVER? I don't want to Use Windows Authentication.

Fitzchak Yitzchaki
REPLY Posted by Fitzchak Yitzchaki on

You can generate an Api Key that can be used in order to connect to the database without be bound to a user on the machine. http://ravendb.net/docs/2.0/samples/api-keys/using-api-keys

Murtuza
REPLY Posted by Murtuza on

Is it possible to instantiate a DocumentStore by directly using a ConnectionString instead of ConnectionStringName? We are trying to use multi-tenancy in our application and are maintaining a separate repository of the Tenants (not in web.config)

Ayende Rahien
REPLY Posted by Ayende Rahien on

No, but you can set the properties yourself, or use the ConnectionStringParser class

add new comment
SUBMIT COMMENT