Connect to RavenDB

⭐ Community Toolkit

This page describes how consuming apps connect to a RavenDB resource that’s already modeled in your AppHost. For the AppHost API surface — adding a RavenDB server, databases, data volumes, secured instances, and more — see RavenDB Hosting integration.

When you reference a RavenDB resource from your AppHost, Aspire injects the connection information into the consuming app as environment variables. Your app can either read those environment variables directly — the pattern works the same from any language — or, in C#, use the Aspire RavenDB client integration for automatic dependency injection, health checks, and telemetry.

Connection properties

Aspire exposes each property as an environment variable named [RESOURCE]_[PROPERTY]. For instance, the Uri property of a resource called ravendb becomes RAVENDB_URI.

RavenDB server resource

The RavenDB server resource exposes the following connection properties:

Property Name	Description
Host	The hostname or IP address of the RavenDB server
Port	The port number the RavenDB server is listening on (8080 for HTTP, 443 for HTTPS)
Uri	The server URI, with the format http://{Host}:{Port} or https://{Host}:{Port}

Example connection string:

Uri: http://localhost:8080

RavenDB database resource

The RavenDB database resource inherits all properties from its parent server resource and adds:

Property Name	Description
Database	The name of the RavenDB database

The full connection string for the database resource uses the format URL={server URI};Database={DatabaseName}:

URL=http://localhost:8080;Database=ravendb

Connect from your app

Pick the language your consuming app is written in. Each example assumes your AppHost adds a RavenDB server resource named ravenServer and a database resource named ravendb, and references the database from the consuming app.

C#

For C# apps, the recommended approach is the Aspire RavenDB client integration. It registers an IDocumentStore through dependency injection and adds health checks and telemetry automatically. If you’d rather read environment variables directly, see the Read environment variables section at the end of this tab.

Install the client integration

Install the 📦 CommunityToolkit.Aspire.RavenDB.Client NuGet package in the client-consuming project:

.NET CLI

.NET CLI — Add CommunityToolkit.Aspire.RavenDB.Client package

dotnet add package CommunityToolkit.Aspire.RavenDB.Client

Program.cs (C# file-based app)

Program.cs

#:package CommunityToolkit.Aspire.RavenDB.Client@*

PackageReference (*.csproj)

XML — Add CommunityToolkit.Aspire.RavenDB.Client package reference

<PackageReference Include="CommunityToolkit.Aspire.RavenDB.Client" Version="*" />

The RavenDB client integration registers an IDocumentStore instance, which serves as the entry point for interacting with the RavenDB server. If your AppHost includes RavenDB database resources, the associated IDocumentSession and IAsyncDocumentSession instances are also registered for dependency injection.

Add the RavenDB client

In Program.cs, call AddRavenDBClient on your IHostApplicationBuilder to register an IDocumentStore:

C# — Program.cs

builder.AddRavenDBClient(connectionName: "ravendb");

Consiglio

The connectionName must match the RavenDB database resource name from the AppHost. For more information, see Add RavenDB server resource and database resource.

Resolve the document store through dependency injection:

C# — ExampleService.cs

public class ExampleService(IDocumentStore store)
{
    // Use store...
}

Add RavenDB client using settings

The AddRavenDBClient method provides overloads that accept a RavenDBClientSettings object for connecting to an existing RavenDB instance without relying on the hosting integration:

C# — Program.cs

var settings = new RavenDBClientSettings
{
    Urls = new[] { serverUrl },
    DatabaseName = myDatabaseName,
    Certificate = myCertificate
};

builder.AddRavenDBClient(settings: settings);

Add keyed RavenDB clients

To register multiple IDocumentStore instances with different connection configurations, use AddKeyedRavenDBClient:

C# — Program.cs

builder.AddKeyedRavenDBClient(serviceKey: "production", connectionName: "production");
builder.AddKeyedRavenDBClient(serviceKey: "testing", connectionName: "testing");

Then resolve each instance by key:

C# — ExampleService.cs

public class ExampleService(
    [FromKeyedServices("production")] IDocumentStore production,
    [FromKeyedServices("testing")] IDocumentStore testing)
{
    // Use stores...
}

Configuration

The Aspire RavenDB client integration offers multiple ways to provide configuration.

Connection strings. When using a connection string from the ConnectionStrings configuration section, pass the connection name to AddRavenDBClient:

C# — Program.cs

builder.AddRavenDBClient("ravendb");

The connection string is resolved from the ConnectionStrings section:

JSON — appsettings.json

{
  "ConnectionStrings": {
    "ravendb": "URL=http://localhost:8080;Database=ravendb"
  }
}

Configuration providers. The client integration supports Microsoft.Extensions.Configuration. It loads RavenDBClientSettings from appsettings.json (or any other configuration source) by using the Aspire:RavenDB:Client key:

JSON — appsettings.json

{
  "Aspire": {
    "RavenDB": {
      "Client": {
        "ConnectionString": "URL=http://localhost:8080;Database=ravendb",
        "DisableHealthChecks": false,
        "HealthCheckTimeout": 10000,
        "DisableTracing": false
      }
    }
  }
}

Inline delegates. Pass an Action<RavenDBClientSettings> to configure settings inline, for example to disable health checks:

C# — Program.cs

builder.AddRavenDBClient(
    connectionName: "ravendb",
    configureSettings: settings =>
    {
        settings.CreateDatabase = true;
        settings.Certificate = myCertificate;
        settings.DisableTracing = true;
    });

Client integration health checks

Aspire client integrations enable health checks by default. The RavenDB client integration adds a health check that verifies the RavenDB server or database is reachable. The health check is wired into the /health HTTP endpoint, where all registered health checks must pass before the app is considered ready to accept traffic.

Read environment variables in C#

If you prefer not to use the Aspire client integration, you can read the Aspire-injected URI from the environment and connect directly using the RavenDB.Client NuGet package:

C# — Program.cs

using Raven.Client.Documents;

var uri = Environment.GetEnvironmentVariable("RAVENDB_URI");
var database = Environment.GetEnvironmentVariable("RAVENDB_DATABASE");

using var store = new DocumentStore
{
    Urls = [uri!],
    Database = database
}.Initialize();

// Use store to interact with RavenDB...

Go

Use the official ravendb-go-client library:

Terminal

go get github.com/ravendb/ravendb-go-client

Read the injected environment variables and connect:

Go — main.go

package main

import (
    "fmt"
    "os"
    ravendb "github.com/ravendb/ravendb-go-client"
)

func main() {
    // Read Aspire-injected connection properties
    serverURL := os.Getenv("RAVENDB_URI")
    database := os.Getenv("RAVENDB_DATABASE")

    store, err := ravendb.NewDocumentStore([]string{serverURL}, database)
    if err != nil {
        panic(err)
    }
    defer store.Close()

    if err = store.Initialize(); err != nil {
        panic(err)
    }

    fmt.Println("Connected to RavenDB at", serverURL)
}

Python

Install the ravendb Python client:

Terminal

pip install ravendb

Read the injected environment variables and connect:

Python — app.py

import os
from ravendb import DocumentStore

# Read Aspire-injected connection properties
server_url = os.getenv("RAVENDB_URI")
database = os.getenv("RAVENDB_DATABASE")

store = DocumentStore(urls=[server_url], database=database)
store.initialize()

# Use store to interact with RavenDB...

TypeScript

Install the ravendb npm package:

Terminal

npm install ravendb

Read the injected environment variables and connect:

TypeScript — index.ts

import { DocumentStore } from 'ravendb';

// Read Aspire-injected connection properties
const serverUrl = process.env.RAVENDB_URI!;
const database = process.env.RAVENDB_DATABASE!;

const store = new DocumentStore([serverUrl], database);
store.initialize();

// Use store to interact with RavenDB...

Consiglio

If your app expects specific environment variable names different from the Aspire defaults, you can pass individual connection properties from the AppHost using WithEnvironment. See the AppHost reference for details.