pub struct Transaction {
    pub operations: Vec<Operation>,
}
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>

The operations in this transaction.

Implementations§

source§

impl Transaction

source

pub fn new() -> Self

Returns a new, empty transaction.

source

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

Adds an operation to the transaction.

source

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

Appends an operation to the transaction and returns self.

source

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

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.

source

pub async fn apply_async<Connection: AsyncLowLevelConnection>( self, db: &Connection ) -> Result<Vec<OperationResult>, Error>

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.

source§

impl Transaction

source

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

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.

source

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

Updates a document in collection.

source

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

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.

source

pub fn delete(collection: CollectionName, header: Header) -> Self

Deletes a document from a collection.

Trait Implementations§

source§

impl Clone for Transaction

source§

fn clone(&self) -> Transaction

Returns a copy of the value. Read more
1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
source§

impl Debug for Transaction

source§

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

Formats the value using the given formatter. Read more
source§

impl Default for Transaction

source§

fn default() -> Transaction

Returns the “default value” for a type. Read more
source§

impl<'de> Deserialize<'de> for Transaction

source§

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>
where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer. Read more
source§

impl From<Operation> for Transaction

source§

fn from(operation: Operation) -> Self

Converts to this type from the input type.
source§

impl Serialize for Transaction

source§

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>
where __S: Serializer,

Serialize this value into the given Serde serializer. Read more

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> Same for T

§

type Output = T

Should always be Self
source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more
source§

impl<T> DeserializeOwned for T
where T: for<'de> Deserialize<'de>,