Struct jammdb::Transaction

pub struct Transaction<'a> { /* fields omitted */ }

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 writable¹ 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 transactions².

There are four important methods. Check out their documentation for more details:

1. get_bucket retreives buckets from the root level. Available in read-only or writable transactions.
2. create_bucket makes new buckets at the root level. Available in writable transactions only.
3. detete_bucket deletes a bucket (including all nested buckets) from the database. Available in writable transactions only.
4. 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());

¹ There can only be a single writeable transaction at a time, so trying to open two writable transactions on the same thread will deadlock.

² 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

impl<'a> Transaction<'a>

pub fn get_bucket<T: AsRef<[u8]>>(
    &'a self,
    name: T
) -> Result<BucketRef<'_>, 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.

pub fn create_bucket<T: AsRef<[u8]>>(
    &'a self,
    name: T
) -> Result<BucketRef<'_>, 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.

pub fn get_or_create_bucket<T: AsRef<[u8]>>(
    &self,
    name: T
) -> Result<BucketRef<'_>, 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.

pub fn delete_bucket<T: AsRef<[u8]>>(&self, name: 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.

pub fn commit(self) -> Result<(), Error>

Writes the changes made in the writeable transaction to the underlying file.

Errors

Will return an IOError error if there are any io errors while writing to disk, or a ReadOnlyTx error if this is called on a read-only transaction.