# Set up SurrealDB in the AppHost

<Badge text="⭐ Community Toolkit" variant="tip" size="large" />

<Image
  src={surrealdbIcon}
  alt="SurrealDB logo"
  width={100}
  height={100}
  class:list={'float-inline-left icon'}
  data-zoom-off
/>

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`](/get-started/app-host/) project.

If you're new to the SurrealDB integration, start with the [Get started with SurrealDB integrations](/integrations/databases/surrealdb/surrealdb-get-started/) guide. For how consuming apps read the connection information this page exposes, see [Connect to SurrealDB](../surrealdb-connect/).
**Note:** TypeScript AppHost support (`addSurrealServer` and related APIs) is not yet available in the generated `./.aspire/modules/aspire.mjs` SDK. All examples on this page are C# only.

## Installation

To start building an Aspire app that uses SurrealDB, install the [📦 CommunityToolkit.Aspire.Hosting.SurrealDb](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.SurrealDb) NuGet package:

<InstallPackage packageName="CommunityToolkit.Aspire.Hosting.SurrealDb" />

Or, choose a manual installation approach:

```csharp title="C# — AppHost.cs"
#:package CommunityToolkit.Aspire.Hosting.SurrealDb@*
```

```xml title="XML — 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:

```csharp title="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...
```

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.

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

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

1. 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](../surrealdb-connect/).

## Add Surrealist

To add [Surrealist](https://hub.docker.com/r/surrealdb/surrealist) to the SurrealDB server resource, call the `WithSurrealist` method:

```csharp title="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);

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

```csharp title="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);

// 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](https://docs.docker.com/engine/storage/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:

```csharp title="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);

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

For more information on providing parameters, see [External parameters](/get-started/resources/).

## Configure logging

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

```csharp title="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);

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