pub struct Tx<'tx> { /* private fields */ }
Expand description
An isolated view of the database
Transactions are how you can interact with the database.
They are created from a DB
,
and can be read-only or writable1 depending on the paramater you pass into the tx
method.
Transactions are completely isolated from each other, so a read-only transaction can expect the data to stay exactly the same for the life
of the transaction, regardless of how many changes are made in other transactions2.
There are four important methods. Check out their documentation for more details:
get_bucket
retreives buckets from the root level. Available in read-only or writable transactions.create_bucket
makes new buckets at the root level. Available in writable transactions only.detete_bucket
deletes a bucket (including all nested buckets) from the database. Available in writable transactions only.commit
saves a writable transaction. Available in writable transactions.
Trying to use the methods that require writable transactions from a read-only transaction will result in an error. If you make edits in a writable transaction,
and you want to save them, you must call the commit
method, otherwise when the transaction is dropped all your changes will be lost.
Examples
use jammdb::{DB, Data};
// create a read-only transaction
let mut tx1 = db.tx(false)?;
// create a writable transcation
let mut tx2 = db.tx(true)?;
// create a new bucket in the writable transaction
tx2.create_bucket("new-bucket")?;
// the read-only transaction will not be able to see the new bucket
assert!(tx1.get_bucket("new-bucket").is_err());
// get a view of an existing bucket from both transactions
let mut b1 = tx1.get_bucket("existing-bucket")?;
let mut b2 = tx2.get_bucket("existing-bucket")?;
// make an edit to the bucket
b2.put("new-key", "new-value")?;
// the read-only transaction will not have this new key
assert_eq!(b1.get("new-key"), None);
// but it will be able to see data that already existed!
assert!(b1.get("existing-key").is_some());
1 There can only be a single writeable transaction at a time, so trying to open two writable transactions on the same thread will deadlock.
2 Keep in mind that long running read-only transactions will prevent the database from reclaiming old pages and your database may increase in disk size quickly if you’re writing lots of data, so it’s a good idea to keep transactions short.
Implementations§
source§impl<'tx> Tx<'tx>
impl<'tx> Tx<'tx>
sourcepub fn get_bucket<'b, T: ToBytes<'tx>>(
&'b self,
name: T
) -> Result<Bucket<'b, 'tx>, Error>
pub fn get_bucket<'b, T: ToBytes<'tx>>( &'b self, name: T ) -> Result<Bucket<'b, 'tx>, Error>
Returns a reference to the root level bucket with the given name.
Errors
Will return a BucketMissing
error if the bucket does not exist,
or an IncompatibleValue
error if the key exists but is not a bucket.
In a read-only transaction, you will get an error when trying to use any of the bucket’s methods that modify data.
sourcepub fn create_bucket<'b, T: ToBytes<'tx>>(
&'b self,
name: T
) -> Result<Bucket<'b, 'tx>, Error>
pub fn create_bucket<'b, T: ToBytes<'tx>>( &'b self, name: T ) -> Result<Bucket<'b, 'tx>, Error>
Creates a new bucket with the given name and returns a reference it.
Errors
Will return a BucketExists
error if the bucket already exists,
an IncompatibleValue
error if the key exists but is not a bucket,
or a ReadOnlyTx
error if this is called on a read-only transaction.
sourcepub fn get_or_create_bucket<'b, T: ToBytes<'tx>>(
&'b self,
name: T
) -> Result<Bucket<'b, 'tx>, Error>
pub fn get_or_create_bucket<'b, T: ToBytes<'tx>>( &'b self, name: T ) -> Result<Bucket<'b, 'tx>, Error>
Creates an existing root-level bucket with the given name if it does not already exist. Gets the existing bucket if it does exist.
Errors
Will return an IncompatibleValue
error if the key exists but is not a bucket,
or a ReadOnlyTx
error if this is called on a read-only transaction.
sourcepub fn delete_bucket<T: ToBytes<'tx>>(&self, key: T) -> Result<(), Error>
pub fn delete_bucket<T: ToBytes<'tx>>(&self, key: T) -> Result<(), Error>
Deletes an existing root-level bucket with the given name
Errors
Will return a BucketMissing
error if the bucket does not exist,
an IncompatibleValue
error if the key exists but is not a bucket,
or a ReadOnlyTx
error if this is called on a read-only transaction.
sourcepub fn buckets<'b>(
&'b self
) -> impl Iterator<Item = (BucketName<'b, 'tx>, Bucket<'b, 'tx>)>
pub fn buckets<'b>( &'b self ) -> impl Iterator<Item = (BucketName<'b, 'tx>, Bucket<'b, 'tx>)>
Iterator over the root level buckets