Struct lmdb_zero::Database
[−]
[src]
pub struct Database<'a> { /* fields omitted */ }
A handle on an LMDB database within an environment.
Note that in many respects the RAII aspect of this struct is more a matter of convenience than correctness. In particular, if holding a read transaction open, it is possible to obtain a handle to a database created after that transaction started, but this handle will not point to anything within that transaction.
The library does, however, guarantee that there will be at most one
Database
object with the same dbi and environment per process.
Lifetime
A Database
must be strictly outlived by its Environment
.
'a
is covariant: given two lifetimes 'x
and 'y
where 'x: 'y
, a
&Database<'x>
will implicitly coerce to &Database<'y>
.
fn convariance<'x, 'y>(db: &lmdb::Database<'x>) where 'x: 'y { let _db2: &lmdb::Database<'y> = db; }
Because of this property, if you need to hold onto an &lmdb::Database
and
must explicitly name both lifetimes, it is usually best to use the same
lifetime for both the reference and the parameter, eg &'x lmdb::Database<'x>
.
Methods
impl<'a> Database<'a>
[src]
fn open(env: &'a Environment,
name: Option<&str>,
options: &DatabaseOptions)
-> Result<Database<'a>>
name: Option<&str>,
options: &DatabaseOptions)
-> Result<Database<'a>>
Open a database in the environment.
A database handle denotes the name and parameters of a database,
independently of whether such a database exists. The database handle is
implicitly closed when the Database
object is dropped.
To use named databases (with name != None
),
EnvBuilder::set_maxdbs()
must have been called to reserve space for
the extra databases. Database names are keys in the unnamed database,
and may be read but not written.
Transaction-local databases are not supported because the resulting ownership semantics are not expressible in rust. This call implicitly creates a write transaction and uses it to create the database, then commits it on success.
One may not open the same database handle multiple times. Attempting to
do so will result in the Error::Reopened
error.
Examples
Open the default database with default options
{ let db = lmdb::Database::open( &env, None, &lmdb::DatabaseOptions::defaults()).unwrap(); // Do stuff with `db` } // The `db` handle is released
Open a named database, creating it if it doesn't exist
// NOT SHOWN: Call `EnvBuilder::set_maxdbs()` with a value greater than // one so that there is space for the named database(s). { let db = lmdb::Database::open( &env, Some("example-db"), &lmdb::DatabaseOptions::new( lmdb::db::CREATE)).unwrap(); // Do stuff with `db` } // The `db` handle is released
Trying to open the same database more than once
{ let db = lmdb::Database::open( &env, None, &lmdb::DatabaseOptions::defaults()).unwrap(); // Can't open the same database twice assert!(lmdb::Database::open( &env, None, &lmdb::DatabaseOptions::defaults()).is_err()); }
fn delete(self) -> Result<()>
Deletes this database.
This call implicitly creates a new write transaction to perform the operation, so that the lifetime of the database handle does not depend on the outcome. The database handle is closed implicitly by this operation.
Note that the other mdb_drop
operation which simply clears the
database is exposed through WriteAccessor
and is transactional.
Example
// NOT SHOWN: Call `EnvBuilder::set_maxdbs()` with a value greater than // one so that there is space for the named database(s). { let db = lmdb::Database::open( &env, Some("example-db"), &lmdb::DatabaseOptions::new( lmdb::db::CREATE)).unwrap(); // Do stuff with `db` // Delete the database itself. This also consumes `db`. db.delete().unwrap(); // We can now recreate the database if we so desire. // Note that you should not use delete+open to clear a database; use // `WriteAccessor::clear_db()` to do that. let db = lmdb::Database::open( &env, Some("example-db"), &lmdb::DatabaseOptions::new( lmdb::db::CREATE)).unwrap(); }
fn assert_same_env(&self, other_env: &Environment) -> Result<()>
Checks that other_env
is the same as the environment on this
Database
.
If it matches, returns Ok(())
; otherwise, returns Err
.
fn dbi(&self) -> MDB_dbi
Returns the underlying integer handle for this database.