serai_db/
lib.rs

1#![cfg_attr(docsrs, feature(doc_cfg))]
2#![doc = include_str!("../README.md")]
3#![deny(missing_docs)]
4#![no_std]
5
6#[cfg(feature = "alloc")]
7extern crate alloc;
8#[cfg(feature = "std")]
9extern crate std;
10
11#[doc(hidden)]
12pub mod __private {
13  #[cfg(feature = "schema")]
14  pub use borsh;
15}
16#[cfg(feature = "schema")]
17mod schema;
18
19#[cfg(feature = "std")]
20mod mem;
21#[cfg(feature = "std")]
22pub use mem::*;
23
24#[cfg(feature = "rocksdb")]
25mod rocks;
26#[cfg(feature = "rocksdb")]
27pub use rocks::{RocksDB, new_rocksdb};
28
29#[cfg(feature = "parity-db")]
30mod parity_db;
31#[cfg(feature = "parity-db")]
32pub use parity_db::{ParityDb, new_parity_db};
33
34/// A handle to an ACID database via which values may be read.
35///
36/// It's undefined if the retrieved values are:
37/// A) The value which was written to the key _when this handle was instantiated_ (from a snapshot)
38/// B) The value which is _currently_ written to the key (which may have been written to by a
39///    committed transaction during the lifetime of this handle)
40///
41/// In other words, there's no guarantee reads are repeatable.
42pub trait Get {
43  /// Get a value from the database.
44  ///
45  /// If the key is not present in the database, this will return `None`.
46  ///
47  /// The implementation MAY panic if the database is corrupt or would become corrupted. If the
48  /// length of the key exceeds an internal limit on the length of keys, this may be considered as
49  /// corruption.
50  fn get(&self, key: impl AsRef<[u8]>) -> Option<impl AsRef<[u8]>>;
51}
52
53/// An ACID transaction.
54///
55/// This transaction implements [`Get`]. If this transaction has queued a write to a key, the
56/// retrieved value for that key will be the latest value queued to be written by this transaction.
57/// If this transaction has not queued a write to a key, it's undefined if the retrieved value is:
58/// A) The value which was written to the key _when the transaction was opened_ (from a snapshot)
59/// B) The value which is _currently_ written to the key (which may have been written to by a
60///    committed transaction during the lifetime of this transaction)
61///
62/// In other words, there's no guarantee reads are repeatable.
63pub trait Transaction: Get {
64  /// Write a value to this key.
65  ///
66  /// If a concurrent transaction has queued a write to this key, the database MAY panic or exhibit
67  /// an undefined choice of which transaction's queued write resolves as the database's current
68  /// value for this key.
69  ///
70  /// The implementation MAY panic if the database is corrupt or would become corrupted. If the
71  /// length of the key or value exceeds internal limits on lengths or the total database size,
72  /// this may be considered as corruption.
73  fn set(&mut self, key: impl AsRef<[u8]>, value: impl AsRef<[u8]>);
74
75  /// Delete the value from this key.
76  ///
77  /// If no value is stored to this key, this operation is effectively a NOP.
78  ///
79  /// This is considered as a write to this key, with properties as documented by
80  /// [`Transaction::put`].
81  ///
82  /// The implementation MAY panic if the database is corrupt or would become corrupted. If the
83  /// length of the key exceeds an internal limit on the length of keys, this may be considered as
84  /// corruption.
85  fn del(&mut self, key: impl AsRef<[u8]>);
86
87  /// Commit this transaction.
88  ///
89  /// The implementation MAY panic if the database is corrupt or would become corrupted.
90  fn commit(self);
91}
92
93/// A handle to an ACID database.
94///
95/// This implements [`Clone`] on the expectation clones refer to the same underlying database. This
96/// effectively makes this a reference-counted handle to the underlying database.
97///
98/// This implements [`Get`], allowing reading the _current_ values in the database without having
99/// to open a transaction.
100pub trait Db: Clone + Get {
101  /// The type representing a database transaction.
102  type Transaction<'db>: Transaction
103  where
104    Self: 'db;
105
106  /// Open a new transaction.
107  fn txn(&mut self) -> Self::Transaction<'_>;
108}
serai_db/lib.rs

serai_db/
lib.rs
