pub struct Database { /* private fields */ }
Expand description

A database stored in BonsaiDb. This type blocks the current thread when used. See AsyncDatabase for this type’s async counterpart.

Converting between Blocking and Async Types

AsyncDatabase and Database can be converted to and from each other using:

Using Database to create a single database

Databaseprovides an easy mechanism to open and access a single database:

// `bonsaidb_core` is re-exported to `bonsaidb::core` or `bonsaidb_local::core`.
use bonsaidb_core::schema::Collection;
// `bonsaidb_local` is re-exported to `bonsaidb::local` if using the omnibus crate.
use bonsaidb_local::{
    config::{Builder, StorageConfiguration},
    Database,
};
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize, Collection)]
#[collection(name = "blog-posts")]
struct BlogPost {
    pub title: String,
    pub contents: String,
}

let db = Database::open::<BlogPost>(StorageConfiguration::new("my-db.bonsaidb"))?;

Under the hood, this initializes a Storage instance pointing at “./my-db.bonsaidb”. It then returns (or creates) a database named “default” with the schema BlogPost.

In this example, BlogPost implements the Collection trait, and all collections can be used as a [Schema].

Implementations§

source§

impl Database

source

pub fn with_effective_permissions( &self, effective_permissions: Permissions ) -> Option<Self>

Restricts an unauthenticated instance to having effective_permissions. Returns None if a session has already been established.

source

pub fn open<DB: Schema>( configuration: StorageConfiguration ) -> Result<Self, Error>

Creates a Storage with a single-database named “default” with its data stored at path. This requires exclusive access to the storage location configured. Attempting to open the same path multiple times concurrently will lead to errors.

Using this method is perfect if only one database is being used. However, if multiple databases are needed, it is much better to store multiple databases in a single Storage instance rather than creating multiple independent databases using this method.

When opening multiple databases using this function, each database will have its own thread pool, cache, task worker pool, and more. By using a single Storage instance, BonsaiDb will use less resources and likely perform better.

source

pub fn schematic(&self) -> &Schematic

Returns the [Schematic] for the schema for this database.

source

pub fn into_async(self) -> AsyncDatabase

Converts this instance into its blocking version, which is able to be used without async. The returned instance uses the current Tokio runtime handle to spawn blocking tasks.

Panics

Panics if called outside the context of a Tokio runtime.

source

pub fn into_async_with_runtime(self, runtime: Handle) -> AsyncDatabase

Converts this instance into its blocking version, which is able to be used without async. The returned instance uses the provided runtime handle to spawn blocking tasks.

source

pub fn to_async(&self) -> AsyncDatabase

Converts this instance into its blocking version, which is able to be used without async. The returned instance uses the current Tokio runtime handle to spawn blocking tasks.

Panics

Panics if called outside the context of a Tokio runtime.

source

pub fn to_async_with_runtime(&self, runtime: Handle) -> AsyncDatabase

Converts this instance into its blocking version, which is able to be used without async. The returned instance uses the provided runtime handle to spawn blocking tasks.

Trait Implementations§

source§

impl Clone for Database

source§

fn clone(&self) -> Database

Returns a copy of the value. Read more
1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
source§

impl Connection for Database

§

type Storage = Storage

The [StorageConnection] type that is paired with this type.
source§

fn storage(&self) -> Self::Storage

Returns the [StorageConnection] implementor that this database belongs to.
source§

fn list_executed_transactions( &self, starting_id: Option<u64>, result_limit: Option<u32> ) -> Result<Vec<Executed>, Error>

Lists executed transactions from this Schema. By default, a maximum of 1000 entries will be returned, but that limit can be overridden by setting result_limit. A hard limit of 100,000 results will be returned. To begin listing after another known transaction_id, pass transaction_id + 1 into starting_id.
source§

fn last_transaction_id(&self) -> Result<Option<u64>, Error>

Fetches the last transaction id that has been committed, if any.
source§

fn compact(&self) -> Result<(), Error>

Compacts the entire database to reclaim unused disk space. Read more
source§

fn compact_key_value_store(&self) -> Result<(), Error>

Compacts the key value store to reclaim unused disk space. Read more
§

fn collection<C>(&self) -> Collection<'_, Self, C>where C: Collection,

Accesses a collection for the connected Schema.
§

fn view<V>(&self) -> View<'_, Self, V, <V as View>::Key>where V: SerializedView,

Accesses a [schema::View] from this connection.
§

fn compact_collection<C>(&self) -> Result<(), Error>where C: Collection,

Compacts the collection to reclaim unused disk space. Read more
source§

impl DatabaseNonBlocking for Database

source§

fn name(&self) -> &str

Returns the name of the database.
source§

impl Debug for Database

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
source§

impl<'a> From<&'a AsyncDatabase> for Database

source§

fn from(database: &'a AsyncDatabase) -> Self

Converts to this type from the input type.
source§

impl From<AsyncDatabase> for Database

source§

fn from(database: AsyncDatabase) -> Self

Converts to this type from the input type.
source§

impl HasSchema for Database

source§

fn schematic(&self) -> &Schematic

Returns the schema for the database.
source§

impl HasSession for Database

source§

fn session(&self) -> Option<&Session>

Returns the currently authenticated session, if any.
§

fn allowed_to<'a, R, P>(&self, resource_name: R, action: &P) -> boolwhere R: AsRef<[Identifier<'a>]>, P: Action,

Checks if action is permitted against resource_name.
§

fn check_permission<'a, R, P>( &self, resource_name: R, action: &P ) -> Result<(), Error>where R: AsRef<[Identifier<'a>]>, P: Action,

Checks if action is permitted against resource_name. If permission is denied, returns a PermissionDenied error.
source§

impl KeyValue for Database

source§

fn execute_key_operation(&self, op: KeyOperation) -> Result<Output, Error>

Executes a single [KeyOperation].
§

fn set_key<S, V, 'a>(&'a self, key: S, value: &'a V) -> Builder<'a, Self, V>where S: Into<String>, V: Serialize + Send + Sync,

Sets key to value. This function returns a builder that is also a Future. Awaiting the builder will execute [Command::Set] with the options given.
§

fn set_binary_key<S, 'a>( &'a self, key: S, bytes: &'a [u8] ) -> Builder<'a, Self, ()>where S: Into<String>,

Sets key to bytes. This function returns a builder that is also a Future. Awaiting the builder will execute [Command::Set] with the options given.
§

fn set_numeric_key<S, V>(&self, key: S, value: V) -> Builder<'_, Self, ()>where S: Into<String>, V: Into<Numeric>,

Sets key to value. This stores the value as a Numeric, enabling atomic math operations to be performed on this key. This function returns a builder that is also a Future. Awaiting the builder will execute [Command::Set] with the options given.
§

fn increment_key_by<S, V>(&self, key: S, value: V) -> Builder<'_, Self, V>where S: Into<String> + Send + Sync, V: Into<Numeric> + TryFrom<Numeric, Error = IncompatibleTypeError> + Send + Sync,

Increments key by value. The value stored must be a Numeric, otherwise an error will be returned. The result of the increment will be the value’s type. For example, if the stored value is currently a u64, but value is a f64, the current value will be converted to an f64, and the stored value will be an f64.
§

fn decrement_key_by<S, V>(&self, key: S, value: V) -> Builder<'_, Self, V>where S: Into<String> + Send + Sync, V: Into<Numeric> + TryFrom<Numeric, Error = IncompatibleTypeError> + Send + Sync,

Decrements key by value. The value stored must be a Numeric, otherwise an error will be returned. The result of the decrement will be the value’s type. For example, if the stored value is currently a u64, but value is a f64, the current value will be converted to an f64, and the stored value will be an f64.
§

fn get_key<S>(&self, key: S) -> Builder<'_, Self>where S: Into<String>,

Gets the value stored at key. This function returns a builder that is also a Future. Awaiting the builder will execute [Command::Get] with the options given.
§

fn delete_key<S>(&self, key: S) -> Result<KeyStatus, Error>where S: Into<String> + Send,

Deletes the value stored at key.
§

fn key_namespace(&self) -> Option<&str>

The current namespace.
§

fn with_key_namespace(&self, namespace: &str) -> Namespaced<'_, Self>

Access this Key-Value store within a namespace. When using the returned [Namespaced] instance, all keys specified will be separated into their own storage designated by namespace.
source§

impl LowLevelConnection for Database

source§

fn apply_transaction( &self, transaction: Transaction ) -> Result<Vec<OperationResult>, Error>

Applies a [Transaction] to the [schema::Schema]. If any operation in the [Transaction] fails, none of the operations will be applied to the [schema::Schema].
source§

fn get_from_collection( &self, id: DocumentId, collection: &CollectionName ) -> Result<Option<OwnedDocument>, Error>

Retrieves the document with id stored within the named collection. Read more
source§

fn list_from_collection( &self, ids: Range<DocumentId>, sort: Sort, limit: Option<u32>, collection: &CollectionName ) -> Result<Vec<OwnedDocument>, Error>

Retrieves all documents within the range of ids from the named collection. To retrieve all documents, pass in .. for ids. Read more
source§

fn list_headers_from_collection( &self, ids: Range<DocumentId>, sort: Sort, limit: Option<u32>, collection: &CollectionName ) -> Result<Vec<Header>, Error>

Retrieves all headers within the range of ids from the named collection. To retrieve all documents, pass in .. for ids. Read more
source§

fn count_from_collection( &self, ids: Range<DocumentId>, collection: &CollectionName ) -> Result<u64, Error>

Counts the number of documents within the range of ids from the named collection. Read more
source§

fn get_multiple_from_collection( &self, ids: &[DocumentId], collection: &CollectionName ) -> Result<Vec<OwnedDocument>, Error>

Retrieves all documents matching ids from the named collection. Documents that are not found are not returned, but no error will be generated. Read more
source§

fn compact_collection_by_name( &self, collection: CollectionName ) -> Result<(), Error>

Compacts the collection to reclaim unused disk space. Read more
source§

fn query_by_name( &self, view: &ViewName, key: Option<SerializedQueryKey>, order: Sort, limit: Option<u32>, access_policy: AccessPolicy ) -> Result<Vec<Serialized>, Error>

Queries for view entries from the named view. Read more
source§

fn query_by_name_with_docs( &self, view: &ViewName, key: Option<SerializedQueryKey>, order: Sort, limit: Option<u32>, access_policy: AccessPolicy ) -> Result<MappedSerializedDocuments, Error>

Queries for view entries from the named view with their source documents. Read more
source§

fn reduce_by_name( &self, view_name: &ViewName, key: Option<SerializedQueryKey>, access_policy: AccessPolicy ) -> Result<Vec<u8>, Error>

Reduces the view entries from the named view. Read more
source§

fn reduce_grouped_by_name( &self, view_name: &ViewName, key: Option<SerializedQueryKey>, access_policy: AccessPolicy ) -> Result<Vec<MappedSerializedValue>, Error>

Reduces the view entries from the named view, reducing the values by each unique key. Read more
source§

fn delete_docs_by_name( &self, view: &ViewName, key: Option<SerializedQueryKey>, access_policy: AccessPolicy ) -> Result<u64, Error>

Deletes all source documents for entries that match within the named view. Read more
§

fn insert<C, PrimaryKey, B>( &self, id: Option<&PrimaryKey>, contents: B ) -> Result<CollectionHeader<<C as Collection>::PrimaryKey>, Error>where C: Collection, B: Into<Bytes> + Send, PrimaryKey: KeyEncoding<<C as Collection>::PrimaryKey> + Send + ?Sized,

Inserts a newly created document into the connected [schema::Schema] for the Collection C. If id is None a unique id will be generated. If an id is provided and a document already exists with that id, a conflict error will be returned. Read more
§

fn update<C, D>(&self, doc: &mut D) -> Result<(), Error>where C: Collection, D: Document<C> + Send + Sync,

Updates an existing document in the connected [schema::Schema] for the Collection C. Upon success, doc.revision will be updated with the new revision. Read more
§

fn overwrite<C, PrimaryKey>( &self, id: &PrimaryKey, contents: Vec<u8, Global> ) -> Result<CollectionHeader<<C as Collection>::PrimaryKey>, Error>where C: Collection, PrimaryKey: KeyEncoding<<C as Collection>::PrimaryKey>,

Overwrites an existing document, or inserts a new document. Upon success, doc.revision will be updated with the new revision information. Read more
§

fn get<C, PrimaryKey>( &self, id: &PrimaryKey ) -> Result<Option<OwnedDocument>, Error>where C: Collection, PrimaryKey: KeyEncoding<<C as Collection>::PrimaryKey> + ?Sized,

Retrieves a stored document from Collection C identified by id. Read more
§

fn get_multiple<'id, C, PrimaryKey, DocumentIds, I>( &self, ids: DocumentIds ) -> Result<Vec<OwnedDocument, Global>, Error>where C: Collection, DocumentIds: IntoIterator<Item = &'id PrimaryKey, IntoIter = I> + Send + Sync, I: Iterator<Item = &'id PrimaryKey> + Send + Sync, PrimaryKey: KeyEncoding<<C as Collection>::PrimaryKey> + 'id + ?Sized,

Retrieves all documents matching ids. Documents that are not found are not returned, but no error will be generated. Read more
§

fn list<'id, C, R, PrimaryKey>( &self, ids: R, order: Sort, limit: Option<u32> ) -> Result<Vec<OwnedDocument, Global>, Error>where C: Collection, R: Into<RangeRef<'id, <C as Collection>::PrimaryKey, PrimaryKey>> + Send, PrimaryKey: KeyEncoding<<C as Collection>::PrimaryKey> + PartialEq<PrimaryKey> + 'id + ?Sized, <C as Collection>::PrimaryKey: Borrow<PrimaryKey> + PartialEq<PrimaryKey>,

Retrieves all documents within the range of ids. To retrieve all documents, pass in .. for ids. Read more
§

fn list_headers<'id, C, R, PrimaryKey>( &self, ids: R, order: Sort, limit: Option<u32> ) -> Result<Vec<Header, Global>, Error>where C: Collection, R: Into<RangeRef<'id, <C as Collection>::PrimaryKey, PrimaryKey>> + Send, PrimaryKey: KeyEncoding<<C as Collection>::PrimaryKey> + PartialEq<PrimaryKey> + 'id + ?Sized, <C as Collection>::PrimaryKey: Borrow<PrimaryKey> + PartialEq<PrimaryKey>,

Retrieves all documents within the range of ids. To retrieve all documents, pass in .. for ids. Read more
§

fn count<'id, C, R, PrimaryKey>(&self, ids: R) -> Result<u64, Error>where C: Collection, R: Into<RangeRef<'id, <C as Collection>::PrimaryKey, PrimaryKey>> + Send, PrimaryKey: KeyEncoding<<C as Collection>::PrimaryKey> + PartialEq<PrimaryKey> + 'id + ?Sized, <C as Collection>::PrimaryKey: Borrow<PrimaryKey> + PartialEq<PrimaryKey>,

Counts the number of documents within the range of ids. Read more
§

fn delete<C, H>(&self, doc: &H) -> Result<(), Error>where C: Collection, H: HasHeader + Send + Sync,

Removes a Document from the database. Read more
§

fn query<V, Key>( &self, key: Option<QueryKey<'_, <V as View>::Key, Key>>, order: Sort, limit: Option<u32>, access_policy: AccessPolicy ) -> Result<Vec<CollectionMap<<<V as View>::Collection as Collection>::PrimaryKey, <V as View>::Key, <V as View>::Value>, Global>, Error>where V: SerializedView, Key: KeyEncoding<<V as View>::Key> + PartialEq<Key> + ?Sized, <V as View>::Key: Borrow<Key> + PartialEq<Key>,

Queries for view entries matching View. Read more
§

fn query_with_docs<V, Key>( &self, key: Option<QueryKey<'_, <V as View>::Key, Key>>, order: Sort, limit: Option<u32>, access_policy: AccessPolicy ) -> Result<MappedDocuments<OwnedDocument, V>, Error>where V: SerializedView, Key: KeyEncoding<<V as View>::Key> + PartialEq<Key> + ?Sized, <V as View>::Key: Borrow<Key> + PartialEq<Key>,

Queries for view entries matching View with their source documents. Read more
§

fn query_with_collection_docs<V, Key>( &self, key: Option<QueryKey<'_, <V as View>::Key, Key>>, order: Sort, limit: Option<u32>, access_policy: AccessPolicy ) -> Result<MappedDocuments<CollectionDocument<<V as View>::Collection>, V>, Error>where Key: KeyEncoding<<V as View>::Key> + PartialEq<Key> + ?Sized, <V as View>::Key: Borrow<Key> + PartialEq<Key>, V: SerializedView, <V as View>::Collection: SerializedCollection, <<V as View>::Collection as SerializedCollection>::Contents: Debug,

Queries for view entries matching View with their source documents, deserialized. Read more
§

fn reduce<V, Key>( &self, key: Option<QueryKey<'_, <V as View>::Key, Key>>, access_policy: AccessPolicy ) -> Result<<V as View>::Value, Error>where V: SerializedView, Key: KeyEncoding<<V as View>::Key> + PartialEq<Key> + ?Sized, <V as View>::Key: Borrow<Key> + PartialEq<Key>,

Reduces the view entries matching View. Read more
§

fn reduce_grouped<V, Key>( &self, key: Option<QueryKey<'_, <V as View>::Key, Key>>, access_policy: AccessPolicy ) -> Result<Vec<MappedValue<<V as View>::Key, <V as View>::Value>, Global>, Error>where V: SerializedView, Key: KeyEncoding<<V as View>::Key> + PartialEq<Key> + ?Sized, <V as View>::Key: Borrow<Key> + PartialEq<Key>,

Reduces the view entries matching View, reducing the values by each unique key. Read more
§

fn delete_docs<V, Key>( &self, key: Option<QueryKey<'_, <V as View>::Key, Key>>, access_policy: AccessPolicy ) -> Result<u64, Error>where V: SerializedView, Key: KeyEncoding<<V as View>::Key> + PartialEq<Key> + ?Sized, <V as View>::Key: Borrow<Key> + PartialEq<Key>,

Deletes all of the documents associated with this view. Read more
source§

impl PubSub for Database

§

type Subscriber = Subscriber

The Subscriber type for this PubSub connection.
source§

fn create_subscriber(&self) -> Result<Self::Subscriber, Error>

Create a new [Subscriber] for this relay.
source§

fn publish_bytes(&self, topic: Vec<u8>, payload: Vec<u8>) -> Result<(), Error>

Publishes a payload to all subscribers of topic.
source§

fn publish_bytes_to_all( &self, topics: impl IntoIterator<Item = Vec<u8>> + Send, payload: Vec<u8> ) -> Result<(), Error>

Publishes a payload to all subscribers of all topics.
§

fn publish<Topic, Payload>( &self, topic: &Topic, payload: &Payload ) -> Result<(), Error>where Topic: Serialize, Payload: Serialize,

Publishes a payload to all subscribers of topic.
§

fn publish_to_all<'topics, Topics, Topic, Payload>( &self, topics: Topics, payload: &Payload ) -> Result<(), Error>where Topics: IntoIterator<Item = &'topics Topic> + 'topics, Topic: Serialize + 'topics, Payload: Serialize,

Publishes a payload to all subscribers of all topics.

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for Twhere U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> Same<T> for T

§

type Output = T

Should always be Self
source§

impl<T> ToOwned for Twhere T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for Twhere V: MultiLane<T>,

§

fn vzip(self) -> V

source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more