Struct bonsaidb::core::transaction::Transaction

pub struct Transaction {
    pub operations: Vec<Operation, Global>,
}

Expand description

A list of operations to execute as a single unit. If any operation fails, all changes are aborted. Transactions are ACID-compliant. ACID stands for:

Atomic: All transactions are atomically applied. Readers outside of the active transaction will never be able to read partially written data. In BonsaiDb, readers are not blocked while writes are happening – reads will continue to read the existing value until the transaction is fully executed. Once the transaction is fully executed, all future queries will reflect the updated state immediately.
Consistent: All transactions will be applied only if the data model is able to remain fully consistent. This means that all constraints, such as unique view keys, are validated before a transaction is allowed to be committed.
Isolated: Each transaction is executed in an isolated environment. Currently, BonsaiDb does not offer interactive transactions, so this is easily guaranteed. When BonsaiDb eventually has interactive transactions, the transaction will have a fully isolated state until it is committed. No two transactions can be affected by each other’s changes.

In the event of a transaction being aborted or a power outage occurs while a transaction is being applied, this isolation ensures that once BonsaiDb opens the database again, the database will reflect the most recently committed.
Durable: When the transaction apply function has finished exectuing, BonsaiDb guarantees that all data has been confirmed by the operating system as being fully written to disk. This ensures that in the event of a power outage, no data that has been confirmed will be lost.

When using one of the high-level functions to push/insert/update/delete documents, behind the scenes single-Operation Transactions are applied. To ensure multiple changes happen in the same database operation, multiple operations can be added to a Transaction:

use bonsaidb_core::transaction::{Operation, Transaction};
let mut tx = Transaction::new();
tx.push(Operation::push_serialized::<MyCollection>(
    &MyCollection::default(),
)?);
tx.push(Operation::push_serialized::<MyCollection>(
    &MyCollection::default(),
)?);
let results = tx.apply(db)?;
assert_eq!(results.len(), 2);
println!("Two new documents inserted: {results:?}");

Fields§

§operations: Vec<Operation, Global>

The operations in this transaction.

Implementations§

§

impl Transaction

pub fn new() -> Transaction

Returns a new, empty transaction.

pub fn push(&mut self, operation: Operation)

Adds an operation to the transaction.

pub fn with(self, operation: Operation) -> Transaction

Appends an operation to the transaction and returns self.

pub fn apply<Connection>(
 self,
 db: &Connection
) -> Result<Vec<OperationResult, Global>, Error>where
 Connection: LowLevelConnection,

Applies the transaction to the database, returning the results of the operations. All operations will succeed or none will be performed and an error will be returned.

pub async fn apply_async<Connection>(
 self,
 db: &Connection
) -> impl Future<Output = Result<Vec<OperationResult, Global>, Error>>where
 Connection: AsyncLowLevelConnection,

Applies the transaction to the database, returning the results of the operations. All operations will succeed or none will be performed and an error will be returned.

§

impl Transaction

pub fn insert(
 collection: CollectionName,
 id: Option<DocumentId>,
 contents: impl Into<Bytes>
) -> Transaction

Inserts a new document with contents into collection. If id is None a unique id will be generated. If an id is provided and a document already exists with that id, a conflict error will be returned.

pub fn update(
 collection: CollectionName,
 header: Header,
 contents: impl Into<Bytes>
) -> Transaction

Updates a document in collection.

pub fn overwrite(
 collection: CollectionName,
 id: DocumentId,
 contents: impl Into<Bytes>
) -> Transaction

Overwrites a document in collection. If a document with id exists, it will be overwritten. If a document with id doesn’t exist, it will be created.