Embedding in .NET

SurrealDB is designed to be run in many different ways, and environments. Due to the separation of the storage and compute layers, SurrealDB can be run in embedded mode, from within a number of different language environments. In .NET, SurrealDB can be run as an in-memory database, or it can persist data using a file-based storage engine.

Memory provider

The memory provider is a simple in-memory database that is useful in some contexts. It can be extremely useful for testing scenarios, or for small applications that do not require persistence.

dotnet add package SurrealDb.Embedded.InMemory

Consume the provider as-is

The simplest way to use an in-memory database instance of SurrealDB is to create an instance of the SurrealDbMemoryClient class.

using var db = new SurrealDbMemoryClient();

const string TABLE = "person";

var person = new Person
{
    Title = "Founder & CEO",
    Name = new() { FirstName = "Tobie", LastName = "Morgan Hitchcock" },
    Marketing = true
};
var created = await db.Create(TABLE, person);
Console.WriteLine(ToJsonString(created));

Consume the provider via Dependency Injection

Following the .NET Dependency Injection pattern, you can register the in-memory provider using the AddInMemoryProvider extension method. This will allow the SurrealDbClient to resolve the mem:// endpoint.

var builder = WebApplication.CreateBuilder(args);

var services = builder.Services;
var configuration = builder.Configuration;

services
  .AddSurreal("Endpoint=mem://")
  .AddInMemoryProvider();

Learn more about Dependency Injection with SurrealDB in .NET in the SDK documentation.

Once the memory provider is configured, you can use the .NET SDK the same way you would with a remote database. Please refer to the .NET client SDK documentation to get started with SurrealDB for .NET.

File providers

The file provider is a more advanced storage engine that can be used to persist data to disk.

dotnet add package SurrealDb.Embedded.RocksDb

dotnet add package SurrealDb.Embedded.SurrealKv

Consume the provider as-is

using var db = new SurrealDbRocksDbClient("data.db");

const string TABLE = "person";

var person = new Person
{
    Title = "Founder & CEO",
    Name = new() { FirstName = "Tobie", LastName = "Morgan Hitchcock" },
    Marketing = true
};
var created = await db.Create(TABLE, person);
Console.WriteLine(ToJsonString(created));

using var db = new SurrealDbKvClient("data.db");

const string TABLE = "person";

var person = new Person
{
    Title = "Founder & CEO",
    Name = new() { FirstName = "Tobie", LastName = "Morgan Hitchcock" },
    Marketing = true
};
var created = await db.Create(TABLE, person);
Console.WriteLine(ToJsonString(created));

Consume the provider via Dependency Injection

var builder = WebApplication.CreateBuilder(args);

var services = builder.Services;
var configuration = builder.Configuration;

services
  .AddSurreal("Endpoint=rocksdb://data.db")
  .AddRocksDbProvider();

var builder = WebApplication.CreateBuilder(args);

var services = builder.Services;
var configuration = builder.Configuration;

services
  .AddSurreal("Endpoint=surrealkv://data.db")
  .AddSurrealKvProvider();

Learn more about Dependency Injection with SurrealDB in .NET in the SDK documentation.

Next step

Once the file provider is configured, you can use the .NET SDK the same way you would with a remote database. Please refer to the .NET client SDK documentation to get started.