Struct SurrealConnection

Source

pub struct SurrealConnection<C: Connection + Debug> { /* private fields */ }

Implementations§

Source §

impl<C: Connection + Debug> SurrealConnection<C>

Source

pub async fn init_doc<D: Document>(&self)

Source

pub async fn init_auth(&self)

Methods from Deref<Target = Surreal<C>>§

Source

pub fn use_ns(&self, ns: impl Into<String>) -> UseNs<'_, C>

Switch to a specific namespace

§Examples

db.use_ns("namespace").await?;

Source

pub fn use_db(&self, db: impl Into<String>) -> UseDb<'_, C>

Switch to a specific database

§Examples

db.use_db("database").await?;

Source

pub fn set( &self, key: impl Into<String>, value: impl Serialize + 'static, ) -> Set<'_, C>

Assigns a value as a parameter for this connection

§Examples

use serde::Serialize;

#[derive(Serialize)]
struct Name {
    first: String,
    last: String,
}

// Assign the variable on the connection
db.set("name", Name {
    first: "Tobie".into(),
    last: "Morgan Hitchcock".into(),
}).await?;

// Use the variable in a subsequent query
db.query("CREATE person SET name = $name").await?;

// Use the variable in a subsequent query
db.query("SELECT * FROM person WHERE name.first = $name.first").await?;

Source

pub fn unset(&self, key: impl Into<String>) -> Unset<'_, C>

Removes a parameter from this connection

§Examples

use serde::Serialize;

#[derive(Serialize)]
struct Name {
    first: String,
    last: String,
}

// Assign the variable on the connection
db.set("name", Name {
    first: "Tobie".into(),
    last: "Morgan Hitchcock".into(),
}).await?;

// Use the variable in a subsequent query
db.query("CREATE person SET name = $name").await?;

// Remove the variable from the connection
db.unset("name").await?;

Signs up a user with a specific record access method

§Examples

use serde::Serialize;
use surrealdb::opt::auth::Root;
use surrealdb::opt::auth::Record;

#[derive(Debug, Serialize)]
struct AuthParams {
    email: String,
    password: String,
}

// Sign in as root
db.signin(Root {
    username: "root",
    password: "root",
})
.await?;

// Select the namespace/database to use
db.use_ns("namespace").use_db("database").await?;

// Define the user record access
let surql = r#"
    DEFINE ACCESS user_access ON DATABASE TYPE RECORD DURATION 24h
    SIGNUP ( CREATE user SET email = $email, password = crypto::argon2::generate($password) )
    SIGNIN ( SELECT * FROM user WHERE email = $email AND crypto::argon2::compare(password, $password) )
"#;
db.query(surql).await?.check()?;

// Sign a user up
db.signup(Record {
    namespace: "namespace",
    database: "database",
    access: "user_access",
    params: AuthParams {
        email: "john.doe@example.com".into(),
        password: "password123".into(),
    },
}).await?;

Signs this connection in to a specific authentication level

§Examples

Namespace signin

use surrealdb::opt::auth::Root;
use surrealdb::opt::auth::Namespace;

// Sign in as root
db.signin(Root {
    username: "root",
    password: "root",
})
.await?;

// Select the namespace/database to use
db.use_ns("namespace").use_db("database").await?;

// Define the user
let surql = "DEFINE USER johndoe ON NAMESPACE PASSWORD 'password123'";
db.query(surql).await?.check()?;

// Sign a user in
db.signin(Namespace {
    namespace: "namespace",
    username: "johndoe",
    password: "password123",
}).await?;

Database signin

use surrealdb::opt::auth::Root;
use surrealdb::opt::auth::Database;

// Sign in as root
db.signin(Root {
    username: "root",
    password: "root",
})
.await?;

// Select the namespace/database to use
db.use_ns("namespace").use_db("database").await?;

// Define the user
let surql = "DEFINE USER johndoe ON DATABASE PASSWORD 'password123'";
db.query(surql).await?.check()?;

// Sign a user in
db.signin(Database {
    namespace: "namespace",
    database: "database",
    username: "johndoe",
    password: "password123",
}).await?;

Record signin

use serde::Serialize;
use surrealdb::opt::auth::Root;
use surrealdb::opt::auth::Record;

#[derive(Debug, Serialize)]
struct AuthParams {
    email: String,
    password: String,
}

// Select the namespace/database to use
db.use_ns("namespace").use_db("database").await?;

// Sign a user in
db.signin(Record {
    namespace: "namespace",
    database: "database",
    access: "user_access",
    params: AuthParams {
        email: "john.doe@example.com".into(),
        password: "password123".into(),
    },
}).await?;

Source

pub fn invalidate(&self) -> Invalidate<'_, C>

Invalidates the authentication for the current connection

§Examples

db.invalidate().await?;

Source

pub fn authenticate(&self, token: impl Into<Jwt>) -> Authenticate<'_, C>

Authenticates the current connection with a JWT token

§Examples

db.authenticate(token).await?;

Source

pub fn query(&self, query: impl IntoQuery) -> Query<'_, C>

Runs a set of SurrealQL statements against the database

§Examples

// Select the namespace/database to use
db.use_ns("namespace").use_db("database").await?;

// Run queries
let mut result = db
    .query("CREATE person")
    .query("SELECT * FROM type::table($table)")
    .bind(("table", "person"))
    .await?;

// Get the first result from the first query
let created: Option<Person> = result.take(0)?;

// Get all of the results from the second query
let people: Vec<Person> = result.take(1)?;

#[derive(serde::Deserialize)]
struct Country {
    name: String
}

// The .take() method can be used for error handling

// If the table has no defined schema, this query will
// create a `country` on the SurrealDB side, but...
let mut result = db
    .query("CREATE country")
    .await?;

// It won't deserialize into a Country struct
if let Err(e) = result.take::<Option<Country>>(0) {
    println!("Failed to make a country: {e:#?}");
    assert!(e.to_string().contains("missing field `name`"));
}

Source

pub fn select<O>(&self, resource: impl IntoResource<O>) -> Select<'_, C, O>

Selects all records in a table, or a specific record

§Examples

// Select the namespace/database to use
db.use_ns("namespace").use_db("database").await?;

// Select all records from a table
let people: Vec<Person> = db.select("person").await?;

// Select a range of records from a table
let people: Vec<Person> = db.select("person").range("jane".."john").await?;

// Select a specific record from a table
let person: Option<Person> = db.select(("person", "h5wxrf2ewk8xjxosxtyc")).await?;

// To listen for updates as they happen on a record, a range of records
// or entire table use a live query. This is done by simply calling `.live()`
// after this method. That gives you a stream of notifications you can listen on.
let mut stream = db.select(resource).live().await?;

while let Some(notification) = stream.next().await {
    // Use the notification
}

Source

pub fn create<R>(&self, resource: impl CreateResource<R>) -> Create<'_, C, R>

Creates a record in the database

§Examples

use serde::Serialize;

#[derive(Serialize)]
struct Settings {
    active: bool,
    marketing: bool,
}

#[derive(Serialize)]
struct User {
    name: &'static str,
    settings: Settings,
}

// Select the namespace/database to use
db.use_ns("namespace").use_db("database").await?;

// Create a record with a random ID
let person: Option<Person> = db.create("person").await?;

// Create a record with a specific ID
let record: Option<Person> = db.create(("person", "tobie"))
    .content(User {
        name: "Tobie",
        settings: Settings {
            active: true,
            marketing: true,
        },
    })
    .await?;

Source

pub fn insert<O>(&self, resource: impl IntoResource<O>) -> Insert<'_, C, O>

Insert a record or records into a table

§Examples

use serde::{Serialize, Deserialize};
use surrealdb::RecordId;

#[derive(Serialize)]
struct Settings {
    active: bool,
    marketing: bool,
}

#[derive(Serialize)]
struct User<'a> {
    name: &'a str,
    settings: Settings,
}

// Select the namespace/database to use
db.use_ns("namespace").use_db("database").await?;

// Insert a record with a specific ID
let person: Option<Person> = db.insert(("person", "tobie"))
    .content(User {
        name: "Tobie",
        settings: Settings {
            active: true,
            marketing: true,
        },
    })
    .await?;

// Insert multiple records into the table
let people: Vec<Person> = db.insert("person")
    .content(vec![
        User {
            name: "Tobie",
            settings: Settings {
                active: true,
                marketing: false,
            },
        },
        User {
            name: "Jaime",
            settings: Settings {
                active: true,
                marketing: true,
            },
        },
    ])
    .await?;

// Insert multiple records with pre-defined IDs
#[derive(Serialize)]
struct UserWithId<'a> {
    id: RecordId,
    name: &'a str,
    settings: Settings,
}

let people: Vec<Person> = db.insert("person")
    .content(vec![
        UserWithId {
            id: ("person", "tobie").into(),
            name: "Tobie",
            settings: Settings {
                active: true,
                marketing: false,
            },
        },
        UserWithId {
            id: ("person", "jaime").into(),
            name: "Jaime",
            settings: Settings {
                active: true,
                marketing: true,
            },
        },
    ])
    .await?;

// Insert multiple records into different tables
#[derive(Serialize)]
struct WithId<'a> {
    id: RecordId,
    name: &'a str,
}

let people: Vec<Person> = db.insert(())
    .content(vec![
        WithId {
            id: ("person", "tobie").into(),
            name: "Tobie",
        },
        WithId {
            id: ("company", "surrealdb").into(),
            name: "SurrealDB",
        },
    ])
    .await?;


// Insert relations
#[derive(Serialize, Deserialize)]
struct Founded {
    #[serde(rename = "in")]
    founder: RecordId,
    #[serde(rename = "out")]
    company: RecordId,
}

let founded: Vec<Founded> = db.insert("founded")
    .relation(vec![
        Founded {
            founder: ("person", "tobie").into(),
            company: ("company", "surrealdb").into(),
        },
        Founded {
            founder: ("person", "jaime").into(),
            company: ("company", "surrealdb").into(),
        },
    ])
    .await?;

Source

pub fn upsert<O>(&self, resource: impl IntoResource<O>) -> Upsert<'_, C, O>

Updates all records in a table, or a specific record

§Examples

Replace the current document / record data with the specified data.

use serde::Serialize;

#[derive(Serialize)]
struct Settings {
    active: bool,
    marketing: bool,
}

#[derive(Serialize)]
struct User {
    name: &'static str,
    settings: Settings,
}

// Select the namespace/database to use
db.use_ns("namespace").use_db("database").await?;

// Update all records in a table
let people: Vec<Person> = db.upsert("person").await?;

// Update a record with a specific ID
let person: Option<Person> = db.upsert(("person", "tobie"))
    .content(User {
        name: "Tobie",
        settings: Settings {
            active: true,
            marketing: true,
        },
    })
    .await?;

Merge the current document / record data with the specified data.

use serde::Serialize;
use time::OffsetDateTime;

#[derive(Serialize)]
struct UpdatedAt {
    updated_at: OffsetDateTime,
}

#[derive(Serialize)]
struct Settings {
    active: bool,
}

#[derive(Serialize)]
struct User {
    updated_at: OffsetDateTime,
    settings: Settings,
}

// Select the namespace/database to use
db.use_ns("namespace").use_db("database").await?;

// Update all records in a table
let people: Vec<Person> = db.upsert("person")
    .merge(UpdatedAt {
        updated_at: OffsetDateTime::now_utc(),
    })
    .await?;

// Update a record with a specific ID
let person: Option<Person> = db.upsert(("person", "tobie"))
    .merge(User {
        updated_at: OffsetDateTime::now_utc(),
        settings: Settings {
            active: true,
        },
    })
    .await?;

Apply JSON Patch changes to all records, or a specific record, in the database.

use serde::Serialize;
use surrealdb::opt::PatchOp;
use time::OffsetDateTime;

#[derive(Serialize)]
struct UpdatedAt {
    updated_at: OffsetDateTime,
}

#[derive(Serialize)]
struct Settings {
    active: bool,
}

#[derive(Serialize)]
struct User {
    updated_at: OffsetDateTime,
    settings: Settings,
}

// Select the namespace/database to use
db.use_ns("namespace").use_db("database").await?;

// Update all records in a table
let people: Vec<Person> = db.upsert("person")
    .patch(PatchOp::replace("/created_at", OffsetDateTime::now_utc()))
    .await?;

// Update a record with a specific ID
let person: Option<Person> = db.upsert(("person", "tobie"))
    .patch(PatchOp::replace("/settings/active", false))
    .patch(PatchOp::add("/tags", ["developer", "engineer"]))
    .patch(PatchOp::remove("/temp"))
    .await?;

Source

pub fn update<O>(&self, resource: impl IntoResource<O>) -> Update<'_, C, O>

Updates all records in a table, or a specific record

§Examples

Replace the current document / record data with the specified data.

use serde::Serialize;

#[derive(Serialize)]
struct Settings {
    active: bool,
    marketing: bool,
}

#[derive(Serialize)]
struct User {
    name: &'static str,
    settings: Settings,
}

// Select the namespace/database to use
db.use_ns("namespace").use_db("database").await?;

// Update all records in a table
let people: Vec<Person> = db.update("person").await?;

// Update a record with a specific ID
let person: Option<Person> = db.update(("person", "tobie"))
    .content(User {
        name: "Tobie",
        settings: Settings {
            active: true,
            marketing: true,
        },
    })
    .await?;

Merge the current document / record data with the specified data.

use serde::Serialize;
use time::OffsetDateTime;

#[derive(Serialize)]
struct UpdatedAt {
    updated_at: OffsetDateTime,
}

#[derive(Serialize)]
struct Settings {
    active: bool,
}

#[derive(Serialize)]
struct User {
    updated_at: OffsetDateTime,
    settings: Settings,
}

// Select the namespace/database to use
db.use_ns("namespace").use_db("database").await?;

// Update all records in a table
let people: Vec<Person> = db.update("person")
    .merge(UpdatedAt {
        updated_at: OffsetDateTime::now_utc(),
    })
    .await?;

// Update a record with a specific ID
let person: Option<Person> = db.update(("person", "tobie"))
    .merge(User {
        updated_at: OffsetDateTime::now_utc(),
        settings: Settings {
            active: true,
        },
    })
    .await?;

Apply JSON Patch changes to all records, or a specific record, in the database.

use serde::Serialize;
use surrealdb::opt::PatchOp;
use time::OffsetDateTime;

#[derive(Serialize)]
struct UpdatedAt {
    updated_at: OffsetDateTime,
}

#[derive(Serialize)]
struct Settings {
    active: bool,
}

#[derive(Serialize)]
struct User {
    updated_at: OffsetDateTime,
    settings: Settings,
}

// Select the namespace/database to use
db.use_ns("namespace").use_db("database").await?;

// Update all records in a table
let people: Vec<Person> = db.update("person")
    .patch(PatchOp::replace("/created_at", OffsetDateTime::now_utc()))
    .await?;

// Update a record with a specific ID
let person: Option<Person> = db.update(("person", "tobie"))
    .patch(PatchOp::replace("/settings/active", false))
    .patch(PatchOp::add("/tags", ["developer", "engineer"]))
    .patch(PatchOp::remove("/temp"))
    .await?;

Source

pub fn delete<O>(&self, resource: impl IntoResource<O>) -> Delete<'_, C, O>

Deletes all records, or a specific record

§Examples

// Select the namespace/database to use
db.use_ns("namespace").use_db("database").await?;

// Delete all records from a table
let people: Vec<Person> = db.delete("person").await?;

// Delete a specific record from a table
let person: Option<Person> = db.delete(("person", "h5wxrf2ewk8xjxosxtyc")).await?;

Source

pub fn version(&self) -> Version<'_, C>

Returns the version of the server

§Examples

let version = db.version().await?;

Source

pub fn run<R>(&self, function: impl IntoFn) -> Run<'_, C, R>

Runs a function

§Examples

// Specify no args by not calling `.args()`
let foo = db.run("fn::foo").await?; // fn::foo()
// A single value will be turned into one argument
let bar = db.run("fn::bar").args(42).await?; // fn::bar(42)
// Arrays are treated as single arguments
let count = db.run("count").args(vec![1,2,3]).await?;
// Specify multiple args using a tuple
let two = db.run("math::log").args((100, 10)).await?; // math::log(100, 10)

Source

pub fn health(&self) -> Health<'_, C>

Checks whether the server is healthy or not

§Examples

db.health().await?;

Source

pub async fn wait_for(&self, event: WaitFor)

Wait for the selected event to happen before proceeding

Source

pub fn export<R>( &self, target: impl IntoExportDestination<R>, ) -> Export<'_, C, R>

Dumps the database contents to a file

§Support

Currently only supported by HTTP and the local engines. Not supported on WebAssembly.

§Examples

// Select the namespace/database to use
db.use_ns("namespace").use_db("database").await?;

// Export to a file
db.export("backup.sql").await?;

// Export to a stream of bytes
let mut backup = db.export(()).await?;
while let Some(result) = backup.next().await {
    match result {
        Ok(bytes) => {
            // Do something with the bytes received...
        }
        Err(error) => {
            // Handle the export error
        }
    }
}

Source

pub fn import(&self, file: P) -> Import<'_, C>
where P: AsRef<Path>,

Restores the database from a file

§Support

Currently only supported by HTTP and the local engines. Not supported on WebAssembly.

§Examples

// Select the namespace/database to use
db.use_ns("namespace").use_db("database").await?;

db.import("backup.sql").await?;

Trait Implementations§

Source §

impl<C: Clone + Connection + Debug> Clone for SurrealConnection<C>

Source §

fn clone(&self) -> SurrealConnection<C>

Returns a duplicate of the value. Read more

1.0.0 · Source§

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

Performs copy-assignment from source. Read more

Source §

impl<C: Connection + Debug> DatabaseConnection for SurrealConnection<C>

Source §

type Error = Error

Source §

async fn authenticate( &self, jwt: &str, ) -> Result<(), AuthenticationError<Self::Error>>

Source §

async fn me(&self) -> Result<User, Self::Error>

Source §

async fn draft<D: Document + Send>( &self, id: &str, data: Value, ) -> Result<Item<Value>, Self::Error>

Source §

async fn delete_draft<D: Document + Send + DeserializeOwned>( &self, id: &str, ) -> Result<Item<Value>, Self::Error>

Source §

async fn publish<D: Document + Send + Serialize + DeserializeOwned + 'static>( &self, id: &str, publish_at: Option<DateTime<Utc>>, data: Valid<D>, ) -> Result<Item<D>, Self::Error>

Source §

async fn put<D: Document + Serialize + DeserializeOwned + Send + Debug + 'static>( &self, item: Item<D>, ) -> Result<Item<D>, Self::Error>

Source §

async fn delete<D: Document + Send + Debug>( &self, id: &str, ) -> Result<Item<D>, Self::Error>

Source §

async fn get_all<D: Document + DeserializeOwned + Send>( &self, ) -> Result<Vec<Item<Value>>, Self::Error>

Source §

async fn get_by_id<D: Document + DeserializeOwned + Send>( &self, id: &str, ) -> Result<Option<Item<Value>>, Self::Error>

Source §

impl<C: Debug + Connection + Debug> Debug for SurrealConnection<C>

Source §

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Source §

impl<C: Connection + Debug> Deref for SurrealConnection<C>

Source §

type Target = Surreal<C>

The resulting type after dereferencing.

Source §

fn deref(&self) -> &Self::Target

Dereferences the value.

Auto Trait Implementations§

§

impl<C> UnwindSafe for SurrealConnection<C>
where C: UnwindSafe,

Blanket Implementations§

Source §

impl<T> Any for T
where T: 'static + ?Sized,

Source §

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more

Source §

impl<T> Borrow<T> for T
where T: ?Sized,

Source §

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more

Source §

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source §

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more

Source §

impl<T> CloneToUninit for T
where T: Clone,

Source §

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)

Performs copy-assignment from self to dest. Read more

Source §

impl<T> From<T> for T

Source §

fn from(t: T) -> T

Returns the argument unchanged.

Source §

impl<T> Instrument for T

Source §

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

Source §

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Source §

impl<T, U> Into for T
where U: From<T>,

Source §

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source §

impl<T> IntoEither for T

Source §

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more

Source §

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more

Source §