Create a new connection

After installing the SDK, you can initialize a new instance of a SurrealDB client. When creating a new connection to a SurrealDB instance, you can choose to connect to a local or remote endpoint.

using SurrealDb.Net;

using var db = new SurrealDbClient("ws://127.0.0.1:8000/rpc");

await db.Connect();
await db.Use("test", "test");

From the code snippet above, you can see that the .NET SDK has a couple of methods that you can use to initialize a new project with SurrealDB.

SurrealDbClient

Creates a new client, detecting the right protocol from the provided endpoint.

new SurrealDbClient(endpoint)

Connection options

You can specify your connection protocol either as http, https, ws, or wss. Since SurrealDB also supports RPC over WebSocket, by default, it is specified with a /rpc suffix.

// Creates a new client using a local endpoint
using var db = new SurrealDbClient("http://127.0.0.1:8000");

// Creates a new client using a remote endpoint
using var db = new SurrealDbClient("wss://cloud.surrealdb.com/rpc");

var options = new SurrealDbOptions
{
    Endpoint = "wss://cloud.surrealdb.com/rpc",
    Namespace = "surrealdb",
    Database = "docs",
};

// Specify a namespace and database pair to use
using var db = new SurrealDbClient(options);

var options = new SurrealDbOptions
{
    Endpoint = "wss://cloud.surrealdb.com/rpc",
    Token = "......",
};

// Authenticate with an existing token
using var db = new SurrealDbClient(options);

var options = new SurrealDbOptions
{
    Endpoint = "wss://cloud.surrealdb.com/rpc",
    Username = "root",
    Password = "surrealdb",
};

// Authenticate using a pair of credentials
using var db = new SurrealDbClient(options);

Effect of connection protocol on token & session duration

The connection protocol you choose affects how authentication tokens and sessions work:

With websockets connections (ws://, wss://) you open a single long-lived stateful connection where after the initial authentication, the session duration applies and if not specified, defaults to NONE meaning that the session never expires unless otherwise specified.

When you connect with a HTTP connection (http://, https://), every request you make is short-lived and stateless, requiring you to authenticate every request individually for which the token is used, creating a short lived session. Hence, the token duration which defaults to 1 hour applies.

You can extend the session duration of a token or a session by setting the DURATION clause when creating a new access method with the DEFINE ACCESS METHOD statement or when defining a new user with the DEFINE USER statement.

Learn more about token and session duration in our security best practices documentation.

.Connect()

The .Connect() executes a connection attempt to the underlying endpoint using the provided connection options.

Example usage

await db.Connect();

.Use()

Depending on the complexity of your use case, you can switch to a specific namespace and database using the .Use() method. This is particularly useful if you want to switch to a different setup after connecting.

Learn more about the .Use() method in the methods section.

Example usage

await db.Use("test", "test");