Struct bonsaidb_local::Storage

pub struct Storage { /* private fields */ }

A file-based, multi-database, multi-user database engine.

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")).await?;

// This is the equivalent code being executed:
let storage =
    Storage::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 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>()?,
)
.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 Storage

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

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

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

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

impl Storage

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

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

pub fn path(&self) -> &Path

Returns the path of the database storage.

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 async fn register_schema<DB: Schema>(&self) -> Result<(), Error>

Registers a schema for use within the server.

pub async fn admin(&self) -> Database

Returns the administration database.

Trait Implementations

impl Clone for Storage

fn clone(&self) -> Storage

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Storage

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

Formats the value using the given formatter.

impl StorageConnection for Storage

type Database = Database

The type that represents a database for this implementation.

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: Schema>(
    &'life0 self,
    name: &'life1 str
) -> Pin<Box<dyn Future<Output = Result<Self::Database, Error>> + Send + 'async_trait>> where
    DB: 'async_trait,
    '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 set_user_password<'user, 'life0, 'async_trait, U: Nameable<'user, u64> + Send + Sync>(
    &'life0 self,
    user: U,
    password: SensitiveString
) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>> where
    'user: 'async_trait,
    U: 'async_trait,
    'life0: 'async_trait,
    Self: 'async_trait, 

Sets a user’s password.

fn authenticate<'user, 'life0, 'async_trait, U: Nameable<'user, u64> + Send + Sync>(
    &'life0 self,
    user: U,
    authentication: Authentication
) -> Pin<Box<dyn Future<Output = Result<Authenticated, Error>> + Send + 'async_trait>> where
    'user: 'async_trait,
    U: 'async_trait,
    'life0: 'async_trait,
    Self: 'async_trait, 

Authenticates as a user with a authentication method.

fn add_permission_group_to_user<'user, 'group, 'life0, 'async_trait, U: Nameable<'user, u64> + Send + Sync, G: Nameable<'group, u64> + Send + Sync>(
    &'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,
    G: 'async_trait,
    '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: Nameable<'user, u64> + Send + Sync, G: Nameable<'group, u64> + Send + Sync>(
    &'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,
    G: 'async_trait,
    'life0: 'async_trait,
    Self: 'async_trait, 

Removes a user from a permission group.

fn add_role_to_user<'user, 'group, 'life0, 'async_trait, U: Nameable<'user, u64> + Send + Sync, G: Nameable<'group, u64> + Send + Sync>(
    &'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,
    G: 'async_trait,
    'life0: 'async_trait,
    Self: 'async_trait, 

Adds a user to a permission group.

fn remove_role_from_user<'user, 'group, 'life0, 'async_trait, U: Nameable<'user, u64> + Send + Sync, G: Nameable<'group, u64> + Send + Sync>(
    &'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,
    G: 'async_trait,
    '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<(), Error>> + Send + 'async_trait, Global>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    DB: Schema + 'async_trait,
    Self: 'async_trait, 

Creates a database named name with the Schema provided.