autumn_plugin_surrealdb/
lib.rs

1//! Autumn plugin for SurrealDB.
2//!
3//! Add [`SurrealDbPlugin`] to the app. Then use the [`SurrealDb`] extractor in a handler.
4//!
5//! ```rust,no_run
6//! use autumn_plugin_surrealdb::{SurrealDb, SurrealDbPlugin, SurrealDbResultExt as _};
7//! use autumn_web::prelude::*;
8//!
9//! #[derive(serde::Deserialize, serde::Serialize)]
10//! struct Profile {
11//!     name: String,
12//! }
13//!
14//! #[get("/profiles/{id}")]
15//! async fn profile(db: SurrealDb, Path(id): Path<String>) -> AutumnResult<Json<serde_json::Value>> {
16//!     let profile = db
17//!         .select_record("profile", &id)
18//!         .await
19//!         .or_http()?
20//!         .map(Json)
21//!         .ok_or_else(|| AutumnError::not_found_msg("no profile"));
22//!     profile
23//! }
24//!
25//! # async fn run() {
26//! autumn_web::app()
27//!     .plugin(
28//!         SurrealDbPlugin::new().configure(|c| {
29//!             c.endpoint = "127.0.0.1:8000".into();
30//!             c.namespace = "app".into();
31//!             c.database = "app".into();
32//!         }),
33//!     )
34//!     .routes(routes![profile])
35//!     .run()
36//!     .await;
37//! # }
38//! ```
39//!
40//! The plugin reads `[surrealdb]` in `autumn.toml`. See [`config`] for the keys.
41//!
42//! # What the plugin gives
43//!
44//! - [`SurrealDb`]: document CRUD (`create_record`, `select_record`, `select_all`,
45//!   `update_record`, `delete_record`) with `serde` types, raw SurrealQL with bound
46//!   variables (`query_json`), and `version()`.
47//! - [`SurrealDbPlugin`]: connects at startup, signs in, selects the namespace and
48//!   database, and puts the handle in the app state.
49//! - A readiness check that runs the `version()` query.
50//!
51//! # Limits
52//!
53//! - The plugin talks to a SurrealDB server over the network. It never embeds
54//!   a database: the `surrealdb` dependency enables the remote protocols only.
55//! - Each call has a timeout (`timeout_ms`). A timed-out call returns an error.
56//! - Logs, error text and `Debug` output never show the password or the token.
57
58mod client;
59pub mod config;
60mod error;
61mod health;
62mod plugin;
63
64pub use client::SurrealDb;
65pub use config::{AuthScope, ConfigError, DEFAULT_SECTION, Protocol, SurrealDbConfig};
66pub use error::{ErrorKind, SurrealDbError, SurrealDbResultExt};
67pub use health::SurrealDbCheck;
68pub use plugin::{PLUGIN_NAME, SurrealDbPlugin};
69
70/// The `surrealdb` crate that the plugin uses. Use it for typed access.
71pub use surrealdb;
autumn_plugin_surrealdb/lib.rs

autumn_plugin_surrealdb/
lib.rs
