surrealdb/
lib.rs

1//! This library provides a low-level database library implementation, a remote client
2//! and a query language definition, for [SurrealDB](https://surrealdb.com), the ultimate cloud database for
3//! tomorrow's applications. SurrealDB is a scalable, distributed, collaborative, document-graph
4//! database for the realtime web.
5//!
6//! This library can be used to start an embedded in-memory datastore, an embedded datastore
7//! persisted to disk, a browser-based embedded datastore backed by IndexedDB, or for connecting
8//! to a distributed [TiKV](https://tikv.org) key-value store.
9//!
10//! It also enables simple and advanced querying of a remote SurrealDB server from
11//! server-side or client-side code. All connections to SurrealDB are made over WebSockets by default,
12//! and automatically reconnect when the connection is terminated.
13//!
14//! # Examples
15//!
16//! ```no_run
17//! use std::borrow::Cow;
18//! use serde::{Serialize, Deserialize};
19//! use serde_json::json;
20//! use surrealdb::{Error, Surreal};
21//! use surrealdb::opt::auth::Root;
22//! use surrealdb::engine::remote::ws::Ws;
23//!
24//! #[derive(Serialize, Deserialize)]
25//! struct Person {
26//!     title: String,
27//!     name: Name,
28//!     marketing: bool,
29//! }
30//!
31//! // Pro tip: Replace String with Cow<'static, str> to
32//! // avoid unnecessary heap allocations when inserting
33//!
34//! #[derive(Serialize, Deserialize)]
35//! struct Name {
36//!     first: Cow<'static, str>,
37//!     last: Cow<'static, str>,
38//! }
39//!
40//! // Install at https://surrealdb.com/install
41//! // and use `surreal start --user root --pass root`
42//! // to start a working database to take the following queries
43
44//! // See the results via `surreal sql --ns namespace --db database --pretty`
45//! // or https://surrealist.app/
46//! // followed by the query `SELECT * FROM person;`
47
48//! #[tokio::main]
49//! async fn main() -> Result<(), Error> {
50//!     let db = Surreal::new::<Ws>("localhost:8000").await?;
51//!
52//!     // Signin as a namespace, database, or root user
53//!     db.signin(Root {
54//!         username: "root",
55//!         password: "root",
56//!     }).await?;
57//!
58//!     // Select a specific namespace / database
59//!     db.use_ns("namespace").use_db("database").await?;
60//!
61//!     // Create a new person with a random ID
62//!     let created: Vec<Person> = db.create("person")
63//!         .content(Person {
64//!             title: "Founder & CEO".into(),
65//!             name: Name {
66//!                 first: "Tobie".into(),
67//!                 last: "Morgan Hitchcock".into(),
68//!             },
69//!             marketing: true,
70//!         })
71//!         .await?;
72//!
73//!     // Create a new person with a specific ID
74//!     let created: Option<Person> = db.create(("person", "jaime"))
75//!         .content(Person {
76//!             title: "Founder & COO".into(),
77//!             name: Name {
78//!                 first: "Jaime".into(),
79//!                 last: "Morgan Hitchcock".into(),
80//!             },
81//!             marketing: false,
82//!         })
83//!         .await?;
84//!
85//!     // Update a person record with a specific ID
86//!     let updated: Option<Person> = db.update(("person", "jaime"))
87//!         .merge(json!({"marketing": true}))
88//!         .await?;
89//!
90//!     // Select all people records
91//!     let people: Vec<Person> = db.select("person").await?;
92//!
93//!     // Perform a custom advanced query
94//!     let query = r#"
95//!         SELECT marketing, count()
96//!         FROM type::table($table)
97//!         GROUP BY marketing
98//!     "#;
99//!
100//!     let groups = db.query(query)
101//!         .bind(("table", "person"))
102//!         .await?;
103//!
104//!     Ok(())
105//! }
106//! ```
107
108#![doc(html_favicon_url = "https://surrealdb.s3.amazonaws.com/favicon.png")]
109#![doc(html_logo_url = "https://surrealdb.s3.amazonaws.com/icon.png")]
110#![cfg_attr(docsrs, feature(doc_cfg))]
111#![cfg_attr(test, deny(warnings))]
112
113#[cfg(all(target_arch = "wasm32", feature = "ml"))]
114compile_error!("The `ml` feature is not supported on the `wasm32` architecture.");
115
116#[macro_use]
117extern crate tracing;
118
119#[doc(hidden)]
120pub use surrealdb_core::*;
121
122pub use uuid::Uuid;
123
124#[macro_use]
125mod mac;
126mod api;
127
128#[doc(hidden)]
129/// Channels for receiving a SurrealQL database export
130pub mod channel {
131	pub use channel::bounded;
132	pub use channel::unbounded;
133	pub use channel::Receiver;
134	pub use channel::Sender;
135}
136
137/// Different error types for embedded and remote databases
138pub mod error {
139	pub use crate::api::err::Error as Api;
140	pub use surrealdb_core::err::Error as Db;
141}
142
143#[cfg(feature = "protocol-http")]
144#[doc(hidden)]
145pub use api::headers;
146
147#[doc(inline)]
148pub use api::{
149	engine, method, opt,
150	value::{
151		self, Action, Bytes, Datetime, Notification, Number, Object, RecordId, RecordIdKey, Value,
152	},
153	Connect, Connection, Response, Result, Surreal,
154};
155
156/// An error originating from the SurrealDB client library
157#[derive(Debug, thiserror::Error, serde::Serialize)]
158pub enum Error {
159	/// An error with an embedded storage engine
160	#[error("{0}")]
161	Db(#[from] crate::error::Db),
162	/// An error with a remote database instance
163	#[error("{0}")]
164	Api(#[from] crate::error::Api),
165}
surrealdb/lib.rs

surrealdb/
lib.rs
