Set up SurrealDB in the AppHost

⭐ Community Toolkit

This article is the reference for the Aspire SurrealDB Hosting integration. It enumerates the AppHost APIs that you use to model a SurrealDB server, namespace, and database as resources in your AppHost project.

If you’re new to the SurrealDB integration, start with the Get started with SurrealDB integrations guide. For how consuming apps read the connection information this page exposes, see Connect to SurrealDB.

Installation

To start building an Aspire app that uses SurrealDB, install the 📦 CommunityToolkit.Aspire.Hosting.SurrealDb NuGet package:

C#

Aspire CLI

Aspire CLI — Add CommunityToolkit.Aspire.Hosting.SurrealDb package

aspire add communitytoolkit-surrealdb

The Aspire CLI is interactive, be sure to select the appropriate search result when prompted:

Aspire CLI — Example output prompt

Select an integration to add:

> communitytoolkit-surrealdb (CommunityToolkit.Aspire.Hosting.SurrealDb)
> Other results listed as selectable options...

Note

If there's only one result, the CLI selects it automatically. You'll still need to confirm the version.

apphost.cs (C# file-based app)

C# — AppHost.cs

#:package CommunityToolkit.Aspire.Hosting.SurrealDb@*

PackageReference (*.csproj)

XML — Add CommunityToolkit.Aspire.Hosting.SurrealDb package reference

<PackageReference Include="CommunityToolkit.Aspire.Hosting.SurrealDb" Version="*" />

Or, choose a manual installation approach:

AppHost.cs

#:package CommunityToolkit.Aspire.Hosting.SurrealDb@*

AppHost.csproj

<PackageReference Include="CommunityToolkit.Aspire.Hosting.SurrealDb" Version="*" />

TypeScript

Terminal

aspire add CommunityToolkit.Aspire.Hosting.SurrealDb

Learn more about aspire add in the command reference.

This updates your aspire.config.json with the SurrealDB hosting integration package:

aspire.config.json

{
  "packages": {
    "CommunityToolkit.Aspire.Hosting.SurrealDb": "*"
  }
}

Add SurrealDB resource

Once you’ve installed the hosting integration in your AppHost project, you can add a SurrealDB server, namespace, and database resource as shown in the following example:

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var db = builder.AddSurrealServer("surreal")
                .AddNamespace("ns")
                .AddDatabase("db");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(db)
       .WaitFor(db);

builder.Build().Run();

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const surreal = await builder.addSurrealServer("surreal");
const ns = await surreal.addNamespace("ns");
const db = await ns.addDatabase("db");

const exampleProject = await builder.addProject("apiservice", "../ExampleProject/ExampleProject.csproj");
await exampleProject.withReference(db);
await exampleProject.waitFor(db);

await builder.build().run();

1. When Aspire adds a container image to the AppHost, as shown in the preceding example with the docker.io/surrealdb/surrealdb image, it creates a new SurrealDB instance on your local machine.

2. The SurrealDB resource includes default credentials with a username of root and a random password generated using the CreateDefaultPasswordParameter method. When the AppHost runs, the password is stored in the AppHost’s secret store under the key surreal-password.

3. Chaining .AddNamespace("ns") declares a SurrealDB namespace resource, and chaining .AddDatabase("db") declares a database inside that namespace.

4. The AppHost reference call configures a connection in the consuming project named after the referenced database resource, such as db in the preceding example.

Note

When you reference a SurrealDB resource from the AppHost, Aspire makes several properties available to the consuming project, such as connection strings, hostnames, and port numbers. For a complete list of these properties and per-language connection examples, see Connect to SurrealDB.

Add Surrealist

To add Surrealist to the SurrealDB server resource, call the WithSurrealist method:

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var surreal = builder.AddSurrealServer("surreal")
                     .WithSurrealist();

var db = surreal
           .AddNamespace("ns")
           .AddDatabase("db");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(db)
       .WaitFor(db);

builder.Build().Run();

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

let surreal = await builder.addSurrealServer("surreal");
surreal = await surreal.withSurrealist();

const ns = await surreal.addNamespace("ns");
const db = await ns.addDatabase("db");

const exampleProject = await builder.addProject("apiservice", "../ExampleProject/ExampleProject.csproj");
await exampleProject.withReference(db);
await exampleProject.waitFor(db);

await builder.build().run();

Surrealist is a web-based user interface for interacting with your SurrealDB database visually. It lets you connect to any SurrealDB instance, execute queries, explore your tables, and design your schemas.

Add SurrealDB resource with data bind mount

To add a data bind mount to the SurrealDB resource, call the WithDataBindMount method:

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var db = builder.AddSurrealServer("surreal")
                .WithDataBindMount("./data/surreal/data")
                .AddNamespace("ns")
                .AddDatabase("db");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(db)
       .WaitFor(db);

builder.Build().Run();

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

let surreal = await builder.addSurrealServer("surreal");
surreal = await surreal.withDataBindMount("./data/surreal/data");

const ns = await surreal.addNamespace("ns");
const db = await ns.addDatabase("db");

const exampleProject = await builder.addProject("apiservice", "../ExampleProject/ExampleProject.csproj");
await exampleProject.withReference(db);
await exampleProject.waitFor(db);

await builder.build().run();

Data bind mounts rely on the host machine’s filesystem to persist SurrealDB data across container restarts. The mount path ./data/surreal/data is resolved relative to the AppHost project directory. For more information on data bind mounts, see Docker docs: Bind mounts.

Add SurrealDB resource with parameters

When you want to explicitly provide the password used by the container image, you can provide it as a parameter:

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var password = builder.AddParameter("password", secret: true);

var db = builder.AddSurrealServer("surreal", password: password)
                .AddNamespace("ns")
                .AddDatabase("db");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(db)
       .WaitFor(db);

builder.Build().Run();

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const password = await builder.addParameter("password", { secret: true });

const surreal = await builder.addSurrealServer("surreal", { password });
const ns = await surreal.addNamespace("ns");
const db = await ns.addDatabase("db");

const exampleProject = await builder.addProject("apiservice", "../ExampleProject/ExampleProject.csproj");
await exampleProject.withReference(db);
await exampleProject.waitFor(db);

await builder.build().run();

For more information on providing parameters, see External parameters.

Configure logging

To configure the log level for the SurrealDB container, call the WithLogLevel method:

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var surreal = builder.AddSurrealServer("surreal")
                     .WithLogLevel(Microsoft.Extensions.Logging.LogLevel.Debug);

var db = surreal
           .AddNamespace("ns")
           .AddDatabase("db");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(db)
       .WaitFor(db);

builder.Build().Run();

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

let surreal = await builder.addSurrealServer("surreal");
surreal = await surreal.withLogLevel("Debug");

const ns = await surreal.addNamespace("ns");
const db = await ns.addDatabase("db");

const exampleProject = await builder.addProject("apiservice", "../ExampleProject/ExampleProject.csproj");
await exampleProject.withReference(db);
await exampleProject.waitFor(db);

await builder.build().run();

The WithLogLevel method enables verbose logging in the SurrealDB container, which is useful during development and debugging. The polyglot TypeScript AppHost accepts the log level as a string (for example, "Trace", "Debug", "Information", "Warning", "Error", "Critical", or "None").

Health checks

The SurrealDB hosting integration automatically adds a health check for the SurrealDB namespace and database resources. The health check uses both the /health endpoint and a simple raw query to verify that SurrealDB is running and that a connection can be established. 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.