This repository is no longer under active development, please use surrealdb.net instead

Surreal .NET

Database driver for SurrealDB available for REST and RPC sessions.

(unofficial)

Table of contents

Table of contents
About
- Primary NuGet Packages
- Documentation
Quick-start
Coverage
Contributing
Contributors ✨

About

Surreal .NET is a database driver for SurrealDB. The connector can access the database via JSON-RPC as well as REST.

Primary NuGet Packages

Name	Description	Nuget
`SurrealDB.Driver.Rpc`	Websocket RPC based database driver for SurrealDB
`SurrealDB.Driver.Rest`	REST based database driver for SurrealDB.
`SurrealDB.Extensions.Service`	Service integration into the ASP.NET Core ecosystem.

Documentation

The API Documentation is available here

Quick-start

Firstly install SurrealDB on your system. See the installation instructions:

# Brew
brew install surrealdb/tap/surreal
# Linux
curl -sSf https://install.surrealdb.com | sh
# Windows - system
choco install surreal --pre
# Windows - user
iwr https://windows.surrealdb.com -useb | iex

While Surreal .NET can be registered as a ASP.NET Core service for usage in a web API, the library can also be included in a console app.

I highly recommend taking a looksie at the examples, but for now let's review a basic console app with the RPC library.

<PackageReference Include="SurrealDB.Driver.Rest" Version="1.0.8" />

using SurrealDB.Configuration;
using SurrealDB.Driver.Rpc;
using SurrealDB.Models;

// start server: surreal start -b 0.0.0.0:8082 -u root -p root --log debug
// Create a configuration for the sever specified above.
Config cfg = Config.Create()
    .WithEndpoint("127.0.0.1:8082")
    .WithDatabase("test")
    .WithNamespace("test")
    .WithBasicAuth("root", "root")
    // Tell the configuration to connect to the server using RPC, and without TLS.
    .WithRpc(insecure: true).Build();

// Create a RPC database connection with the configuration.
DatabaseRpc db = new(cfg);
// Connect using the defined connection.
await db.Open();
// Create a struct with the fields we want to insert, nesting is supported.
Person you = new("Max Mustermann", 39, new("Musterstraße 1", 12345, "Musterstadt"), "0123456789", "max@mustermann.de");
// Insert the struct into the database, table = person, id = maxmustermann.
// If id` is not specified it will be random-generated, the id can be read from the response.
RpcResponse create = await db.Create("person:maxmustermann", you);
// Read the struct from the database to verify it was inserted correctly.
RpcResponse select = await db.Select("person:maxmustermann");
if (select.TryGetResult(out Result result)) {
    // Prints: {"address":{"city":"Musterstadt","street":"Musterstraße 1","zip":12345},"age":39,"email":"max@mustermann.de","id":"test:maxmustermann","name":"Max Mustermann","phone":"0123456789"}
    Console.WriteLine(result.Inner);
    Person alsoYou = result.GetObject<Person>();
    // Prints: Yes we equals? True
    Console.WriteLine($"Yes we equals? {you == alsoYou}");
}


/// <summary>
/// A Person.
/// </summary>
record struct Person(string name, int age, Address address, string phone, string email);

/// <summary>
/// The address of one or more people.
/// </summary>
record struct Address(string street, int zip, string city);

Coverage

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.