Struct WriteTransaction

pub struct WriteTransaction { /* private fields */ }

A read/write transaction

Only a single WriteTransaction may exist at a time

Implementations

impl WriteTransaction

pub fn persistent_savepoint(&self) -> Result<u64, SavepointError>

Creates a snapshot of the current database state, which can be used to rollback the database. This savepoint will exist until it is deleted with [delete_savepoint()].

Note that while a savepoint exists, pages that become unused after it was created are not freed. Therefore, the lifetime of a savepoint should be minimized.

Returns [SavepointError::InvalidSavepoint], if the transaction is “dirty” (any tables have been opened) or if the transaction’s durability is less than [Durability::Immediate]

pub fn get_persistent_savepoint( &self, id: u64, ) -> Result<Savepoint, SavepointError>

Get a persistent savepoint given its id

pub fn delete_persistent_savepoint( &self, id: u64, ) -> Result<bool, SavepointError>

Delete the given persistent savepoint.

Note that if the transaction is abort()’ed this deletion will be rolled back.

Returns true if the savepoint existed Returns [SavepointError::InvalidSavepoint] if the transaction’s durability is less than [Durability::Immediate]

pub fn list_persistent_savepoints(&self) -> Result<impl Iterator<Item = u64>>

List all persistent savepoints

pub fn ephemeral_savepoint(&self) -> Result<Savepoint, SavepointError>

Creates a snapshot of the current database state, which can be used to rollback the database

This savepoint will be freed as soon as the returned [Savepoint] is dropped.

Returns [SavepointError::InvalidSavepoint], if the transaction is “dirty” (any tables have been opened)

pub fn restore_savepoint( &mut self, savepoint: &Savepoint, ) -> Result<(), SavepointError>

Restore the state of the database to the given Savepoint

Calling this method invalidates all Savepoints created after savepoint

pub fn set_durability(&mut self, durability: Durability)

Set the desired durability level for writes made in this transaction Defaults to Durability::Immediate

Will panic if the durability is reduced below [Durability::Immediate] after a persistent savepoint has been created or deleted.

pub fn set_two_phase_commit(&mut self, enabled: bool)

Enable or disable 2-phase commit (defaults to disabled)

By default, data is written using the following 1-phase commit algorithm:

1. Update the inactive commit slot with the new database state
2. Flip the god byte primary bit to activate the newly updated commit slot
3. Call fsync to ensure all writes have been persisted to disk

All data is written with checksums. When opening the database after a crash, the most recent of the two commit slots with a valid checksum is used.

Security considerations: The checksum used is xxhash, a fast, non-cryptographic hash function with close to perfect collision resistance when used with non-malicious input. An attacker with an extremely high degree of control over the database’s workload, including the ability to cause the database process to crash, can cause invalid data to be written with a valid checksum, leaving the database in an invalid, attacker-controlled state.

Alternatively, you can enable 2-phase commit, which writes data like this:

1. Update the inactive commit slot with the new database state
2. Call fsync to ensure the database slate and commit slot update have been persisted
3. Flip the god byte primary bit to activate the newly updated commit slot
4. Call fsync to ensure the write to the god byte has been persisted

This mitigates a theoretical attack where an attacker who

1. can control the order in which pages are flushed to disk
2. can introduce crashes during fsync,
3. has knowledge of the database file contents, and
4. can include arbitrary data in a write transaction

could cause a transaction to partially commit (some but not all of the data is written). This is described in the design doc in futher detail.

Security considerations: Many hard disk drives and SSDs do not actually guarantee that data has been persisted to disk after calling fsync. Even with 2-phase commit, an attacker with a high degree of control over the database’s workload, including the ability to cause the database process to crash, can cause the database to crash with the god byte primary bit pointing to an invalid commit slot, leaving the database in an invalid, potentially attacker- controlled state.

pub fn set_quick_repair(&mut self, enabled: bool)

Enable or disable quick-repair (defaults to disabled)

By default, when reopening the database after a crash, redb needs to do a full repair. This involves walking the entire database to verify the checksums and reconstruct the allocator state, so it can be very slow if the database is large.

Alternatively, you can enable quick-repair. In this mode, redb saves the allocator state as part of each commit (so it doesn’t need to be reconstructed), and enables 2-phase commit (which guarantees that the primary commit slot is valid without needing to look at the checksums). This means commits are slower, but recovery after a crash is almost instant.

pub fn open_table<'txn, K: Key + 'static, V: Value + 'static>( &'txn self, definition: TableDefinition<'_, K, V>, ) -> Result<Table<'txn, K, V>, TableError>

Open the given table

The table will be created if it does not exist

pub fn open_multimap_table<'txn, K: Key + 'static, V: Key + 'static>( &'txn self, definition: MultimapTableDefinition<'_, K, V>, ) -> Result<MultimapTable<'txn, K, V>, TableError>

Open the given table

The table will be created if it does not exist

pub fn delete_table( &self, definition: impl TableHandle, ) -> Result<bool, TableError>

Delete the given table

Returns a bool indicating whether the table existed

pub fn delete_multimap_table( &self, definition: impl MultimapTableHandle, ) -> Result<bool, TableError>

Delete the given table

Returns a bool indicating whether the table existed

pub fn list_tables( &self, ) -> Result<impl Iterator<Item = UntypedTableHandle> + '_>

List all the tables

pub fn list_multimap_tables( &self, ) -> Result<impl Iterator<Item = UntypedMultimapTableHandle> + '_>

List all the multimap tables

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

Commit the transaction

All writes performed in this transaction will be visible to future transactions, and are durable as consistent with the Durability level set by Self::set_durability

pub fn abort(self) -> Result

Abort the transaction

All writes performed in this transaction will be rolled back

pub fn stats(&self) -> Result<DatabaseStats>

Retrieves information about storage usage in the database

Trait Implementations

impl Drop for WriteTransaction

fn drop(&mut self)

Executes the destructor for this type.

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 704 bytes