Struct SurrealClient 

pub struct SurrealClient { /* private fields */ }

Implementations

impl SurrealClient

pub fn new( engine: Box<dyn Engine>, namespace: Option<String>, database: Option<String>, ) -> Self

Create a new SurrealDB instance with the given engine and optional namespace/database

pub fn with_debug(self, enabled: bool) -> Self

Enable debug mode to log queries

pub fn is_debug(&self) -> bool

Check if debug mode is enabled

pub async fn let_var(&mut self, key: &str, value: Value) -> Result<()>

Set a parameter for the session

pub async fn unset(&mut self, key: &str) -> Result<()>

Unset a parameter from the session

pub async fn create(&self, resource: &str, data: Option<Value>) -> Result<Value>

Create a record in the database

pub async fn select(&self, resource: &str) -> Result<Value>

Select records from the database

pub async fn select_all(&self, table: Table) -> Result<Value>

Select all records from a table

pub async fn select_record(&self, record: RecordId) -> Result<Value>

Select a specific record by ID

pub async fn select_range(&self, range: RecordRange) -> Result<Value>

Select a range of records

pub async fn update(&self, resource: &str, data: Option<Value>) -> Result<Value>

Update records in the database

pub async fn update_record( &self, record: RecordId, data: Value, ) -> Result<Value>

Update a specific record by ID

pub async fn update_all(&self, table: Table, data: Value) -> Result<Value>

Update all records in a table

pub async fn upsert(&self, resource: &str, data: Option<Value>) -> Result<Value>

Upsert (insert or update) records in the database

pub async fn upsert_record( &self, record: RecordId, data: Value, ) -> Result<Value>

Upsert a specific record by ID

pub async fn merge(&self, resource: &str, data: Value) -> Result<Value>

Merge data into records in the database

pub async fn merge_record(&self, record: RecordId, data: Value) -> Result<Value>

Merge data into a specific record by ID

pub async fn merge_all(&self, table: Table, data: Value) -> Result<Value>

Merge data into all records in a table

pub async fn patch(&self, resource: &str, patches: Vec<Value>) -> Result<Value>

Apply JSON patches to records Apply patches to records in the database

pub async fn delete(&self, resource: &str) -> Result<Value>

Delete records from the database

pub async fn delete_record(&self, record: RecordId) -> Result<Value>

Delete a specific record by ID

pub async fn delete_all(&self, table: Table) -> Result<Value>

Delete all records from a table

pub async fn insert(&self, table: &str, data: Value) -> Result<Value>

Insert records into the database Insert data into a table

pub async fn insert_many(&self, table: Table, data: Vec<Value>) -> Result<Value>

Insert multiple records

pub async fn relate( &self, from: &str, relation: &str, to: &str, data: Option<Value>, ) -> Result<Value>

Create a relation between records

pub async fn relate_records( &self, from: RecordId, relation: Table, to: RecordId, data: Option<Value>, ) -> Result<Value>

Create a relation between specific records

pub async fn run(&self, func: &str, args: Option<Value>) -> Result<Value>

Run a stored function

pub async fn query(&self, sql: &str, variables: Option<Value>) -> Result<Value>

Execute a custom SurrealQL query

Examples found in repository

examples/cloud_token.rs (line 29)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let token = std::env::var("SURREAL_TOKEN").expect("set SURREAL_TOKEN");
    let host = std::env::var("SURREAL_HOST").unwrap_or_else(|_| {
        "wss://close-wasp-06fmkfm5uhq2f77ih987dcdac4.aws-euw1.surreal.cloud".into()
    });
    let query = std::env::var("SURREAL_QUERY")
        .unwrap_or_else(|_| "USE NS main DB `vantage-leads`; INFO FOR DB;".into());

    println!("connecting to {host} ...");
    let client = SurrealConnection::dsn(&host)?
        .auth_token(token)
        .version_check(false)
        .connect()
        .await?;
    println!(
        "connected. server version = {:?}\n",
        client.version().await?
    );

    let result = client.query(&query, None).await?;
    println!("{}", serde_json::to_string_pretty(&result)?);

    Ok(())
}

pub async fn info(&self) -> Result<Value>

Get information about the current session

pub async fn version(&self) -> Result<String>

Get the version of the SurrealDB instance

Examples found in repository

examples/cloud_token.rs (line 26)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let token = std::env::var("SURREAL_TOKEN").expect("set SURREAL_TOKEN");
    let host = std::env::var("SURREAL_HOST").unwrap_or_else(|_| {
        "wss://close-wasp-06fmkfm5uhq2f77ih987dcdac4.aws-euw1.surreal.cloud".into()
    });
    let query = std::env::var("SURREAL_QUERY")
        .unwrap_or_else(|_| "USE NS main DB `vantage-leads`; INFO FOR DB;".into());

    println!("connecting to {host} ...");
    let client = SurrealConnection::dsn(&host)?
        .auth_token(token)
        .version_check(false)
        .connect()
        .await?;
    println!(
        "connected. server version = {:?}\n",
        client.version().await?
    );

    let result = client.query(&query, None).await?;
    println!("{}", serde_json::to_string_pretty(&result)?);

    Ok(())
}

pub async fn close(self) -> Result<()>

Close the connection

pub async fn import( &self, _content: &str, _username: &str, _password: &str, ) -> Result<Value>

Import database content (HTTP only)

pub async fn export(&self, _username: &str, _password: &str) -> Result<String>

Export database content (HTTP only)

pub async fn import_ml( &self, _content: &str, _username: Option<&str>, _password: Option<&str>, ) -> Result<Value>

Import ML model (HTTP only)

pub async fn export_ml( &self, _name: &str, _version: Option<&str>, _username: Option<&str>, _password: Option<&str>, ) -> Result<String>

Export ML model (HTTP only)

pub async fn live(&self, resource: &str) -> Result<LiveStream>

Start a live query on a table (or record) and stream change notifications.

Issues the live RPC, then registers the returned live-query id with the engine so its read loop forwards every matching CREATE/UPDATE/ DELETE frame onto the returned LiveStream. Requires a WebSocket connection — request/response-only engines return an error from Engine::register_live.

The stream stays open until the connection closes; call kill with the stream’s query_id to release the server-side query early.

pub async fn kill(&self, query_id: &str) -> Result<()>

Stop a live query by its id (the LiveStream::query_id).

Sends the kill RPC and drops the local subscriber so no further notifications are delivered for that id.

pub async fn query_cbor( &self, sql: &str, variables: CborValue, ) -> Result<CborValue>

Execute a custom SurrealQL query with CBOR parameters

Trait Implementations

impl Clone for SurrealClient

fn clone(&self) -> Self

Clone the client - creates a new client instance sharing the same engine and session

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.