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 lets you model a SurrealDB server, namespace, and database as first-class resources in your AppHost, then hand the connection information to any consuming app — regardless of language.

Why use SurrealDB with Aspire

Adding SurrealDB through Aspire — rather than wiring up containers and connection strings by hand — gives you:

• Zero-config local development. Aspire runs SurrealDB from the docker.io/surrealdb/surrealdb container image with credentials generated automatically for you.
• Consistent connection info across languages. Once you reference the database from a consuming app, Aspire injects connection properties as environment variables in a predictable format that works from C#, TypeScript, Python, Go, or any other language.
• Built-in health checks. The hosting integration automatically registers a health check so the dashboard and your orchestrator can tell when SurrealDB is ready.
• Dashboard observability. The SurrealDB resource shows up in the Aspire dashboard with logs, status, and telemetry alongside your other services.
• A first-class C# client integration. C# apps can use the CommunityToolkit.Aspire.SurrealDb package for dependency injection, health checks, and OpenTelemetry, all wired up from the same resource name.

How the pieces fit together

The SurrealDB integration has two sides: a hosting integration that you use in your AppHost to model the database resources, and a connection story for consuming apps that reference them.

architecture-beta

  group apphost(server)[AppHost]
  group consumer(server)[Consuming app]

  service hosting(server)[Hosting integration] in apphost
  service surreal(database)[SurrealDB server] in apphost
  service db(database)[surrealdb] in apphost

  service client(iconoir:server-connection)[Client integration] in consumer
  service app(server)[App] in consumer

  hosting:R --> L:surreal
  surreal:R --> L:db
  db:R --> L:client
  client:R --> L:app

The hosting integration lives in your AppHost project and models the SurrealDB server, namespace, and database as resources. The client integration lives in each consuming app and uses the connection information Aspire injects to talk to the database.

Getting there is a two-step process: model the SurrealDB resources in your AppHost, then connect from each app that needs it.

1. Model SurrealDB in your AppHost

   Add the SurrealDB hosting integration to your AppHost, then declare a SurrealDB server, namespace, and database, and reference them from the apps that need it. The SurrealDB Hosting integration article walks through every capability — adding Surrealist, data bind mounts, log levels, and custom parameters — with C# examples.

   Set up SurrealDB in the AppHost

2. Connect from your consuming app

   When you reference a SurrealDB resource from a consuming app, Aspire injects its connection information as environment variables. See Connect to SurrealDB for the connection properties reference and per-language examples for C#, Go, Python, and TypeScript — including the full C# client integration.

   Connect to SurrealDB

See also

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