Struct WriteBatchWithTransaction 

pub struct WriteBatchWithTransaction<const TRANSACTION: bool> { /* private fields */ }

An atomic batch of write operations.

delete_range is not supported in Transaction.

Making an atomic commit of several writes:

use rust_rocksdb::{DB, Options, WriteBatchWithTransaction};

let tempdir = tempfile::Builder::new()
    .prefix("_path_for_rocksdb_storage1")
    .tempdir()
    .expect("Failed to create temporary path for the _path_for_rocksdb_storage1");
let path = tempdir.path();
{
    let db = DB::open_default(path).unwrap();
    let mut batch = WriteBatchWithTransaction::<false>::default();
    batch.put(b"my key", b"my value");
    batch.put(b"key2", b"value2");
    batch.put(b"key3", b"value3");

    // delete_range is supported when use without transaction
    batch.delete_range(b"key2", b"key3");

    db.write(&batch); // Atomically commits the batch
}
let _ = DB::destroy(&Options::default(), path);

Implementations

impl<const TRANSACTION: bool> WriteBatchWithTransaction<TRANSACTION>

pub fn new() -> Self

Create a new WriteBatch without allocating memory.

pub fn with_capacity_bytes(capacity_bytes: usize) -> Self

Creates WriteBatch with the specified capacity in bytes. Allocates immediately.

pub fn from_data(data: &[u8]) -> Self

Construct with a reference to a byte array serialized by WriteBatch.

pub fn len(&self) -> usize

pub fn size_in_bytes(&self) -> usize

Return WriteBatch serialized size (in bytes).

pub fn data(&self) -> &[u8]

Return a reference to a byte array which represents a serialized version of the batch.

pub fn is_empty(&self) -> bool

pub fn iterate<T: WriteBatchIterator>(&self, callbacks: &mut T)

Iterate the put, delete, and log data operations within this write batch. Note that this does not return an Iterator but instead will invoke the put(), delete(), and log_data() member functions of the provided WriteBatchIterator trait implementation.

pub fn iterate_cf<T: WriteBatchIteratorCf>(&self, callbacks: &mut T)

Iterate the put, delete, merge, and log data operations within this write batch with column family information. Note that this does not return an Iterator but instead will invoke the put_cf(), delete_cf(), merge_cf(), and log_data() member functions of the provided WriteBatchIteratorCf trait implementation.

Notes

• For operations on the default column family (“default”), the cf_id parameter passed to the callbacks will be 0

pub fn put<K, V>(&mut self, key: K, value: V)

where K: AsRef<[u8]>, V: AsRef<[u8]>,

Insert a value into the database under the given key.

pub fn put_vectored( &mut self, key: &[IoSlice<'_>], value: &[IoSlice<'_>], ) -> Result<(), Error>

Inserts one key and value assembled from multiple byte slices.

This avoids concatenating the parts in Rust. RocksDB copies the key and value parts into the write batch during this call, so the slices do not need to outlive the method.

pub fn put_cf<K, V>(&mut self, cf: &impl AsColumnFamilyRef, key: K, value: V)

where K: AsRef<[u8]>, V: AsRef<[u8]>,

Insert a value into the specific column family of the database under the given key.

pub fn put_cf_vectored( &mut self, cf: &impl AsColumnFamilyRef, key: &[IoSlice<'_>], value: &[IoSlice<'_>], ) -> Result<(), Error>

Inserts one key and value assembled from multiple byte slices into a column family.

This avoids concatenating the parts in Rust. RocksDB copies the key and value parts into the write batch during this call, so the slices do not need to outlive the method.

pub fn put_cf_with_ts<K, V, S>( &mut self, cf: &impl AsColumnFamilyRef, key: K, ts: S, value: V, )

where K: AsRef<[u8]>, V: AsRef<[u8]>, S: AsRef<[u8]>,

Insert a value into the specific column family of the database under the given key with timestamp.

pub fn merge<K, V>(&mut self, key: K, value: V)

where K: AsRef<[u8]>, V: AsRef<[u8]>,

pub fn merge_vectored( &mut self, key: &[IoSlice<'_>], value: &[IoSlice<'_>], ) -> Result<(), Error>

Merges one key and value assembled from multiple byte slices.

This avoids concatenating the parts in Rust. RocksDB copies the key and value parts into the write batch during this call, so the slices do not need to outlive the method.

pub fn merge_cf<K, V>(&mut self, cf: &impl AsColumnFamilyRef, key: K, value: V)

where K: AsRef<[u8]>, V: AsRef<[u8]>,

pub fn merge_cf_vectored( &mut self, cf: &impl AsColumnFamilyRef, key: &[IoSlice<'_>], value: &[IoSlice<'_>], ) -> Result<(), Error>

Merges one key and value assembled from multiple byte slices in a column family.

This avoids concatenating the parts in Rust. RocksDB copies the key and value parts into the write batch during this call, so the slices do not need to outlive the method.

pub fn delete<K: AsRef<[u8]>>(&mut self, key: K)

Removes the database entry for key. Does nothing if the key was not found.

pub fn delete_vectored(&mut self, key: &[IoSlice<'_>]) -> Result<(), Error>

Removes the entry for one key assembled from multiple byte slices.

This avoids concatenating the parts in Rust. RocksDB copies the key parts into the write batch during this call, so the slices do not need to outlive the method.

pub fn delete_cf<K: AsRef<[u8]>>(&mut self, cf: &impl AsColumnFamilyRef, key: K)

Removes the database entry in the specific column family for key. Does nothing if the key was not found.

pub fn delete_cf_vectored( &mut self, cf: &impl AsColumnFamilyRef, key: &[IoSlice<'_>], ) -> Result<(), Error>

Removes the entry for one key assembled from multiple byte slices in a column family.

This avoids concatenating the parts in Rust. RocksDB copies the key parts into the write batch during this call, so the slices do not need to outlive the method.

pub fn single_delete<K: AsRef<[u8]>>(&mut self, key: K)

Removes the database entry for a key that was written exactly once.

This is a cheaper delete than delete, but it is only correct when the key has had at most one put and no merge since the last delete of that key. Using it on a key that was written more than once leaves an older version of the key visible, and RocksDB does not report that as an error.

pub fn single_delete_cf<K: AsRef<[u8]>>( &mut self, cf: &impl AsColumnFamilyRef, key: K, )

Removes the entry for a write-once key in the given column family.

See single_delete for when this is safe to use.

pub fn single_delete_cf_with_ts<K: AsRef<[u8]>, S: AsRef<[u8]>>( &mut self, cf: &impl AsColumnFamilyRef, key: K, ts: S, )

Removes the entry for a write-once key in a column family that uses user-defined timestamps.

See single_delete for when this is safe to use.

pub fn delete_cf_with_ts<K: AsRef<[u8]>, S: AsRef<[u8]>>( &mut self, cf: &impl AsColumnFamilyRef, key: K, ts: S, )

Removes the database entry in the specific column family with timestamp for key. Does nothing if the key was not found.

pub fn put_log_data<V: AsRef<[u8]>>(&mut self, log_data: V)

pub fn clear(&mut self)

Clear all updates buffered in this batch.

pub fn set_save_point(&mut self)

Record the current state of the batch so it can be undone later.

Save points nest. Each set_save_point pushes onto a stack that rollback_to_save_point and pop_save_point pop from.

pub fn rollback_to_save_point(&mut self) -> Result<(), Error>

Undo every operation recorded since the most recent save point, and pop that save point.

Returns an error if there is no save point to roll back to.

pub fn pop_save_point(&mut self) -> Result<(), Error>

Pop the most recent save point without undoing anything.

Returns an error if there is no save point to pop.

pub fn verify_checksum(&self) -> Result<(), Error>

Recompute the per-key protection info over the batch and check it against what was stored when each entry was added.

Only meaningful for a batch built with a non-zero protection_bytes_per_key, which is the fourth argument to rocksdb_writebatch_create_with_params. On a batch without protection this succeeds without checking anything.

pub unsafe fn update_timestamps<S, F>( &mut self, ts: S, get_ts_size: F, ) -> Result<(), Error>

where S: AsRef<[u8]>, F: FnMut(u32) -> usize,

Overwrite the user-defined timestamp on every entry in the batch.

get_ts_size is called with each column family id the batch touches and must return the timestamp width configured for that column family, or 0 if it does not use timestamps. ts must be exactly as wide as every non-zero size it returns.

This is for reassigning a timestamp to an already-built batch, such as when a commit timestamp is only known at write time.

Safety

Every key already recorded for a column family whose get_ts_size returns a non-zero width must be at least that many bytes long, which in practice means it was written through one of the _with_ts methods and already carries a timestamp suffix of exactly that width. RocksDB overwrites the last width bytes of each key without checking that the key is that long, so a shorter key makes it write in front of the key and corrupt the heap. Mixing plain put with a non-zero width for the same column family is what usually triggers this.

Errors

Returns an error if ts is empty, if its length differs from a non-zero width returned by get_ts_size, or if get_ts_size reports that it could not find the width for a column family.

impl WriteBatchWithTransaction<false>

pub fn delete_range<K: AsRef<[u8]>>(&mut self, from: K, to: K)

Remove database entries from start key to end key.

Removes the database entries in the range [“begin_key”, “end_key”), i.e., including “begin_key” and excluding “end_key”. It is not an error if no keys exist in the range [“begin_key”, “end_key”).

pub fn delete_range_vectored( &mut self, from: &[IoSlice<'_>], to: &[IoSlice<'_>], ) -> Result<(), Error>

Removes entries in a range whose bounds are assembled from byte slices.

The range includes from and excludes to. Both bounds must be split into the same number of parts: the System backend forwards them to rocksdb_writebatch_delete_rangev, which takes one part count for the pair. Split them differently and this returns an error.

RocksDB copies both bounds into the write batch during this call, so the slices do not need to outlive the method.

pub fn delete_range_cf<K: AsRef<[u8]>>( &mut self, cf: &impl AsColumnFamilyRef, from: K, to: K, )

Remove database entries in column family from start key to end key.

Removes the database entries in the range [“begin_key”, “end_key”), i.e., including “begin_key” and excluding “end_key”. It is not an error if no keys exist in the range [“begin_key”, “end_key”).

pub fn delete_range_cf_vectored( &mut self, cf: &impl AsColumnFamilyRef, from: &[IoSlice<'_>], to: &[IoSlice<'_>], ) -> Result<(), Error>

Removes entries in a column family range whose bounds are assembled from byte slices.

The range includes from and excludes to, and both bounds must be split into the same number of parts. See delete_range_vectored.

RocksDB copies both bounds into the write batch during this call, so the slices do not need to outlive the method.

Trait Implementations

impl<const TRANSACTION: bool> Default for WriteBatchWithTransaction<TRANSACTION>

fn default() -> Self

Returns the “default value” for a type.

impl<const TRANSACTION: bool> Drop for WriteBatchWithTransaction<TRANSACTION>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl<const TRANSACTION: bool> Send for WriteBatchWithTransaction<TRANSACTION>