Class TransactionDb

Namespace

RocksDbNet

Assembly

RocksDb.Net.dll

A database that supports transactions with per-key locking and conflict detection. Maps to rocksdb_transactiondb_t.

public sealed class TransactionDb : RocksDbHandle, IDisposable

Inheritance

object

RocksDbHandle

TransactionDb

Implements

IDisposable

Inherited Members

RocksDbHandle.Handle

RocksDbHandle.Owned

RocksDbHandle.IsDisposed

RocksDbHandle.ThrowIfDisposed()

RocksDbHandle.Dispose()

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Thread-safe except for disposal, as with RocksDb: dispose only once nothing else is using the database or a transaction from it.

Every write takes locks, whether it goes through a Transaction or straight through this object. A second writer touching a locked key waits for the lock timeout and then fails, or fails at once if deadlock detection spots a cycle.

This is a separate type from RocksDb rather than a subclass, because RocksDb gives a transaction database a different native type with a different close, and genuinely no compaction, ingestion, range deletion or column family dropping. A subclass would inherit a dozen members that do not exist here.

Like RocksDb, opening takes ownership of the DbOptions and disposes it when the database closes. The TransactionDbOptions are copied, so those may be disposed immediately.

Properties

ColumnFamilyNames

Names of the column families this database knows about.

public IReadOnlyCollection<string> ColumnFamilyNames { get; }

Property Value

IReadOnlyCollection<string>

Remarks

The default family is always in here, whether or not it was named when the database was opened. It used to drop out: the backing dictionary is empty for a database opened without an explicit family list, so the default name was reported only while the dictionary stayed empty, and creating a family afterwards replaced it in the listing rather than adding to it. The family still existed and GetColumnFamily(string) still resolved it, so the listing disagreed with the lookup — including in the "Known families" message that lookup throws.

Methods

BeginTransaction(WriteOptions?, TransactionOptions?)

Begins a transaction.

public Transaction BeginTransaction(WriteOptions? writeOptions = null, TransactionOptions? transactionOptions = null)

Parameters

writeOptions WriteOptions

transactionOptions TransactionOptions

Returns

Transaction

Remarks

Dispose the returned transaction, whether or not it is committed. Committing and rolling back do not release it; they only decide what happens to its writes.

ContainsKey(ReadOnlySpan<byte>, ColumnFamilyHandle, ReadOptions?)

Returns whether key exists, exactly, without copying its value.

public bool ContainsKey(ReadOnlySpan<byte> key, ColumnFamilyHandle cf, ReadOptions? options = null)

Parameters

key ReadOnlySpan<byte>

cf ColumnFamilyHandle

options ReadOptions

Returns

bool

Remarks

Unlike KeyMayExist, which consults only the bloom filters and can answer yes for a key that is absent, this is a real read and is never wrong. It costs the same as reading the value, less the copy: the value is located and pinned, then released unread.

Exceptions

RocksDbException

The read failed, as opposed to finding nothing.

ContainsKey(ReadOnlySpan<byte>, ReadOptions?)

Returns whether key exists, exactly, without copying its value.

public bool ContainsKey(ReadOnlySpan<byte> key, ReadOptions? options = null)

Parameters

key ReadOnlySpan<byte>

options ReadOptions

Returns

bool

Remarks

Unlike KeyMayExist, which consults only the bloom filters and can answer yes for a key that is absent, this is a real read and is never wrong. It costs the same as reading the value, less the copy: the value is located and pinned, then released unread.

Exceptions

RocksDbException

The read failed, as opposed to finding nothing.

ContainsKey(string, ColumnFamilyHandle, ReadOptions?)

Returns whether the UTF-8 encoded key exists in cf, exactly.

public bool ContainsKey(string key, ColumnFamilyHandle cf, ReadOptions? options = null)

Parameters

key string

cf ColumnFamilyHandle

options ReadOptions

Returns

bool

Remarks

Unlike KeyMayExist, which consults only the bloom filters and can answer yes for a key that is absent, this is a real read and is never wrong. It costs the same as reading the value, less the copy: the value is located and pinned, then released unread.

ContainsKey(string, ReadOptions?)

Returns whether the UTF-8 encoded key exists, exactly.

public bool ContainsKey(string key, ReadOptions? options = null)

Parameters

key string

options ReadOptions

Returns

bool

Remarks

Unlike KeyMayExist, which consults only the bloom filters and can answer yes for a key that is absent, this is a real read and is never wrong. It costs the same as reading the value, less the copy: the value is located and pinned, then released unread.

CreateCheckpoint()

Creates a checkpoint object for this database.

public Checkpoint CreateCheckpoint()

Returns

Checkpoint

Remarks

The same on-disk snapshot Create(RocksDb) takes of an ordinary database. Committed transactions are in it; one still in progress is not, since nothing it wrote is in the database until it commits. Dispose the checkpoint before this database: it registers as a child, so the ordering is enforced rather than merely documented.

CreateColumnFamily(DbOptions, string)

Creates a column family and returns its handle.

public ColumnFamilyHandle CreateColumnFamily(DbOptions options, string name)

Parameters

options DbOptions

name string

Returns

ColumnFamilyHandle

Delete(ReadOnlySpan<byte>, ColumnFamilyHandle, WriteOptions?)

Deletes a key.

public void Delete(ReadOnlySpan<byte> key, ColumnFamilyHandle cf, WriteOptions? options = null)

Parameters

key ReadOnlySpan<byte>

cf ColumnFamilyHandle

options WriteOptions

Delete(ReadOnlySpan<byte>, WriteOptions?)

Deletes a key.

public void Delete(ReadOnlySpan<byte> key, WriteOptions? options = null)

Parameters

key ReadOnlySpan<byte>

options WriteOptions

Delete(string, WriteOptions?)

Deletes a key.

public void Delete(string key, WriteOptions? options = null)

Parameters

key string

options WriteOptions

DisposeHandle()

Releases the native handle. Called during disposal.

protected override void DisposeHandle()

Remarks

Protected rather than public: it destroys the native object without marking this instance disposed or clearing the handle, so calling it from outside and then disposing normally would free the same pointer twice. It was the most Dispose-looking member on the type. Callers want Dispose().

DisposeUnmanagedResources()

Releases unmanaged resources used by the current instance.

protected override void DisposeUnmanagedResources()

Remarks

Protected for the same reason as DisposeHandle().

Flush(ColumnFamilyHandle, FlushOptions?)

Flushes the memtable to disk.

public void Flush(ColumnFamilyHandle cf, FlushOptions? options = null)

Parameters

cf ColumnFamilyHandle

options FlushOptions

Flush(FlushOptions?)

Flushes the memtable to disk.

public void Flush(FlushOptions? options = null)

Parameters

options FlushOptions

Flush(IReadOnlyList<ColumnFamilyHandle>, FlushOptions?)

Flushes the specified column families together.

public void Flush(IReadOnlyList<ColumnFamilyHandle> columnFamilies, FlushOptions? options = null)

Parameters

columnFamilies IReadOnlyList<ColumnFamilyHandle>

options FlushOptions

Remarks

As with Flush(IReadOnlyList<ColumnFamilyHandle>, FlushOptions?), an empty list flushes nothing.

FlushWal(FlushWalOptions)

Flushes the write-ahead log, with control over the rate limiter priority as well as syncing.

public void FlushWal(FlushWalOptions options)

Parameters

options FlushWalOptions

Remarks

The counterpart to FlushWal(FlushWalOptions), which this type was missing even though the C API has it.

FlushWal(bool)

Flushes the write-ahead log.

public void FlushWal(bool sync)

Parameters

sync bool

Whether to fsync the file as well. Flushing without syncing hands the buffer to the operating system and nothing more.

Remarks

There is no default, and there used to be one that disagreed with FlushWal(bool). See that method for why both now require the argument.

Get(ReadOnlySpan<byte>, ColumnFamilyHandle, ReadOptions?)

Reads a key, or returns null if it is absent.

public byte[]? Get(ReadOnlySpan<byte> key, ColumnFamilyHandle cf, ReadOptions? options = null)

Parameters

key ReadOnlySpan<byte>

cf ColumnFamilyHandle

options ReadOptions

Returns

byte[]

Get(ReadOnlySpan<byte>, ReadOptions?)

Reads a key, or returns null if it is absent.

public byte[]? Get(ReadOnlySpan<byte> key, ReadOptions? options = null)

Parameters

key ReadOnlySpan<byte>

options ReadOptions

Returns

byte[]

GetColumnFamily(string)

Returns the handle for the column family called name.

public ColumnFamilyHandle GetColumnFamily(string name)

Parameters

name string

Returns

ColumnFamilyHandle

Exceptions

KeyNotFoundException

No such column family is known.

GetDefaultColumnFamily()

Returns a non-owning wrapper around the default column family handle. Do not call Dispose on the returned handle — its lifetime is managed by the database.

public ColumnFamilyHandle GetDefaultColumnFamily()

Returns

ColumnFamilyHandle

Remarks

The handle is only reachable through the underlying non-transactional database, since rocksdb_get_default_column_family_handle takes a rocksdb_t*. rocksdb_transactiondb_get_base_db allocates a rocksdb_t wrapper around a DB* this database owns, and rocksdb_transactiondb_close_base_db deletes that wrapper and nothing else — so the base database is not closed, and the column family handle taken from it outlives the wrapper it came through.

Cached, because each call allocates a fresh rocksdb_column_family_handle_t and the wrapper is non-owning, so every call would otherwise leak one.

GetPinned(ReadOnlySpan<byte>, ColumnFamilyHandle, ReadOptions?)

Reads a key without copying the value into managed memory, or returns null if it is absent.

public PinnableSlice? GetPinned(ReadOnlySpan<byte> key, ColumnFamilyHandle cf, ReadOptions? options = null)

Parameters

key ReadOnlySpan<byte>

cf ColumnFamilyHandle

options ReadOptions

Returns

PinnableSlice

GetPinned(ReadOnlySpan<byte>, ReadOptions?)

Reads a key without copying the value into managed memory, or returns null if it is absent.

public PinnableSlice? GetPinned(ReadOnlySpan<byte> key, ReadOptions? options = null)

Parameters

key ReadOnlySpan<byte>

options ReadOptions

Returns

PinnableSlice

GetPreparedTransactions()

Returns the transactions that were prepared but never committed or rolled back, so that recovery can resolve them.

public IReadOnlyList<Transaction> GetPreparedTransactions()

Returns

IReadOnlyList<Transaction>

Remarks

This is the other half of Prepare() and the reason to prepare at all. Reopening a database after a crash leaves any prepared transaction in place, still holding its locks; this is how a process finds them. Each carries the Name it was prepared under, which is what lets a coordinator decide whether it should now commit or roll back.

The returned transactions are owned by the caller: commit or roll each one back and then dispose it, exactly as for one from BeginTransaction(WriteOptions?, TransactionOptions?). Leaving them undisposed keeps their keys locked against every other writer.

A prepared transaction this process already holds is returned as the same Transaction object, whether it came from BeginTransaction(WriteOptions?, TransactionOptions?) or from an earlier call to this method. It is still one transaction, so it is resolved and disposed once.

An empty list is the normal result. A database that was closed cleanly has nothing outstanding.

GetProperty(string)

Reads a string-valued RocksDb property.

public string? GetProperty(string propertyName)

Parameters

propertyName string

Returns

string

GetPropertyInt(string)

Reads an integer-valued RocksDb property.

public ulong? GetPropertyInt(string propertyName)

Parameters

propertyName string

Returns

ulong?

GetString(string, ColumnFamilyHandle, ReadOptions?)

Reads a UTF-8 key as a string, or null if absent.

public string? GetString(string key, ColumnFamilyHandle cf, ReadOptions? options = null)

Parameters

key string

cf ColumnFamilyHandle

options ReadOptions

Returns

string

GetString(string, ReadOptions?)

Reads a UTF-8 key as a string, or null if absent.

public string? GetString(string key, ReadOptions? options = null)

Parameters

key string

options ReadOptions

Returns

string

Merge(ReadOnlySpan<byte>, ReadOnlySpan<byte>, ColumnFamilyHandle, WriteOptions?)

Applies a merge operation to a key.

public void Merge(ReadOnlySpan<byte> key, ReadOnlySpan<byte> value, ColumnFamilyHandle cf, WriteOptions? options = null)

Parameters

key ReadOnlySpan<byte>

value ReadOnlySpan<byte>

cf ColumnFamilyHandle

options WriteOptions

Merge(ReadOnlySpan<byte>, ReadOnlySpan<byte>, WriteOptions?)

Applies a merge operation to a key.

public void Merge(ReadOnlySpan<byte> key, ReadOnlySpan<byte> value, WriteOptions? options = null)

Parameters

key ReadOnlySpan<byte>

value ReadOnlySpan<byte>

options WriteOptions

MultiGet(IReadOnlyList<byte[]>, ColumnFamilyHandle, ReadOptions?)

Reads several keys from cf in one call.

public byte[]?[] MultiGet(IReadOnlyList<byte[]> keys, ColumnFamilyHandle cf, ReadOptions? options = null)

Parameters

keys IReadOnlyList<byte[]>

cf ColumnFamilyHandle

options ReadOptions

Returns

byte[][]

One entry per key, null where the key is absent.

Remarks

Sees committed data only, and takes no locks. Use MultiGet(IReadOnlyList<byte[]>, ReadOptions?) to see a transaction's own writes, or MultiGetForUpdate(IReadOnlyList<byte[]>, ReadOptions?) to lock what was read.

MultiGet(IReadOnlyList<byte[]>, ReadOptions?)

Reads several keys from the default column family in one call, outside any transaction.

public byte[]?[] MultiGet(IReadOnlyList<byte[]> keys, ReadOptions? options = null)

Parameters

keys IReadOnlyList<byte[]>

options ReadOptions

Returns

byte[][]

One entry per key, null where the key is absent.

Remarks

Sees committed data only, and takes no locks. Use MultiGet(IReadOnlyList<byte[]>, ReadOptions?) to see a transaction's own writes, or MultiGetForUpdate(IReadOnlyList<byte[]>, ReadOptions?) to lock what was read.

MultiGet(IReadOnlyList<byte[]>, IReadOnlyList<ColumnFamilyHandle>, ReadOptions?)

Reads several keys in one call, each from the column family at the same position in columnFamilies.

public byte[]?[] MultiGet(IReadOnlyList<byte[]> keys, IReadOnlyList<ColumnFamilyHandle> columnFamilies, ReadOptions? options = null)

Parameters

keys IReadOnlyList<byte[]>

columnFamilies IReadOnlyList<ColumnFamilyHandle>

options ReadOptions

Returns

byte[][]

One entry per key, null where the key is absent.

Exceptions

ArgumentException

The two lists are of different lengths.

NewIterator(ColumnFamilyHandle, ReadOptions?)

Creates an iterator over the default column family.

public Iterator NewIterator(ColumnFamilyHandle cf, ReadOptions? options = null)

Parameters

cf ColumnFamilyHandle

options ReadOptions

Returns

Iterator

NewIterator(ReadOptions?)

Creates an iterator over the default column family.

public Iterator NewIterator(ReadOptions? options = null)

Parameters

options ReadOptions

Returns

Iterator

NewSnapshot()

Takes a point-in-time snapshot.

public Snapshot NewSnapshot()

Returns

Snapshot

Open(DbOptions, TransactionDbOptions, string)

Opens, or creates, a transaction database at path.

public static TransactionDb Open(DbOptions options, TransactionDbOptions transactionDbOptions, string path)

Parameters

options DbOptions

transactionDbOptions TransactionDbOptions

path string

Returns

TransactionDb

Open(DbOptions, TransactionDbOptions, string, IReadOnlyList<ColumnFamilyDescriptor>)

Opens, or creates, a transaction database with the given column families.

public static TransactionDb Open(DbOptions options, TransactionDbOptions transactionDbOptions, string path, IReadOnlyList<ColumnFamilyDescriptor> columnFamilies)

Parameters

options DbOptions

transactionDbOptions TransactionDbOptions

path string

columnFamilies IReadOnlyList<ColumnFamilyDescriptor>

Returns

TransactionDb

Put(ReadOnlySpan<byte>, ReadOnlySpan<byte>, ColumnFamilyHandle, WriteOptions?)

Writes a key and value, taking the same locks a transaction would.

public void Put(ReadOnlySpan<byte> key, ReadOnlySpan<byte> value, ColumnFamilyHandle cf, WriteOptions? options = null)

Parameters

key ReadOnlySpan<byte>

value ReadOnlySpan<byte>

cf ColumnFamilyHandle

options WriteOptions

Put(ReadOnlySpan<byte>, ReadOnlySpan<byte>, WriteOptions?)

Writes a key and value, taking the same locks a transaction would.

public void Put(ReadOnlySpan<byte> key, ReadOnlySpan<byte> value, WriteOptions? options = null)

Parameters

key ReadOnlySpan<byte>

value ReadOnlySpan<byte>

options WriteOptions

Put(string, string, ColumnFamilyHandle, WriteOptions?)

Writes a UTF-8 key and value.

public void Put(string key, string value, ColumnFamilyHandle cf, WriteOptions? options = null)

Parameters

key string

value string

cf ColumnFamilyHandle

options WriteOptions

Put(string, string, WriteOptions?)

Writes a UTF-8 key and value.

public void Put(string key, string value, WriteOptions? options = null)

Parameters

key string

value string

options WriteOptions

TryGetColumnFamily(string, out ColumnFamilyHandle?)

Looks up a column family handle, returning false rather than throwing when there is none.

public bool TryGetColumnFamily(string name, out ColumnFamilyHandle? columnFamily)

Parameters

name string

columnFamily ColumnFamilyHandle

Returns

bool

Exceptions

ObjectDisposedException

The handle registered for name has been disposed. The default family is the exception: it is resolved again instead.

TryGet<T>(ReadOnlySpan<byte>, ColumnFamilyHandle, ValueDecoder<T>, out T, ReadOptions?)

Reads key and decodes its value in place, without copying it into a managed array.

public bool TryGet<T>(ReadOnlySpan<byte> key, ColumnFamilyHandle cf, ValueDecoder<T> decode, out T value, ReadOptions? options = null)

Parameters

key ReadOnlySpan<byte>

The key to read.

cf ColumnFamilyHandle

decode ValueDecoder<T>

Turns the value into a T. The span it is given is valid only until it returns. Not called when the key is absent.

value T

The decoded value, when the key was found.

options ReadOptions

Read options, or null for the defaults.

Returns

bool

true if the key was found.

Type Parameters

T

What the value decodes to.

Remarks

The value is read through a pinned slice and released once decode returns, or throws; an exception from the decoder reaches the caller unchanged. Compared with decoding the array Get returns, this saves allocating and copying the value.

A static lambda allocates nothing. A decoder that needs state, such as serializer options, can take it through the overload with a state argument instead of capturing it.

Exceptions

RocksDbException

The read failed, as opposed to finding nothing.

TryGet<T>(ReadOnlySpan<byte>, ValueDecoder<T>, out T, ReadOptions?)

Reads key and decodes its value in place, without copying it into a managed array.

public bool TryGet<T>(ReadOnlySpan<byte> key, ValueDecoder<T> decode, out T value, ReadOptions? options = null)

Parameters

key ReadOnlySpan<byte>

The key to read.

decode ValueDecoder<T>

Turns the value into a T. The span it is given is valid only until it returns. Not called when the key is absent.

value T

The decoded value, when the key was found.

options ReadOptions

Read options, or null for the defaults.

Returns

bool

true if the key was found.

Type Parameters

T

What the value decodes to.

Remarks

The value is read through a pinned slice and released once decode returns, or throws; an exception from the decoder reaches the caller unchanged. Compared with decoding the array Get returns, this saves allocating and copying the value.

A static lambda allocates nothing. A decoder that needs state, such as serializer options, can take it through the overload with a state argument instead of capturing it.

Exceptions

RocksDbException

The read failed, as opposed to finding nothing.

TryGet<TState, T>(ReadOnlySpan<byte>, ColumnFamilyHandle, TState, ValueDecoder<TState, T>, out T, ReadOptions?)

Reads key and decodes its value in place, passing state to the decoder rather than having it captured.

public bool TryGet<TState, T>(ReadOnlySpan<byte> key, ColumnFamilyHandle cf, TState state, ValueDecoder<TState, T> decode, out T value, ReadOptions? options = null)

Parameters

key ReadOnlySpan<byte>

The key to read.

cf ColumnFamilyHandle

state TState

Passed to decode unchanged.

decode ValueDecoder<TState, T>

Turns the value into a T. The span it is given is valid only until it returns. Not called when the key is absent.

value T

The decoded value, when the key was found.

options ReadOptions

Read options, or null for the defaults.

Returns

bool

true if the key was found.

Type Parameters

TState

The state the decoder needs.

T

What the value decodes to.

Remarks

The value is read through a pinned slice and released once decode returns, or throws; an exception from the decoder reaches the caller unchanged. Compared with decoding the array Get returns, this saves allocating and copying the value.

A static lambda allocates nothing. A decoder that needs state, such as serializer options, can take it through the overload with a state argument instead of capturing it.

Exceptions

RocksDbException

The read failed, as opposed to finding nothing.

TryGet<TState, T>(ReadOnlySpan<byte>, TState, ValueDecoder<TState, T>, out T, ReadOptions?)

Reads key and decodes its value in place, passing state to the decoder rather than having it captured.

public bool TryGet<TState, T>(ReadOnlySpan<byte> key, TState state, ValueDecoder<TState, T> decode, out T value, ReadOptions? options = null)

Parameters

key ReadOnlySpan<byte>

The key to read.

state TState

Passed to decode unchanged.

decode ValueDecoder<TState, T>

Turns the value into a T. The span it is given is valid only until it returns. Not called when the key is absent.

value T

The decoded value, when the key was found.

options ReadOptions

Read options, or null for the defaults.

Returns

bool

true if the key was found.

Type Parameters

TState

The state the decoder needs.

T

What the value decodes to.

Remarks

The value is read through a pinned slice and released once decode returns, or throws; an exception from the decoder reaches the caller unchanged. Compared with decoding the array Get returns, this saves allocating and copying the value.

A static lambda allocates nothing. A decoder that needs state, such as serializer options, can take it through the overload with a state argument instead of capturing it.

Exceptions

RocksDbException

The read failed, as opposed to finding nothing.

Write(WriteBatch, WriteOptions?)

Applies a write batch atomically.

public void Write(WriteBatch batch, WriteOptions? options = null)

Parameters

batch WriteBatch

options WriteOptions