Struct ejdb::Database

pub struct Database(_);

An EJDB database handle.

This type represents an access point for an EJDB database. An object of this type can be created by open() or open_with_mode() methods or with DatabaseOpenMode::open() method. When a value of this type is dropped, the database will be closed automatically.

This type has methods to access EJDB database metadata as well as methods for manipulating collections.

Methods

impl Database

pub fn get_metadata(&self) -> Result<DatabaseMetadata>

Loads and returns information about the database.

This method always reloads the metadata each time it is called, therefore, for example, if you called this method, then changed something in the database, and then called it again, its results will be different.

Failures

Fails when the underlying EJDB operation can't be completed successfully or when the loaded BSON document can't be deserialized from EJDB representation.

Example

let db = Database::open("/path/to/db").unwrap();
let meta = db.get_metadata().unwrap();
// work with the metadata object.

impl Database

pub fn open_with_mode<P: Into<Vec<u8>>>(
    path: P,
    open_mode: DatabaseOpenMode
) -> Result<Database>

Opens the specified database with the provided open mode.

The path argument may be anything convertible to a vector of bytes. Strings, string slices, bytes, bytes slices will all do.

See also DatabaseOpenMode::open() method for a possibly more convenient alternative.

Failures

Returns an error when the database can't be accessed, or if path contains zero bytes and probably in other cases when EJDB library can't open the database.

Example

let db = Database::open_with_mode("/path/to/db", DatabaseOpenMode::default()).unwrap();
// work with the database

pub fn open<P: Into<Vec<u8>>>(path: P) -> Result<Database>

A shortcut for Database::open_with_mode(path, DatabaseOpenMode::default()).

This method is used in most cases when one needs to open a database.

Example

let db = Database::open("/path/to/database").unwrap();
// work with the database

pub fn get_collection<S: Into<Vec<u8>>>(
    &self,
    name: S
) -> Result<Option<Collection>>

Returns the given collection by its name, if it exists.

This method will only return a collection if it already exists in the database; it won't create a new collection. See Database::collection_with_options() and Database::collection() methods if you need to create new collections.

path argument may be of any type convertible to a vector of bytes, like strings or byte arrays.

Failures

Fails if name contains zero bytes or in other cases when the corresponding EJDB operation can't be completed.

Example

let db = Database::open("/path/to/db").unwrap();
match db.get_collection("some_collection").unwrap() {
    Some(coll) => { /* work with the collection */ }
    None => { /* do something else */ }
}

pub fn collection_with_options<S: Into<Vec<u8>>>(
    &self,
    name: S,
    options: CollectionOptions
) -> Result<Collection>

Returns a collection by its name or creates one with the given options if it doesn't exist.

name argument may be of any type convertible to a byte vector, for example, strings or byte slices. CollectionOptions specify which options the collection will have if it doesn't exist; if it does exist, this argument is ignored.

See also CollectionOptions::get_or_create() method for a possibly more convenient alternative.

Failures

Returns an error when name argument contains zero bytes in it or when the corresponding EJDB operation cannot be completed successfully.

Example

let db = Database::open("/path/to/db").unwrap();
let coll = db.collection_with_options("some_collection", CollectionOptions::default()).unwrap();
// work with the collection

pub fn collection<S: Into<Vec<u8>>>(&self, name: S) -> Result<Collection>

A shortcut for Database::collection_with_options(&db, name, CollectionOptions::default()).

This method is used in most cases when access to a collection is needed.

Example

let db = Database::open("/path/to/db").unwrap();
let coll = db.collection("some_collection").unwrap();
// work with the collection

pub fn drop_collection<S: Into<Vec<u8>>>(
    &self,
    name: S,
    prune: bool
) -> Result<()>

Removes the specified collection from the database, possibly dropping all the data in it.

This method removes a collection from the database. Its second argument, prune, determines whether all the data files for the collection should be removed as well (true for removing, naturally). name may be of any type convertible to a byte vector, for example, a string or a byte slice.

Failures

Returns an error if name argument contains zero bytes inside it or if the corresponding EJDB operation cannot be completed successfully.

Example

let db = Database::open("/path/to/db").unwrap();
db.drop_collection("some_collection", true).unwrap();

Trait Implementations

impl Send for Database

impl Drop for Database

fn drop(&mut self)

Executes the destructor for this type.

impl Debug for Database

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

Formats the value using the given formatter.