Fdb

Namespace: FoundationDB.Client · class

FoundationDB binding

Properties

ApiVersion

static int ApiVersion { get; }

Returns the currently selected API version.

The value will be 0 if has not been called yet. If less than , some features will be emulated by the native binding.

BindingVersion

static int BindingVersion { get; }

Returns the maximum API version supported by the currently loaded native binding

The value will be 0 if has not been called yet.

IsNetworkRunning

static bool IsNetworkRunning { get; }

Returns true if the Network thread start is executing, otherwise false

NetworkThreadStopped

static CancellationToken NetworkThreadStopped { get; }

Token that will fire when the network thread stops or is aborted

Methods

CreateFailedScope

static IFdbDatabaseScopeProvider<TState> CreateFailedScope<TState>(Exception error, CancellationToken lifetime = null)

Create a poisoned database provider that will always throw the same error back to the caller

error — Exception that will be thrown every time someone attempts to use this scope (or a child scope)
lifetime — Optional cancellation token that can be used to externally abort the new scope

static IFdbDatabaseScopeProvider CreateFailedScope(Exception error, CancellationToken lifetime = null)

Create a poisoned database provider that will always throw the same error back to the caller

error — Exception that will be thrown every time someone attempts to use this scope (or a child scope)
lifetime — Optional cancellation token that can be used to externally abort the new scope

CreateRootScope

static IFdbDatabaseScopeProvider CreateRootScope(IFdbDatabase db, CancellationToken lifetime = null)

Create a root scope provider that will use the provided database instance

db — Database instance that will be exposed
lifetime — Optional cancellation token that can be used to externally abort the new scope

static IFdbDatabaseScopeProvider<TState> CreateRootScope<TState>(IFdbDatabase db, Func<IFdbDatabase, CancellationToken, Task<(IFdbDatabase, TState)>> init, CancellationToken lifetime = null)

Create a scope that will execute some initialization logic before the first transaction is allowed to run

db — Parent provider
init — Handler that must run successfully once before allowing transactions on this scope
lifetime — Optional cancellation token that can be used to externally abort the new scope

static IFdbDatabaseScopeProvider CreateRootScope(IFdbDatabase db, Func<IFdbDatabase, CancellationToken, Task> init, CancellationToken lifetime = null)

Create a scope that will execute some initialization logic before the first transaction is allowed to run

db — Parent database
init — Handler that must run successfully once before allowing transactions on this scope
lifetime — Optional cancellation token that can be used to externally abort the new scope

CreateScope

static IFdbDatabaseScopeProvider CreateScope(IFdbDatabaseScopeProvider parent, Func<IFdbDatabase, CancellationToken, Task<IFdbDatabase>> handler, CancellationToken lifetime = null)

Create a scope provider that will run some initialization logic before transactions are allowed to run

parent — Parent scope that will provide a database instance to this scope
handler — Handler that will be called once the parent provider becomes ready, and before any transactions started from this scope
lifetime — Optional cancellation token that can be used to externally abort the new scope

static IFdbDatabaseScopeProvider<TState> CreateScope<TState>(IFdbDatabaseScopeProvider parent, Func<IFdbDatabase, CancellationToken, Task<(IFdbDatabase, TState)>> handler, CancellationToken lifetime = null)

Create a scope provider that will run some initialization logic before transactions are allowed to run

parent — Parent scope that will provide a database instance to this scope
handler — Handler that will be called once the parent provider becomes ready, and before any transactions started from this scope
lifetime — Optional cancellation token that can be used to externally abort the new scope

static IFdbDatabaseScopeProvider<TState> CreateScope<TState>(IFdbDatabaseScopeProvider parent, Func<IFdbDatabase, CancellationToken, Task<TState>> handler, CancellationToken lifetime = null)

Create a scope provider that will run some initialization logic before transactions are allowed to run

parent — Parent scope that will provide a database instance to this scope
handler — Handler that will be called once the parent provider becomes ready, and before any transactions started from this scope
lifetime — Optional cancellation token that can be used to externally abort the new scope

static IFdbDatabaseScopeProvider CreateScope(IFdbDatabaseScopeProvider provider, Func<IFdbDatabase, CancellationToken, Task> init, CancellationToken lifetime = null)

Create a scope that will execute some initialization logic before the first transaction is allowed to run

provider — Parent provider
init — Handler that must run successfully once before allowing transactions on this scope
lifetime — Optional cancellation token that can be used to externally abort the new scope

EnsureApiVersion

static void EnsureApiVersion(int min, int? max = null)

Ensure that the currently selected ApiVersion is between the specified bounds

min — Minimum version that is supported by the caller. If the current version is lower, an exception will be thrown
max — If not null, maximum version that is supported by the caller. If the current version is higher, an exception will be thrown

GetClientVersion

static (string, string, string) GetClientVersion()

Returns the version of the client library, git commit hash of the build, and the supported protocol version

GetDefaultApiVersion

static int GetDefaultApiVersion()

Returns the default API version that is supported by the version of this binding

The version may be different from the version supported by the installed client, and the database cluster itself! This version should only be used by tools that are versioned and deployed alongside the binding package. Application and Layers should define their own API version and not rely on this value.

GetMaxApiVersion

static int GetMaxApiVersion()

Returns the maximum API version currently supported by the installed client.

The version of the installed client (fdb_c.dll) can be different higher (or lower) than the version supported by this binding (FoundationDB.Client.dll)! If you want the highest possible version that is supported by both the binding and the client, you must call . Attempts to select an API version higher than this value will fail.

GetMaxSafeApiVersion

static int GetMaxSafeApiVersion()

Returns the maximum API version that is supported by both this binding and the installed client.

Returns: Value that can be safely passed to Start, if you want to be on the bleeding edge.

This value can be lower than the value returned by if the FoundationDB client installed on this machine is more recent that the version of this assembly. Using this version may break your application if new features change the behavior of the client (ex: default mode for snapshot transactions between v2.x and v3.x).

static int GetMaxSafeApiVersion(int minVersion, int? maxVersion = null)

Returns the maximum API version that is supported by both this binding and the installed client.

Returns: Value that can be safely passed to Start, if you want to be on the bleeding edge.

GetMinApiVersion

static int GetMinApiVersion()

Returns the minimum API version currently supported by this binding.

Attempts to select an API version lower than this value will fail.

OpenAsync

static Task<IFdbDatabase> OpenAsync(CancellationToken ct = null)

Create a new connection with the "DB" database on the cluster specified by the default cluster file.

ct — Token used to abort the operation

Returns: Task that will return an FdbDatabase, or an exception

Since connections are not pooled, so this method can be costly and should NOT be called every time you need to read or write from the database. Instead, you should open a database instance at the start of your process, and use it a singleton.

static Task<IFdbDatabase> OpenAsync(FdbConnectionOptions options, CancellationToken ct)

Create a new connection with a database using the specified options

options — Connection options used to specify the cluster file, partition path, default timeouts, etc...
ct — Token used to abort the operation

Returns: Task that will return an FdbDatabase, or an exception

Start

static void Start()

Start the Network Thread, using the pre-selected API version.

If you need a specific API version level, you should call . Otherwise, the max safe default API version will be selected.

static void Start(int apiVersion)

Start the Network Thread, using the specified API version level

apiVersion — API version that will be used by this application. A value of 0 mean "max safe default version".

This method can only be called once per process, and the API version cannot be changed until the process restarts.

Stop

static void Stop()

Stop the Network Thread

UseApiVersion

static void UseApiVersion(int value)

Sets the desired API version of the binding. The selected version level may affect the availability and behavior or certain features.

The version can only be set before calling or any method that indirectly calls it. If the value is 0, then the maximum version supported by both this binding and the FoundationDB client (see ). If you want to be conservative, you should target a specific version level, and only change to newer versions after making sure that all tests are passing!