connect

Connects to a local or remote database endpoint.

db.connect(address)

Arguments

Example usage

The .connect() method will usually take a String or a type that implements Into<String>. Note that the final .connect() with a Config is possible because of the implementation impl<T> IntoEndpoint for (T, Config) where T: Into<String>.

use std::sync::LazyLock;
use std::time::Duration;
use surrealdb::engine::remote::ws::{Client, Ws, Wss};
use surrealdb::opt::Config;
use surrealdb::Surreal;

static DB: LazyLock<Surreal<Client>> = LazyLock::new(Surreal::init);

#[tokio::main]
async fn main() -> surrealdb::Result<()> {
    // Connect to a local endpoint
    DB.connect::<Ws>("127.0.0.1:8000").await?;
    // Connect to a remote endpoint
    DB.connect::<Wss>("cloud.surrealdb.com").await?;
    // A tuple with a Config struct can also be passed in for fine tuning of the connection
    let config = Config::default().query_timeout(Duration::from_millis(1500));
    DB.connect::<Ws>(("127.0.0.1:8000", config)).await?;
    Ok(())
}

Connecting over gRPC

Available since: v3.3.0

Alongside WebSocket and HTTP, the SDK can talk to a server over gRPC. The server exposes it on the same address and port as the other two, so no extra server configuration is needed.

gRPC is the only remote protocol that delivers query results incrementally, which is what makes .stream_items() worthwhile on a remote connection. On WebSocket and HTTP the results are buffered and replayed instead.

The engine is behind the protocol-grpc feature, which is not enabled by default:

surrealdb = { version = "3", features = ["protocol-grpc"] }

Use Grpc for a plain connection and Grpcs for a TLS one, in the same way as Ws and Wss.

use surrealdb::Surreal;
use surrealdb::engine::remote::grpc::Grpc;
use surrealdb::opt::auth::Root;
use surrealdb::types::Value;

#[tokio::main]
async fn main() -> surrealdb::Result<()> {
    let db = Surreal::new::<Grpc>("127.0.0.1:8000").await?;

    db.signin(Root {
        username: "root".to_string(),
        password: "secret".to_string(),
    })
    .await?;

    db.use_ns("main").use_db("main").await?;

    let mut res = db.query("RETURN 1 + 1").await?;
    println!("{:?}", res.take::<Value>(0)?);
    Ok(())
}

The any engine accepts grpc:// and grpcs:// URLs, so a connection can be chosen at runtime in the same way as ws:// or http://.

let db = surrealdb::engine::any::connect("grpc://127.0.0.1:8000").await?;

Message size

Available since: v3.3.0

A gRPC message has a size limit at each end. The server sets its own with SURREAL_GRPC_MAX_MESSAGE_SIZE and advertises it on connection, and the SDK takes that advertised figure by default. Config::grpc sets the client's own figure, for a workload that writes a large batch in one transaction:

use surrealdb::opt::{Config, GrpcConfig};

let config = Config::new().grpc(GrpcConfig::new().max_message_size(128 * 1024 * 1024))?;
let db = surrealdb::engine::any::connect(("grpc://127.0.0.1:8000", config)).await?;

The two directions are limited separately, because different settings apply to each. A request is bounded by whichever is smaller of the client's figure and the server's, since no client setting can make a server accept more than it allows. The error for a request refused for size names the side that set the limit, so raising the server variable only helps when the server set it. A response is bounded by the client's figure, or by the server's advertised figure when the client sets none, since that is the memory this client gives one message. The server also keeps every message it sends within its own SURREAL_GRPC_MAX_MESSAGE_SIZE: it splits query results across messages, and answers with an error naming that variable when a single record or live query notification is larger, so raising the client's figure alone does not let a larger record through.

.grpc() returns a Result. A size too small for the protocol's own framing is refused at this point rather than at connect time, since no server could serve it.

See also

• •

  .connect() method on Docs.rs

• •

  Streaming query results with .stream_items()