We highly recommend updating your Linux OS prior to launching the RavenDB server. Also check if .NET Core requires any other prerequisites in the Prerequisites for .NET Core on Linux article written by Microsoft.
If you want to test RavenDB without manual setup try RavenDB Cloud.
We offer one free instance per customer. For more information, please read our dedicated article.
The RavenDB server is using a settings.json file to store the server-wide configuration options. This file is located in the Server directory, but please note that after making changes to this file, a server restart is required in order for them to be applied.
You can read more about the available configuration options in our dedicated article.
The configuration file included in each RavenDB server distribution package is as follows:
If you intend to run as a service, the write permissions should be granted to the user running the service (e.g. "Local Service").
Our GUI, the RavenDB Management Studio, comes free with every license type:
After installation and setup, the Studio can be accessed via the browser using the ServerUrl or the ServerPublicUrl value e.g. http://localhost:8080.
To let a developer start coding an application quickly, RavenDB will run with the following default security mode:
Default Security Mode
As long as the database is used inside the local machine and no outside connections are allowed, you can ignore security concerns
and you require no authentication. Once you set RavenDB to listen to connections outside your local machine,
your database will immediately block this now vulnerable configuration and require the administrator to properly setup the security and
access control to prevent unauthorized access to your data or to explicitly allow the unsecured configuration.
We recommend using the 'Setup Wizard' to easily install RavenDB securely from the very start.
Read more about security and how to enable authentication here.
After your server is up and running, to write an application you need to acquire one of the Client access libraries:
In order to start, you need to create an instance of the DocumentStore - the main entry point for your application which is responsible for establishing and managing connections between a RavenDB server (or cluster) and your application.
Before proceeding to the examples, we would like to point out that most of the articles are using the Northwind database. You can read more about it and how to deploy it here.
The DocumentStore is capable of working with multiple databases and for proper operation we recommend having only one instance of it per application.
The following articles can extend your knowledge about the DocumentStore and its configuration:
The Session is used to manipulate the data. It implements the Unit of Work pattern and is capable of batching the requests to save expensive remote calls. In contrast to a DocumentStore it is a lightweight object and can be created more frequently. For example, in web applications, a common (and recommended) pattern is to create a session per request.
Example I - Storing
RavenDB is a Document Database. All stored objects are called documents. Each document contains a unique ID that identifies it, data and adjacent metadata, both stored in JSON format. The metadata contains information describing the document, e.g. the last modification date (@last-modified property) or the collection (@collection property) assignment.
Example II - Loading
The Session was designed to help the user write efficient code easily. For example, when a document is being loaded (.Load) from the server, there is an option to retrieve additional documents in the same request (using .Include), keeping the number of expensive calls to minimum.
Besides that, the session implements the Unit of Work pattern, meaning that all changes to loaded entities are automatically tracked. The SaveChanges call will synchronize (with the server) only the documents that have changed within the session. All of those changes are sent in one request (saving network calls) and processed in one transaction (you can read why RavenDB is an ACID databasehere).
Example III - Querying
To satisfy queries, indexes are used. From the querying perspective, an index defines which document fields can be used to find a document. The whole indexing process is done asynchronously, which gives very quick querying response times, even when large amounts of data have been changed. However, an implication of this approach is that the index might be stale.
When no index is specified in the query (like in the query below), RavenDB will use its intelligent auto-indexes feature that will either use an already existing index or create a new one if no match is found. The other option is to write the index yourself and deploy it to the server. Those indexes are called Static Indexes.
Behind the scenes, queries are translated to the Raven Query Language (RQL) syntax. Read more about RQL here.
The following articles can extend your knowledge about the Session: