SurrealDb.Net
0.7.0
dotnet add package SurrealDb.Net --version 0.7.0
NuGet\Install-Package SurrealDb.Net -Version 0.7.0
<PackageReference Include="SurrealDb.Net" Version="0.7.0" />
paket add SurrealDb.Net --version 0.7.0
#r "nuget: SurrealDb.Net, 0.7.0"
// Install SurrealDb.Net as a Cake Addin #addin nuget:?package=SurrealDb.Net&version=0.7.0 // Install SurrealDb.Net as a Cake Tool #tool nuget:?package=SurrealDb.Net&version=0.7.0
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.
using var clientHttp = new SurrealDbClient("http://127.0.0.1:8000");
using var clientHttps = new SurrealDbClient("https://127.0.0.1:8000");
using var clientWs = new SurrealDbClient("ws://127.0.0.1:8000/rpc");
using 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 orSurrealDbClient
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.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();
}
}
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.
Product | Versions 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. net9.0 is compatible. |
.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. |
-
.NETStandard 2.1
- ConcurrentHashSet (>= 1.3.0)
- Dahomey.Cbor (>= 1.24.3)
- Microsoft.Extensions.Http (>= 8.0.0)
- Microsoft.IO.RecyclableMemoryStream (>= 3.0.1)
- Microsoft.Spatial (>= 7.18.0)
- Semver (>= 2.3.0)
- System.Collections.Immutable (>= 8.0.0)
- SystemTextJsonPatch (>= 4.0.0)
- Websocket.Client (>= 5.1.1)
-
net6.0
- ConcurrentHashSet (>= 1.3.0)
- Dahomey.Cbor (>= 1.24.3)
- Microsoft.Extensions.Http (>= 8.0.0)
- Microsoft.IO.RecyclableMemoryStream (>= 3.0.1)
- Microsoft.Spatial (>= 7.18.0)
- Semver (>= 2.3.0)
- System.Collections.Immutable (>= 8.0.0)
- SystemTextJsonPatch (>= 4.0.0)
- Websocket.Client (>= 5.1.1)
-
net7.0
- ConcurrentHashSet (>= 1.3.0)
- Dahomey.Cbor (>= 1.24.3)
- Microsoft.Extensions.Http (>= 8.0.0)
- Microsoft.IO.RecyclableMemoryStream (>= 3.0.1)
- Microsoft.Spatial (>= 7.18.0)
- Semver (>= 2.3.0)
- System.Collections.Immutable (>= 8.0.0)
- SystemTextJsonPatch (>= 4.0.0)
- Websocket.Client (>= 5.1.1)
-
net8.0
- ConcurrentHashSet (>= 1.3.0)
- Dahomey.Cbor (>= 1.24.3)
- Microsoft.Extensions.Http (>= 8.0.0)
- Microsoft.IO.RecyclableMemoryStream (>= 3.0.1)
- Microsoft.Spatial (>= 7.18.0)
- Semver (>= 2.3.0)
- System.Collections.Immutable (>= 8.0.0)
- SystemTextJsonPatch (>= 4.0.0)
- Websocket.Client (>= 5.1.1)
-
net9.0
- ConcurrentHashSet (>= 1.3.0)
- Dahomey.Cbor (>= 1.24.3)
- Microsoft.Extensions.Http (>= 8.0.0)
- Microsoft.IO.RecyclableMemoryStream (>= 3.0.1)
- Microsoft.Spatial (>= 7.18.0)
- Semver (>= 2.3.0)
- System.Collections.Immutable (>= 8.0.0)
- SystemTextJsonPatch (>= 4.0.0)
- Websocket.Client (>= 5.1.1)
NuGet packages (5)
Showing the top 5 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 |
|
SurrealDb.Embedded.RocksDb
File provider for the SurrealDB library for .NET, backed by RocksDB |
|
SurrealDb.Embedded.SurrealKv
File provider for the SurrealDB library for .NET, backed by SurrealKV |
GitHub repositories
This package is not used by any popular GitHub repositories.