Struct bonsaidb::local::AsyncStorage
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:
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
impl AsyncStorage
pub async fn open(
configuration: StorageConfiguration
) -> impl Future<Output = Result<AsyncStorage, Error>>
pub async fn open( configuration: StorageConfiguration ) -> impl Future<Output = Result<AsyncStorage, Error>>
Creates or opens a multi-database AsyncStorage
with its data stored in directory
.
pub async fn restore<L>(
&self,
location: L
) -> impl Future<Output = Result<(), Error>>where
L: AnyBackupLocation + 'static,
pub async fn restore<L>( &self, location: L ) -> impl Future<Output = Result<(), Error>>where L: AnyBackupLocation + 'static,
Restores all data from a previously stored backup location
.
pub async fn backup<L>(
&self,
location: L
) -> impl Future<Output = Result<(), Error>>where
L: AnyBackupLocation + 'static,
pub async fn backup<L>( &self, location: L ) -> impl Future<Output = Result<(), Error>>where L: AnyBackupLocation + 'static,
Stores a copy of all data in this instance to location
.
pub fn with_effective_permissions(
&self,
effective_permissions: Permissions
) -> Option<AsyncStorage>
pub fn with_effective_permissions( &self, effective_permissions: Permissions ) -> Option<AsyncStorage>
Restricts an unauthenticated instance to having effective_permissions
.
Returns None
if a session has already been established.
pub fn into_blocking(self) -> Storage
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
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
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
impl AsyncStorageConnection for AsyncStorage
§type Authenticated = AsyncStorage
type Authenticated = AsyncStorage
StorageConnection
type returned from authentication calls.§type Database = AsyncDatabase
type Database = AsyncDatabase
§fn admin<'life0, 'async_trait>(
&'life0 self
) -> Pin<Box<dyn Future<Output = <AsyncStorage as AsyncStorageConnection>::Database> + Send + 'async_trait, Global>>where
'life0: 'async_trait,
AsyncStorage: 'async_trait,
fn admin<'life0, 'async_trait>( &'life0 self ) -> Pin<Box<dyn Future<Output = <AsyncStorage as AsyncStorageConnection>::Database> + Send + 'async_trait, Global>>where 'life0: 'async_trait, AsyncStorage: 'async_trait,
§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, Global>>where
'life0: 'async_trait,
'life1: 'async_trait,
AsyncStorage: 'async_trait,
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, Global>>where 'life0: 'async_trait, 'life1: 'async_trait, AsyncStorage: 'async_trait,
§fn database<'life0, 'life1, 'async_trait, DB>(
&'life0 self,
name: &'life1 str
) -> Pin<Box<dyn Future<Output = Result<<AsyncStorage as AsyncStorageConnection>::Database, Error>> + Send + 'async_trait, Global>>where
'life0: 'async_trait,
'life1: 'async_trait,
DB: 'async_trait + Schema,
AsyncStorage: 'async_trait,
fn database<'life0, 'life1, 'async_trait, DB>( &'life0 self, name: &'life1 str ) -> Pin<Box<dyn Future<Output = Result<<AsyncStorage as AsyncStorageConnection>::Database, Error>> + Send + 'async_trait, Global>>where 'life0: 'async_trait, 'life1: 'async_trait, DB: 'async_trait + Schema, AsyncStorage: 'async_trait,
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, Global>>where
'life0: 'async_trait,
'life1: 'async_trait,
AsyncStorage: 'async_trait,
fn delete_database<'life0, 'life1, 'async_trait>( &'life0 self, name: &'life1 str ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait, Global>>where 'life0: 'async_trait, 'life1: 'async_trait, AsyncStorage: 'async_trait,
name
. Read more§fn list_databases<'life0, 'async_trait>(
&'life0 self
) -> Pin<Box<dyn Future<Output = Result<Vec<Database, Global>, Error>> + Send + 'async_trait, Global>>where
'life0: 'async_trait,
AsyncStorage: 'async_trait,
fn list_databases<'life0, 'async_trait>( &'life0 self ) -> Pin<Box<dyn Future<Output = Result<Vec<Database, Global>, Error>> + Send + 'async_trait, Global>>where 'life0: 'async_trait, AsyncStorage: 'async_trait,
§fn list_available_schemas<'life0, 'async_trait>(
&'life0 self
) -> Pin<Box<dyn Future<Output = Result<Vec<SchemaSummary, Global>, Error>> + Send + 'async_trait, Global>>where
'life0: 'async_trait,
AsyncStorage: 'async_trait,
fn list_available_schemas<'life0, 'async_trait>( &'life0 self ) -> Pin<Box<dyn Future<Output = Result<Vec<SchemaSummary, Global>, Error>> + Send + 'async_trait, Global>>where 'life0: 'async_trait, AsyncStorage: 'async_trait,
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, Global>>where
'life0: 'async_trait,
'life1: 'async_trait,
AsyncStorage: 'async_trait,
fn create_user<'life0, 'life1, 'async_trait>( &'life0 self, username: &'life1 str ) -> Pin<Box<dyn Future<Output = Result<u64, Error>> + Send + 'async_trait, Global>>where 'life0: 'async_trait, 'life1: 'async_trait, AsyncStorage: 'async_trait,
§fn delete_user<'user, 'life0, 'async_trait, U>(
&'life0 self,
user: U
) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait, Global>>where
'user: 'async_trait,
'life0: 'async_trait,
U: 'async_trait + Nameable<'user, u64> + Send + Sync,
AsyncStorage: 'async_trait,
fn delete_user<'user, 'life0, 'async_trait, U>( &'life0 self, user: U ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait, Global>>where 'user: 'async_trait, 'life0: 'async_trait, U: 'async_trait + Nameable<'user, u64> + Send + Sync, AsyncStorage: 'async_trait,
§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, Global>>where
'user: 'async_trait,
'life0: 'async_trait,
U: 'async_trait + Nameable<'user, u64> + Send + Sync,
AsyncStorage: 'async_trait,
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, Global>>where 'user: 'async_trait, 'life0: 'async_trait, U: 'async_trait + Nameable<'user, u64> + Send + Sync, AsyncStorage: 'async_trait,
§fn authenticate<'life0, 'async_trait>(
&'life0 self,
authentication: Authentication
) -> Pin<Box<dyn Future<Output = Result<AsyncStorage, Error>> + Send + 'async_trait, Global>>where
'life0: 'async_trait,
AsyncStorage: 'async_trait,
fn authenticate<'life0, 'async_trait>( &'life0 self, authentication: Authentication ) -> Pin<Box<dyn Future<Output = Result<AsyncStorage, Error>> + Send + 'async_trait, Global>>where 'life0: 'async_trait, AsyncStorage: 'async_trait,
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<<AsyncStorage as AsyncStorageConnection>::Authenticated, Error>> + Send + 'async_trait, Global>>where
'life0: 'async_trait,
'life1: 'async_trait,
AsyncStorage: 'async_trait,
fn assume_identity<'life0, 'life1, 'async_trait>( &'life0 self, identity: IdentityReference<'life1> ) -> Pin<Box<dyn Future<Output = Result<<AsyncStorage as AsyncStorageConnection>::Authenticated, Error>> + Send + 'async_trait, Global>>where 'life0: 'async_trait, 'life1: 'async_trait, AsyncStorage: 'async_trait,
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, Global>>where
'user: 'async_trait,
'group: 'async_trait,
'life0: 'async_trait,
U: 'async_trait + Nameable<'user, u64> + Send + Sync,
G: 'async_trait + Nameable<'group, u64> + Send + Sync,
AsyncStorage: 'async_trait,
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, Global>>where 'user: 'async_trait, 'group: 'async_trait, 'life0: 'async_trait, U: 'async_trait + Nameable<'user, u64> + Send + Sync, G: 'async_trait + Nameable<'group, u64> + Send + Sync, AsyncStorage: 'async_trait,
§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, Global>>where
'user: 'async_trait,
'group: 'async_trait,
'life0: 'async_trait,
U: 'async_trait + Nameable<'user, u64> + Send + Sync,
G: 'async_trait + Nameable<'group, u64> + Send + Sync,
AsyncStorage: 'async_trait,
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, Global>>where 'user: 'async_trait, 'group: 'async_trait, 'life0: 'async_trait, U: 'async_trait + Nameable<'user, u64> + Send + Sync, G: 'async_trait + Nameable<'group, u64> + Send + Sync, AsyncStorage: 'async_trait,
§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, Global>>where
'user: 'async_trait,
'group: 'async_trait,
'life0: 'async_trait,
U: 'async_trait + Nameable<'user, u64> + Send + Sync,
G: 'async_trait + Nameable<'group, u64> + Send + Sync,
AsyncStorage: 'async_trait,
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, Global>>where 'user: 'async_trait, 'group: 'async_trait, 'life0: 'async_trait, U: 'async_trait + Nameable<'user, u64> + Send + Sync, G: 'async_trait + Nameable<'group, u64> + Send + Sync, AsyncStorage: 'async_trait,
§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, Global>>where
'user: 'async_trait,
'group: 'async_trait,
'life0: 'async_trait,
U: 'async_trait + Nameable<'user, u64> + Send + Sync,
G: 'async_trait + Nameable<'group, u64> + Send + Sync,
AsyncStorage: 'async_trait,
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, Global>>where 'user: 'async_trait, 'group: 'async_trait, 'life0: 'async_trait, U: 'async_trait + Nameable<'user, u64> + Send + Sync, G: 'async_trait + Nameable<'group, u64> + Send + Sync, AsyncStorage: 'async_trait,
§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,
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,
§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,
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,
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,
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,
User
using a password. If
successful, the returned instance will have the permissions from
identity
.§impl Clone for AsyncStorage
impl Clone for AsyncStorage
§fn clone(&self) -> AsyncStorage
fn clone(&self) -> AsyncStorage
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read more§impl Debug for AsyncStorage
impl Debug for AsyncStorage
§impl<'a> From<&'a AsyncStorage> for Storage
impl<'a> From<&'a AsyncStorage> for Storage
§fn from(storage: &'a AsyncStorage) -> Storage
fn from(storage: &'a AsyncStorage) -> Storage
§impl From<AsyncStorage> for Storage
impl From<AsyncStorage> for Storage
§fn from(storage: AsyncStorage) -> Storage
fn from(storage: AsyncStorage) -> Storage
§impl HasSession for AsyncStorage
impl HasSession for AsyncStorage
§fn allowed_to<'a, R, P>(&self, resource_name: R, action: &P) -> boolwhere
R: AsRef<[Identifier<'a>]>,
P: Action,
fn allowed_to<'a, R, P>(&self, resource_name: R, action: &P) -> boolwhere R: AsRef<[Identifier<'a>]>, P: Action,
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,
fn check_permission<'a, R, P>( &self, resource_name: R, action: &P ) -> Result<(), Error>where R: AsRef<[Identifier<'a>]>, P: Action,
action
is permitted against resource_name
. If permission
is denied, returns a PermissionDenied
error.§impl StorageNonBlocking for AsyncStorage
impl StorageNonBlocking for AsyncStorage
§fn assume_session(&self, session: Session) -> Result<AsyncStorage, Error>
fn assume_session(&self, session: Session) -> Result<AsyncStorage, Error>
Storage
with session
as the effective
authentication session. This call will only succeed if there is no
current session.