Client API: Creating a Document Store



Creating a Document Store - Configuration

The following properties can be configured when creating a new Document Store:

  • Urls (required)

    • An initial URLs list of your RavenDB cluster nodes that is used when the client accesses the database for the first time.

    • Upon the first database access, the client will fetch the Database Group Topology from the first server on this list that it successfully connected to. An exception is thrown if the client fails to connect with neither of the servers specified on this list. The URLs from the Database Group Topology will supersede this initial URLs list for any future access to that database.

    • Note: Do not create a Document Store with URLs that point to servers outside of your cluster.

    • Note: This list is not binding. You can always modify your cluster later dynamically, add new nodes or remove existing ones as necessary. Learn more in Cluster View Operations.

  • Database (optional)
    The default database which the Client will work against.
    A different database can be specified when creating a Session if needed.

  • Conventions (optional)
    Customize the Client behavior with a variety of options, overriding the default settings.

  • Certificate (optional)
    X.509 certificate used to authenticate the client to the RavenDB server

After setting the above configurations as necessary, call .Initialize() to begin using the Document Store.

The Document Store is immutable - all above configuration are frozen upon calling .Initialize().
Create a new document store object if you need different default configuration values.

Certificate Cleanup

When the store is disposed of, it is advisable to also dispose of any certificate attached to it to avoid the accumulation of unneeded certificate files, especially if certificates are added often.

To dispose of a certificate set an AfterDispose store event, triggered when the store is disposed of, and use it to call the Certificate.Dispose() method.

// Use the AfterDispose store event to remove the certificate after the store is disposed of
Store.AfterDispose += (sender, args) => Store.Certificate.Dispose();

Note: In RavenDB 6.x and on certificate cleanup is automatic and the procedure described here is unnecessary.

Creating a Document Store - Example

This example demonstrates how to implement the singleton pattern in the initialization of a Document Store, as well as how to set initial default configurations.

// The `DocumentStoreHolder` class holds a single Document Store instance.
public class DocumentStoreHolder
{
    // Use Lazy<IDocumentStore> to initialize the document store lazily. 
    // This ensures that it is created only once - when first accessing the public `Store` property.
    private static Lazy<IDocumentStore> store = new Lazy<IDocumentStore>(CreateStore);

    public static IDocumentStore Store => store.Value;
    
    private static IDocumentStore CreateStore()
    {
        IDocumentStore store = new DocumentStore()
        {
            // Define the cluster node URLs (required)
            Urls = new[] { "http://your_RavenDB_cluster_node", 
                           /*some additional nodes of this cluster*/ },

            // Set conventions as necessary (optional)
            Conventions =
            {
                MaxNumberOfRequestsPerSession = 10,
                UseOptimisticConcurrency = true
            },

            // Define a default database (optional)
            Database = "your_database_name",

            // Define a client certificate (optional)
            Certificate = new X509Certificate2("C:\\path_to_your_pfx_file\\cert.pfx"),

        // Initialize the Document Store
        }.Initialize();

        // When the store is disposed of, the certificate file will be removed as well
        Store.AfterDispose += (sender, args) => Store.Certificate.Dispose();

        return store;
    }
}