Struct bonsaidb::local::Database

source ·
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<Database>

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

source

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

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) -> <Database as Connection>::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
source§

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

Accesses a collection for the connected Schema.
source§

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

Accesses a schema::View from this connection.
source§

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

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

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

source§

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

Converts to this type from the input type.
source§

impl<'a, B> From<&'a ServerDatabase<B>> for Database
where B: Backend,

source§

fn from(server: &'a ServerDatabase<B>) -> Database

Converts to this type from the input type.
source§

impl From<AsyncDatabase> for Database

source§

fn from(database: AsyncDatabase) -> Database

Converts to this type from the input type.
source§

impl<B> From<ServerDatabase<B>> for Database
where B: Backend,

source§

fn from(server: ServerDatabase<B>) -> Database

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.
source§

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.
source§

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.
source§

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.
source§

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.
source§

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.
source§

fn increment_key_by<S, V>(&self, key: S, value: V) -> Builder<'_, Self, V>

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.
source§

fn decrement_key_by<S, V>(&self, key: S, value: V) -> Builder<'_, Self, V>

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.
source§

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.
source§

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

Deletes the value stored at key.
source§

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

The current namespace.
source§

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
source§

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
source§

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
source§

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. Read more
source§

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
source§

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. Read more
source§

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. Read more
source§

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. Read more
source§

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. Read more
source§

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

Removes a Document from the database. Read more
source§

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. Read more
source§

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. Read more
source§

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>

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

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. Read more
source§

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. Read more
source§

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. Read more
source§

impl PubSub for Database

§

type Subscriber = Subscriber

The Subscriber type for this PubSub connection.
source§

fn create_subscriber(&self) -> Result<<Database as PubSub>::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.
source§

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

Publishes a payload to all subscribers of topic.
source§

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 T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
§

impl<'a, T, E> AsTaggedExplicit<'a, E> for T
where T: 'a,

§

fn explicit(self, class: Class, tag: u32) -> TaggedParser<'a, Explicit, Self, E>

§

impl<'a, T, E> AsTaggedImplicit<'a, E> for T
where T: 'a,

§

fn implicit( self, class: Class, constructed: bool, tag: u32 ) -> TaggedParser<'a, Implicit, Self, E>

source§

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

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where 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.

§

impl<T> Instrument for T

§

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

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

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 T
where 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 for T

§

type Output = T

Should always be Self
source§

impl<T> ToOwned for T
where 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 T
where 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 T
where 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 T
where V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> WithSubscriber for T

§

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
§

fn with_current_subscriber(self) -> WithDispatch<Self>

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