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

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.

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

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.

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

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

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

Write(WriteBatch, WriteOptions?)

Applies a write batch atomically.

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

Parameters

batch WriteBatch

options WriteOptions