SurrealDb.Embedded.SurrealKv 1.0.0

surrealdb.net

File provider of the official SurrealDB SDK for .NET, backed by SurrealKV.

Documentation

View the SDK documentation here.

How to install

dotnet add package SurrealDb.Embedded.SurrealKv

Getting started

Constructing a new SurrealDB client

You can easily create a new SurrealDB client which will provide a file instance of SurrealDB, backed by SurrealKV.

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

Dependency injection

You can use Dependency Injection with the services.AddSurreal() and .AddSurrealKvProvider() functions.

Default instance

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

Then you will be able to use the ISurrealDbClient interface or SurrealDbClient class anywhere.

public class MyClass
{
  private readonly ISurrealDbClient _client;

  public MyClass(ISurrealDbClient client)
  {
    _client = client;
  }

  // ...
}

Note that the default lifetime of this service is Scoped. You can override this as follows:

services.AddSurreal(options, ServiceLifetime.Scoped);

Connection String

Consider the following appsettings.json file:

{
  "AllowedHosts": "*",
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "ConnectionStrings": {
    "SurrealDB": "Endpoint=surrealkv://data.db;Namespace=test;Database=test"
  }
}

You can use the Connection String instead of having to deal with a SurrealDbOptions.

services
  .AddSurreal(configuration.GetConnectionString("SurrealDB"))
  .AddSurrealKvProvider();

It will automatically create a new SurrealDB using the Client endpoint and configure the client using the different values for namespace, database. Note that these values are optional but the endpoint is still required.

Multiple instances

Having a default instance for a project is enough most of the time, but there may be times when you'd like to target multiple SurrealDB instances, either at different addresses or at the same address but inside different NS/DBs. You can use multiple instances as long as you provide 1 interface per client, as in the following example.

interface IBackupSurrealDbClient : ISurrealDbClient { }
interface IMonitoringSurrealDbClient : ISurrealDbClient { }

services
  .AddSurreal(configuration.GetConnectionString("SurrealDB.Main"))
  .AddSurrealKvProvider();
services.AddSurreal<IBackupSurrealDbClient>(configuration.GetConnectionString("SurrealDB.Backup"));
services.AddSurreal<IMonitoringSurrealDbClient>(configuration.GetConnectionString("SurrealDB.Monitoring"));

Here you will have 3 instances:

• the default one using the memory provider, you can keep using ISurrealDbClient interface or SurrealDbClient class anywhere
• a remote client for backup purpose, using the IBackupSurrealDbClient interface
• a remote client for monitoring purpose, using the IMonitoringSurrealDbClient interface

Use the client

[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
  private const string Table = "weatherForecast";

  private readonly ISurrealDbClient _surrealDbClient;

  public WeatherForecastController(ISurrealDbClient surrealDbClient)
  {
    _surrealDbClient = surrealDbClient;
  }

  [HttpGet]
  public Task<IEnumerable<WeatherForecast>> GetAll(CancellationToken cancellationToken)
  {
    return _surrealDbClient.Select<WeatherForecast>(Table, cancellationToken);
  }

  [HttpGet("{id}")]
  public async Task<IActionResult> Get(string id, CancellationToken cancellationToken)
  {
    var weatherForecast = await _surrealDbClient.Select<WeatherForecast>((Table, id), cancellationToken);

    if (weatherForecast is null)
      return NotFound();

    return Ok(weatherForecast);
  }

  [HttpPost]
  public Task<WeatherForecast> Create(CreateWeatherForecast data, CancellationToken cancellationToken)
  {
    var weatherForecast = new WeatherForecast
    {
      Date = data.Date,
      Country = data.Country,
      TemperatureC = data.TemperatureC,
      Summary = data.Summary
    };

    return _surrealDbClient.Create(Table, weatherForecast, cancellationToken);
  }

  [HttpPut]
  public Task<WeatherForecast> Update(WeatherForecast data, CancellationToken cancellationToken)
  {
    return _surrealDbClient.Upsert(data, cancellationToken);
  }

  [HttpPatch]
  public Task<IEnumerable<WeatherForecast>> PatchAll(
    JsonPatchDocument<WeatherForecast> patches,
    CancellationToken cancellationToken
  )
  {
    return _surrealDbClient.PatchAll(Table, patches, cancellationToken);
  }

  [HttpPatch("{id}")]
  public Task<WeatherForecast> Patch(
    string id,
    JsonPatchDocument<WeatherForecast> patches,
    CancellationToken cancellationToken
  )
  {
    return _surrealDbClient.Patch((Table, id), patches, cancellationToken);
  }

  [HttpDelete]
  public Task DeleteAll(CancellationToken cancellationToken)
  {
    return _surrealDbClient.Delete(Table, cancellationToken);
  }

  [HttpDelete("{id}")]
  public async Task<IActionResult> Delete(string id, CancellationToken cancellationToken)
  {
    bool success = await _surrealDbClient.Delete((Table, id), cancellationToken);

    if (!success)
      return NotFound();

    return Ok();
  }
}