Get started with the SurrealDB integrations

⭐ Community Toolkit

SurrealDB is a native, open-source, multi-model database that lets you store and manage data across relational, document, graph, time-series, vector & search, and geospatial models—all in one place. The Aspire SurrealDB integration enables you to connect to existing SurrealDB instances or create new instances from Aspire using the docker.io/surrealdb/surrealdb container image.

In this introduction, you’ll see how to install and use the Aspire SurrealDB integrations in a simple configuration. If you already have this knowledge, see SurrealDB hosting integration for full reference details.

참고

To follow this guide, you must have created an Aspire solution to work with. To learn how to do that, see Build your first Aspire app.

Set up hosting integration

To begin, install the Aspire SurrealDB Hosting integration in your Aspire AppHost project. This integration allows you to create and manage SurrealDB instances from your Aspire hosting projects:

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

참고

결과가 하나라면 자동 선택됩니다. 버전은 직접 확인해야 합니다.

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

Next, in the AppHost project, register and consume the SurrealDB integration using the AddSurrealServer extension method to add the SurrealDB container to the application builder. Chain a call to the returned resource builder to AddNamespace and then AddDatabase, to add a SurrealDB database resource:

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

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

Set up client integration

In each of the consuming client projects, install the Aspire SurrealDB client integration:

.NET CLI

.NET CLI — Add CommunityToolkit.Aspire.SurrealDb package

dotnet add package CommunityToolkit.Aspire.SurrealDb

Program.cs (C# file-based app)

Program.cs

#:package CommunityToolkit.Aspire.SurrealDb@*

PackageReference (*.csproj)

XML — Add CommunityToolkit.Aspire.SurrealDb package reference

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

In the Program.cs file of your client-consuming project, call the AddSurrealClient extension method to register a SurrealDbClient for use via the dependency injection container. The method takes a connection name parameter.

builder.AddSurrealClient(connectionName: "db");

You can then retrieve the SurrealDbClient instance using dependency injection. For example, to retrieve the client from a service:

public class ExampleService(SurrealDbClient client)
{
    // Use client...
}

For full reference details, see SurrealDB hosting integration and SurrealDB client integration.

See also

• SurrealDB
• SurrealDB documentation
• .NET SDK for SurrealDB
• Aspire Community Toolkit GitHub repo