pub struct Storage { /* private fields */ }
Expand description
A file-based, multi-database, multi-user database engine. This type blocks
the current thread when used. See AsyncStorage
for
this type’s async counterpart.
Converting between Blocking and Async Types
AsyncStorage
and Storage
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 Database::open
to Storage::open
Database::open
is a simple method that uses Storage
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::StorageConnection;
use bonsaidb_core::schema::Schema;
// `bonsaidb_local` is re-exported to `bonsaidb::local` if using the omnibus crate.
use bonsaidb_local::{
config::{Builder, StorageConfiguration},
Database, Storage,
};
// This creates a Storage instance, creates a database, and returns it.
let db = Database::open::<MySchema>(StorageConfiguration::new("my-db.bonsaidb"))?;
// This is the equivalent code being executed:
let storage =
Storage::open(StorageConfiguration::new("my-db.bonsaidb").with_schema::<MySchema>()?)?;
storage.create_database::<MySchema>("default", true)?;
let db = storage.database::<MySchema>("default")?;
Using multiple databases
This example shows how to use Storage
to create and use multiple databases
with multiple schemas:
use bonsaidb_core::connection::StorageConnection;
use bonsaidb_core::schema::{Collection, Schema};
use bonsaidb_local::config::{Builder, StorageConfiguration};
use bonsaidb_local::Storage;
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 = Storage::open(
StorageConfiguration::new("my-db.bonsaidb")
.with_schema::<BlogPost>()?
.with_schema::<MySchema>()?,
)?;
storage.create_database::<BlogPost>("ectons-blog", true)?;
let ectons_blog = storage.database::<BlogPost>("ectons-blog")?;
storage.create_database::<MySchema>("another-db", true)?;
let another_db = storage.database::<MySchema>("another-db")?;
Implementations§
§impl Storage
impl Storage
pub fn open(configuration: StorageConfiguration) -> Result<Storage, Error>
pub fn open(configuration: StorageConfiguration) -> Result<Storage, Error>
Creates or opens a multi-database Storage
with its data stored in directory
.
pub fn unique_id(&self) -> StorageId
pub fn unique_id(&self) -> StorageId
Returns the unique id of the server.
This value is set from the StorageConfiguration
or randomly
generated when creating a server. It shouldn’t be changed after a server
is in use, as doing can cause issues. For example, the vault that
manages encrypted storage uses the server ID to store the vault key. If
the server ID changes, the vault key storage will need to be updated
with the new server ID.
pub fn register_schema<DB>(&self) -> Result<(), Error>where
DB: Schema,
pub fn register_schema<DB>(&self) -> Result<(), Error>where DB: Schema,
Registers a schema for use within the server.
pub fn with_effective_permissions(
&self,
effective_permissions: Permissions
) -> Option<Storage>
pub fn with_effective_permissions( &self, effective_permissions: Permissions ) -> Option<Storage>
Restricts an unauthenticated instance to having effective_permissions
.
Returns None
if a session has already been established.
pub fn into_async(self) -> AsyncStorage
pub fn into_async(self) -> AsyncStorage
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.
pub fn into_async_with_runtime(self, runtime: Handle) -> AsyncStorage
pub fn into_async_with_runtime(self, runtime: Handle) -> AsyncStorage
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.
pub fn to_async(&self) -> AsyncStorage
pub fn to_async(&self) -> AsyncStorage
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.
pub fn to_async_with_runtime(&self, runtime: Handle) -> AsyncStorage
pub fn to_async_with_runtime(&self, runtime: Handle) -> AsyncStorage
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§
§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
source§impl<'a, B> From<&'a CustomServer<B>> for Storagewhere
B: Backend,
impl<'a, B> From<&'a CustomServer<B>> for Storagewhere B: Backend,
source§fn from(server: &'a CustomServer<B>) -> Storage
fn from(server: &'a CustomServer<B>) -> Storage
§impl From<AsyncStorage> for Storage
impl From<AsyncStorage> for Storage
§fn from(storage: AsyncStorage) -> Storage
fn from(storage: AsyncStorage) -> Storage
source§impl<B> From<CustomServer<B>> for Storagewhere
B: Backend,
impl<B> From<CustomServer<B>> for Storagewhere B: Backend,
source§fn from(server: CustomServer<B>) -> Storage
fn from(server: CustomServer<B>) -> Storage
§impl HasSession for Storage
impl HasSession for Storage
§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 StorageConnection for Storage
impl StorageConnection for Storage
§type Authenticated = Storage
type Authenticated = Storage
StorageConnection
type returned from authentication calls.§fn admin(&self) -> <Storage as StorageConnection>::Database
fn admin(&self) -> <Storage as StorageConnection>::Database
§fn create_database_with_schema(
&self,
name: &str,
schema: SchemaName,
only_if_needed: bool
) -> Result<(), Error>
fn create_database_with_schema( &self, name: &str, schema: SchemaName, only_if_needed: bool ) -> Result<(), Error>
§fn database<DB>(
&self,
name: &str
) -> Result<<Storage as StorageConnection>::Database, Error>where
DB: Schema,
fn database<DB>( &self, name: &str ) -> Result<<Storage as StorageConnection>::Database, Error>where DB: Schema,
name
with schema DB
.§fn list_databases(&self) -> Result<Vec<Database, Global>, Error>
fn list_databases(&self) -> Result<Vec<Database, Global>, Error>
§fn list_available_schemas(&self) -> Result<Vec<SchemaSummary, Global>, Error>
fn list_available_schemas(&self) -> Result<Vec<SchemaSummary, Global>, Error>
SchemaName
s registered with this storage.§fn delete_user<'user, U>(&self, user: U) -> Result<(), Error>where
U: Nameable<'user, u64> + Send + Sync,
fn delete_user<'user, U>(&self, user: U) -> Result<(), Error>where U: Nameable<'user, u64> + Send + Sync,
§fn set_user_password<'user, U>(
&self,
user: U,
password: SensitiveString
) -> Result<(), Error>where
U: Nameable<'user, u64> + Send + Sync,
fn set_user_password<'user, U>( &self, user: U, password: SensitiveString ) -> Result<(), Error>where U: Nameable<'user, u64> + Send + Sync,
§fn authenticate(&self, authentication: Authentication) -> Result<Storage, Error>
fn authenticate(&self, authentication: Authentication) -> Result<Storage, Error>
§fn assume_identity(
&self,
identity: IdentityReference<'_>
) -> Result<<Storage as StorageConnection>::Authenticated, Error>
fn assume_identity( &self, identity: IdentityReference<'_> ) -> Result<<Storage as StorageConnection>::Authenticated, Error>
identity
. If successful, the returned instance will have
the permissions from identity
.§fn add_permission_group_to_user<'user, 'group, U, G>(
&self,
user: U,
permission_group: G
) -> Result<(), Error>where
U: Nameable<'user, u64> + Send + Sync,
G: Nameable<'group, u64> + Send + Sync,
fn add_permission_group_to_user<'user, 'group, U, G>( &self, user: U, permission_group: G ) -> Result<(), Error>where U: Nameable<'user, u64> + Send + Sync, G: Nameable<'group, u64> + Send + Sync,
§fn remove_permission_group_from_user<'user, 'group, U, G>(
&self,
user: U,
permission_group: G
) -> Result<(), Error>where
U: Nameable<'user, u64> + Send + Sync,
G: Nameable<'group, u64> + Send + Sync,
fn remove_permission_group_from_user<'user, 'group, U, G>( &self, user: U, permission_group: G ) -> Result<(), Error>where U: Nameable<'user, u64> + Send + Sync, G: Nameable<'group, u64> + Send + Sync,
§fn add_role_to_user<'user, 'group, U, G>(
&self,
user: U,
role: G
) -> Result<(), Error>where
U: Nameable<'user, u64> + Send + Sync,
G: Nameable<'group, u64> + Send + Sync,
fn add_role_to_user<'user, 'group, U, G>( &self, user: U, role: G ) -> Result<(), Error>where U: Nameable<'user, u64> + Send + Sync, G: Nameable<'group, u64> + Send + Sync,
§fn remove_role_from_user<'user, 'group, U, G>(
&self,
user: U,
role: G
) -> Result<(), Error>where
U: Nameable<'user, u64> + Send + Sync,
G: Nameable<'group, u64> + Send + Sync,
fn remove_role_from_user<'user, 'group, U, G>( &self, user: U, role: G ) -> Result<(), Error>where U: Nameable<'user, u64> + Send + Sync, G: Nameable<'group, u64> + Send + Sync,
§fn create_database<DB>(
&self,
name: &str,
only_if_needed: bool
) -> Result<Self::Database, Error>where
DB: Schema,
fn create_database<DB>( &self, name: &str, only_if_needed: bool ) -> Result<Self::Database, Error>where DB: Schema,
§fn authenticate_with_token(
&self,
id: u64,
token: &SensitiveString
) -> Result<<Self::Authenticated as StorageConnection>::Authenticated, Error>
fn authenticate_with_token( &self, id: u64, token: &SensitiveString ) -> Result<<Self::Authenticated as StorageConnection>::Authenticated, Error>
AuthenticationToken
. If
successful, the returned instance will have the permissions from
identity
.§fn authenticate_with_password<'name, User>(
&self,
user: User,
password: SensitiveString
) -> Result<Self::Authenticated, Error>where
User: Nameable<'name, u64>,
fn authenticate_with_password<'name, User>( &self, user: User, password: SensitiveString ) -> Result<Self::Authenticated, Error>where User: Nameable<'name, u64>,
User
using a password. If
successful, the returned instance will have the permissions from
identity
.