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§

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

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.

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

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.

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.

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.

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§

Returns a copy of the value. Read more
Performs copy-assignment from source. Read more
The [StorageConnection] type that is paired with this type.
Returns the [StorageConnection] implementor that this database belongs to.
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. Read more
Fetches the last transaction id that has been committed, if any.
Compacts the entire database to reclaim unused disk space. Read more
Compacts the key value store to reclaim unused disk space. Read more
Accesses a collection for the connected Schema.
Accesses a [schema::View] from this connection.
Compacts the collection to reclaim unused disk space. Read more
Returns the name of the database.
Formats the value using the given formatter. Read more
Converts to this type from the input type.
Converts to this type from the input type.
Returns the currently authenticated session, if any.
Checks if action is permitted against resource_name.
Checks if action is permitted against resource_name. If permission is denied, returns a PermissionDenied error. Read more
Executes a single [KeyOperation].
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. Read more
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. Read more
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. Read more
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. Read more
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. Read more
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. Read more
Deletes the value stored at key.
The current namespace.
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. Read more
Returns the schema for the database.
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]. Read more
Retrieves the document with id stored within the named collection. Read more
Retrieves all documents within the range of ids from the named collection. To retrieve all documents, pass in .. for ids. Read more
Retrieves all headers within the range of ids from the named collection. To retrieve all documents, pass in .. for ids. Read more
Counts the number of documents within the range of ids from the named collection. Read more
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
Compacts the collection to reclaim unused disk space. Read more
Queries for view entries from the named view. Read more
Queries for view entries from the named view with their source documents. Read more
Reduces the view entries from the named view. Read more
Reduces the view entries from the named view, reducing the values by each unique key. Read more
Deletes all source documents for entries that match within the named view. Read more
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
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
Overwrites an existing document, or inserts a new document. Upon success, doc.revision will be updated with the new revision information. Read more
Retrieves a stored document from Collection C identified by id. Read more
Retrieves all documents matching ids. Documents that are not found are not returned, but no error will be generated. Read more
Retrieves all documents within the range of ids. To retrieve all documents, pass in .. for ids. Read more
Retrieves all documents within the range of ids. To retrieve all documents, pass in .. for ids. Read more
Counts the number of documents within the range of ids. Read more
Removes a Document from the database. Read more
Queries for view entries matching View. Read more
Queries for view entries matching View with their source documents. Read more
Queries for view entries matching View with their source documents, deserialized. Read more
Reduces the view entries matching View. Read more
Reduces the view entries matching View, reducing the values by each unique key. Read more
Deletes all of the documents associated with this view. Read more
The Subscriber type for this PubSub connection.
Create a new [Subscriber] for this relay.
Publishes a payload to all subscribers of topic.
Publishes a payload to all subscribers of all topics.
Publishes a payload to all subscribers of topic.
Publishes a payload to all subscribers of all topics.

Auto Trait Implementations§

Blanket Implementations§

Gets the TypeId of self. Read more
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more

Returns the argument unchanged.

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

Calls U::from(self).

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

The alignment of pointer.
The type for initializers.
Initializes a with the given initializer. Read more
Dereferences the given pointer. Read more
Mutably dereferences the given pointer. Read more
Drops the object pointed to by the given pointer. Read more
Should always be Self
The resulting type after obtaining ownership.
Creates owned data from borrowed data, usually by cloning. Read more
Uses borrowed data to replace owned data, usually by cloning. Read more
The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.
Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more