The official SurrealDB library for Rust.
SurrealDB is an end-to-end cloud native database for web, mobile, serverless, jamstack, backend, and traditional applications. SurrealDB reduces the development time of modern applications by simplifying your database and API stack, removing the need for most server-side components, allowing you to build secure, performant apps quicker and cheaper. SurrealDB acts as both a database and a modern, realtime, collaborative API backend layer. SurrealDB can run as a single server or in a highly-available, highly-scalable distributed mode - with support for SQL querying from client devices, GraphQL, ACID transactions, WebSocket connections, structured and unstructured data, graph querying, full-text indexing, geospatial querying, and row-by-row permissions-based access.
View the features, the latest releases, the product roadmap, and documentation.
- Connects to remote servers (
Surreal<WsClient>
orSurreal<HttpClient>
) - Can be used as an embedded database (
Surreal<Db>
) - Compiles to WebAssembly
- Supports typed SQL statements
- Invalid SQL queries are never sent to the server, the client uses the same parser the server uses
- Static clients, no need for
once_cell
orlazy_static
- Clonable connections with auto-reconnect capabilities, no need for a connection pool
- Range queries
- Consistent API across all supported protocols or storage engines
- Asynchronous, lock-free connections
- TLS support via either
rustls
ornative-tls
- FFI bindings for third-party languages
To add this crate as a Rust dependency, simply run
cargo add surrealdb-rs --git https://github.com/surrealdb/surrealdb.rs
IMPORTANT: This client supports SurrealDB v1.0.0-beta.8+20221030.c12a1cc
or later. So please make sure you have that or a newer version of the server before proceeding. For now, that means a recent nightly version.
This library enables simple and advanced querying of a remote database from server-side or client-side (via Wasm) code. By default, all connections to SurrealDB are made over WebSockets, and automatically reconnect when the connection is terminated. Connections are automatically closed when they get dropped.
use serde::{Deserialize, Serialize};
use serde_json::json;
use std::borrow::Cow;
use surrealdb_rs::param::Root;
use surrealdb_rs::protocol::Ws;
use surrealdb_rs::{Result, Surreal};
#[derive(Serialize, Deserialize)]
struct Name {
first: Cow<'static, str>,
last: Cow<'static, str>,
}
#[derive(Serialize, Deserialize)]
struct Person {
#[serde(skip_serializing)]
id: Option<String>,
title: Cow<'static, str>,
name: Name,
marketing: bool,
}
#[tokio::main]
async fn main() -> Result<()> {
let db = Surreal::connect::<Ws>("localhost:8000").await?;
// Signin as a namespace, database, or root user
db.signin(Root {
username: "root",
password: "root",
})
.await?;
// Select a specific namespace and database
db.use_ns("test").use_db("test").await?;
// Create a new person with a random ID
let tobie: Person = db
.create("person")
.content(Person {
id: None,
title: "Founder & CEO".into(),
name: Name {
first: "Tobie".into(),
last: "Morgan Hitchcock".into(),
},
marketing: true,
})
.await?;
assert!(tobie.id.is_some());
// Create a new person with a specific ID
let mut jaime: Person = db
.create(("person", "jaime"))
.content(Person {
id: None,
title: "Founder & COO".into(),
name: Name {
first: "Jaime".into(),
last: "Morgan Hitchcock".into(),
},
marketing: false,
})
.await?;
assert_eq!(jaime.id.unwrap(), "person:jaime");
// Update a person record with a specific ID
jaime = db
.update(("person", "jaime"))
.merge(json!({ "marketing": true }))
.await?;
assert!(jaime.marketing);
// Select all people records
let people: Vec<Person> = db.select("person").await?;
assert!(!people.is_empty());
// Perform a custom advanced query
#[rustfmt::skip]
let groups = db
.query("
SELECT marketing,
count()
FROM type::table($table)
GROUP BY marketing
")
.bind(("table", "person"))
.await?;
dbg!(groups);
// Delete all people upto but not including Jaime
db.delete("person").range(.."jaime").await?;
// Delete all people
db.delete("person").await?;
Ok(())
}