Trait SurrealEngine 

pub trait SurrealEngine:
    Debug
    + Send
    + Sync
    + 'static {
    // Required methods
    fn query(
        &self,
        ctx: EngineContext,
        query: Cow<'static, str>,
        variables: Variables,
    ) -> EngineFuture<'_, Vec<QueryResult>>;
    fn run(
        &self,
        ctx: EngineContext,
        name: String,
        version: Option<String>,
        args: Array,
    ) -> EngineFuture<'_, Value>;
    fn use_ns_db(
        &self,
        ctx: EngineContext,
        namespace: Option<String>,
        database: Option<String>,
    ) -> EngineFuture<'_, (Option<String>, Option<String>)>;
    fn set(
        &self,
        ctx: EngineContext,
        key: String,
        value: Value,
    ) -> EngineFuture<'_, ()>;
    fn unset(&self, ctx: EngineContext, key: String) -> EngineFuture<'_, ()>;
    fn signup(
        &self,
        ctx: EngineContext,
        credentials: Object,
    ) -> EngineFuture<'_, Token>;
    fn signin(
        &self,
        ctx: EngineContext,
        credentials: Object,
    ) -> EngineFuture<'_, Token>;
    fn authenticate(
        &self,
        ctx: EngineContext,
        token: Token,
    ) -> EngineFuture<'_, Token>;
    fn refresh(
        &self,
        ctx: EngineContext,
        token: Token,
    ) -> EngineFuture<'_, Token>;
    fn revoke(&self, ctx: EngineContext, token: Token) -> EngineFuture<'_, ()>;
    fn invalidate(&self, ctx: EngineContext) -> EngineFuture<'_, ()>;
    fn begin(&self, ctx: EngineContext) -> EngineFuture<'_, Uuid>;
    fn commit(&self, ctx: EngineContext, txn: Uuid) -> EngineFuture<'_, ()>;
    fn rollback(&self, ctx: EngineContext, txn: Uuid) -> EngineFuture<'_, ()>;
    fn health(&self, ctx: EngineContext) -> EngineFuture<'_, ()>;
    fn version(&self, ctx: EngineContext) -> EngineFuture<'_, String>;

    // Provided methods
    fn query_stream(
        &self,
        ctx: EngineContext,
        query: Cow<'static, str>,
        variables: Variables,
        items: Sender<QueryStreamItem>,
    ) -> EngineFuture<'_, ()> { ... }
    fn subscribe_live(
        &self,
        _ctx: EngineContext,
        _uuid: Uuid,
        _notifications: Sender<Result<Notification, Error>>,
    ) -> EngineFuture<'_, ()> { ... }
    fn kill(&self, _ctx: EngineContext, _uuid: Uuid) -> EngineFuture<'_, ()> { ... }
    fn export_file(
        &self,
        _ctx: EngineContext,
        _path: PathBuf,
        _config: Option<DbExportConfig>,
    ) -> EngineFuture<'_, ()> { ... }
    fn export_bytes(
        &self,
        _ctx: EngineContext,
        _bytes: Sender<Result<Vec<u8>, Error>>,
        _config: Option<DbExportConfig>,
    ) -> EngineFuture<'_, ()> { ... }
    fn export_ml_file(
        &self,
        _ctx: EngineContext,
        _path: PathBuf,
        _config: MlExportConfig,
    ) -> EngineFuture<'_, ()> { ... }
    fn export_ml_bytes(
        &self,
        _ctx: EngineContext,
        _bytes: Sender<Result<Vec<u8>, Error>>,
        _config: MlExportConfig,
    ) -> EngineFuture<'_, ()> { ... }
    fn import_file(
        &self,
        _ctx: EngineContext,
        _path: PathBuf,
    ) -> EngineFuture<'_, ()> { ... }
    fn import_ml_file(
        &self,
        _ctx: EngineContext,
        _path: PathBuf,
    ) -> EngineFuture<'_, ()> { ... }
}

The interface every SurrealDB engine implements, and the only thing the Rust SDK calls to reach a database.

One method per operation, each taking and returning the types that operation actually deals in, so no engine has to encode a result into a generic Value purely for the SDK to take it apart again. An embedded engine hands its own values straight back; a remote engine converts once, from its wire format.

Methods for capabilities an engine may not have – live queries, export and import – default to reporting that they are unsupported, so an engine implements only what it serves. The SDK gates most of these on ExtraFeatures before calling, so the default is a backstop rather than the usual path.

Stability

This is an internal interface between crates released together. It carries no stability guarantee and may change in any release, including a patch release.

Required Methods

fn query( &self, ctx: EngineContext, query: Cow<'static, str>, variables: Variables, ) -> EngineFuture<'_, Vec<QueryResult>>

Executes SurrealQL, returning one result per statement, in order.

fn run( &self, ctx: EngineContext, name: String, version: Option<String>, args: Array, ) -> EngineFuture<'_, Value>

Calls a function, or a machine learning model when version is set.

fn use_ns_db( &self, ctx: EngineContext, namespace: Option<String>, database: Option<String>, ) -> EngineFuture<'_, (Option<String>, Option<String>)>

Selects the namespace and/or database, returning the resulting selection. None for either argument leaves that one unchanged.

fn set( &self, ctx: EngineContext, key: String, value: Value, ) -> EngineFuture<'_, ()>

Binds a session variable.

fn unset(&self, ctx: EngineContext, key: String) -> EngineFuture<'_, ()>

Removes a session variable.

fn signup( &self, ctx: EngineContext, credentials: Object, ) -> EngineFuture<'_, Token>

Registers a record user and authenticates the session as them.

fn signin( &self, ctx: EngineContext, credentials: Object, ) -> EngineFuture<'_, Token>

Authenticates the session with credentials.

fn authenticate( &self, ctx: EngineContext, token: Token, ) -> EngineFuture<'_, Token>

Authenticates the session with an existing token, returning the token now in effect.

A server may hand back a token of its own rather than the one it was given, so the result is what the session is authenticated with – not necessarily the argument.

fn refresh(&self, ctx: EngineContext, token: Token) -> EngineFuture<'_, Token>

Exchanges a refresh token for a fresh token pair.

fn revoke(&self, ctx: EngineContext, token: Token) -> EngineFuture<'_, ()>

Invalidates a refresh token so it can no longer be redeemed.

fn invalidate(&self, ctx: EngineContext) -> EngineFuture<'_, ()>

Drops the session’s authentication.

fn begin(&self, ctx: EngineContext) -> EngineFuture<'_, Uuid>

Opens an explicit transaction, returning its id.

fn commit(&self, ctx: EngineContext, txn: Uuid) -> EngineFuture<'_, ()>

Commits an explicit transaction.

fn rollback(&self, ctx: EngineContext, txn: Uuid) -> EngineFuture<'_, ()>

Cancels an explicit transaction.

fn health(&self, ctx: EngineContext) -> EngineFuture<'_, ()>

Checks that the engine is reachable.

fn version(&self, ctx: EngineContext) -> EngineFuture<'_, String>

Reports the database version, as the server spells it (for example surrealdb-3.0.0).

Provided Methods

fn query_stream( &self, ctx: EngineContext, query: Cow<'static, str>, variables: Variables, items: Sender<QueryStreamItem>, ) -> EngineFuture<'_, ()>

Executes SurrealQL, sending results into items as they are produced.

The returned future is the execution: drive it while draining items, and treat the channel closing as “no more results” rather than as success, since a failure that belongs to no single statement is reported by the future.

The default answers from Self::query and replays the finished results, which is what an engine whose transport cannot carry incremental results should do — the caller sees the same items either way, just all at once. Overriding it is worthwhile only where results can actually reach the caller before the query ends.

Rows are provisional until their statement’s Finished item arrives; see QueryStreamItem.

fn subscribe_live( &self, _ctx: EngineContext, _uuid: Uuid, _notifications: Sender<Result<Notification, Error>>, ) -> EngineFuture<'_, ()>

Registers the channel a live query’s notifications are delivered on.

fn kill(&self, _ctx: EngineContext, _uuid: Uuid) -> EngineFuture<'_, ()>

Kills a live query.

fn export_file( &self, _ctx: EngineContext, _path: PathBuf, _config: Option<DbExportConfig>, ) -> EngineFuture<'_, ()>

Exports the database to a file.

fn export_bytes( &self, _ctx: EngineContext, _bytes: Sender<Result<Vec<u8>, Error>>, _config: Option<DbExportConfig>, ) -> EngineFuture<'_, ()>

Exports the database, streaming it to a channel.

fn export_ml_file( &self, _ctx: EngineContext, _path: PathBuf, _config: MlExportConfig, ) -> EngineFuture<'_, ()>

Exports a machine learning model to a file.

fn export_ml_bytes( &self, _ctx: EngineContext, _bytes: Sender<Result<Vec<u8>, Error>>, _config: MlExportConfig, ) -> EngineFuture<'_, ()>

Exports a machine learning model, streaming it to a channel.

fn import_file( &self, _ctx: EngineContext, _path: PathBuf, ) -> EngineFuture<'_, ()>

Imports a database export from a file.

fn import_ml_file( &self, _ctx: EngineContext, _path: PathBuf, ) -> EngineFuture<'_, ()>

Imports a machine learning model from a file.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl SurrealEngine for RouteChannelEngine