SurrealDB
SurrealDB Docs Logo

Enter a search query

Navigation

Enter a search query

SurrealDB SurrealQL Surrealist UI Cloud Extensions
SDKs
RustRust JavaScriptJavaScript Node.jsNode.js WebAssemblyWebAssembly JavaJava GolangGolang PythonPython .NET.NET PHPPHP
Integrations
Examples
Lab ExamplesLab Examples Lab TutorialsLab Tutorials
Education
Quick tourQuick tour FundamentalsFundamentals BookBook Movie databaseMovie database Sidekick assistantSidekick assistant
Sign in
Table of Contents
SDK methodsnew

new()

Connects to a local or remote database endpoint.

Method Syntax
Surreal::new::<T>(address)

Arguments

ArgumentDescription
endpoint

The database endpoint to connect to.

Example usage

Basic example

use surrealdb::engine::remote::ws::Ws;
use surrealdb::Surreal;

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

Configuring the database

The new() function takes an argument of impl IntoEndpoint, which is implemented not only for strings and string-like structs like PathBuf and SocketAddr, but also a tuple of one of these types for the address along with a second Config struct for the configuration.

Example with all capabilities enabled except one function
#[tokio::main]
async fn main() -> Result<(), Error> {
    let config = Config::default()
        .capabilities(Capabilities::all().with_deny_function("math::abs")?);
    let db = connect(("mem://", config)).await?;

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

    // Result: Err(Db(FunctionNotAllowed("math::abs")))
    println!("{:?}", db.query("math::abs(-10)").await?);
    println!("{:?}", db.run::<i32>("math::abs").args(-10).await);

    Ok(())
}

Using SurrealKV with versioning

To make a new connection that includes SurrealKV versioning, add the “surreal-kv” feature flag to the surrealdb dependency in Cargo.toml, add the path to the folder containing the database inside new(), and call the .versioned() method.

use surrealdb::engine::local::SurrealKv;
use surrealdb::Surreal;

#[tokio::main]
async fn main() -> surrealdb::Result<()> {
    let db = Surreal::new::<SurrealKv>("path/to/database-folder").versioned().await?;
    Ok(())
}

See also