sp_database/
lib.rs

1// This file is part of Substrate.
2
3// Copyright (C) Parity Technologies (UK) Ltd.
4// SPDX-License-Identifier: Apache-2.0
5
6// Licensed under the Apache License, Version 2.0 (the "License");
7// you may not use this file except in compliance with the License.
8// You may obtain a copy of the License at
9//
10// 	http://www.apache.org/licenses/LICENSE-2.0
11//
12// Unless required by applicable law or agreed to in writing, software
13// distributed under the License is distributed on an "AS IS" BASIS,
14// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15// See the License for the specific language governing permissions and
16// limitations under the License.
17
18//! The main database trait, allowing Substrate to store data persistently.
19
20pub mod error;
21mod kvdb;
22mod mem;
23
24pub use crate::kvdb::as_database;
25#[cfg(feature = "rocksdb")]
26pub use crate::kvdb::as_rocksdb_database;
27pub use mem::MemDb;
28
29/// An identifier for a column.
30pub type ColumnId = u32;
31
32/// An alteration to the database.
33#[derive(Clone)]
34pub enum Change<H> {
35	Set(ColumnId, Vec<u8>, Vec<u8>),
36	Remove(ColumnId, Vec<u8>),
37	Store(ColumnId, H, Vec<u8>),
38	Reference(ColumnId, H),
39	Release(ColumnId, H),
40}
41
42/// A series of changes to the database that can be committed atomically. They do not take effect
43/// until passed into `Database::commit`.
44#[derive(Default, Clone)]
45pub struct Transaction<H>(pub Vec<Change<H>>);
46
47impl<H> Transaction<H> {
48	/// Create a new transaction to be prepared and committed atomically.
49	pub fn new() -> Self {
50		Transaction(Vec::new())
51	}
52	/// Set the value of `key` in `col` to `value`, replacing anything that is there currently.
53	pub fn set(&mut self, col: ColumnId, key: &[u8], value: &[u8]) {
54		self.0.push(Change::Set(col, key.to_vec(), value.to_vec()))
55	}
56	/// Set the value of `key` in `col` to `value`, replacing anything that is there currently.
57	pub fn set_from_vec(&mut self, col: ColumnId, key: &[u8], value: Vec<u8>) {
58		self.0.push(Change::Set(col, key.to_vec(), value))
59	}
60	/// Remove the value of `key` in `col`.
61	pub fn remove(&mut self, col: ColumnId, key: &[u8]) {
62		self.0.push(Change::Remove(col, key.to_vec()))
63	}
64	/// Store the `preimage` of `hash` into the database, so that it may be looked up later with
65	/// `Database::get`. This may be called multiple times, but subsequent
66	/// calls will ignore `preimage` and simply increase the number of references on `hash`.
67	pub fn store(&mut self, col: ColumnId, hash: H, preimage: Vec<u8>) {
68		self.0.push(Change::Store(col, hash, preimage))
69	}
70	/// Increase the number of references for `hash` in the database.
71	pub fn reference(&mut self, col: ColumnId, hash: H) {
72		self.0.push(Change::Reference(col, hash))
73	}
74	/// Release the preimage of `hash` from the database. An equal number of these to the number of
75	/// corresponding `store`s must have been given before it is legal for `Database::get` to
76	/// be unable to provide the preimage.
77	pub fn release(&mut self, col: ColumnId, hash: H) {
78		self.0.push(Change::Release(col, hash))
79	}
80}
81
82pub trait Database<H: Clone + AsRef<[u8]>>: Send + Sync {
83	/// Commit the `transaction` to the database atomically. Any further calls to `get` or `lookup`
84	/// will reflect the new state.
85	fn commit(&self, transaction: Transaction<H>) -> error::Result<()>;
86
87	/// Retrieve the value previously stored against `key` or `None` if
88	/// `key` is not currently in the database.
89	fn get(&self, col: ColumnId, key: &[u8]) -> Option<Vec<u8>>;
90
91	/// Check if the value exists in the database without retrieving it.
92	fn contains(&self, col: ColumnId, key: &[u8]) -> bool {
93		self.get(col, key).is_some()
94	}
95
96	/// Check value size in the database possibly without retrieving it.
97	fn value_size(&self, col: ColumnId, key: &[u8]) -> Option<usize> {
98		self.get(col, key).map(|v| v.len())
99	}
100
101	/// Call `f` with the value previously stored against `key`.
102	///
103	/// This may be faster than `get` since it doesn't allocate.
104	/// Use `with_get` helper function if you need `f` to return a value from `f`
105	fn with_get(&self, col: ColumnId, key: &[u8], f: &mut dyn FnMut(&[u8])) {
106		if let Some(v) = self.get(col, key) {
107			f(&v)
108		}
109	}
110
111	/// Check if database supports internal ref counting for state data.
112	///
113	/// For backwards compatibility returns `false` by default.
114	fn supports_ref_counting(&self) -> bool {
115		false
116	}
117
118	/// Remove a possible path-prefix from the key.
119	///
120	/// Not all database implementations use a prefix for keys, so this function may be a noop.
121	fn sanitize_key(&self, _key: &mut Vec<u8>) {}
122
123	/// Optimize a database column.
124	fn optimize_db_col(&self, _col: ColumnId) -> error::Result<()> {
125		Ok(())
126	}
127}
128
129impl<H> std::fmt::Debug for dyn Database<H> {
130	fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
131		write!(f, "Database")
132	}
133}
134
135/// Call `f` with the value previously stored against `key` and return the result, or `None` if
136/// `key` is not currently in the database.
137///
138/// This may be faster than `get` since it doesn't allocate.
139pub fn with_get<R, H: Clone + AsRef<[u8]>>(
140	db: &dyn Database<H>,
141	col: ColumnId,
142	key: &[u8],
143	mut f: impl FnMut(&[u8]) -> R,
144) -> Option<R> {
145	let mut result: Option<R> = None;
146	let mut adapter = |k: &_| {
147		result = Some(f(k));
148	};
149	db.with_get(col, key, &mut adapter);
150	result
151}
sp_database/lib.rs

sp_database/
lib.rs
