Skip to main content

surrealdb_datastore/
lib.rs

1//! The SurrealDB datastore layer.
2//!
3//! This crate owns the keyspace: which keys exist, and the durable shapes their
4//! values take. How a key encodes is one layer down, in `surrealdb-kvs`; what the
5//! engine does with a decoded value is one layer up.
6//!
7//! This crate is an internal implementation detail of SurrealDB: its API is
8//! unstable and changes without notice. Depend on the `surrealdb` SDK or
9//! `surrealdb-core` instead.
10
11// `fail!` reports a broken invariant the same way in every layer; imported
12// crate-wide because nested modules do not inherit a file-level `use`.
13// The moved modules spell their neighbours the way core did - `catalog::X`,
14// `expr::X`, `val::X` - so the same aliases keep those paths valid here.
15
16// TODO: Remove once this crate no longer needs it; see `absolute_paths` in the workspace lints.
17#![allow(clippy::absolute_paths)]
18// Sealed async bodies nest `OutOfLine` futures, which deepens layout queries past the default.
19#![recursion_limit = "256"]
20
21pub use surrealdb_catalog as catalog;
22pub use surrealdb_expr::{expr, val};
23
24#[macro_use]
25extern crate common;
26#[macro_use]
27extern crate tracing;
28
29#[macro_use]
30mod mac;
31
32/// Attaching a span to a future.
33///
34/// With `observability`, this is [`tracing::Instrument`]. Without it,
35/// `instrument` returns the future unchanged, so no span wrapper is built or
36/// polled.
37pub(crate) mod obs {
38	#[cfg(feature = "observability")]
39	pub(crate) use tracing::Instrument;
40
41	#[cfg(not(feature = "observability"))]
42	pub(crate) trait Instrument: Sized {
43		/// Returns `self` unchanged; the span is dropped.
44		fn instrument(self, _span: tracing::Span) -> Self {
45			self
46		}
47	}
48
49	#[cfg(not(feature = "observability"))]
50	impl<T> Instrument for T {}
51}
52
53pub mod absence;
54pub mod cache;
55pub mod catalog_reads;
56pub mod clock;
57pub mod close;
58pub mod config;
59pub mod creations;
60pub mod factory;
61pub mod feature;
62pub mod index_shapes;
63pub mod index_state;
64pub mod into;
65pub mod key;
66pub mod layouts;
67pub mod out_of_line;
68pub mod pending_guard;
69mod record_writes;
70pub mod sequences;
71pub mod speculation;
72pub mod tasklease;
73pub mod tr;
74pub mod triggers;
75pub mod tx;
76pub mod unseen_indexes;
77pub mod util;
78pub mod version;
79
80pub use error::DatastoreError;
81
82/// Recover a storage failure from an [`anyhow::Error`], whichever shape it took.
83///
84/// A storage failure reaches `anyhow` two ways: raised bare by the transactor,
85/// or held as the cause of a layer error, which is how a function typed on that
86/// layer's error re-raises it. Callers should not have to know which, so every
87/// check goes through here rather than matching one shape and quietly missing
88/// the other. Matching only the bare shape is the more dangerous mistake,
89/// because it compiles, reads correctly, and turns a recognised condition into
90/// an unrecognised one.
91///
92/// Recognition therefore walks the source chain instead of naming the wrappers:
93/// they are declared in crates above this one, so they cannot be named from
94/// here, and a wrapper that did not record the storage failure as its source
95/// would not carry the cause to the client either. Following `source` is the
96/// same link the wire mapping already depends on.
97pub fn storage_error(err: &anyhow::Error) -> Option<&surrealdb_kvs::Error> {
98	err.chain().find_map(|e| e.downcast_ref::<surrealdb_kvs::Error>())
99}
100
101/// Whether a failure is a conditional write reporting that the value it
102/// required was not there.
103///
104/// Raised by the compare operations themselves — `putc`, `delc`, `clrc` — so it
105/// arrives from the call that performed the write, never from the commit.
106pub fn is_condition_not_met(err: &anyhow::Error) -> bool {
107	matches!(storage_error(err), Some(surrealdb_kvs::Error::TransactionConditionNotMet))
108}
109
110/// Whether a failure is a transaction conflict the caller may retry.
111pub fn is_retryable_transaction_conflict(err: &anyhow::Error) -> bool {
112	storage_error(err).is_some_and(surrealdb_kvs::Error::is_retryable)
113}
114
115/// Whether a failure reports that the storage engine is shutting down.
116///
117/// Transient from the cluster's perspective: the interrupted work is safe to
118/// retry after the process restarts, so callers that persist failure state
119/// (such as the concurrent index builder) must not record it as permanent.
120pub fn is_shutdown_error(err: &anyhow::Error) -> bool {
121	matches!(storage_error(err), Some(surrealdb_kvs::Error::Shutdown))
122}
123
124/// Whether a failure reports a commit whose outcome is unknown — the
125/// transaction may or may not have been applied.
126///
127/// Callers must not describe it as work that did not happen, and must not
128/// retry it: the write may already exist, and replaying a non-idempotent
129/// statement would apply it twice.
130pub fn is_indeterminate_commit(err: &anyhow::Error) -> bool {
131	matches!(storage_error(err), Some(surrealdb_kvs::Error::CommitOutcomeUnknown(_)))
132}
133
134#[cfg(test)]
135mod storage_error_tests {
136	use super::{is_retryable_transaction_conflict, is_shutdown_error, storage_error};
137
138	/// Stands in for the layer errors above this crate, which hold a storage
139	/// failure as their cause so a function typed on their own error can
140	/// re-raise it. Those types cannot be named from here, which is the whole
141	/// reason recognition follows `source` rather than matching them.
142	#[derive(Debug, thiserror::Error)]
143	#[error("There was a problem with the key-value store: {0}")]
144	struct Wrapped(#[from] surrealdb_kvs::Error);
145
146	#[derive(Debug, thiserror::Error)]
147	#[error("not a storage failure")]
148	struct Foreign;
149
150	#[test]
151	fn either_shape_is_recovered() {
152		for err in [
153			anyhow::Error::new(surrealdb_kvs::Error::TransactionKeyAlreadyExists),
154			anyhow::Error::new(Wrapped(surrealdb_kvs::Error::TransactionKeyAlreadyExists)),
155		] {
156			assert!(
157				matches!(
158					storage_error(&err),
159					Some(surrealdb_kvs::Error::TransactionKeyAlreadyExists)
160				),
161				"a key-already-exists failure went unrecognised: {err}"
162			);
163		}
164	}
165
166	#[test]
167	fn either_shape_classifies_the_same() {
168		for err in [
169			anyhow::Error::new(surrealdb_kvs::Error::TransactionConflict("busy".to_string())),
170			anyhow::Error::new(Wrapped(surrealdb_kvs::Error::TransactionConflict(
171				"busy".to_string(),
172			))),
173		] {
174			assert!(is_retryable_transaction_conflict(&err), "conflict not retryable: {err}");
175			assert!(!is_shutdown_error(&err), "conflict misread as a shutdown: {err}");
176		}
177		for err in [
178			anyhow::Error::new(surrealdb_kvs::Error::Shutdown),
179			anyhow::Error::new(Wrapped(surrealdb_kvs::Error::Shutdown)),
180		] {
181			assert!(is_shutdown_error(&err), "shutdown not recognised: {err}");
182			assert!(!is_retryable_transaction_conflict(&err), "shutdown misread as retryable");
183		}
184	}
185
186	#[test]
187	fn a_foreign_error_is_not_a_storage_failure() {
188		let err = anyhow::Error::new(Foreign);
189		assert!(storage_error(&err).is_none());
190		assert!(!is_retryable_transaction_conflict(&err));
191		assert!(!is_shutdown_error(&err));
192	}
193}
194
195pub use config::TransactionConfig;
196pub use factory::{ReadRequest, TransactionFactory};
197pub use feature::{FeatureLevelCell, FeatureLevelState, LevelledMode, Readable};
198pub use into::IntoBytes;
199pub use layouts::{Admission, LayoutSet, RowGate};
200pub use surrealdb_kvs::consts::NORMAL_BATCH_SIZE;
201pub use surrealdb_kvs::{
202	Direction, Error, Key, KeyRange, Result, TransactionType, Val, Version, api, consts, err,
203	timestamp,
204};
205pub use tr::Transactor;
206pub use tx::{DocIdsReclaimClaim, Transaction, WriteBatch};
207pub mod error;
208#[cfg(any(test, feature = "test-hooks"))]
209pub mod testing;
210pub mod values;