Connect via SDK

Once you have created a Surreal Cloud Instance, you can connect to it using any of the available SDKs. This allows you to interact with your Surreal Cloud Instance programmatically.

After you have selected your SDK, you will need to provide your connection details which will populate the code snippet to your Surreal Cloud Instance.

Enter connection details

When using any of the SurrealDB SDKs, before you can start querying your Surreal Cloud Instance, you will need to provide your connection details. SurrealDB requires namespace & database details so that it knows where to run and store your data. Learn more about namespaces and databases in the SurrealDB documentation.

Create a root authentication

Note

This step is only required if you are authenticating using the signin method on your initial connection. Learn more about access methods and system Users in the SurrealDB documentation.

First navigate to the Authentication panel of Surrealist. There, you can create a root user by clicking on the + button in the Root Authentication section.

In the dialog that appears, select either:

• new system user: create a root user by entering a username, password, and selecting a role to define their access level to Instance resources and permissions
• new access method: create an access method by entering a name and selecting the type to define its access level to Instance resources and permissions

For both options, you can configure the Token duration and session duration.

After creating your root authentication, you will be able to authenticate with your Surreal Cloud Instance using any of the available SDKs.

If you want to create a Namespace and Database authentication for record-level access, you will need to first create a Namespace and Database. Learn more about namespaces and databases in the SurrealDB documentation.

Connect to your Surreal Cloud Instance

After you have created your root authentication for root-level access, you can use the credentials to sign in to your Surreal Cloud Instance.

The connect method takes your Surreal Cloud connection string as an argument to connect to your Surreal Cloud Instance. You can then fill in the namespace and database details to select the specific namespace and database you want to use.

If you are using a system user option of the root authentication, you can also fill in the username and password details to sign in to your Surreal Cloud Instance.

Note

If you are using a non-root user, depending on the access method you have created, you will need to fill in the access details to sign in to your Surreal Cloud Instance. Please refer to the documentation for your specific SDK for more information.

Below are examples of how you can connect to your Instance using the SurrealDB SDK:

use surrealdb::engine::remote::ws::Wss;
use surrealdb::opt::auth::Root;
use surrealdb::Surreal;

#[tokio::main]
async fn main() -> surrealdb::Result<()> {
	// Connect to the server
	let db = Surreal::new::<Wss>("cloud-docs-068rp16e0hsnl62vgooa7omjks.aws-euw1.staging.surrealdb.cloud").await?;

	// Signin as a namespace, database, or root user
	db.signin(Root {
		username: "<created root user>",
		password: "<created root password>",
	})
	.await?;

	// Select a specific namespace / database
	db.use_ns("Cloud Namespace").use_db("Cloud Database").await?;

	Ok(())
}

import { Surreal } from "surrealdb";
const db = new Surreal();

// Connect to the server
await db.connect('wss://cloud-docs-068rp16e0hsnl62vgooa7omjks.aws-euw1.staging.surrealdb.cloud');

// Signin as a namespace, database, or root user
await db.signin({
	username: '<created root user>',
	password: '<created root password>',
});

// Select a specific namespace / database
await db.use({ ns: 'Cloud Namespace', db: 'Cloud Database' });

# Open a connection
async with Surreal(url="wss://cloud-demo-06a98cg0u1qs3d4mnl774mlq8k.aws-use1.surreal.cloud") as db:
# Select a namespace and database
await db.use('Cloud Namespace', 'Cloud Database')
# Authenticate
await db.signin({"username"="<created root user>", "password"="<created root password>"})

using SurrealDb.Net;
using SurrealDb.Net.Models.Auth;

using var db = new SurrealDbClient("https://cloud-docs-068rp16e0hsnl62vgooa7omjks.aws-euw1.staging.surrealdb.cloud/rpc");

// Select a namespace and database
await db.Use("Cloud Namespace", "Cloud Database");

// Authenticate
await db.SignIn(new RootAuth
{
    Username = "<created root user>",
    Password = "<created root password>",
});

db = new Surreal();

$db->connect("wss://cloud-docs-068rp16e0hsnl62vgooa7omjks.aws-euw1.staging.surrealdb.cloud/rpc", [
    "namespace" => "Cloud Namespace",
    "database" => "Cloud Database",
    "versionCheck" => false // <-- optional ( default: true )
]);

$db->signin([
   "username" => "<created root user>",
   "password" => "<created root password>"
]);

Next steps

Learn more about the SurrealDB SDKs in the SurrealDB documentation.