Struct bonsaidb_local::AsyncStorage

pub struct AsyncStorage { /* private fields */ }

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:

• AsyncStorage::into_blocking()
• AsyncStorage::to_blocking()
• AsyncStorage::as_blocking()
• Storage::into_async()
• Storage::to_async()
• Storage::into_async_with_runtime()
• Storage::to_async_with_runtime()

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

impl AsyncStorage

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

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

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

Restores all data from a previously stored backup location.

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

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

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

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

pub fn to_blocking(&self) -> Storage

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

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

impl Clone for AsyncStorage

fn clone(&self) -> AsyncStorage

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for AsyncStorage

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

Formats the value using the given formatter.

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

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

Converts to this type from the input type.

impl From<AsyncStorage> for Storage

fn from(storage: AsyncStorage) -> Self

Converts to this type from the input type.

impl HasSession for AsyncStorage

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

fn path(&self) -> &Path

Returns the path of the database storage.

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.