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, 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,
    schema::{Collection, Schema},
};
use bonsaidb_local::{
    config::{Builder, StorageConfiguration},
    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 Database = AsyncDatabase

The type that represents a database for this implementation.

type Authenticated = AsyncStorage

The StorageConnection type returned from authentication calls.

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

Lists the databases in this storage.

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

Lists the SchemaNames 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
    'life0: 'async_trait,
    'life1: 'async_trait,
    Self: '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
    'user: 'async_trait,
    U: 'async_trait + Nameable<'user, u64> + Send + Sync,
    'life0: 'async_trait,
    Self: '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
    'user: 'async_trait,
    U: 'async_trait + Nameable<'user, u64> + Send + Sync,
    'life0: 'async_trait,
    Self: '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
    'life0: 'async_trait,
    Self: '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
    'life0: 'async_trait,
    'life1: 'async_trait,
    Self: '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
    'user: 'async_trait,
    'group: 'async_trait,
    U: 'async_trait + Nameable<'user, u64> + Send + Sync,
    G: 'async_trait + Nameable<'group, u64> + Send + Sync,
    'life0: 'async_trait,
    Self: '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
    'user: 'async_trait,
    'group: 'async_trait,
    U: 'async_trait + Nameable<'user, u64> + Send + Sync,
    G: 'async_trait + Nameable<'group, u64> + Send + Sync,
    'life0: 'async_trait,
    Self: '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
    'user: 'async_trait,
    'group: 'async_trait,
    U: 'async_trait + Nameable<'user, u64> + Send + Sync,
    G: 'async_trait + Nameable<'group, u64> + Send + Sync,
    'life0: 'async_trait,
    Self: '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
    'user: 'async_trait,
    'group: 'async_trait,
    U: 'async_trait + Nameable<'user, u64> + Send + Sync,
    G: 'async_trait + Nameable<'group, u64> + Send + Sync,
    'life0: 'async_trait,
    Self: '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, Global>> 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, Global>> 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, Global>> 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.