SurrealDb.Net 0.6.0

dotnet add package SurrealDb.Net --version 0.6.0                
NuGet\Install-Package SurrealDb.Net -Version 0.6.0                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="SurrealDb.Net" Version="0.6.0" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add SurrealDb.Net --version 0.6.0                
#r "nuget: SurrealDb.Net, 0.6.0"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install SurrealDb.Net as a Cake Addin
#addin nuget:?package=SurrealDb.Net&version=0.6.0

// Install SurrealDb.Net as a Cake Tool
#tool nuget:?package=SurrealDb.Net&version=0.6.0                

<br>

<p align="center"> <img width=120 src="https://raw.githubusercontent.com/surrealdb/icons/main/surreal.svg" />   <img width=120 src="https://raw.githubusercontent.com/surrealdb/icons/main/dotnet.svg" /> </p>

<h3 align="center">The official SurrealDB SDK for .NET.</h3>

<br>

<p align="center"> <a href="https://github.com/surrealdb/surrealdb.net"><img src="https://img.shields.io/badge/status-beta-ff00bb.svg?style=flat-square"></a>   <a href="https://surrealdb.com/docs/integration/libraries/dotnet"><img src="https://img.shields.io/badge/docs-view-44cc11.svg?style=flat-square"></a>   <a href="https://www.nuget.org/packages/SurrealDb.Net"><img src="https://img.shields.io/nuget/v/surrealdb.net?style=flat-square"></a>   <a href="https://www.nuget.org/packages/SurrealDb.Net"><img src="https://img.shields.io/nuget/dt/surrealdb?style=flat-square"></a>   <a href="https://codecov.io/github/surrealdb/surrealdb.net"><img src="https://img.shields.io/codecov/c/github/surrealdb/surrealdb.net?style=flat-square"></a> </p>

<p align="center"> <a href="https://surrealdb.com/discord"><img src="https://img.shields.io/discord/902568124350599239?label=discord&style=flat-square&color=5a66f6"></a>   <a href="https://twitter.com/surrealdb"><img src="https://img.shields.io/badge/twitter-follow_us-1d9bf0.svg?style=flat-square"></a>   <a href="https://www.linkedin.com/company/surrealdb/"><img src="https://img.shields.io/badge/linkedin-connect_with_us-0a66c2.svg?style=flat-square"></a>   <a href="https://www.youtube.com/channel/UCjf2teVEuYVvvVC-gFZNq6w"><img src="https://img.shields.io/badge/youtube-subscribe-fc1c1c.svg?style=flat-square"></a> </p>

surrealdb.net

The official SurrealDB SDK for .NET.

Documentation

View the SDK documentation here.

How to install

dotnet add package SurrealDb.Net

Getting started

This library supports connecting to SurrealDB over the remote HTTP and WebSocket connection protocols http, https, ws, and wss.

The examples below require SurrealDB to be installed and running on port 8000.

Constructing a new SurrealDB client

You can easily create a new SurrealDB client. All you have to do is define the endpoint to the SurrealDB instance.

var clientHttp = new SurrealDbClient("http://127.0.0.1:8000");
var clientHttps = new SurrealDbClient("https://127.0.0.1:8000");
var clientWs = new SurrealDbClient("ws://127.0.0.1:8000/rpc");
var clientWss = new SurrealDbClient("wss://127.0.0.1:8000/rpc");

// Now you can call other methods including Signin & Use

Dependency injection

You can use Dependency Injection with the services.AddSurreal() function.

Default instance
var options = SurrealDbOptions
	.Create()
	.WithEndpoint("http://127.0.0.1:8000")
	.WithNamespace("test")
	.WithDatabase("test")
	.WithUsername("root")
	.WithPassword("root")
	.Build();

services.AddSurreal(options);

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 Singleton. 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": "Server=http://127.0.0.1:8000;Namespace=test;Database=test;Username=root;Password=root"
  }
}

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

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

It will automatically create a new SurrealDB using the Server endpoint and configure the client using the different values for namespace, database, username and password. 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"));
services.AddSurreal<IBackupSurrealDbClient>(configuration.GetConnectionString("SurrealDB.Backup"));
services.AddSurreal<IMonitoringSurrealDbClient>(configuration.GetConnectionString("SurrealDB.Monitoring"));

Here you will have 3 instances:

  • the default one, you can keep using ISurrealDbClient interface or SurrealDbClient class anywhere
  • a client for backup purpose, using the IBackupSurrealDbClient interface
  • a 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.Patch(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();
	}
}

Contributing

.NET release versions

The .NET release versions must follow these rules:

  • Should target at least the latest LTS (Long-Term Support) version
  • Should target at least the latest STS (Standard-Term Support) version

SurrealDb.Net targets .NET versions following the .NET Support Policy by Microsoft. Additionally, SurrealDb.Net targets .NET Standard 2.1 explicitly to continue support of the Mono runtime (Unity, Xamarin, etc...).

Note that the support for .NET standard 2.1 will be maintained until further notice.

Version Description Release Date End of Support
.NET Standard 2.1 June 27, 2016 N/A
.NET 6 LTS November 8, 2021 November 12, 2024
.NET 7 STS November 8, 2022 May 14, 2024
.NET 8 Current LTS November 14, 2023 November 10, 2026

Formatting

This project is using CSharpier, an opinionated code formatter.

Command line

You can install it on your machine via dotnet tool.

# Run this command at the root of the project
dotnet tool install csharpier

You can then use it as a cli:

dotnet csharpier .

The list of command-line options is available here: https://csharpier.com/docs/CLI

IDE integration

CSharpier supports multiple code editors, including Visual Studio, Jetbrains Rider, VSCode and Neovim. You will be able to run format on file save after configuring the settings in your IDE.

Testing

This project was written following testing best practices:

  • TDD, leveraging:
    • clean code/architecture
    • regression testing
    • adding new features and tests easily
  • a vast majority of tests are integration tests, ensuring compatibility with a concrete SurrealDB version
  • each integration test is using a separate SurrealDB namespace/database

Unit/Integration tests are written using xUnit and FluentAssertions.

You will need a local SurrealDB instance alongside the tests. Start one using the following command:

surreal start --log debug --user root --pass root memory --allow-guests

Once ready, go to the root directory of the project and run the following command:

dotnet watch test --project SurrealDb.Net.Tests

Due to the asynchronous nature of Live Queries, they are tested against a separate project named SurrealDb.Net.LiveQuery.Tests. Where the default test project allow full parallelization, this project completely disable test parallelization. To execute tests on Live Queries, run the following command:

dotnet watch test --project SurrealDb.Net.LiveQuery.Tests

Note 1: Because Live Query tests are not run in parallel, it can take quite some time to run all tests.

Note 2: You can run the two test projects in parallel.

Benchmarking

This project also contains benchmarks in order to detect possible performance regressions.

You will need a local SurrealDB instance alongside the tests. Start one using the following command:

surreal start --user root --pass root memory --allow-guests

Once ready, go to the root directory of the project and run the following command:

dotnet run -c Release --project SurrealDb.Net.Benchmarks.Remote --filter '*'
./prepare_embedded_benchmarks.sh -s
dotnet run -c Release --project SurrealDb.Net.Benchmarks.Embedded --filter '*'
./prepare_embedded_benchmarks.sh -e

For Windows:

./prepare_embedded_benchmarks.ps1 -s
dotnet run -c Release --project SurrealDb.Net.Benchmarks.Embedded --filter '*'
./prepare_embedded_benchmarks.ps1 -e
Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.1 is compatible. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (3)

Showing the top 3 NuGet packages that depend on SurrealDb.Net:

Package Downloads
CloudTheWolf.DSharpPlus.Scaffolding.Data

Database System for CloudTheWolf.DSharpPlus.Scaffolding

SurrealDb.Reactive

Reactive Extensions for the SurrealDB library for .NET

SurrealDb.Embedded.InMemory

In-memory provider for the SurrealDB library for .NET

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
0.6.0 666 10/21/2024
0.5.1 1,670 7/12/2024
0.5.0 3,657 4/4/2024
0.4.0 853 2/8/2024
0.3.1 468 1/19/2024
0.2.0 1,130 11/21/2023
0.1.4 2,673 10/25/2023
0.1.3 355 9/25/2023