Skip to main content

cozo/
lib.rs

1/*
2 * Copyright 2022, The Cozo Project Authors.
3 *
4 * This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
5 * If a copy of the MPL was not distributed with this file,
6 * You can obtain one at https://mozilla.org/MPL/2.0/.
7 */
8
9//! This crate provides the core functionalities of [CozoDB](https://cozodb.org).
10//! It may be used to embed CozoDB in your application.
11//!
12//! This doc describes the Rust API. To learn how to use CozoDB to query (CozoScript), see:
13//!
14//! * [The CozoDB documentation](https://docs.cozodb.org)
15//!
16//! Rust API usage:
17//! ```
18//! use cozo::*;
19//!
20//! let db = DbInstance::new("mem", "", Default::default()).unwrap();
21//! let script = "?[a] := a in [1, 2, 3]";
22//! let result = db.run_script(script, Default::default(), ScriptMutability::Immutable).unwrap();
23//! println!("{:?}", result);
24//! ```
25//! We created an in-memory database above. There are other persistent options:
26//! see [DbInstance::new]. It is perfectly fine to run multiple storage engines in the same process.
27//!
28#![doc = document_features::document_features!()]
29#![warn(rust_2018_idioms, future_incompatible)]
30#![warn(missing_docs)]
31#![allow(clippy::type_complexity)]
32#![allow(clippy::too_many_arguments)]
33
34use std::collections::BTreeMap;
35use std::path::Path;
36use std::sync::Arc;
37#[allow(unused_imports)]
38use std::time::Instant;
39
40use crossbeam::channel::{bounded, Receiver, Sender};
41use data::functions::current_validity;
42use lazy_static::lazy_static;
43pub use miette::Error;
44use miette::Report;
45#[allow(unused_imports)]
46use miette::{
47    bail, miette, GraphicalReportHandler, GraphicalTheme, IntoDiagnostic, JSONReportHandler,
48    Result, ThemeCharacters, ThemeStyles,
49};
50use parse::parse_script;
51use parse::CozoScript;
52use serde_json::json;
53
54pub use data::value::{DataValue, Num, RegexWrapper, UuidWrapper, Validity, ValidityTs};
55pub use fixed_rule::{FixedRule, FixedRuleInputRelation, FixedRulePayload};
56pub use runtime::db::Db;
57pub use runtime::db::NamedRows;
58pub use runtime::relation::decode_tuple_from_kv;
59pub use runtime::temp_store::RegularTempStore;
60pub use storage::mem::{new_cozo_mem, MemStorage};
61#[cfg(feature = "storage-rocksdb")]
62pub use storage::rocks::{new_cozo_rocksdb, RocksDbStorage};
63#[cfg(feature = "storage-new-rocksdb")]
64pub use storage::newrocks::{new_cozo_newrocksdb, NewRocksDbStorage};
65#[cfg(feature = "storage-sled")]
66pub use storage::sled::{new_cozo_sled, SledStorage};
67#[cfg(feature = "storage-sqlite")]
68pub use storage::sqlite::{new_cozo_sqlite, SqliteStorage};
69#[cfg(feature = "storage-tikv")]
70pub use storage::tikv::{new_cozo_tikv, TiKvStorage};
71pub use storage::{Storage, StoreTx};
72
73pub use crate::data::expr::Expr;
74use crate::data::json::JsonValue;
75pub use crate::data::symb::Symbol;
76pub use crate::data::value::{JsonData, Vector};
77pub use crate::fixed_rule::SimpleFixedRule;
78pub use crate::parse::SourceSpan;
79pub use crate::runtime::callback::CallbackOp;
80pub use crate::runtime::db::evaluate_expressions;
81pub use crate::runtime::db::get_variables;
82pub use crate::runtime::db::Payload;
83pub use crate::runtime::db::Poison;
84pub use crate::runtime::db::ScriptMutability;
85pub use crate::runtime::db::TransactionPayload;
86
87pub mod data;
88pub(crate) mod fixed_rule;
89pub(crate) mod fts;
90pub mod parse;
91pub(crate) mod query;
92pub(crate) mod runtime;
93pub(crate) mod storage;
94pub(crate) mod utils;
95
96/// A dispatcher for concrete storage implementations, wrapping [Db]. This is done so that
97/// client code does not have to deal with generic code constantly. You may prefer to use
98/// [Db] directly, especially if you provide a custom storage engine.
99///
100/// Many methods are dispatching methods for the corresponding methods on [Db].
101///
102/// Other methods are wrappers simplifying signatures to deal with only strings.
103/// These methods made code for interop with other languages much easier,
104/// but are not desirable if you are using Rust.
105#[derive(Clone)]
106pub enum DbInstance {
107    /// In memory storage (not persistent)
108    Mem(Db<MemStorage>),
109    #[cfg(feature = "storage-sqlite")]
110    /// Sqlite storage
111    Sqlite(Db<SqliteStorage>),
112    #[cfg(feature = "storage-rocksdb")]
113    /// RocksDB storage
114    RocksDb(Db<RocksDbStorage>),
115    #[cfg(feature = "storage-new-rocksdb")]
116    /// New RocksDB storage
117    NewRocksDb(Db<NewRocksDbStorage>),
118    #[cfg(feature = "storage-sled")]
119    /// Sled storage (experimental)
120    Sled(Db<SledStorage>),
121    #[cfg(feature = "storage-tikv")]
122    /// TiKV storage (experimental)
123    TiKv(Db<TiKvStorage>),
124}
125
126impl Default for DbInstance {
127    fn default() -> Self {
128        Self::new("mem", "", Default::default()).unwrap()
129    }
130}
131
132impl DbInstance {
133    /// Create a DbInstance, which is a dispatcher for various concrete implementations.
134    /// The valid engines are:
135    ///
136    /// * `mem`
137    /// * `sqlite`
138    /// * `rocksdb`
139    /// * `newrocksdb`
140    /// * `sled`
141    /// * `tikv`
142    ///
143    /// assuming all features are enabled during compilation. Otherwise only
144    /// some of the engines are available. The `mem` engine is always available.
145    ///
146    /// `path` is ignored for `mem` and `tikv` engines.
147    /// `options` is ignored for every engine except `tikv`.
148    #[allow(unused_variables)]
149    pub fn new(engine: &str, path: impl AsRef<Path>, options: &str) -> Result<Self> {
150        let options = if options.is_empty() { "{}" } else { options };
151        Ok(match engine {
152            "mem" => Self::Mem(new_cozo_mem()?),
153            #[cfg(feature = "storage-sqlite")]
154            "sqlite" => Self::Sqlite(new_cozo_sqlite(path)?),
155            #[cfg(feature = "storage-rocksdb")]
156            "rocksdb" => Self::RocksDb(new_cozo_rocksdb(path)?),
157            #[cfg(feature = "storage-new-rocksdb")]
158            "newrocksdb" => Self::NewRocksDb(new_cozo_newrocksdb(path)?),
159            #[cfg(feature = "storage-sled")]
160            "sled" => Self::Sled(new_cozo_sled(path)?),
161            #[cfg(feature = "storage-tikv")]
162            "tikv" => {
163                #[derive(serde_derive::Deserialize)]
164                struct TiKvOpts {
165                    end_points: Vec<String>,
166                    optimistic: bool,
167                }
168                let opts: TiKvOpts = serde_json::from_str(options).into_diagnostic()?;
169                Self::TiKv(new_cozo_tikv(opts.end_points.clone(), opts.optimistic)?)
170            }
171            k => bail!(
172                "database engine '{}' not supported (maybe not compiled in)",
173                k
174            ),
175        })
176    }
177    /// Same as [Self::new], but inputs and error messages are all in strings
178    pub fn new_with_str(
179        engine: &str,
180        path: &str,
181        options: &str,
182    ) -> std::result::Result<Self, String> {
183        Self::new(engine, path, options).map_err(|err| err.to_string())
184    }
185
186    /// Dispatcher method.  See [crate::Db::get_fixed_rules].
187    pub fn get_fixed_rules(&self) -> BTreeMap<String, Arc<Box<dyn FixedRule>>> {
188        match self {
189            DbInstance::Mem(db) => db.get_fixed_rules(),
190            #[cfg(feature = "storage-sqlite")]
191            DbInstance::Sqlite(db) => db.get_fixed_rules(),
192            #[cfg(feature = "storage-rocksdb")]
193            DbInstance::RocksDb(db) => db.get_fixed_rules(),
194            #[cfg(feature = "storage-new-rocksdb")]
195            DbInstance::NewRocksDb(db) => db.get_fixed_rules(),
196            #[cfg(feature = "storage-sled")]
197            DbInstance::Sled(db) => db.get_fixed_rules(),
198            #[cfg(feature = "storage-tikv")]
199            DbInstance::TiKv(db) => db.get_fixed_rules(),
200        }
201    }
202    /// Dispatcher method. See [crate::Db::run_script].
203    pub fn run_script(
204        &self,
205        payload: &str,
206        params: BTreeMap<String, DataValue>,
207        mutability: ScriptMutability,
208    ) -> Result<NamedRows> {
209        let cur_vld = current_validity();
210        self.run_script_ast(
211            parse_script(payload, &params, &self.get_fixed_rules(), cur_vld)?,
212            cur_vld,
213            mutability,
214        )
215    }
216    /// `run_script` with mutable script and no parameters
217    pub fn run_default(&self, payload: &str) -> Result<NamedRows> {
218        self.run_script(payload, BTreeMap::new(), ScriptMutability::Mutable)
219    }
220    /// Run a parsed (AST) program. If you have a string script, use `run_script` or `run_default`.
221    pub fn run_script_ast(
222        &self,
223        payload: CozoScript,
224        cur_vld: ValidityTs,
225        mutability: ScriptMutability,
226    ) -> Result<NamedRows> {
227        match self {
228            DbInstance::Mem(db) => db.run_script_ast(payload, cur_vld, mutability),
229            #[cfg(feature = "storage-sqlite")]
230            DbInstance::Sqlite(db) => db.run_script_ast(payload, cur_vld, mutability),
231            #[cfg(feature = "storage-rocksdb")]
232            DbInstance::RocksDb(db) => db.run_script_ast(payload, cur_vld, mutability),
233            #[cfg(feature = "storage-new-rocksdb")]
234            DbInstance::NewRocksDb(db) => db.run_script_ast(payload, cur_vld, mutability),
235            #[cfg(feature = "storage-sled")]
236            DbInstance::Sled(db) => db.run_script_ast(payload, cur_vld, mutability),
237            #[cfg(feature = "storage-tikv")]
238            DbInstance::TiKv(db) => db.run_script_ast(payload, cur_vld, mutability),
239        }
240    }
241    /// Run the CozoScript passed in. The `params` argument is a map of parameters.
242    /// Fold any error into the return JSON itself.
243    /// See [crate::Db::run_script].
244    pub fn run_script_fold_err(
245        &self,
246        payload: &str,
247        params: BTreeMap<String, DataValue>,
248        mutability: ScriptMutability,
249    ) -> JsonValue {
250        #[cfg(not(target_arch = "wasm32"))]
251        let start = Instant::now();
252
253        match self.run_script(payload, params, mutability) {
254            Ok(named_rows) => {
255                let mut j_val = named_rows.into_json();
256                #[cfg(not(target_arch = "wasm32"))]
257                let took = start.elapsed().as_secs_f64();
258                let map = j_val.as_object_mut().unwrap();
259                map.insert("ok".to_string(), json!(true));
260                #[cfg(not(target_arch = "wasm32"))]
261                map.insert("took".to_string(), json!(took));
262
263                j_val
264            }
265            Err(err) => format_error_as_json(err, Some(payload)),
266        }
267    }
268    /// Run the CozoScript passed in. The `params` argument is a map of parameters formatted as JSON.
269    /// See [crate::Db::run_script].
270    pub fn run_script_str(&self, payload: &str, params: &str, immutable: bool) -> String {
271        let params_json = if params.is_empty() {
272            BTreeMap::default()
273        } else {
274            match serde_json::from_str::<BTreeMap<String, JsonValue>>(params) {
275                Ok(map) => map
276                    .into_iter()
277                    .map(|(k, v)| (k, DataValue::from(v)))
278                    .collect(),
279                Err(_) => {
280                    return json!({"ok": false, "message": "params argument is not a JSON map"})
281                        .to_string();
282                }
283            }
284        };
285        self.run_script_fold_err(
286            payload,
287            params_json,
288            if immutable {
289                ScriptMutability::Immutable
290            } else {
291                ScriptMutability::Mutable
292            },
293        )
294        .to_string()
295    }
296    /// Dispatcher method. See [crate::Db::export_relations].
297    pub fn export_relations<I, T>(&self, relations: I) -> Result<BTreeMap<String, NamedRows>>
298    where
299        T: AsRef<str>,
300        I: Iterator<Item = T>,
301    {
302        match self {
303            DbInstance::Mem(db) => db.export_relations(relations),
304            #[cfg(feature = "storage-sqlite")]
305            DbInstance::Sqlite(db) => db.export_relations(relations),
306            #[cfg(feature = "storage-rocksdb")]
307            DbInstance::RocksDb(db) => db.export_relations(relations),
308            #[cfg(feature = "storage-new-rocksdb")]
309            DbInstance::NewRocksDb(db) => db.export_relations(relations),
310            #[cfg(feature = "storage-sled")]
311            DbInstance::Sled(db) => db.export_relations(relations),
312            #[cfg(feature = "storage-tikv")]
313            DbInstance::TiKv(db) => db.export_relations(relations),
314        }
315    }
316    /// Export relations to JSON-encoded string.
317    /// See [crate::Db::export_relations]
318    pub fn export_relations_str(&self, data: &str) -> String {
319        match self.export_relations_str_inner(data) {
320            Ok(s) => {
321                let ret = json!({"ok": true, "data": s});
322                format!("{ret}")
323            }
324            Err(err) => {
325                let ret = json!({"ok": false, "message": err.to_string()});
326                format!("{ret}")
327            }
328        }
329    }
330    fn export_relations_str_inner(&self, data: &str) -> Result<JsonValue> {
331        #[derive(serde_derive::Deserialize)]
332        struct Payload {
333            relations: Vec<String>,
334        }
335        let j_val: Payload = serde_json::from_str(data).into_diagnostic()?;
336        let results = self.export_relations(j_val.relations.iter().map(|s| s as &str))?;
337        Ok(results
338            .into_iter()
339            .map(|(k, v)| (k, v.into_json()))
340            .collect())
341    }
342    /// Dispatcher method. See [crate::Db::import_relations].
343    pub fn import_relations(&self, data: BTreeMap<String, NamedRows>) -> Result<()> {
344        match self {
345            DbInstance::Mem(db) => db.import_relations(data),
346            #[cfg(feature = "storage-sqlite")]
347            DbInstance::Sqlite(db) => db.import_relations(data),
348            #[cfg(feature = "storage-rocksdb")]
349            DbInstance::RocksDb(db) => db.import_relations(data),
350            #[cfg(feature = "storage-new-rocksdb")]
351            DbInstance::NewRocksDb(db) => db.import_relations(data),
352            #[cfg(feature = "storage-sled")]
353            DbInstance::Sled(db) => db.import_relations(data),
354            #[cfg(feature = "storage-tikv")]
355            DbInstance::TiKv(db) => db.import_relations(data),
356        }
357    }
358    /// Import a relation, the data is given as a JSON string, and the returned result is converted into a string.
359    /// See [crate::Db::import_relations].
360    pub fn import_relations_str(&self, data: &str) -> String {
361        match self.import_relations_str_with_err(data) {
362            Ok(()) => {
363                format!("{}", json!({"ok": true}))
364            }
365            Err(err) => {
366                format!("{}", json!({"ok": false, "message": err.to_string()}))
367            }
368        }
369    }
370    /// Import a relation, the data is given as a JSON string.
371    /// See [crate::Db::import_relations].
372    pub fn import_relations_str_with_err(&self, data: &str) -> Result<()> {
373        let json_data: JsonValue = serde_json::from_str(data).into_diagnostic()?;
374        let json_object = json_data
375            .as_object()
376            .ok_or_else(|| miette!("A JSON object is requried"))?;
377        let mapping = json_object
378            .iter()
379            .map(|(k, v)| -> Result<(String, NamedRows)> {
380                Ok((k.to_string(), NamedRows::from_json(v)?))
381            })
382            .collect::<Result<_>>()?;
383        self.import_relations(mapping)
384    }
385    /// Dispatcher method. See [crate::Db::backup_db].
386    pub fn backup_db(&self, out_file: impl AsRef<Path>) -> Result<()> {
387        match self {
388            DbInstance::Mem(db) => db.backup_db(out_file),
389            #[cfg(feature = "storage-sqlite")]
390            DbInstance::Sqlite(db) => db.backup_db(out_file),
391            #[cfg(feature = "storage-rocksdb")]
392            DbInstance::RocksDb(db) => db.backup_db(out_file),
393            #[cfg(feature = "storage-new-rocksdb")]
394            DbInstance::NewRocksDb(db) => db.backup_db(out_file),
395            #[cfg(feature = "storage-sled")]
396            DbInstance::Sled(db) => db.backup_db(out_file),
397            #[cfg(feature = "storage-tikv")]
398            DbInstance::TiKv(db) => db.backup_db(out_file),
399        }
400    }
401    /// Backup the running database into an Sqlite file, with JSON string return value.
402    /// See [crate::Db::backup_db].
403    pub fn backup_db_str(&self, out_file: impl AsRef<Path>) -> String {
404        match self.backup_db(out_file) {
405            Ok(_) => json!({"ok": true}).to_string(),
406            Err(err) => json!({"ok": false, "message": err.to_string()}).to_string(),
407        }
408    }
409    /// Dispatcher method. See [crate::Db::restore_backup].
410    pub fn restore_backup(&self, in_file: impl AsRef<Path>) -> Result<()> {
411        match self {
412            DbInstance::Mem(db) => db.restore_backup(in_file),
413            #[cfg(feature = "storage-sqlite")]
414            DbInstance::Sqlite(db) => db.restore_backup(in_file),
415            #[cfg(feature = "storage-rocksdb")]
416            DbInstance::RocksDb(db) => db.restore_backup(in_file),
417            #[cfg(feature = "storage-new-rocksdb")]
418            DbInstance::NewRocksDb(db) => db.restore_backup(in_file),
419            #[cfg(feature = "storage-sled")]
420            DbInstance::Sled(db) => db.restore_backup(in_file),
421            #[cfg(feature = "storage-tikv")]
422            DbInstance::TiKv(db) => db.restore_backup(in_file),
423        }
424    }
425    /// Restore from an Sqlite backup, with JSON string return value.
426    /// See [crate::Db::restore_backup].
427    pub fn restore_backup_str(&self, in_file: impl AsRef<Path>) -> String {
428        match self.restore_backup(in_file) {
429            Ok(_) => json!({"ok": true}).to_string(),
430            Err(err) => json!({"ok": false, "message": err.to_string()}).to_string(),
431        }
432    }
433    /// Dispatcher method. See [crate::Db::import_from_backup].
434    pub fn import_from_backup(
435        &self,
436        in_file: impl AsRef<Path>,
437        relations: &[String],
438    ) -> Result<()> {
439        match self {
440            DbInstance::Mem(db) => db.import_from_backup(in_file, relations),
441            #[cfg(feature = "storage-sqlite")]
442            DbInstance::Sqlite(db) => db.import_from_backup(in_file, relations),
443            #[cfg(feature = "storage-rocksdb")]
444            DbInstance::RocksDb(db) => db.import_from_backup(in_file, relations),
445            #[cfg(feature = "storage-new-rocksdb")]
446            DbInstance::NewRocksDb(db) => db.import_from_backup(in_file, relations),
447            #[cfg(feature = "storage-sled")]
448            DbInstance::Sled(db) => db.import_from_backup(in_file, relations),
449            #[cfg(feature = "storage-tikv")]
450            DbInstance::TiKv(db) => db.import_from_backup(in_file, relations),
451        }
452    }
453    /// Import relations from an Sqlite backup, with JSON string return value.
454    /// See [crate::Db::import_from_backup].
455    pub fn import_from_backup_str(&self, payload: &str) -> String {
456        match self.import_from_backup_str_inner(payload) {
457            Ok(_) => json!({"ok": true}).to_string(),
458            Err(err) => json!({"ok": false, "message": err.to_string()}).to_string(),
459        }
460    }
461    fn import_from_backup_str_inner(&self, payload: &str) -> Result<()> {
462        #[derive(serde_derive::Deserialize)]
463        struct Payload {
464            path: String,
465            relations: Vec<String>,
466        }
467        let json_payload: Payload = serde_json::from_str(payload).into_diagnostic()?;
468
469        self.import_from_backup(&json_payload.path, &json_payload.relations)
470    }
471
472    /// Dispatcher method. See [crate::Db::register_callback].
473    #[cfg(not(target_arch = "wasm32"))]
474    pub fn register_callback(
475        &self,
476        relation: &str,
477        capacity: Option<usize>,
478    ) -> (u32, Receiver<(CallbackOp, NamedRows, NamedRows)>) {
479        match self {
480            DbInstance::Mem(db) => db.register_callback(relation, capacity),
481            #[cfg(feature = "storage-sqlite")]
482            DbInstance::Sqlite(db) => db.register_callback(relation, capacity),
483            #[cfg(feature = "storage-rocksdb")]
484            DbInstance::RocksDb(db) => db.register_callback(relation, capacity),
485            #[cfg(feature = "storage-new-rocksdb")]
486            DbInstance::NewRocksDb(db) => db.register_callback(relation, capacity),
487            #[cfg(feature = "storage-sled")]
488            DbInstance::Sled(db) => db.register_callback(relation, capacity),
489            #[cfg(feature = "storage-tikv")]
490            DbInstance::TiKv(db) => db.register_callback(relation, capacity),
491        }
492    }
493
494    /// Dispatcher method. See [crate::Db::unregister_callback].
495    #[cfg(not(target_arch = "wasm32"))]
496    pub fn unregister_callback(&self, id: u32) -> bool {
497        match self {
498            DbInstance::Mem(db) => db.unregister_callback(id),
499            #[cfg(feature = "storage-sqlite")]
500            DbInstance::Sqlite(db) => db.unregister_callback(id),
501            #[cfg(feature = "storage-rocksdb")]
502            DbInstance::RocksDb(db) => db.unregister_callback(id),
503            #[cfg(feature = "storage-new-rocksdb")]
504            DbInstance::NewRocksDb(db) => db.unregister_callback(id),
505            #[cfg(feature = "storage-sled")]
506            DbInstance::Sled(db) => db.unregister_callback(id),
507            #[cfg(feature = "storage-tikv")]
508            DbInstance::TiKv(db) => db.unregister_callback(id),
509        }
510    }
511    /// Dispatcher method. See [crate::Db::register_fixed_rule].
512    pub fn register_fixed_rule<R>(&self, name: String, rule_impl: R) -> Result<()>
513    where
514        R: FixedRule + 'static,
515    {
516        match self {
517            DbInstance::Mem(db) => db.register_fixed_rule(name, rule_impl),
518            #[cfg(feature = "storage-sqlite")]
519            DbInstance::Sqlite(db) => db.register_fixed_rule(name, rule_impl),
520            #[cfg(feature = "storage-rocksdb")]
521            DbInstance::RocksDb(db) => db.register_fixed_rule(name, rule_impl),
522            #[cfg(feature = "storage-new-rocksdb")]
523            DbInstance::NewRocksDb(db) => db.register_fixed_rule(name, rule_impl),
524            #[cfg(feature = "storage-sled")]
525            DbInstance::Sled(db) => db.register_fixed_rule(name, rule_impl),
526            #[cfg(feature = "storage-tikv")]
527            DbInstance::TiKv(db) => db.register_fixed_rule(name, rule_impl),
528        }
529    }
530    /// Dispatcher method. See [crate::Db::unregister_fixed_rule]
531    pub fn unregister_fixed_rule(&self, name: &str) -> Result<bool> {
532        match self {
533            DbInstance::Mem(db) => db.unregister_fixed_rule(name),
534            #[cfg(feature = "storage-sqlite")]
535            DbInstance::Sqlite(db) => db.unregister_fixed_rule(name),
536            #[cfg(feature = "storage-rocksdb")]
537            DbInstance::RocksDb(db) => db.unregister_fixed_rule(name),
538            #[cfg(feature = "storage-new-rocksdb")]
539            DbInstance::NewRocksDb(db) => db.unregister_fixed_rule(name),
540            #[cfg(feature = "storage-sled")]
541            DbInstance::Sled(db) => db.unregister_fixed_rule(name),
542            #[cfg(feature = "storage-tikv")]
543            DbInstance::TiKv(db) => db.unregister_fixed_rule(name),
544        }
545    }
546
547    /// Dispatcher method. See [crate::Db::run_multi_transaction]
548    pub fn run_multi_transaction(
549        &self,
550        write: bool,
551        payloads: Receiver<TransactionPayload>,
552        results: Sender<Result<NamedRows>>,
553    ) {
554        match self {
555            DbInstance::Mem(db) => db.run_multi_transaction(write, payloads, results),
556            #[cfg(feature = "storage-sqlite")]
557            DbInstance::Sqlite(db) => db.run_multi_transaction(write, payloads, results),
558            #[cfg(feature = "storage-rocksdb")]
559            DbInstance::RocksDb(db) => db.run_multi_transaction(write, payloads, results),
560            #[cfg(feature = "storage-new-rocksdb")]
561            DbInstance::NewRocksDb(db) => db.run_multi_transaction(write, payloads, results),
562            #[cfg(feature = "storage-sled")]
563            DbInstance::Sled(db) => db.run_multi_transaction(write, payloads, results),
564            #[cfg(feature = "storage-tikv")]
565            DbInstance::TiKv(db) => db.run_multi_transaction(write, payloads, results),
566        }
567    }
568    /// A higher-level, blocking wrapper for [crate::Db::run_multi_transaction]. Runs the transaction on a dedicated thread.
569    /// Write transactions _may_ block other reads, but we guarantee that this does not happen for the RocksDB backend.
570    pub fn multi_transaction(&self, write: bool) -> MultiTransaction {
571        let (app2db_send, app2db_recv) = bounded(1);
572        let (db2app_send, db2app_recv) = bounded(1);
573        let db = self.clone();
574        #[cfg(target_arch = "wasm32")]
575        std::thread::spawn(move || db.run_multi_transaction(write, app2db_recv, db2app_send));
576        #[cfg(not(target_arch = "wasm32"))]
577        rayon::spawn(move || db.run_multi_transaction(write, app2db_recv, db2app_send));
578        MultiTransaction {
579            sender: app2db_send,
580            receiver: db2app_recv,
581        }
582    }
583}
584
585/// A multi-transaction handle.
586/// You should use either the fields directly, or the associated functions.
587pub struct MultiTransaction {
588    /// Commands can be sent into the transaction through this channel
589    pub sender: Sender<TransactionPayload>,
590    /// Results can be retrieved from the transaction from this channel
591    pub receiver: Receiver<Result<NamedRows>>,
592}
593
594impl MultiTransaction {
595    /// Runs a single script in the transaction.
596    pub fn run_script(
597        &self,
598        payload: &str,
599        params: BTreeMap<String, DataValue>,
600    ) -> Result<NamedRows> {
601        if let Err(err) = self
602            .sender
603            .send(TransactionPayload::Query((payload.to_string(), params)))
604        {
605            bail!(err);
606        }
607        match self.receiver.recv() {
608            Ok(r) => r,
609            Err(err) => bail!(err),
610        }
611    }
612    /// Commits the multi-transaction
613    pub fn commit(&self) -> Result<()> {
614        if let Err(err) = self.sender.send(TransactionPayload::Commit) {
615            bail!(err);
616        }
617        match self.receiver.recv() {
618            Ok(_) => Ok(()),
619            Err(err) => bail!(err),
620        }
621    }
622    /// Aborts the multi-transaction
623    pub fn abort(&self) -> Result<()> {
624        if let Err(err) = self.sender.send(TransactionPayload::Abort) {
625            bail!(err);
626        }
627        match self.receiver.recv() {
628            Ok(_) => Ok(()),
629            Err(err) => bail!(err),
630        }
631    }
632}
633
634/// Convert error raised by the database into friendly JSON format
635pub fn format_error_as_json(mut err: Report, source: Option<&str>) -> JsonValue {
636    if err.source_code().is_none() {
637        if let Some(src) = source {
638            err = err.with_source_code(format!("{src} "));
639        }
640    }
641    let mut text_err = String::new();
642    let mut json_err = String::new();
643    TEXT_ERR_HANDLER
644        .render_report(&mut text_err, err.as_ref())
645        .expect("render text error failed");
646    JSON_ERR_HANDLER
647        .render_report(&mut json_err, err.as_ref())
648        .expect("render json error failed");
649    let mut json: serde_json::Value =
650        serde_json::from_str(&json_err).expect("parse rendered json error failed");
651    let map = json.as_object_mut().unwrap();
652    map.insert("ok".to_string(), json!(false));
653    map.insert("display".to_string(), json!(text_err));
654    json
655}
656
657lazy_static! {
658    static ref TEXT_ERR_HANDLER: GraphicalReportHandler = miette::GraphicalReportHandler::new()
659        .with_theme(GraphicalTheme {
660            characters: ThemeCharacters::unicode(),
661            styles: ThemeStyles::ansi()
662        });
663    static ref JSON_ERR_HANDLER: JSONReportHandler = miette::JSONReportHandler::new();
664}