FdbDatabase

Namespace: FoundationDB.Client · class

Implements: IFdbDatabase, IFdbRetryable, IFdbReadOnlyRetryable, IDisposable, IFdbDatabaseOptions, IFdbDatabaseProvider, IFdbDatabaseScopeProvider

FoundationDB database session handle

Remarks

An instance of this class can be used to create any number of concurrent transactions that will read and/or write to this particular database.

Properties

Cancellation

CancellationToken Cancellation { get; }

Returns a cancellation token that is linked with the lifetime of this database instance

The token will be cancelled if the database instance is disposed

ClusterFile

string ClusterFile { get; }

Full path to the '.cluster' file that contains the connection string to the cluster

This should be a valid path, accessible with read and write permissions by the process.

This property and ConnectionString are mutually exclusive.

ConnectionString

string ConnectionString { get; }

Connection string to the cluster

The format of this string is the same as the content of a .cluster file.

This property and ClusterFile are mutually exclusive.

DefaultMaxRetryDelay

int DefaultMaxRetryDelay { get; set; }

Default Maximum Retry Delay value (in milliseconds) for all transactions created from this database instance.

If changed, will only be effective for future transactions

DefaultRetryLimit

int DefaultRetryLimit { get; set; }

Default Retry Limit value for all transactions created from this database instance.

If changed, will only be effective for future transactions

DefaultTimeout

int DefaultTimeout { get; set; }

Default Timeout value (in milliseconds) for all transactions created from this database instance.

If changed, will only be effective for future transactions

DefaultTracing

FdbTracingOptions DefaultTracing { get; set; }

Default tracing options for all transactions created from this database instance.

If changed, will only be effective for future transactions

DirectoryLayer

FdbDirectoryLayer DirectoryLayer { get; }

Directory Layer used by this database instance

IsReadOnly

bool IsReadOnly { get; }

If true, this database instance will only allow starting read-only transactions.

Options

IFdbDatabaseOptions Options { get; }

Helper that can set options for this database

Root

FdbDirectorySubspaceLocation Root { get; }

Returns the root path used by this database instance

Time

TimeProvider Time { get; }

Time source used by this database for managed waits and timestamps (watch idle-timeouts and transaction-log stamps).

Defaults to the system clock. A test can inject a fake provider (for example through a FakeDbStore or AddFakeDb) so that managed time-based waits advance with virtual time instead of the wall clock.

A database backed by the native fdb client must keep a system-based provider: the native client enforces its own timeouts and retry backoff, so a fake clock cannot drive those and would only desynchronize the managed bulk-write commit cadence from the native five-second transaction limit.

Methods

BeginTransaction

IFdbTransaction BeginTransaction(FdbTransactionMode mode, CancellationToken ct, FdbOperationContext context = null)

Starts a new transaction on this database, with the specified mode

mode — Mode of the transaction (read-only, read-write, ....)
ct — Optional cancellation token that can abort all pending async operations started by this transaction.
context — Existing parent context, if the transaction needs to be linked with a retry loop, or a parent transaction. If null, will create a new standalone context valid only for this transaction

Returns: New transaction instance that can read from or write to the database.

You MUST call Dispose() on the transaction when you are done with it. You SHOULD wrap it in a 'using' statement to ensure that it is disposed in all cases.

using(var tr = db.BeginTransaction(CancellationToken.None))
{
	tr.Set(Slice.FromString("Hello"), Slice.FromString("World"));
	tr.Clear(Slice.FromString("OldValue"));
	await tr.CommitAsync();
}

BeginTransactionAsync

ValueTask<IFdbTransaction> BeginTransactionAsync(FdbTransactionMode mode, CancellationToken ct, FdbOperationContext context = null)

Starts a new transaction on this database, with the specified mode

mode — Mode of the transaction (read-only, read-write, ....)
ct — Optional cancellation token that can abort all pending async operations started by this transaction.
context — Existing parent context, if the transaction needs to be linked with a retry loop, or a parent transaction. If null, will create a new standalone context valid only for this transaction

Returns: New transaction instance that can read from or write to the database.

You MUST call Dispose() on the transaction when you are done with it. You SHOULD wrap it in a 'using' statement to ensure that it is disposed in all cases.

using(var tr = db.BeginTransaction(CancellationToken.None))
{
	tr.Set(Slice.FromString("Hello"), Slice.FromString("World"));
	tr.Clear(Slice.FromString("OldValue"));
	await tr.CommitAsync();
}

Create

static FdbDatabase Create(IFdbDatabaseHandler handler, FdbDirectoryLayer directory, FdbDirectorySubspaceLocation root, bool readOnly, CancellationToken globalToken, TimeProvider time = null)

Create a new Database instance from a database handler

handler — Handle to the native FDB_DATABASE*
directory — Directory Layer instance used by this database instance
root — Root location of the database
readOnly — If true, the database instance will only allow read-only transactions
globalToken — Global cancellation token that this database instance should use as a global shutdown signal
time — Time source for managed waits and timestamps (see Time); defaults to the system clock.

CreateScope

IFdbDatabaseScopeProvider<TState> CreateScope<TState>(Func<IFdbDatabase, CancellationToken, Task<(IFdbDatabase, TState)>> start, CancellationToken lifetime = null)

Create a scope that will use the database provided by this instance, and which also needs to perform some initialization steps before being ready (ex: using the DirectoryLayer to open subspaces, ...)

start — Handler that will be called AFTER the database becomes ready, but BEFORE any consumer of this scope can run.
lifetime — Optional cancellation token that can be used to externally abort the new scope

CreateSnapshotAsync

Task CreateSnapshotAsync(string uid, string snapCommand, CancellationToken ct)

Creates a new snapshot of the database

Dispose

void Dispose()

Close this database instance, aborting any pending transaction that was created by this instance.

ForceRecoveryWithDataLossAsync

Task ForceRecoveryWithDataLossAsync(string dcId, CancellationToken ct)

Forces a recovery that could induce data loss

GetApiVersion

int GetApiVersion()

Returns the currently enforced API version for this database instance.

GetClientStatus

Task<Slice> GetClientStatus(CancellationToken ct)

Returns the client status

GetMainThreadBusyness

double GetMainThreadBusyness()

Returns a value between 0 and 1 that reflect the saturation of the client main thread.

Returns: Value between 0 (no activity) and 1 (completely saturated)

The value is updated in the background at regular interval (by default every second).

GetServerProtocolVersionAsync

Task<FdbProtocolVersion> GetServerProtocolVersionAsync(FdbProtocolVersion expectedVersion, CancellationToken ct)

Returns the protocol version reported by the coordinator this client is connected to.

expectedVersion — If this value is not equal to None, the task will not complete until the protocol version is different than expected (or ct fires).
ct — Token used to cancel the operation.

Returns: Task that returns the current protocol version

This will never complete if the remote server is running a protocol from FDB 5.0 or older.

GetTenant

IFdbTenant GetTenant(FdbTenantName name)

Gets a tenant from this database

name — Name of the tenant

Returns: Instance that can execute transactions in the context of this tenant

ReadAsync

Task ReadAsync(Func<IFdbReadOnlyTransaction, Task> handler, CancellationToken ct)

Runs an idempotent transaction block inside a read-only transaction, which can be executed more than once if any retryable error occurs.

handler — Idempotent handler that will only read from the database, and may be retried if a recoverable error occurs.
ct — Token used to cancel the operation

Returns: Task that succeeds if no error occurred during execution of handler.

Since the method does not result any result, it should only be used to verify the content of the database. Any attempt to write or commit using the transaction will throw. Given that the can run more than once, and that there is no guarantee that the transaction commits once it returns, you MUST NOT mutate any global state (counters, cache, global dictionary) inside this lambda! You must wait for the Task to complete successfully before updating the global state of the application.

Task<TResult> ReadAsync<TResult>(Func<IFdbReadOnlyTransaction, Task<TResult>> handler, CancellationToken ct)

Runs an idempotent transaction block inside a read-only transaction, which can be executed more than once if any retryable error occurs.

handler — Idempotent handler that will only read from the database, and may be retried if a recoverable error occurs.
ct — Token used to cancel the operation

Returns: Result of the last successful execution of handler.

Any attempt to write or commit using the transaction will throw. Given that the can run more than once, and that there is no guarantee that the transaction commits once it returns, you MUST NOT mutate any global state (counters, cache, global dictionary) inside this lambda! You must wait for the Task to complete successfully before updating the global state of the application.

Task ReadAsync<TState>(TState state, Func<IFdbReadOnlyTransaction, TState, Task> handler, CancellationToken ct)

Runs an idempotent transaction block inside a read-only transaction, which can be executed more than once if any retryable error occurs.

state — Caller-provided context or state that will be passed through to the handler
handler — Idempotent handler that will only read from the database, and may be retried if a recoverable error occurs.
ct — Token used to cancel the operation

Returns: Task that succeeds if no error occurred during execution of handler.

Task<TResult> ReadAsync<TState, TResult>(TState state, Func<IFdbReadOnlyTransaction, TState, Task<TResult>> handler, CancellationToken ct)

Runs an idempotent transaction block inside a read-only transaction, which can be executed more than once if any retryable error occurs.

state — Caller-provided context or state that will be passed through to the handler
handler — Idempotent handler that will only read from the database, and may be retried if a recoverable error occurs.
ct — Token used to cancel the operation

Returns: Task that succeeds if no error occurred during execution of handler.

Task<TResult> ReadAsync<TResult>(Func<IFdbReadOnlyTransaction, Task<TResult>> handler, Action<IFdbReadOnlyTransaction, TResult> success, CancellationToken ct)

Runs an idempotent transaction block inside a read-only transaction, which can be executed more than once if any retryable error occurs.

handler — Idempotent handler that will only read from the database, and may be retried if a recoverable error occurs.
ct — Token used to cancel the operation

Returns: Task that succeeds if no error occurred during execution of handler.

Task<TResult> ReadAsync<TIntermediate, TResult>(Func<IFdbReadOnlyTransaction, Task<TIntermediate>> handler, Func<IFdbReadOnlyTransaction, TIntermediate, TResult> success, CancellationToken ct)

Runs an idempotent transaction block inside a read-only transaction, which can be executed more than once if any retryable error occurs.

handler — Idempotent handler that will only read from the database, and may be retried if a recoverable error occurs.
ct — Token used to cancel the operation

Returns: Task that succeeds if no error occurred during execution of handler.

Task<TResult> ReadAsync<TIntermediate, TResult>(Func<IFdbReadOnlyTransaction, Task<TIntermediate>> handler, Func<IFdbReadOnlyTransaction, TIntermediate, Task<TResult>> success, CancellationToken ct)

Runs an idempotent transaction block inside a read-only transaction, which can be executed more than once if any retryable error occurs.

handler — Idempotent handler that will only read from the database, and may be retried if a recoverable error occurs.
ct — Token used to cancel the operation

Returns: Task that succeeds if no error occurred during execution of handler.

Task<TResult> ReadAsync<TState, TIntermediate, TResult>(TState state, Func<IFdbReadOnlyTransaction, TState, Task<TIntermediate>> handler, Func<IFdbReadOnlyTransaction, TIntermediate, Task<TResult>> success, CancellationToken ct)

Runs an idempotent transaction block inside a read-only transaction, which can be executed more than once if any retryable error occurs.

state — Caller-provided context or state that will be passed through to the handler
handler — Idempotent handler that will only read from the database, and may be retried if a recoverable error occurs.
success — Handler that will be called once the transaction executes successfully. The result from the last invocation of handler will be passed as the second parameter.
ct — Token used to cancel the operation

Returns: Result return by success, if it was called.

ReadWriteAsync

Task<TResult> ReadWriteAsync<TResult>(Func<IFdbTransaction, Task<TResult>> handler, CancellationToken ct)

Run an idempotent transaction block inside a writable transaction, which can be executed more than once if any retryable error occurs.

handler — Idempotent handler that will attempt to mutate the database, and may be retried until the transaction commits, or a non-recoverable error occurs.
ct — Token used to cancel the operation

Returns: Result of the last successful execution of handler.

You do not need to commit the transaction inside the handler, it will be done automatically! Given that the can run more than once, and that there is no guarantee that the transaction commits once it returns, you MUST NOT mutate any global state (counters, cache, global dictionary) inside this lambda! You must wait for the Task to complete successfully before updating the global state of the application.

Task<TResult> ReadWriteAsync<TResult>(Action<IFdbTransaction> handler, Func<IFdbTransaction, TResult> success, CancellationToken ct)

Run an idempotent transaction block inside a writable transaction, which can be executed more than once if any retryable error occurs.

handler — Idempotent handler that will attempt to mutate the database, and may be retried until the transaction commits, or a non-recoverable error occurs.
success — Handler that will be called once the transaction commits successfully.
ct — Token used to cancel the operation

Returns: Result return by success, if it was called.

You do not need to commit the transaction inside the handler, it will be done automatically! Given that the can run more than once, and that there is no guarantee that the transaction commits once it returns, you MUST NOT mutate any global state (counters, cache, global dictionary) inside this lambda, and only inside the handler! Please note that there is NO guarantee that will be invoked even if the transaction commits successfully! The execution may be interrupted before the handler has time to execute.

Task<TResult> ReadWriteAsync<TState, TResult>(TState state, Func<IFdbTransaction, TState, Task<TResult>> handler, CancellationToken ct)

Run an idempotent transaction block inside a writable transaction, which can be executed more than once if any retryable error occurs.

state — Caller-provided context or state that will be passed through to the handler
handler — Idempotent handler that will attempt to mutate the database, and may be retried until the transaction commits, or a non-recoverable error occurs.
ct — Token used to cancel the operation

Returns: Result of the last successful execution of handler.

Task<TResult> ReadWriteAsync<TResult>(Func<IFdbTransaction, Task<TResult>> handler, Action<IFdbTransaction, TResult> success, CancellationToken ct)

Run an idempotent transaction block inside a writable transaction, which can be executed more than once if any retryable error occurs.

handler — Idempotent handler that will attempt to mutate the database, and may be retried until the transaction commits, or a non-recoverable error occurs.
ct — Token used to cancel the operation

Returns: Result of the last successful execution of handler.

Task<TResult> ReadWriteAsync<TResult>(Func<IFdbTransaction, Task> handler, Func<IFdbTransaction, Task<TResult>> success, CancellationToken ct)

Run an idempotent transaction block inside a writable transaction, which can be executed more than once if any retryable error occurs.

handler — Idempotent handler that will attempt to mutate the database, and may be retried until the transaction commits, or a non-recoverable error occurs.
success — Handler that will be called once the transaction commits successfully.
ct — Token used to cancel the operation

Returns: Result return by success, if it was called.

You do not need to commit the transaction inside the handler, it will be done automatically! Given that the can run more than once, and that there is no guarantee that the transaction commits once it returns, you MUST NOT mutate any global state (counters, cache, global dictionary) inside this lambda, and only inside the handler! Please note that there is NO guarantee that will be invoked even if the transaction commits successfully! The execution may be interrupted before the handler has time to execute.

Task<TResult> ReadWriteAsync<TResult>(Func<IFdbTransaction, Task> handler, Func<IFdbTransaction, TResult> success, CancellationToken ct)

Run an idempotent transaction block inside a writable transaction, which can be executed more than once if any retryable error occurs.

handler — Idempotent handler that will attempt to mutate the database, and may be retried until the transaction commits, or a non-recoverable error occurs.
success — Handler that will be called once the transaction commits successfully.
ct — Token used to cancel the operation

Returns: Result return by success, if it was called.

You do not need to commit the transaction inside the handler, it will be done automatically! Given that the can run more than once, and that there is no guarantee that the transaction commits once it returns, you MUST NOT mutate any global state (counters, cache, global dictionary) inside this lambda, and only inside the handler! Please note that there is NO guarantee that will be invoked even if the transaction commits successfully! The execution may be interrupted before the handler has time to execute.

Task<TResult> ReadWriteAsync<TIntermediate, TResult>(Func<IFdbTransaction, Task<TIntermediate>> handler, Func<IFdbTransaction, TIntermediate, TResult> success, CancellationToken ct)

Run an idempotent transaction block inside a writable transaction, which can be executed more than once if any retryable error occurs.

handler — Idempotent handler that will attempt to mutate the database, and may be retried until the transaction commits, or a non-recoverable error occurs.
ct — Token used to cancel the operation

Returns: Result of the last successful execution of handler.

Task<TResult> ReadWriteAsync<TIntermediate, TResult>(Func<IFdbTransaction, Task<TIntermediate>> handler, Func<IFdbTransaction, TIntermediate, Task<TResult>> success, CancellationToken ct)

Run an idempotent transaction block inside a writable transaction, which can be executed more than once if any retryable error occurs.

handler — Idempotent handler that will attempt to mutate the database, and may be retried until the transaction commits, or a non-recoverable error occurs.
ct — Token used to cancel the operation

Returns: Result of the last successful execution of handler.

Task<TResult> ReadWriteAsync<TState, TIntermediate, TResult>(TState state, Func<IFdbTransaction, TState, Task<TIntermediate>> handler, Func<IFdbTransaction, TIntermediate, Task<TResult>> success, CancellationToken ct)

Run an idempotent transaction block inside a writable transaction, which can be executed more than once if any retryable error occurs.

state — Caller-provided context or state that will be passed through to the handler
handler — Idempotent handler that will attempt to mutate the database, and may be retried until the transaction commits, or a non-recoverable error occurs.
success — Handler that will be called once the transaction commits successfully. The intermediate result from the last invocation of handler will be passed as the seconde parameter.
ct — Token used to cancel the operation

Returns: Result return by success, if it was called.

You do not need to commit the transaction inside the handler, it will be done automatically! Given that the can run more than once, and that there is no guarantee that the transaction commits once it returns, you MUST NOT mutate any global state (counters, cache, global dictionary) inside this lambda, and only inside the handler! Please note that there is NO guarantee that will be invoked even if the transaction commits successfully! The execution may be interrupted before the handler has time to execute.

RebootWorkerAsync

Task RebootWorkerAsync(string name, bool check, int duration, CancellationToken ct)

Attempts to reboot a work in the cluster

SetDefaultLogHandler

void SetDefaultLogHandler(Action<FdbTransactionLog> handler, FdbLoggingOptions options = null)

Sets the default log handler for this database

handler — Default handler that is attached to any new transaction, and will be invoked when they complete.

This handler may not be called if logging is disabled, if a transaction overrides its handler, or if it calls

SetOption

IFdbDatabaseOptions SetOption(FdbDatabaseOption option)

Set an option on this database that does not take any parameter

option — Option to set

IFdbDatabaseOptions SetOption(FdbDatabaseOption option, ReadOnlySpan<char> value)

Set an option on this database that takes a string value

option — Option to set
value — Value of the parameter (can be empty)

IFdbDatabaseOptions SetOption(FdbDatabaseOption option, ReadOnlySpan<byte> value)

Set an option on this database that takes a byte array value

option — Option to set
value — Value of the parameter (can be empty)

IFdbDatabaseOptions SetOption(FdbDatabaseOption option, long value)

Set an option on this database that takes an integer value

option — Option to set
value — Value of the parameter

WriteAsync

Task WriteAsync(Action<IFdbTransaction> handler, CancellationToken ct)

Run an idempotent transaction block inside a writable transaction, which can be executed more than once if any retryable error occurs.

handler — Idempotent handler that will attempt to mutate the database, and may be retried until the transaction commits, or a non-recoverable error occurs.
ct — Token used to cancel the operation

Task WriteAsync(Func<IFdbTransaction, Task> handler, CancellationToken ct)

Run an idempotent transaction block inside a writable transaction, which can be executed more than once if any retryable error occurs.

handler — Idempotent handler that will attempt to mutate the database, and may be retried until the transaction commits, or a non-recoverable error occurs.
ct — Token used to cancel the operation

Task WriteAsync<TState>(TState state, Action<IFdbTransaction, TState> handler, CancellationToken ct)

Run an idempotent transaction block inside a writable transaction, which can be executed more than once if any retryable error occurs.

state — Caller-provided context or state that will be passed through to the handler
handler — Idempotent handler that will attempt to mutate the database, and may be retried until the transaction commits, or a non-recoverable error occurs.
ct — Token used to cancel the operation

Task WriteAsync<TState>(TState state, Func<IFdbTransaction, TState, Task> handler, CancellationToken ct)

Run an idempotent transaction block inside a writable transaction, which can be executed more than once if any retryable error occurs.

state — Caller-provided context or state that will be passed through to the handler
handler — Idempotent handler that will attempt to mutate the database, and may be retried until the transaction commits, or a non-recoverable error occurs.
ct — Token used to cancel the operation

Task WriteAsync(Action<IFdbTransaction> handler, Action<IFdbTransaction> success, CancellationToken ct)

Run an idempotent transaction block inside a writable transaction, which can be executed more than once if any retryable error occurs.

handler — Idempotent handler that will attempt to mutate the database, and may be retried until the transaction commits, or a non-recoverable error occurs.
success — Handler that will be called once the transaction commits successfully.
ct — Token used to cancel the operation

You do not need to commit the transaction inside the handler, it will be done automatically! Given that the can run more than once, and that there is no guarantee that the transaction commits once it returns, you MUST NOT mutate any global state (counters, cache, global dictionary) inside this lambda, and only inside the handler! Please note that there is NO guarantee that will be invoked even if the transaction commits successfully! The execution may be interrupted before the handler has time to execute.

Task WriteAsync(Action<IFdbTransaction> handler, Func<IFdbTransaction, Task> success, CancellationToken ct)

Run an idempotent transaction block inside a writable transaction, which can be executed more than once if any retryable error occurs.

handler — Idempotent handler that will attempt to mutate the database, and may be retried until the transaction commits, or a non-recoverable error occurs.
success — Handler that will be called once the transaction commits successfully.
ct — Token used to cancel the operation

You do not need to commit the transaction inside the handler, it will be done automatically! Given that the can run more than once, and that there is no guarantee that the transaction commits once it returns, you MUST NOT mutate any global state (counters, cache, global dictionary) inside this lambda, and only inside the handler! Please note that there is NO guarantee that will be invoked even if the transaction commits successfully! The execution may be interrupted before the handler has time to execute.

Task WriteAsync(Func<IFdbTransaction, Task> handler, Action<IFdbTransaction> success, CancellationToken ct)

Run an idempotent transaction block inside a writable transaction, which can be executed more than once if any retryable error occurs.

handler — Idempotent handler that will attempt to mutate the database, and may be retried until the transaction commits, or a non-recoverable error occurs.
success — Handler that will be called once the transaction commits successfully.
ct — Token used to cancel the operation

You do not need to commit the transaction inside the handler, it will be done automatically! Given that the can run more than once, and that there is no guarantee that the transaction commits once it returns, you MUST NOT mutate any global state (counters, cache, global dictionary) inside this lambda, and only inside the handler! Please note that there is NO guarantee that will be invoked even if the transaction commits successfully! The execution may be interrupted before the handler has time to execute.

Task WriteAsync(Func<IFdbTransaction, Task> handler, Func<IFdbTransaction, Task> success, CancellationToken ct)

Run an idempotent transaction block inside a writable transaction, which can be executed more than once if any retryable error occurs.

handler — Idempotent handler that will attempt to mutate the database, and may be retried until the transaction commits, or a non-recoverable error occurs.
success — Handler that will be called once the transaction commits successfully.
ct — Token used to cancel the operation

You do not need to commit the transaction inside the handler, it will be done automatically! Given that the can run more than once, and that there is no guarantee that the transaction commits once it returns, you MUST NOT mutate any global state (counters, cache, global dictionary) inside this lambda, and only inside the handler! Please note that there is NO guarantee that will be invoked even if the transaction commits successfully! The execution may be interrupted before the handler has time to execute.