Struct bonsaidb_local::Storage
source · [−]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, 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,
schema::{Collection, Schema},
};
use bonsaidb_local::{
config::{Builder, StorageConfiguration},
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
sourceimpl Storage
impl Storage
sourcepub fn open(configuration: StorageConfiguration) -> Result<Self, Error>
pub fn open(configuration: StorageConfiguration) -> Result<Self, Error>
Creates or opens a multi-database Storage
with its data stored in directory
.
sourcepub 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.
sourcepub fn register_schema<DB: Schema>(&self) -> Result<(), Error>
pub fn register_schema<DB: Schema>(&self) -> Result<(), Error>
Registers a schema for use within the server.
sourcepub fn with_effective_permissions(
&self,
effective_permissions: Permissions
) -> Option<Self>
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.
sourcepub 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.
sourcepub 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.
sourcepub 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.
sourcepub 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
sourceimpl<'a> From<&'a AsyncStorage> for Storage
impl<'a> From<&'a AsyncStorage> for Storage
sourcefn from(storage: &'a AsyncStorage) -> Self
fn from(storage: &'a AsyncStorage) -> Self
Converts to this type from the input type.
sourceimpl From<AsyncStorage> for Storage
impl From<AsyncStorage> for Storage
sourcefn from(storage: AsyncStorage) -> Self
fn from(storage: AsyncStorage) -> Self
Converts to this type from the input type.
sourceimpl HasSession for Storage
impl HasSession for Storage
sourceimpl StorageConnection for Storage
impl StorageConnection for Storage
type Authenticated = Storage
type Authenticated = Storage
The StorageConnection
type returned from authentication calls.
sourcefn 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>
Creates a database named name
using the SchemaName
schema
. Read more
sourcefn database<DB: Schema>(&self, name: &str) -> Result<Self::Database, Error>
fn database<DB: Schema>(&self, name: &str) -> Result<Self::Database, Error>
Returns a reference to database name
with schema DB
.
sourcefn delete_database(&self, name: &str) -> Result<(), Error>
fn delete_database(&self, name: &str) -> Result<(), Error>
Deletes a database named name
. Read more
sourcefn list_available_schemas(&self) -> Result<Vec<SchemaName>, Error>
fn list_available_schemas(&self) -> Result<Vec<SchemaName>, Error>
Lists the SchemaName
s registered with this storage.
sourcefn delete_user<'user, U: Nameable<'user, u64> + Send + Sync>(
&self,
user: U
) -> Result<(), Error>
fn delete_user<'user, U: Nameable<'user, u64> + Send + Sync>(
&self,
user: U
) -> Result<(), Error>
Deletes a user.
sourcefn set_user_password<'user, U: Nameable<'user, u64> + Send + Sync>(
&self,
user: U,
password: SensitiveString
) -> Result<(), Error>
fn set_user_password<'user, U: Nameable<'user, u64> + Send + Sync>(
&self,
user: U,
password: SensitiveString
) -> Result<(), Error>
Sets a user’s password.
sourcefn authenticate(&self, authentication: Authentication) -> Result<Self, Error>
fn authenticate(&self, authentication: Authentication) -> Result<Self, Error>
Authenticates using the active session, returning a connection with a new session upon success. The existing connection will remain usable with the existing authentication, if any. Read more
sourcefn assume_identity(
&self,
identity: IdentityReference<'_>
) -> Result<Self::Authenticated, Error>
fn assume_identity(
&self,
identity: IdentityReference<'_>
) -> Result<Self::Authenticated, Error>
Assumes the identity
. If successful, the returned instance will have
the permissions from identity
. Read more
sourcefn add_permission_group_to_user<'user, 'group, U: Nameable<'user, u64> + Send + Sync, G: Nameable<'group, u64> + Send + Sync>(
&self,
user: U,
permission_group: G
) -> Result<(), Error>
fn add_permission_group_to_user<'user, 'group, U: Nameable<'user, u64> + Send + Sync, G: Nameable<'group, u64> + Send + Sync>(
&self,
user: U,
permission_group: G
) -> Result<(), Error>
Adds a user to a permission group.
sourcefn remove_permission_group_from_user<'user, 'group, U: Nameable<'user, u64> + Send + Sync, G: Nameable<'group, u64> + Send + Sync>(
&self,
user: U,
permission_group: G
) -> Result<(), Error>
fn remove_permission_group_from_user<'user, 'group, U: Nameable<'user, u64> + Send + Sync, G: Nameable<'group, u64> + Send + Sync>(
&self,
user: U,
permission_group: G
) -> Result<(), Error>
Removes a user from a permission group.
sourcefn add_role_to_user<'user, 'group, U: Nameable<'user, u64> + Send + Sync, G: Nameable<'group, u64> + Send + Sync>(
&self,
user: U,
role: G
) -> Result<(), Error>
fn add_role_to_user<'user, 'group, U: Nameable<'user, u64> + Send + Sync, G: Nameable<'group, u64> + Send + Sync>(
&self,
user: U,
role: G
) -> Result<(), Error>
Adds a user to a permission group.
sourcefn remove_role_from_user<'user, 'group, U: Nameable<'user, u64> + Send + Sync, G: Nameable<'group, u64> + Send + Sync>(
&self,
user: U,
role: G
) -> Result<(), Error>
fn remove_role_from_user<'user, 'group, U: Nameable<'user, u64> + Send + Sync, G: Nameable<'group, u64> + Send + Sync>(
&self,
user: U,
role: G
) -> Result<(), Error>
Removes a user from a permission group.
sourcefn 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,
Creates a database named name
with the Schema
provided. Read more
sourcefn 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>
Authenticates using an
AuthenticationToken
. If
successful, the returned instance will have the permissions from
identity
. Read more
sourcefn 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>,
sourceimpl StorageNonBlocking for Storage
impl StorageNonBlocking for Storage
Auto Trait Implementations
impl !RefUnwindSafe for Storage
impl Send for Storage
impl Sync for Storage
impl Unpin for Storage
impl !UnwindSafe for Storage
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> Instrument for T
impl<T> Instrument for T
sourcefn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
sourcefn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
impl<T> Pointable for T
impl<T> Pointable for T
sourceimpl<T> ToOwned for T where
T: Clone,
impl<T> ToOwned for T where
T: Clone,
type Owned = T
type Owned = T
The resulting type after obtaining ownership.
sourcefn clone_into(&self, target: &mut T)
fn clone_into(&self, target: &mut T)
toowned_clone_into
)Uses borrowed data to replace owned data, usually by cloning. Read more
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
fn vzip(self) -> V
sourceimpl<T> WithSubscriber for T
impl<T> WithSubscriber for T
sourcefn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
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
sourcefn with_current_subscriber(self) -> WithDispatch<Self>
fn with_current_subscriber(self) -> WithDispatch<Self>
Attaches the current default Subscriber
to this type, returning a
WithDispatch
wrapper. Read more