Trait bonsaidb_core::schema::Collection

source · [−]

pub trait Collection: Debug + Send + Sync {
    fn collection_name() -> CollectionName;
    fn define_views(schema: &mut Schematic) -> Result<(), Error>;

    fn encryption_key() -> Option<KeyId> { ... }
}

Expand description

A namespaced collection of Document<Self> items and views.

Deriving this trait

This trait can be derived instead of manually implemented:

use bonsaidb_core::schema::Collection;
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize, Default, Collection)]
#[collection(name = "MyCollection")]
pub struct MyCollection;

If you’re publishing a collection for use in multiple projects, consider giving the collection an authority, which gives your collection a namespace:

use bonsaidb_core::schema::Collection;
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize, Default, Collection)]
#[collection(name = "MyCollection", authority = "khonsulabs")]
pub struct MyCollection;

The list of views can be specified using the views parameter:

use bonsaidb_core::schema::{Collection, View};
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize, Default, Collection)]
#[collection(name = "MyCollection", views = [ScoresByRank])]
pub struct MyCollection;

#[derive(Debug, Clone, View)]
#[view(collection = MyCollection, key = u32, value = f32, name = "scores-by-rank")]
pub struct ScoresByRank;

Specifying a Collection Encryption Key

By default, encryption will be required if an encryption_key is provided:

use bonsaidb_core::{document::KeyId, schema::Collection};
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize, Default, Collection)]
#[collection(name = "MyCollection", encryption_key = Some(KeyId::Master))]
pub struct MyCollection;

The encryption_required parameter can be provided if you wish to be explicit:

use bonsaidb_core::{document::KeyId, schema::Collection};
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize, Default, Collection)]
#[collection(name = "MyCollection")]
#[collection(encryption_key = Some(KeyId::Master), encryption_required)]
pub struct MyCollection;

Or, if you wish your collection to be encrypted if its available, but not cause errors when being stored without encryption, you can provide the encryption_optional parameter:

use bonsaidb_core::{document::KeyId, schema::Collection};
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize, Default, Collection)]
#[collection(name = "MyCollection")]
#[collection(encryption_key = Some(KeyId::Master), encryption_optional)]
pub struct MyCollection;

Changing the serialization strategy

BonsaiDb uses transmog to allow customizing serialization formats. To use one of the formats Transmog already supports, add its crate to your Cargo.toml and use it like this example using transmog_bincode:

use bonsaidb_core::schema::Collection;
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize, Default, Collection)]
#[collection(name = "MyCollection")]
#[collection(serialization = transmog_bincode::Bincode)]
pub struct MyCollection;

To manually implement SerializedCollection you can pass None to serialization:

use bonsaidb_core::schema::Collection;

#[derive(Debug, Default, Collection)]
#[collection(name = "MyCollection")]
#[collection(serialization = None)]
pub struct MyCollection;