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:

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": "*"
  }
}

C#

Aspire CLI

Aspire CLI — CommunityToolkit.Aspire.Hosting.SurrealDb パッケージを追加

aspire add communitytoolkit-surrealdb

Aspire CLI は対話的です。求められたら適切な結果を選択してください:

Aspire CLI — 出力例

Select an integration to add:

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

ノート

結果が 1 つだけなら自動的に選択されます。バージョンは確認が必要です。

apphost.cs (C# file-based app)

C# — AppHost.cs

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

PackageReference (*.csproj)

XML — CommunityToolkit.Aspire.Hosting.SurrealDb パッケージ参照を追加

<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="*" />

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:

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();

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();

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.

ノート

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:

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();

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();

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:

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();

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();

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:

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();

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();

For more information on providing parameters, see External parameters.

Configure logging

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

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();

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();

The WithLogLevel method enables verbose logging in the SurrealDB container, which is useful during development and debugging. The non-C# 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.