Struct bonsaidb_local::Database

pub struct Database { /* private fields */ }

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:

• AsyncDatabase::into_blocking()
• AsyncDatabase::to_blocking()
• AsyncDatabase::as_blocking()
• Database::into_async()
• Database::to_async()
• Database::into_async_with_runtime()
• Database::to_async_with_runtime()

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

impl Database

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.

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.

pub fn schematic(&self) -> &Schematic

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

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.

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.

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.

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

impl Clone for Database

fn clone(&self) -> Database

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Connection for Database

type Storage = Storage

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

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

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

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.

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

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

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

Compacts the entire database to reclaim unused disk space.

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

Compacts the key value store to reclaim unused disk space.

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.

impl DatabaseNonBlocking for Database

fn name(&self) -> &str

Returns the name of the database.

impl Debug for Database

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

Formats the value using the given formatter.

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

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

Converts to this type from the input type.

impl From<AsyncDatabase> for Database

fn from(database: AsyncDatabase) -> Self

Converts to this type from the input type.

impl HasSchema for Database

fn schematic(&self) -> &Schematic

Returns the schema for the database.

impl HasSession for Database

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

Returns the currently authenticated session, if any.

fn allowed_to<'a, R, P>(&self, resource_name: R, action: &P) -> bool

where 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.

impl KeyValue for Database

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.

impl LowLevelConnection for Database

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].

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

Retrieves the document with id stored within the named collection.

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.

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.

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.

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.

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

Compacts the collection to reclaim unused disk space.

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.

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.

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.

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.

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.

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.

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.

fn overwrite<C, PrimaryKey>( &self, id: &PrimaryKey, contents: Vec<u8> ) -> 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.

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.

fn get_multiple<'id, C, PrimaryKey, DocumentIds, I>( &self, ids: DocumentIds ) -> Result<Vec<OwnedDocument>, 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.

fn list<'id, C, R, PrimaryKey>( &self, ids: R, order: Sort, limit: Option<u32> ) -> Result<Vec<OwnedDocument>, Error>

where C: Collection, R: Into<RangeRef<'id, <C as Collection>::PrimaryKey, PrimaryKey>> + Send, PrimaryKey: KeyEncoding<<C as Collection>::PrimaryKey> + PartialEq + '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.

fn list_headers<'id, C, R, PrimaryKey>( &self, ids: R, order: Sort, limit: Option<u32> ) -> Result<Vec<Header>, Error>

where C: Collection, R: Into<RangeRef<'id, <C as Collection>::PrimaryKey, PrimaryKey>> + Send, PrimaryKey: KeyEncoding<<C as Collection>::PrimaryKey> + PartialEq + '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.

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 + 'id + ?Sized, <C as Collection>::PrimaryKey: Borrow<PrimaryKey> + PartialEq<PrimaryKey>,

Counts the number of documents within the range of ids.

fn delete<C, H>(&self, doc: &H) -> Result<(), Error>

where C: Collection, H: HasHeader + Send + Sync,

Removes a Document from the database.

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>>, Error>

where V: SerializedView, Key: KeyEncoding<<V as View>::Key> + PartialEq + ?Sized, <V as View>::Key: Borrow<Key> + PartialEq<Key>,

Queries for view entries matching View.

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 + ?Sized, <V as View>::Key: Borrow<Key> + PartialEq<Key>,

Queries for view entries matching View with their source documents.

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 + ?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.

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 + ?Sized, <V as View>::Key: Borrow<Key> + PartialEq<Key>,

Reduces the view entries matching View.

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>>, Error>

where V: SerializedView, Key: KeyEncoding<<V as View>::Key> + PartialEq + ?Sized, <V as View>::Key: Borrow<Key> + PartialEq<Key>,

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

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 + ?Sized, <V as View>::Key: Borrow<Key> + PartialEq<Key>,

Deletes all of the documents associated with this view.

impl PubSub for Database

type Subscriber = Subscriber

The Subscriber type for this PubSub connection.

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

Create a new [Subscriber] for this relay.

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

Publishes a payload to all subscribers of topic.

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.