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.
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.
NoteThis 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:
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.
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.
NoteIf 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 serde::{Deserialize, Serialize}; use surrealdb::engine::any; use surrealdb::opt::auth::Root; use tokio; struct Person { name: String, } async fn main() -> Result<(), Box<dyn std::error::Error>> { // Open a connection let db = any::connect("wss://cloud-docs-068rp16e0hsnl62vgooa7omjks.aws-euw1.staging.surrealdb.cloud").await?; // Select a namespace and database db.use_ns("Cloud Namespace").use_db("Cloud Database").await?; // Authenticate db.signin(Root { username: "<created root user>", password: "<created root password>", }).await?; db.query("CREATE person:john SET name = 'John Doe', age = 25").await?.check()?; // Query that person let john: Option<Person> = db.select(("person", "john")).await?; dbg!(john); Ok(()) }
import { Surreal, RecordID } from "surrealdb"; const db = new Surreal(); // Open a connection and authenticate await db.connect("wss://cloud-docs-068rp16e0hsnl62vgooa7omjks.aws-euw1.staging.surrealdb.cloud", { // Declare the namespace and database in the connection string there is no need to use the `use` method namespace: "Cloud Namespace", database: "Cloud Database", auth: { username: "<created root user>", password: "<created root password>", } }); // If you want to select a specific namespace / database outside the connection string, you can use the `use` method // await db.use({ ns: 'Cloud Namespace', db: 'Cloud Database' }); // Create record await db.create(new RecordID("person"), { title: "Founder & CEO", name: { first: "Tobie", last: "Morgan Hitchcock", }, tags: ["python", "documentation"], }); // Select all records in person table console.log(await db.select("person")); await db.close();
from surrealdb import Surreal, RecordID # Open a connection with Surreal(url="wss://cloud-demo-06a98cg0u1qs3d4mnl774mlq8k.aws-use1.surreal.cloud") as db: # Select a namespace and database db.use("Cloud Namespace", "Cloud Database") # Authenticate db.signin(username="<created root user>", password="<created root password>") # Create a record db.create(RecordID("grocery", "1"), { "name": "Banana", "quantity": 10, }) # Select a specific record print(db.select(RecordID("grocery", "1")))
using SurrealDb.Net; using SurrealDb.Net.Models; using SurrealDb.Net.Models.Auth; using System.Text.Json; const string TABLE = "person"; using var db = new SurrealDbClient("wss://cloud-docs-068rp16e0hsnl62vgooa7omjks.aws-euw1.staging.surrealdb.cloud/rpc"); await db.SignIn(new RootAuth { Username = "<created root user>", Password = "<created root password>" }); await db.Use("Cloud Namespace", "Cloud Database"); // Create a new instance of a person with nested properties var person = new Person { Title = "Founder & CEO", Name = new() { FirstName = "Tobie", LastName = "Morgan Hitchcock" }, Marketing = true }; // Create a new record in the database and store the result var created = await db.Create(TABLE, person); Console.WriteLine(ToJsonString(created)); // Merge (update) an existing record with new marketing value // Uses generic types to specify the merge data and return type var updated = await db.Merge<ResponsibilityMerge, Person>( new() { Id = (TABLE, "jaime"), Marketing = true } ); Console.WriteLine(ToJsonString(updated)); // Select all records from the person table var people = await db.Select<Person>(TABLE); Console.WriteLine(ToJsonString(people)); // Perform a grouped query to count records by marketing status var queryResponse = await db.Query( $"SELECT Marketing, count() AS Count FROM type::table({TABLE}) GROUP BY Marketing" ); var groups = queryResponse.GetValue<List<Group>>(0); Console.WriteLine(ToJsonString(groups)); static string ToJsonString(object? o) { return JsonSerializer.Serialize(o, new JsonSerializerOptions { WriteIndented = true, }); } public class Person : Record { public string? Title { get; set; } public Name? Name { get; set; } public bool Marketing { get; set; } } public class Name { public string? FirstName { get; set; } public string? LastName { get; set; } } public class ResponsibilityMerge : Record { public bool Marketing { get; set; } } public class Group { public bool Marketing { get; set; } public int Count { get; set; } } // Run dotnet run
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>" ]);
Learn more about the SurrealDB SDKs in the SurrealDB documentation.