Set up SurrealDB in the AppHost

此内容尚不支持你的语言。

⭐ Community Toolkit

This article is the reference for the Aspire SurrealDB Hosting integration. It enumerates the AppHost C# 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:

aspire add communitytoolkit-surrealdb

Aspire CLI 是交互式的；按提示选择合适的搜索结果：

Select an integration to add:

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

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

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

Or, choose a manual installation approach:

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

<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:

var builder = DistributedApplication.CreateBuilder(args);

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

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

// After adding all resources, run the app...

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.
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.
Chaining .AddNamespace("ns") declares a SurrealDB namespace resource, and chaining .AddDatabase("db") declares a database inside that namespace.
The AppHost reference call configures a connection in the consuming project named after the referenced database resource, such as db in the preceding example.

Add Surrealist

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

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

// After adding all resources, run the app...

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:

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

// After adding all resources, run the app...

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:

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

// After adding all resources, run the app...

For more information on providing parameters, see External parameters.

Configure logging

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

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

// After adding all resources, run the app...

The WithLogLevel method enables verbose logging in the SurrealDB container, which is useful during development and debugging.

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.