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

A file-based, multi-database, multi-user database engine. This type is designed for use with Tokio. For blocking (non-asynchronous) code, see the Storage type instead.

Converting between Blocking and Async Types

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

Converting from AsyncDatabase::open to AsyncStorage::open

AsyncDatabase::open is a simple method that uses AsyncStorage to create a database named default with the schema provided. These two ways of opening the database are the same:

// `bonsaidb_core` is re-exported to `bonsaidb::core` or `bonsaidb_local::core`.
use bonsaidb_core::connection::AsyncStorageConnection;
use bonsaidb_core::schema::Schema;
// `bonsaidb_local` is re-exported to `bonsaidb::local` if using the omnibus crate.
use bonsaidb_local::{
    config::{Builder, StorageConfiguration},
    AsyncDatabase, AsyncStorage,
};
// This creates a Storage instance, creates a database, and returns it.
let db = AsyncDatabase::open::<MySchema>(StorageConfiguration::new("my-db.bonsaidb")).await?;

// This is the equivalent code being executed:
let storage =
    AsyncStorage::open(StorageConfiguration::new("my-db.bonsaidb").with_schema::<MySchema>()?)
        .await?;
storage.create_database::<MySchema>("default", true).await?;
let db = storage.database::<MySchema>("default").await?;

Using multiple databases

This example shows how to use AsyncStorage to create and use multiple databases with multiple schemas:

use bonsaidb_core::connection::AsyncStorageConnection;
use bonsaidb_core::schema::{Collection, Schema};
use bonsaidb_local::config::{Builder, StorageConfiguration};
use bonsaidb_local::AsyncStorage;
use serde::{Deserialize, Serialize};

#[derive(Debug, Schema)]
#[schema(name = "my-schema", collections = [BlogPost, Author])]
struct MySchema;

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

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

let storage = AsyncStorage::open(
    StorageConfiguration::new("my-db.bonsaidb")
        .with_schema::<BlogPost>()?
        .with_schema::<MySchema>()?,
)
.await?;

storage
    .create_database::<BlogPost>("ectons-blog", true)
    .await?;
let ectons_blog = storage.database::<BlogPost>("ectons-blog").await?;
storage
    .create_database::<MySchema>("another-db", true)
    .await?;
let another_db = storage.database::<MySchema>("another-db").await?;

Implementations§

source§

impl AsyncStorage

source

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

Creates or opens a multi-database AsyncStorage with its data stored in directory.

source

pub async fn restore<L: AnyBackupLocation + 'static>( &self, location: L ) -> Result<(), Error>

Restores all data from a previously stored backup location.

source

pub async fn backup<L: AnyBackupLocation + 'static>( &self, location: L ) -> Result<(), Error>

Stores a copy of all data in this instance to location.

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 into_blocking(self) -> Storage

Converts this instance into its blocking version, which is able to be used without async.

source

pub fn to_blocking(&self) -> Storage

Converts this instance into its blocking version, which is able to be used without async.

source

pub fn as_blocking(&self) -> &Storage

Returns a reference to this instance’s blocking version, which is able to be used without async.

Trait Implementations§

source§

impl AsyncStorageConnection for AsyncStorage

§

type Authenticated = AsyncStorage

The [StorageConnection] type returned from authentication calls.
§

type Database = AsyncDatabase

The type that represents a database for this implementation.
source§

fn admin<'life0, 'async_trait>( &'life0 self ) -> Pin<Box<dyn Future<Output = Self::Database> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Returns the currently authenticated session, if any.
source§

fn create_database_with_schema<'life0, 'life1, 'async_trait>( &'life0 self, name: &'life1 str, schema: SchemaName, only_if_needed: bool ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Creates a database named name using the [SchemaName] schema. Read more
source§

fn database<'life0, 'life1, 'async_trait, DB>( &'life0 self, name: &'life1 str ) -> Pin<Box<dyn Future<Output = Result<Self::Database, Error>> + Send + 'async_trait>>
where DB: 'async_trait + Schema, Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Returns a reference to database name with schema DB.
source§

fn delete_database<'life0, 'life1, 'async_trait>( &'life0 self, name: &'life1 str ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Deletes a database named name. Read more
source§

fn list_databases<'life0, 'async_trait>( &'life0 self ) -> Pin<Box<dyn Future<Output = Result<Vec<Database>, Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Lists the databases in this storage.
source§

fn list_available_schemas<'life0, 'async_trait>( &'life0 self ) -> Pin<Box<dyn Future<Output = Result<Vec<SchemaSummary>, Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Lists the [SchemaName]s registered with this storage.
source§

fn create_user<'life0, 'life1, 'async_trait>( &'life0 self, username: &'life1 str ) -> Pin<Box<dyn Future<Output = Result<u64, Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Creates a user.
source§

fn delete_user<'user, 'life0, 'async_trait, U>( &'life0 self, user: U ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
where U: 'async_trait + Nameable<'user, u64> + Send + Sync, Self: 'async_trait, 'user: 'async_trait, 'life0: 'async_trait,

Deletes a user.
source§

fn set_user_password<'user, 'life0, 'async_trait, U>( &'life0 self, user: U, password: SensitiveString ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
where U: 'async_trait + Nameable<'user, u64> + Send + Sync, Self: 'async_trait, 'user: 'async_trait, 'life0: 'async_trait,

Sets a user’s password.
source§

fn authenticate<'life0, 'async_trait>( &'life0 self, authentication: Authentication ) -> Pin<Box<dyn Future<Output = Result<Self, Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Authenticates using an AuthenticationToken. If successful, the returned instance will have the permissions from identity.
source§

fn assume_identity<'life0, 'life1, 'async_trait>( &'life0 self, identity: IdentityReference<'life1> ) -> Pin<Box<dyn Future<Output = Result<Self::Authenticated, Error>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Assumes the identity. If successful, the returned instance will have the merged permissions of the current authentication session and the permissions from identity.
source§

fn add_permission_group_to_user<'user, 'group, 'life0, 'async_trait, U, G>( &'life0 self, user: U, permission_group: G ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
where U: 'async_trait + Nameable<'user, u64> + Send + Sync, G: 'async_trait + Nameable<'group, u64> + Send + Sync, Self: 'async_trait, 'user: 'async_trait, 'group: 'async_trait, 'life0: 'async_trait,

Adds a user to a permission group.
source§

fn remove_permission_group_from_user<'user, 'group, 'life0, 'async_trait, U, G>( &'life0 self, user: U, permission_group: G ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
where U: 'async_trait + Nameable<'user, u64> + Send + Sync, G: 'async_trait + Nameable<'group, u64> + Send + Sync, Self: 'async_trait, 'user: 'async_trait, 'group: 'async_trait, 'life0: 'async_trait,

Removes a user from a permission group.
source§

fn add_role_to_user<'user, 'group, 'life0, 'async_trait, U, G>( &'life0 self, user: U, role: G ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
where U: 'async_trait + Nameable<'user, u64> + Send + Sync, G: 'async_trait + Nameable<'group, u64> + Send + Sync, Self: 'async_trait, 'user: 'async_trait, 'group: 'async_trait, 'life0: 'async_trait,

Adds a user to a permission group.
source§

fn remove_role_from_user<'user, 'group, 'life0, 'async_trait, U, G>( &'life0 self, user: U, role: G ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
where U: 'async_trait + Nameable<'user, u64> + Send + Sync, G: 'async_trait + Nameable<'group, u64> + Send + Sync, Self: 'async_trait, 'user: 'async_trait, 'group: 'async_trait, 'life0: 'async_trait,

Removes a user from a permission group.
§

fn create_database<'life0, 'life1, 'async_trait, DB>( &'life0 self, name: &'life1 str, only_if_needed: bool ) -> Pin<Box<dyn Future<Output = Result<Self::Database, Error>> + Send + 'async_trait>>
where 'life0: 'async_trait, 'life1: 'async_trait, DB: 'async_trait + Schema, Self: 'async_trait,

Creates a database named name with the Schema provided. Read more
§

fn authenticate_with_token<'life0, 'life1, 'async_trait>( &'life0 self, id: u64, token: &'life1 SensitiveString ) -> Pin<Box<dyn Future<Output = Result<<Self::Authenticated as AsyncStorageConnection>::Authenticated, Error>> + Send + 'async_trait>>
where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

Authenticates using an AuthenticationToken. If successful, the returned instance will have the permissions from identity.
§

fn authenticate_with_password<'name, 'life0, 'async_trait, User>( &'life0 self, user: User, password: SensitiveString ) -> Pin<Box<dyn Future<Output = Result<Self::Authenticated, Error>> + Send + 'async_trait>>
where 'name: 'async_trait, 'life0: 'async_trait, User: 'async_trait + Nameable<'name, u64> + Send, Self: 'async_trait,

Authenticates a User using a password. If successful, the returned instance will have the permissions from identity.
source§

impl Clone for AsyncStorage

source§

fn clone(&self) -> AsyncStorage

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 Debug for AsyncStorage

source§

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

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

impl<'a> From<&'a AsyncStorage> for Storage

source§

fn from(storage: &'a AsyncStorage) -> Self

Converts to this type from the input type.
source§

impl From<AsyncStorage> for Storage

source§

fn from(storage: AsyncStorage) -> Self

Converts to this type from the input type.
source§

impl HasSession for AsyncStorage

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

impl StorageNonBlocking for AsyncStorage

source§

fn path(&self) -> &Path

Returns the path of the database storage.
source§

fn assume_session(&self, session: Session) -> Result<Self, Error>

Returns a new instance of Storage with session as the effective authentication session. This call will only succeed if there is no current session.

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